---
title: "Overview"
slug: "rest-overview"
updated: 2024-10-30T14:36:14Z
published: 2024-10-30T14:36:14Z
canonical: "docs.oscal.io/rest-overview"
---

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

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

| `METHOD /{model-name}` `METHOD /{model-name}/{content-uuid}` `METHOD /{model-name}/{content-uuid}/snapshot` `METHOD /{model-name}/{content-uuid}/snapshot/{snapshot-uuid}` `METHOD /{model-name}/{content-uuid}/attachment` `METHOD /{model-name}/{content-uuid}/attachment/{resource-uuid}` `METHOD /{model-name}/{content-uuid}/attachment/{resource-uuid}/resource` |
| --- |

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](/v1/docs/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](https://www.w3.org/TR/xmlschema11-2/#NCName), which is consistent with the [OSCAL token data type](https://pages.nist.gov/metaschema/specification/datatypes/#token). The identifier must also be unique within the server's scope of control. They *should* use [RFC-4122 compliant](https://datatracker.ietf.org/doc/html/rfc4122) v4 or v5 UUIDs, consistent with the [OSCAL UUID data type](https://pages.nist.gov/metaschema/specification/datatypes/#uuid).

#### Snapshot Identifiers

Similar to content identifiers, snapshot identifiers are [RFC-4122](https://datatracker.ietf.org/doc/html/rfc4122) 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"
    }
]
```