Content Identifiers

Content Identifiers in OSCAL REST API

The OSCAL REST API specifies a dual-identifier system to balance the needs of both server-side uniqueness and client-side document tracking. The rational for this approach is discussed in the issue at Issue 102: Revised File Identifier Handling of the OSCAL REST OpenAPI Specification GitHub Repository and our team is looking for your feedback!

The approach takes elements from the System for Cross-domain Identity Management (SCIM): Core Schema standard described in https://www.rfc-editor.org/rfc/rfc7643#section-3.1, which implements an id and external id.

This specification uses two distinct types of identifiers:

• Content Identifier
• External Identifier

Content Identifier

The content identifier (contentuuid) is the primary identifier used with the API endpoints. Consistent with the OSCAL Universally Unique Identifier (UUID) data type, this is an RFC-4122 v4 or v5 compliant UUID. The content identifier identifies the document within a specific implementation of the OSCAL REST API.

When receiving new OSCAL content via a POST request, the implementation will assign a content identifier to the document and place it in the document ID array (//metaschema/document-ids) with a scheme value of http://oscal.io/oscal/identifier/contentuuid. If a content identifier is already present it will be replaced.

External Identifier

Because the client does not have control over the Content UUID, the external Identifier (externaluuid) is an optional identifier that can be used by the client to identify a document. The API operations do not modify the this identifier enabling life cycle management of documents by the client. The external Identifier does not have to be a UUID but it is recommended.

How It Works

Creating New Documents (POST)

When creating a new document, clients have two options:

1. Include an External UUID:

{
    "catalog": {
        "metadata": {
            "document-ids": [
                {
                    "scheme": "http://oscal.io/oscal/identifier/externaluuid",
                    "identifier": "9c0a0e1c-9bdf-4cc4-acda-c32122525406"
                }
            ]
        }
    }
}

2. Submit without any identifier:

{
    "catalog": {
        "metadata": {
            "document-ids": []
        }
    }
}

In both cases, the server will respond with both the server-assigned Content UUID and any provided External UUID:

{
    "catalog": {
        "metadata": {
            "document-ids": [
                {
                    "scheme": "http://oscal.io/oscal/identifier/contentuuid",
                    "identifier": "8b291c95-22da-4ca1-b9ce-6dc782a417b1"
                },
                {
                    "scheme": "http://oscal.io/oscal/identifier/externaluuid",
                    "identifier": "9c0a0e1c-9bdf-4cc4-acda-c32122525406"
                }
            ]
        }
    }
}

Accessing Documents

All API operations must use the Content UUID:

GET /catalogs/8b291c95-22da-4ca1-b9ce-6dc782a417b1
PUT /catalogs/8b291c95-22da-4ca1-b9ce-6dc782a417b1
DELETE /catalogs/8b291c95-22da-4ca1-b9ce-6dc782a417b1

Best Practices

1. Client-Side Tracking: While optional, clients are encouraged to assign External UUIDs when creating documents. This allows for consistent document identification across different systems and implementations.

2. API Operations: Always use the server-assigned Content UUID for API operations, regardless of whether an External UUID exists.

3. UUID Format: Both Content and External UUIDs should follow the v4 or v5 UUID format specifications.

This dual-identifier approach ensures system-wide uniqueness while providing flexibility for client-side document management and tracking.