Revised File Identifier Handling

[brian-comply0]

User Story

As a tool developer, I want file identifiers to be more reliable and consistent across implementations, so that document references are more universal.

Description

Per a suggestion from @pkothare, file identifiers should:

• better align with the OSCAL specification;
• be embedded within the OSCAL document; and
• be universal across implementations.

The draft specification currently allows each implementation to assign their own unique identifier, and is completely silent on how that identifier is managed, and does not consider the possibility of using the same identifier to reference the same document in multiple different systems.

Further, while the OSCAL standard offers a document identifier field in metadata, this field is not required.

Acceptance Criteria

• [ ] The OSCALRESTOpenAPI.json file is updated to reflect this change at the appropriate endpoints.
• [ ] the OSCAL REST Open API content is updated to reflect this change
  • [ ] Revise identifier explanation
  • [ ] Revise endpoint references and identifier references throughout documentation
  • [ ] Add usage scenarios

Proposed Solution

The OSCAL REST OpenAPI Specification should be revised such that:

• OSCAL-compliant v4 or v5 UUIDs are used for API document identifiers
• OSCAL REST OpenAPI clients MUST assign an immutable document identifier to OSCAL content prior to POSTing to an OSCAL REST OpenAPI server
• OSCAL REST OpenAPI servers SHOULD/MUST do the following upon receipt of new OSCAL content via the POST method:
  • SHOULD make a snapshot of the content in its unaltered form;
  • MUST check for an OSCAL.io identifier in the metadata\document-ids array, and honor it as the unique identifier used in future API calls;
  • if no OSCAL.io identifier is found, generate a v4 or v5 UUID value and insert it into the metadata\document-ids array as the OSCAL.io identifier.