OSCAL: a shared format for publishing, implementing, and assessing security controls

The problem: control documentation that cannot be read by a machine

Security controls are described in prose, in tables, in PDFs, and in spreadsheets, and the same control can appear in a policy document, in an implementation record, and in an assessment report with three different structures. A tool cannot read any of that without a bespoke parser per document type. OSCAL is NIST's attempt to change that. It is a set of hierarchical XML, JSON, and YAML based formats that provide standardized representations of information pertaining to the publication, implementation, and assessment of security controls. The audience is security teams and, especially, the vendors building automation on top of them. NIST is explicitly seeking tool developers, vendors, and service providers who would like to implement the OSCAL models in commercial and open source offerings, and service providers willing to represent control implementation information about their products. That is the strategic bet: a common data model so that a scanner, a configuration management tool, and a GRC platform can exchange evidence without custom translation layers.

Hierarchical models with three serialisations of the same content

The structure is described as hierarchical, and each model is available in XML, JSON, and YAML. That triple matters more than it might first appear. XML suits enterprises with existing XML pipelines and government tooling, JSON suits web services and API-shaped integrations, and YAML suits configuration and source control review, where a diff of a control implementation record is meant to be human readable. Because the three are serialisations of the same model rather than separate designs, a tool can be written against one and a team can pick the form that fits their process. The repository layout shows how the models are built: a src directory, a build directory, a decisions directory that records design choices, a versioning-and-branching.md document, a USERS.md file, and a README_validations.md. The primary language of the repository is XSLT, which reflects that much of the tooling is transformation between the representations rather than runtime code.

Minimal formats, generic enough to be extended

The design intent is stated in the project documentation, and it is a constraint rather than a slogan. The effort stresses the agile development of a set of minimal formats that are both generic enough to capture the breadth of data in scope, meaning control specifications, while also capable of ad hoc tuning and extension to support the peculiarities of both industry or sector standards and new control types. The word minimal is doing real work there. A minimal model is one where an implementer can extend it for a sector specific control without forking the whole schema, and where the core stays small enough that two implementations can agree on the common part. The consequence for a tool author is that you should expect to write mapping code between the core model and whatever your customers' frameworks look like. OSCAL gives you the shared vocabulary for the parts everyone agrees on, and expects you to handle the rest yourself.

One project, five repositories, and where the content lives

The work is split across five repositories, and knowing which is which saves time. This repository is the main OSCAL project and contains the source code for the OSCAL models. OSCAL-Pages holds the public OSCAL website content. OSCAL-Reference holds the model documentation and developer reference content. OSCAL-Content holds examples of OSCAL model content. OSCAL-DEFINE is the project for managing research into the development and enhancement of OSCAL. The reference material is published as an XML and JSON schema reference on the OSCAL website, together with examples and other resources. For a team evaluating the project, OSCAL-Reference is where you learn the model and OSCAL-Content is where you see it populated. The OSCAL website also carries the schema reference and examples, so you can read the shape of the data before cloning anything.

Machine readable catalogs for the NIST publications you are assessed against

This is the part with immediate practical value. The NIST team maintains OSCAL content updated to the latest OSCAL revision, and the content repository provides the NIST SP 800-53 revision 5 catalog and the security and privacy NIST SP 800-53B baselines, the NIST SP 800-53 revision 4 catalog and the three revision 4 baselines which are preserved for historic purposes, the CSF v2.0 catalog, the NIST SP 800-171 revision 3 catalog, and the NIST SP 800-218 version 1 catalog. All of this content is provided in XML, JSON, and YAML. For anyone working with 800-53, that means the control text and the parameterised baselines arrive as data rather than as a PDF you have to parse. The revision 4 material is kept deliberately, which tells you something about how the project treats change: old revisions stay representable, because audit evidence refers to the catalogue that was in force at the time of the assessment.

Cloning the models, and the release cadence you would pin against

The repository is cloned with submodules, which matters because the models are not self contained:

git clone --recurse-submodules https://github.com/usnistgov/OSCAL.git

Releases are published on GitHub, and each release page provides a complete summary of the changes made in that release, with the changes based on feedback and contributions from the OSCAL community. The recent tagged versions are v1.2.3 on 2026-08-07, v1.2.2 on 2026-04-30, and v1.2.1 on 2026-03-06, so the project releases on a minor version cadence with several releases a year. The project status notes say future efforts will include providing a more complete set of documentation for all the OSCAL layers and models, creating more examples, and providing a diverse set of tutorials. That is an honest statement of what is not finished yet, and it is the main caveat for anyone planning an implementation: the model is more settled than the documentation and the example set around it.

Where OSCAL is the wrong choice, and how to plug in

The clearest limitation is scope. OSCAL models the NIST control world, so if your organisation is assessed against a framework it does not cover, you are outside the model and you will build an extension, which is exactly the maintenance burden the standard tries to remove. The second limitation is that OSCAL is a specification, not a tool. It gives you schemas and content, and it leaves collection, evaluation, gap analysis, and reporting to implementers. Adopting the formats without building or buying that pipeline produces well formed documents that nobody reads programmatically. The third is licensing. The licence recorded for this repository is a custom one that GitHub cannot classify, and the text lives in LICENSE.md, so if you intend to embed these schemas and catalogs in a commercial product, read that file yourself, and this is not legal advice. The upside is that the alternative is usually worse. A typical GRC team without OSCAL maintains control mappings in spreadsheets and re-implements parsers for each framework, which is the cost NIST set out to remove.

Editorial conclusion

OSCAL fits teams that already live in the NIST control world and want control catalogs, implementation records, and assessment results in a machine readable form instead of spreadsheets, particularly compliance engineers, GRC tooling vendors, and automation vendors building around the NIST ecosystem. It is the wrong tool if your controls live in a framework OSCAL does not model, or if you need a finished pipeline rather than a specification, because OSCAL defines the data model and leaves collection, evaluation, and reporting to implementers. Before adopting it, check the OSCAL content repository for a catalog matching the publication you are assessed against, read versioning-and-branching.md before pinning a version, and note that the repository licence is a custom one, so read LICENSE.md rather than assuming a standard open source licence.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. usnistgov/OSCAL on GitHub