OSCAL REST OpenAPI
- 16 Sep 2024
- 1 Minute to read
- Contributors
- Print
- DarkLight
OSCAL REST OpenAPI
- Updated on 16 Sep 2024
- 1 Minute to read
- Contributors
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
For Public Review and Feedback
An open-source REST API specification for exchanging 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 3.1 standard.
You can review the OSCAL REST OpenAPI specification in its raw JSON format or using an OpenAPI viewer. RAW | Cheat Sheet | VIEWER * * OpenAPI has 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;
- add comments to existing issue; or
- if no appropriate issue exists, create a new issue.
More Information
- Overview - START HERE!
- Primary Endpoints
- Attachment Management
- Snapshot Management
- Profile Resolution Management
- Format Specification
- Supporting Information
- Specification Viewer
- Scenarios
Known Issues: XML Representation
Due to known-issues, 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-idsis presented instead ofdocument-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.
Was this article helpful?