• Beta
    OSCAL REST OpenAPI
    • 16 Sep 2024
    • 1 Minute to read
    • Contributors
    • Dark
      Light

    OSCAL REST OpenAPI

    • Dark
      Light

    Article summary

    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:


    More Information

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


    Was this article helpful?

    What's Next
    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.
    ESC

    Eddy AI, facilitating knowledge discovery through conversational intelligence