Versioning mechanism for OSCAL schemas

[anweiss]

Not sure if this has already been solidified. Using this as a starting point for a discussion on an appropriate versioning mechanism for all OSCAL schemas. Some thoughts below:

• Leverage existing revisioning approach (thinking in terms of Special Publication revisions)
• Take traditional semantic versioning approach
• Timed releases (e.g. month.year)

[david-waltermire]

Part of moving to a more production-oriented footing is to start to version our schema. We should address this as a user story following completion of issue #120.

[wendellpiez]

Now our documentation pipeline is in order (#120) we are in a position to move forward with this.

Currently, both catalog and profile models provide two ways of declaring a schema version:

1. Each has an attribute at the top level @schema-version. Currently it is not validated; but a particular schema could provide a fixed value for that documents valid to that schema. So a validating parser would detect a discrepancy if a different schema is used. Neither the catalog nor the profile schema has a hard-coded value like this as of yet. Alternatively, this value could be left free for validation outside the schema in/by a local process or Schematron.
2. Additionally, document metadata can describe a binding to a metaschema (including a nominal version number), which should correspond to the schema in use. These values could also be interrogated and validated (using Schematron or another mechanism that can compare values in multiple files).

NB: the Metaschema does not yet support versioning or binding schema versions to metaschema versions. This could be a useful feature.

However, the more important part of this problem is defining the policy on which these mechanisms depend - what should be the version numbers and how and when they should increment.

Needed: some discussion of these policies and how much we should implement for Milestone 1.

[iMichaela]

5/23/2019

No update at this time.

[david-waltermire]

Also discuss how this will affect schema naming (see issue #49).

[david-waltermire]

We discussed the following path forward the other day.

What needs to be done follows:

• [x] Use the @version attribute on OSCAL XML schema as follows:

  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
             xmlns:oscal-catalog="http://csrc.nist.gov/ns/oscal/1.0"
             xmlns:oscal-prose="http://csrc.nist.gov/ns/oscal/1.0"
             elementFormDefault="qualified"
             targetNamespace="http://csrc.nist.gov/ns/oscal/1.0"
             version="1.0-M1">

• [x] Add the version to the $id item in the OSCAL JSON Schema as follows:

  { "$schema" : "http://json-schema.org/draft-07/schema#",
      "$id" : "http://csrc.nist.gov/ns/oscal/1.0-M1/oscal-catalog-schema.json",
      "$comment" : "OSCAL Control Catalog Format: JSON Schema",
      "type" : "object",
  "definitions" : 

• [x] Add an oscal-version element to the top-level element in the XML OSCAL content models as follows:

  <profile xmlns="http://csrc.nist.gov/ns/oscal/1.0" id="uuid-65730d33-d3d9-433c-95b0-ce341005d442">
      <metadata>
        <title>NIST Special Publication 800-53 Revision 4 HIGH IMPACT BASELINE</title>
  
        <last-modified-date>2019-06-03T11:27:50.543-04:00</last-modified-date>
        <version>2015-01-22</version>
        <oscal-version>1.0-M1</oscal-version>

• [x] Add an oscal-version item to the top-level item in the JSON OSCAL content models as follows:

  {
    profile: {
      id: "uuid-818283dc-f635-4d36-9352-2349f09881cf",
      metadata: {
        title: "NIST Special Publication 800-53 Revision 4 LOW IMPACT BASELINE",
        last-modified-date: "2019-06-03T11:29:15.432-04:00",
        version: "2015-01-22",
        oscal-version: "1.0-M1",

[wendellpiez]

@david-waltermire-nist should the field oscal-version inside metadata be required?

I am making it required until you say it should be optional.

[david-waltermire]

This is done.

[wendellpiez]

Reopening -- I don't think the second half is done -- seeing to it that this value appears in the generated schemas.

[wendellpiez]

Added an element schema-version to the Metaschema.

Its value is propagated to XML and JSON schemas as described above.

It can also be cross-checked against the value of oscal-version in catalog and profile metadata.

Making PR.

[david-waltermire]

PR #415 wrapped up the remaining work. Closing.