---
title: "Content Identifiers"
slug: "content-identifiers"
updated: 2026-03-23T14:23:07Z
published: 2026-03-23T14:23:07Z
canonical: "docs.oscal.io/content-identifiers"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oscal.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/EasyDynamics/oscal-rest/issues/102) of the OSCAL REST OpenAPI Specification [GitHub Repository](https://github.com/EasyDynamics/oscal-rest) and our team is looking for your [feedback](https://docs.oscal.io/docs/oscal-rest-openapi#feedback-is-welcome-and-encouraged)!

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](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.

          Content Identifier Summary

          

A Content UUID is a server-assigned identifier that uniquely identifies a document within the system. This identifier:

- Is automatically generated by the server for each new document
- Is immutable once assigned
- Must be used for all API operations (GET, PUT, DELETE) targeting a specific document
- Uses the scheme `http://oscal.io/oscal/identifier/contentuuid`

### 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.

          External Identifier Summary

          

An External Identifier is an optional client-assigned identifier that allows clients to maintain their own identification scheme. This identifier:

- Can be provided by clients when creating (POST) new documents
- Is preserved by the server but not used for API operations
- Allows clients to maintain consistent document identification across different systems
- Uses the scheme `http://oscal.io/oscal/identifier/externaluuid`

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

1. **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](https://datatracker.ietf.org/doc/html/rfc4122) or [v5](https://www.rfc-editor.org/rfc/rfc9562.html) UUID format specifications.

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