---
title: "OSCAL REST OpenAPI"
slug: "oscal-rest-openapi"
updated: 2024-11-16T17:32:12Z
published: 2024-11-16T17:32:12Z
canonical: "docs.oscal.io/oscal-rest-openapi"
---

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

# OSCAL REST OpenAPI

## For Public Review and Feedback

An open-source REST API specification for exchanging [OSCAL](https://pages.nist.gov/OSCAL/) content between tools and organizations.

The OSCAL REST OpenAPI Specification addresses OSCAL XML, JSON and YAML content for all seven OSCAL models. 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 also have methods and endpoints for live profile resolution and snapshots of resolved profiles.

## OpenAPI Specification

The OSCAL REST OpenAPI specification is expressed using the [OpenAPI](https://spec.openapis.org/oas/latest.html) 3.1 standard.

| You can review the OSCAL REST OpenAPI specification in its raw JSON format or using an OpenAPI viewer. [RAW](https://raw.githubusercontent.com/EasyDynamics/oscal-rest/develop/OSCALRestOpenAPI.json) \| [Cheat Sheet](https://cdn.document360.io/fcf0031a-ef98-4389-b56d-d2beba546bdd/Images/Documentation/OSCAL_REST_OpenAPI_Cheat_Sheet_v2%281%29.pdf?sv=2026-02-06&spr=https&st=2026-11-02T09%3A44%3A10Z&se=2026-11-02T10%3A44%3A10Z&sr=c&sp=r&sig=IyEQb5aHwU4Mno1q6v3DlHbFj5dNL4xhAHnIFYe24Oc%3D) \| [VIEWER *](/v1/docs/openapi-specification-viewer) * OpenAPI has [known issues](/docs/oscal-rest-openapi#known-issues) representing XML. See the bottom of this page for more detail. |
| --- |

### Feedback is welcome and encouraged!

Please consider one of the following mechanisms to provide feedback or request a change:

- send an email to [oscal@oscal.io](mailto:oscal@oscal.io);
- add comments to [existing issue](https://github.com/EasyDynamics/oscal-rest/issues); or
- if no appropriate issue exists, [create a new issue](https://github.com/EasyDynamics/oscal-services/issues/new/choose).

---

## More Information

- [Overview](/v1/docs/rest-overview) - START HERE!
- [Content Identifiers](/v1/docs/content-identifiers)
- [Primary Endpoints](/v1/docs/primary-endpoints)
- [Attachment Management](/v1/docs/attachment-management)
- [Snapshot Management](/v1/docs/snapshot-endpoints)
- [Profile Resolution Management](/v1/docs/profile-resolution-management)
- [Format Specification](/v1/docs/format-specification)
- [Supporting Information](/v1/docs/supporting-information)
- [Specification Viewer](/v1/docs/openapi-specification-viewer)
- [Scenarios](/v1/docs/scenarios)

### Known Issues: XML Representation

 
 

Due to [known-issues](https://github.com/OAI/OpenAPI-Specification/issues/630), OpenAPI is unable to accurately represent XML. As a result, OpenAPI viewers do not present OSCAL XML schemas and examples correctly.

 

When the OSCAL REST OpenAPI Specification calls for OSCAL content to be accepted or returned, the content must always be fully schema-valid to the NIST OSCAL XML specification. Even if the OpenAPI specification shows a invalid schema or example.

---

 What to Expect:
    

- XML node attributes are incorrectly presented as child nodes.
- Some OpenAPI viewers show an incorrect XML root element or incorrectly wrap the OSCAL XML content in an additional tag.
- OpenAPI viewers incorrectly use the JSON/YAML plural version of OSCAL key words instead of the singular version that appears in the OSCAL XML syntax. (Example: metadata `document-ids` is presented instead of `document-id`)

These issues exist in all versions of the OpenAPI specification to date. As a result all OpenAPI viewers and code generators incorrectly represent OSCAL XML content.