Add version property to Explicitly Version JSON Schemas like XML Schemas

[ohsh6o]

User Story:

As an OSCAL tool developer, I would like the JSON Schema to add an additional version attribute in the schema prelude.

Goals:

Like the OSCAL XML Schemas, it is useful to version the schema itself so tooling can introspect a component/SSP/SAP/SAR/POA&M model and the tooling knows a particular version it is processing to properly process and prevent conflicts between breaking changes for one or more data model schemas.

Example from the XML Schema: https://github.com/usnistgov/OSCAL/blob/master/xml/schema/oscal_component_schema.xsd#L8
Counter-example from current JSON Schema: https://github.com/usnistgov/OSCAL/blob/master/json/schema/oscal_component_schema.json#L2-L5

Ongoing discussion in the following Gitter thread: https://gitter.im/usnistgov-OSCAL/Lobby?at=6090340dff705616c76dde40

Dependencies:

None that I am aware of this time.

Acceptance Criteria

• All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

{The items above are general acceptance criteria for all User Stories. Please describe anything else that must be completed for this issue to be considered resolved.}

[ohsh6o]

There is no standard explicit meta-property like $version to match $id and using the latter for versioning is ill-advised, per "deep" initial research. I defer to you all if there is a better solution or $id could be acceptable, but given how you currently use it, I doubt it.

[wendellpiez]

This is related to #902.

It would be great to have a target design of what the JSON Schema property set looks like at the top. TMK we have not addressed this at all systematically. Both properties such as version, and top-level documentation, should be included.

Both these issues should be tied to ongoing work in the Metaschema pipelines. Maybe we need a tracker issue.

[davaya]

SDF (https://datatracker.ietf.org/doc/draft-ietf-asdf-sdf/) has a "version" keyword:

While the format of the version string is marked as TBD, it is
intended to be lexicographically increasing over the life of a model:
a newer model always has a version string that string-compares higher
than all previous versions.

There is value in having both a unique name of a document containing 2 or 3 levels of semver and a sequence number within that unique name. I agree with adding a version keyword to the JSON schema to be a sequence number within $id. https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8 recommends against using a $ prefix (e.g., $version ) for extension keywords.

[david-waltermire]

Given that "$version" and "version" are not keywords recognized by JSON Schema 07, I don't think we can add either property to the schema. Adding this will cause all kinds of mischief with various JSON schema validators.

I think we need to consider adding the version to "$id". Maybe something like:

http://csrc.nist.gov/ns/oscal/1.0.0/oscal-ssp-schema.json

Can we live with this?

[ohsh6o]

Sorry I never responded to this, let alone brought it up in today's model meeting (despite opening the issue). This "seems ok to me" but I relayed this feedback based on feedback from others I met in the user community for their particular use case. I will follow up and ask what their thoughts are on this topic.

[davaya]

It "seems OK" to me too, but 1) I'd like to know if any JSON Schema validators reject a version keyword, and 2) if we rely on putting all versioning info in the package namespace $id then we'll need to be much more specific on how to parse it into "package X" + "newer version of package X". Without that detail, and support for that kind of parsing in JSON Schema validators (which doesn't exist and AFAIK isn't even being considered), every micro version of

http://csrc.nist.gov/ns/oscal/1.0.0/oscal-ssp-schema.json   (package X)
http://csrc.nist.gov/ns/oscal/1.0.1/oscal-ssp-schema.json   (package Y)

is treated as a different package, leading to either an explosion of unresolved references or ineffective patch attempts.

[wendellpiez]

@davaya @david-waltermire-nist as to (1) I can confirm that ajv does not like $version or version in a JSON Schema. There may be a setting to silence the error - I am not an AJV (or JSON Schema) expert.

As to (2) maybe we should consider using only the major version increment in the JSON Schema ID?

http://csrc.nist.gov/ns/oscal/1.0/oscal-ssp-schema.json

for any 1.0.x OSCAL?

[david-waltermire]

The JSON schemas will include the version in the $id field. See issue #902.

This change was integrated with PR #948 and will be released with OSCAL 1.0.0.

[david-waltermire]

@davaya Sorting out the JSON schema id will need to be handled programmatically. I wish I had a better answer.