OSCAL REST API Definition

This is 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.

The OSCAL REST OpenAPI Specification is expressed using OpenAPI 3.1.

For more information, vist and bookmark https://docs.oscal.io/docs/oscal-rest-openapi

Conventions and Organization

All endpoint syntax is provided as:

METHOD /{model-name} METHOD /{model-name}/{identifier} METHOD /{model-name}/{identifier}/snapshot METHOD /{model-name}/{identifier}/snapshot/{identifier} METHOD /{model-name}/{identifier}/attachment METHOD /{model-name}/{identifier}/attachment/{resource-uuid} METHOD /{model-name}/{identifier}/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

Profiles have additional endpoints related to profile resolution:

METHOD /profile/{identifier}/resolved-catalog METHOD /profile/{identifier}/resolved-snapshot METHOD /profile/{identifier}/resolved-snapshot/{identifier}

Known Issue: XML Expression

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.

There is a known-issue that prevents proper expression of OSCAL XML content in OpenAPI.

XML elements have both attributes and children. JSON elements only have children. There is no way to specify an element attribute using a JSON schema.

All versions of the OpenAPI specification, up to and including 3.1, only accept JSON schema definitions. As a result all OpenAPI viewers and code generators incorrectly represent OSCAL XML element attributes as element children.

Viewing / Editing

The proposed OSCAL REST OpenAPI specification is expressed using the OpenAPI 3.1 standard: RAW | VIEWER

Contributing and Feedback

If you have feedback, please consider one of the following options:

• Add a comment to an existing issue;
• If you don't see an appropriate existing issue, create a new issue; or
• send a message to us: oscal@oscal.io.

For the process of Contributing to the project, please review CONTRIBUTING.md and adhere to the Code of Conduct.

Licensing

For information on the project's license, please review the LICENSE file.