Overview

The OSCAL REST OpenAPI Specification is defined using the OpenAPI 3.1 standard. It addresses OSCAL XML, JSON and YAML content for all seven OSCAL models and provides for identity assertion.

Each OSCAL model has a primary set of REST API methods and endpoints for the OSCAL content itself, as well as methods and endpoints for snapshots and attachments. OSCAL profiles have an additional set of methods and endpoints related to live profile resolution and snapshots of resolved profiles.

Conventions and Organization

All endpoint syntax is provided as:

The {model-name} is always one of the seven root-level OSCAL model names exactly as they are defined in the OSCAL syntax. Simply replace {model-name} with one of the following:

• catalog
• profile
• component-definition
• system-security-plan
• assessment plan
• assessment-results
• plan-of-action-and-milestones

Language

This information makes consistent use of the following terms:

• must indicates a requirement or behavior that must be present for an implementation to be considered compliant.
• should indicates something that is recommended, yet optional.
• may indicates something that is allowed.

Valid OSCAL

When the specification calls for OSCAL content to be accepted or returned, the content must be fully OSCAL valid. Even if the specification shows a non-compliant schema or example.

Implementations should accept all valid versions of OSCAL from 1.0.0 through the latest published by NIST (excluding drafts and release candidates). As with all OSCAL content, the oscal-version field in the metadata declares the OSCAL version for the content. Implementations should use that declared version when validating content for acceptance.

Identifiers

There are three types of identifiers used within the OSCAL REST OpenAPI specification:

• Content Identifiers
• Resource Identifiers
• Snapshot Identifiers

Content Identifiers

The content identifier (content-uuid) is the primary identifier used within the API endpoints. Consistent with the OSCAL Universally Unique Identifier (UUID) data type, this is an RFC-4122 v4 or v5 compliant UUID.

The goal is to use the same Content UUID to refer to OSCAL content in any implementation that adopts the specification. This is practical due to the nature of the v4 and v5 UUID specification.

When receiving new OSCAL content via a POST method, the implementation must check for the presence of an existing content identifier in the document ID array (//metaschema/document-ids), indicated with a scheme value of http://oscal.io/oscal/identifier/content-uuid.

• If the content identifier is present and v4 or v5 UUID compliant, the implementation must use this value as the content-uuid.
• If the content identifier is not present, the implementation must generate a v4 or v5 UUID for use as the content-uuid and insert it into document ID array using http://oscal.io/oscal/identifier/content-uuid as the scheme value.
• If the content identifier is present, but is neither v4 nor v5 UUID compliant, the implementation may either reject the entire POST content as invalid or replace the content identifier with a v4 or v5 UUID.
  Example

"document-ids": [
    {
        "identifier": "247a9d37-ee69-41d0-80d7-78d506cea640", 
        "scheme" : "http://oscal.io/oscal/identifier/content-uuid"
    }
]

Resource Identifiers

The REST API specification tightly couples attachment endpoint identifiers with the OSCAL back-matter resource UUID values, and are indicated in the endpoint syntax using {resource-uuid}.

OSCAL file and snapshot identifiers are indicated in the endpoint syntax with {identifier}. These identifiers are created and managed by the server implementation. The identifier must be a non-colonized name as defined by the W3C XML Schema Definition Language, which is consistent with the OSCAL token data type. The identifier must also be unique within the server's scope of control. They should use RFC-4122 compliant v4 or v5 UUIDs, consistent with the OSCAL UUID data type.

Snapshot Identifiers

Similar to content identifiers, snapshot identifiers are RFC-4122 v4 or v5 compliant UUIDs. This applies both to snapshot-uuid and resolved-snapshot-uuid values.

When receiving a POST method for a snapshot or resolved profile snapshot, the implementation must generate a v4 or v5 UUID to be used as the snapshot-uuid or resolved-snapshot-uuid, and insert it into the document ID array (//metaschema/document-ids), indicated with a scheme value of http://oscal.io/oscal/identifier/snapshot-uuid or http://oscal.io/oscal/identifier/resolved-snapshot-uuid as appropriate.

When returning a list of snapshots for a given content identifier, all entries in the list have the same content-uuid, and are differentiated by the presence of the snapshot-uuid or resolved-snapshot-uuid value in the document ID array.

Examples

"document-ids": [
    {
        "identifier": "99004c68-d8c0-4e18-b288-f3c836887680", 
        "scheme" : "http://oscal.io/oscal/identifier/snapshot-uuid"
    },
    {
        "identifier": "247a9d37-ee69-41d0-80d7-78d506cea640", 
        "scheme" : "http://oscal.io/oscal/identifier/content-uuid"
    }
]

"document-ids": [
    {
        "identifier": "c26a4e1e-92ea-4b38-8dbf-ed6da404ba61", 
        "scheme" : "http://oscal.io/oscal/identifier/resolved-snapshot-uuid"
    },
    {
        "identifier": "247a9d37-ee69-41d0-80d7-78d506cea640", 
        "scheme" : "http://oscal.io/oscal/identifier/content-uuid"
    }
]