The language-neutral contract for OSCAL data bindings: OpenSpec capability specs, the vendored NIST OSCAL JSON Schema, the naming manifest, and the conformance corpus. Each language binding implements the contract and passes the corpus.
This repo is an OpenSpec store.
OSCAL is a standard format from NIST for writing down security and compliance information in a form computers can read: what a system is, which security controls it uses, and how well it meets them. Organizations exchange these documents with auditors, agencies, and each other.
The standard is published as a schema, which is a technical description of what a valid document looks like. A schema is not a ready-made tool. Each team that wants to read or write OSCAL in its own programming language has to build a library from it, and that causes three problems:
- The same document gets different answers. One library accepts a document and another rejects it, or both accept it and read it differently. Two organizations then disagree about whether the same compliance record is correct.
- The same thing gets different names. Each library invents its own names for the parts of a document. Code and knowledge do not carry from one language to another, and every team learns the standard again from the start.
- Nobody can prove a library is right. Without a shared yardstick, "this library follows OSCAL" is a claim that the author makes and the user must trust.
This repo fixes this by holding the rules once, in a form that does not depend on any programming language:
- A written contract that says what every library must do and how it must report problems.
- One naming list that gives each part of OSCAL a single name that every library uses.
- A shared set of test documents with the expected result for each. A library passes when it gives these results.
- A copy of the official NIST schema, unchanged, so everyone works from the same source.
The repo holds no software that reads or writes OSCAL. The libraries that do (see Known implementations) follow this contract and prove it by passing the test documents. Releases are numbered and signed, so a library can name the exact version of the rules it follows and anyone can check it (see Verify a release).
openspec/: the capability specs (specs/), the changes (changes/), the config, the identifier ledgerspec-ids.yaml, and the requirement indexrequirements.json.npm run requirements:writegenerates the index from the main specs. It lists the identifier, capability, and title of each requirement.traceability.schema.jsonis the JSON Schema of the traceability record that each binding keeps (see binding-surface). The requirements of each spec are in reading order, not in identifier order. A reader finds a requirement by its identifier with search oropenspec/requirements.json.schemas/<release>/: the NIST OSCAL JSON Schema files of one release, byte-for-byte, withsha256sums.metaschema/<release>/: the NIST OSCAL Metaschema modules of one release and the Metaschema datatypes XSD, byte-for-byte, withsha256sums. The constraint manifest comes from these files. The directories of the store group files by the kind of content that they hold, not by the repository that the content comes from. The modules inmetaschema/<release>/and the JSON Schema files inschemas/<release>/come from the same OSCAL release. The datatypes XSD comes fromusnistgov/metaschema.SOURCE.mdin each directory records the source of each file.manifest/<release>/: the manifests.names.jsonis the generated naming manifest. It holds the canonical name, kind, and schema pointers of each type.overrides.jsonis the hand-edited naming input.constraints.jsonis the generated constraint manifest. It holds the Metaschema constraints that the JSON Schema cannot state, as queries that a binding runs.constraint-exclusions.jsonis the hand-edited list of the constraints that the manifest leaves out.manifest/*.schema.jsonare the JSON Schemas of these files (see manifest/1.2.3/README.md).corpus/<release>/: the conformance corpus.docs/: shared documents that the specs cite, such as canonical JSON for conformance comparison.scripts/: the store tooling.
-
Clone this repo.
-
Register it:
openspec store register <path>. -
In a binding repo, add the store to
openspec/config.yaml:references: - { id: oscal-bindings-specs, remote: "https://github.com/cairn-proofs/oscal-bindings-specs.git" }
A reference is planning context only. Builds and conformance runs use the tagged archive, pinned by its sha256.
To get an issue when a newer release is published, a binding calls the reusable workflow
pin-move-check.yml on a schedule and passes the version that it pins. The
workflow opens one issue, "Move the spec pin to v", in the binding's tracker. It runs with the binding's own
GITHUB_TOKEN and needs no secret. The header of the workflow file shows the caller.
oscal-bindings-python, in Python: repository, issue tracker.oscal-bindings-typescript, in TypeScript: repository, issue tracker.
Each binding keeps its own expected conformance failures, in its own repository. This store holds no data about the
state of a binding (see schema-versioning). npm run binding-links:check
reads this list.
CONTRIBUTING.md describes how to change a requirement and how a binding adds or promotes an operation.
mise pins Node and the OpenSpec CLI. package-lock.json pins the npm dependencies.
mise installnpm cinpm run check
npm run check runs these checks. CI runs the same command on each pull request.
- The TypeScript typecheck.
- The identifier checker and its self-test.
- The requirement index generator self-test, which also checks the traceability record JSON Schema on sample
records, and
npm run requirements:check: it fails whenopenspec/requirements.jsondiffers from the generator output. - The
VERSIONcheck and its self-test. See Version. - The schema
sha256check. - The canonical JSON self-test.
- The YAML reader self-test.
scripts/yaml-reader.tsis the reference reader that the corpus check uses for YAML inputs. - The corpus check (see corpus/1.2.3/README.md).
- The binding link check and its self-test,
npm run binding-links:check. It fails when a tracked file outsideopenspec/changes/links an individual issue or pull request in a binding repository. The binding repositories are the repositories in Known implementations and eachoscal-bindings-*repository other than this store. - The names generator self-test, and
npm run names:check: it validates each manifest file and fails whennames.jsondiffers from the generator output. - The release checks and their self-test,
npm run releases:check. A released name that changes needs a breakingVERSIONincrement, and a releasedschemas/<release>/file must not change.VERSIONmust also meet the step rule in Version. These checks read git tags and history, so they fail in a shallow clone or a clone without tags. They also list each name change against the base ref (SPEC_IDS_BASE, defaultHEAD), and CI writes that list to the job summary. openspec validate --all --strict.
To change a canonical name, edit manifest/<release>/overrides.json, run npm run names:write, and commit both
files.
To add, rename, or remove a requirement in the main specs, run npm run requirements:write, and commit the index with
the specs.
VERSION holds the spec artifact version. The version is MAJOR.MINOR.PATCH+oscal.<release>, for example
0.1.0+oscal.1.2.3. It follows Semantic Versioning 2.0.0, has no pre-release label, and holds the OSCAL
release as build metadata.
- A reviewer decides if a change is a break, an addition or a fix (VER-003). Semantic Versioning 2.0.0 gives the increment for each kind.
- A change that needs an increment sets
VERSIONto the version of the next release. Do this also when no release follows at once. Changes between two releases share one increment. VERSIONmust be the latest release, or one patch, minor or major step above it (VER-008). The latest release is the release tag onmainwith the highest precedence, for all OSCAL releases.npm run releases:checkfails whenVERSIONis not one of these versions. It cannot find an increment that is too small, so the reviewer checks that too.- For the steps after the merge, see Release.
This repo's threat model is a Threat Composer .tc.json file, kept in
a separate private repo, oscal-bindings-specs-threat-models, rather than in this repo. Access to it is optional: you
do not need it to build, test or contribute.
If you have access, clone it beside this repo, not inside it:
gh repo clone cairn-proofs/oscal-bindings-specs-threat-models ../oscal-bindings-specs-threat-models
Open the .tc.json file there with the Threat Composer VS Code extension or web app.
- Merge the pull request that sets the new version in
VERSION. See Version. - Push the tag
v<VERSION>on that commit ofmain, for examplev0.1.0+oscal.1.2.3. - CI runs
npm run check, builds the archive withnpm run archive, and attaches the archive andSHA256SUMSto a draft GitHub release. CI fails when the tag is not onmainor does not matchVERSION. - Review the draft and publish it.
- Each binding that calls
pin-move-check.ymlgets its pin-move issue on its next scheduled run. Open the issue by hand for a binding that does not call it.
Pin the archive by the sha256 in SHA256SUMS, not by the tag. Before you pin or update a pin, check the archive you
downloaded. In the commands below, <version> is the release version, for example 0.8.0+oscal.1.2.3.
-
The archive matches
SHA256SUMS:shasum -a 256 -c SHA256SUMS -
This repo's CI built the archive from the tag (SLSA build provenance, logged in the public Sigstore transparency log):
gh attestation verify oscal-bindings-specs-<version>.tar.gz --repo cairn-proofs/oscal-bindings-specs \ --cert-identity "https://github.com/cairn-proofs/oscal-bindings-specs/.github/workflows/build.yml@refs/tags/v<version>" -
The archive is the asset published in the release (GitHub release attestation):
gh release verify-asset v<version> oscal-bindings-specs-<version>.tar.gz --repo cairn-proofs/oscal-bindings-specs -
The archive holds exactly the tagged files. In a clone of this repo with its tags, run
scripts/verify-release.sh v<version>. It rebuilds the archive withgit archivefrom the tag, compares it with the published archive, and runs checks 1 to 3, skipping a check the release cannot pass (see below). It runs no code from the tag. It needsghsigned in.
Older releases cannot pass every check. Releases up to and including v0.7.0+oscal.1.2.3 were built before CI
attested provenance, so check 2 fails for them. v0.1.0+oscal.1.2.3 and v0.2.0+oscal.1.2.3 are not immutable
releases, so check 3 fails for them. Checks 1 and 4 pass for every release.
These checks show that the archive matches the tagged commit. They do not show that the tagged commit is free of unwanted changes.