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:

• Document Identifiers (Content UUID and External UUID)
• Resource Identifiers
• Snapshot Identifiers

Document Identifiers

Read more on Document Identifiers.

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"
    }
]