Skip to content

Latest commit

 

History

History
78 lines (48 loc) · 3.68 KB

README.md

File metadata and controls

78 lines (48 loc) · 3.68 KB
Raw

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:

METHODS ENDPOINTS
GET, POST /{model-name}
GET, PUT, DELETE /{model-name}/{content-uuid}
GET, POST /{model-name}/{content-uuid}/attachment
GET, PUT, DELETE /{model-name}/{content-uuid}/attachment/{resource-uuid}
GET, POST /{model-name}/{content-uuid}/snapshot
GET, PUT, DELETE {model-name}/{content-uuid}/snapshot/{snapshot-uuid}

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:

METHODS ENDPOINTS
GET /profile/{content-uuid}/resolved-catalog
GET, POST /profile/{content-uuid}/resolved-snapshot
GET, PUT, DELETE /{model-name}/{content-uuid}/resolved-snapshot-uuid

Known Issue: XML Expression

There is a known OpenAPI issue that prevents proper definition of OSCAL XML schemas.

When the specification calls for OSCAL content to be accepted or returned, the content must be fully valid OSCAL per the NIST standard, even if the specification shows a non-compliant schema or example.

Additional Information

All versions of the OpenAPI specification only accept JSON schema definitions, and attempts to derive any XML schema from the JSON schema.

The issue is JSON elements only have children, while XML elements have both attributes and children. There is no way to specify an OSCAL XML element attributes using a JSON schema. 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:

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.