Define a version/revision data element for catalogs and profiles

[anweiss]

User Story:

As an OSCAL catalog and/or profile producer, I should have a way to include the version/revision of my catalog and/or profile directly within the OSCAL artifact as an appropriate flag/element. Today, the version/revision can only be articulated in the title element and/or the artifact file name itself per the naming conventions proposed in example-naming-conventions.md in PR #201.

Goals:

The catalog/profile version/revision should be exposed as an element/flag in the OSCAL model. Today, it's up to catalog/profile producers to decide whether or not to include this information in the title element and/or choose to follow the naming conventions as proposed by PR #201 and include the info in the file name itself. As a result, it presents tool developers and implementers with an unreliable way to determine the specific version/revision to which a catalog/profile is associated.

Dependencies:

This should be addressed in PR #201.

Acceptance Criteria

Catalog/profile producers can include version/revision information directly in a field in their artifacts and that which is defined by the OSCAL data model.

[iMichaela]

Status Meeting: 8/23/2018

More discussions are necessary to create a consistent format that generates a unique identifies. The metadata headers will include a uid.

[wendellpiez]

Addressing this issue fully may requires resolving some outstanding git issues in my repo in order to confirm all work that should be checked in and merged, has been.

Presently (in one or another version) we expect to handle this issue in several ways:

1. Versioning schemas. OSCAL namespaces and even file references can have versioning behind them. OSCAL catalogs and profiles now (may) have model-version flags to indicate the nominal version or flavor of OSCAL (schema+extra-schema) to which a document conforms.
2. @id attribute on the document element. Presently, catalogs are receiving UUIDs for this value. How this is assigned (and indeed the scope of uniqueness) is up to an application to define.
3. Values, both normalized/controlled, and nominal, given in the data, for example in the metadata header.

This issue as defined in the original ticket described only the first of these. Would it be possible to close this Issue when @anweiss and myself can confirm that the modeling question (specifically, the availability of the requisite attribute on the requisite element) has been not only implemented, but committed and merged?

For example see model-version='0.9.1' on
https://raw.githubusercontent.com/usnistgov/OSCAL/master/content/nist.gov/SP800-53/rev4/NIST_SP-800-53_rev4_catalog.xml

NB this attribute has not yet been propagated to the profiles, partly because its value is not yet meaningful.

[iMichaela]

8/30/2018 Status Meeting

Candidate solution for a unique identifier of the file could leverage NIST beacon service https://beacon.nist.gov/home

[wendellpiez]

Sprint 13 Progress Note

See #196 for progress on a schema for all document-level metadata (header info) including document identifiers.

% Complete: 20%? we have a model, but so far no examples to illustrate it.

Since this issue is important, our documentation may need a section just on identifiers and traceability and how OSCAL supports them.

[wendellpiez]

Adding to the work item here that we also need (a redundancy of) links from profiles to their catalogs (supporting hashes etc) as well perhaps from any OSCAL instance to its metaschema resources -- if only because users will need a trail to follow regarding what they are looking at. So far the metaschema is the only link back from the instance to the body of work (docs etc) beyond the XSD itself.

In other words, profiles and catalogs need a little boilerplate pointing to documentation of (its) OSCAL and supporting validable claims regarding metaschema version, catalog version/hash etc. This is especially true since certain properties of catalogs (indeed: control architecture itself) is defined at the catalog level, not the OSCAL level.

[wendellpiez]

Sprint 13 Progress September 20

The current draft metaschema for metadata headers includes ample hooks for "two-factor" (and three-factor) cross-checking of document artifacts between IDs, file names and addresses/URIs, nominal URIs, hashes, and controlled identifiers of arbitrary kinds. (cf #196)

See examples here: https://github.com/wendellpiez/OSCAL/tree/feature-metadata-schema/schema/metaschema these are very much WIP.

% Complete: 60% notionally, but no one has validated the design so far, so 40%?

[wendellpiez]

Sprint 13 Progress September 27

Because the relevant fields are in the document metadata as well as at the top level, this Issue essentially hangs on #196.

Once #196 is resolved, it should be straightforward to consider the acceptance criteria for this one. (Are the relevant fields present and is their use demonstrated and documented.)

However, this does raise the issue of documentation, as well....

[iMichaela]

9/26/2018

#196 is being broken in smaller issues that will also incorporate #220.