Content Identifiers

Content Identifiers in OSCAL REST API

The OSCAL REST API implements a dual-identifier system to balance the needs of both server-side uniqueness and client-side document tracking. The issue, with details for determination of this approach can be found on the 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 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/contentuuid. If the content identifier is present and v4 or v5 UUID compliant, the implementation must use this value as the contentuuid.

If the content identifier is not present, the implementation must generate a v4 or v5 UUID for use as the contentuuid and insert it into document ID array using http://oscal.io/oscal/identifier/contentuuid 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.

External Identifier

An external Identifier (externaluuid) is an optional identifier used by the client for preserving API operations. This identifier is preserved between operations, enabling life cycle management of documents between a client and an implementation of the API.

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

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.