Concept of Operations (ConOps)
The OSCAL Class is designed to support any version of OSCAL and all published models. It is further designed to be used in air gapped environments where Internet connectivity may not be available.
The OSCAL_Support class creates and maintains a database that contains all of the NIST-published support files for all OSCAL versions and models. This is referred to in documentation as the OSCAL Support Module.
The OSCAL class is able to validate and convert any OSCAL version and module where the NIST-published support files are present in the OSCAL Support Model. No Internet connection required.
As NIST publishes additional models and OSCAL versions, they can be added to the OSCAL Support Module. An Internet connect is rquired to update the OSCAL Support Module; however, once updated, it can be copied to any computer for use.
OSCAL Class Initiation:
- Acquire Content
- Validate Content (automatic)
- Import Content (automatic)
Acquire content
Content is acquired by the instance in one of two ways:
- Passed Directly: When valid OSCAL XML, JSON or YAML content is passed directly via the
contentattribute. - Loaded from File or URL: When valid OSCAL XML, JSON, or YAML content is present in an accessible file specified via the
filenameattribute.
New OSCAL content may also be generated.
Validate Content
Once acquired, content is interogated as follows:
- Is the content a recognized OSCAL format (XML, JSON or YAML)?
- Is the content well formed in its native format?
- Does the content have a single
/*/metadata/oscal-versionfield? - Is the value in the
oscal-versionfield a supported* OSCAL version? - Is the root element a recognized OSCAL model-name for the specified
oscal-version? - Based on the OSCAL format, version and model, is the content OSCAL schema-valid**?
NOTES:
- The OSCAL Class has an OSCAL support module that contains the NIST-published OSCAL validation and conversion support files for each OSCAL version. The support module can “learn” newer versions of OSCAL as they are published.
- The appropriate XML schema is used for XML content. The appropriate JSON schema is used for JSON and YAML content.
OSCAL Class Inheritence
The class for each OSCAL model inherits the OSCAL class. All OSCAL common capabilities are defined here. This includes importing, format conversion and validation as well as metadata and back-matter interaction. Other common constructs such as properties and links are also handled in the core OSCAL module.
Model-specific classes are grouped by OSCAL layer and include both model-specific and layer-specific capabilities. For example, oscal_controls.py includes the Catalog, Profile and Mapping classes and all functions related to controls and control groups. It also includes profile resolution capabilites.
OSCAL Support Class ConOps
This module includes the OSCAL_support class and one stand-alone function. This class manages the NIST-published OSCAL support files (metaschema, schema, and converters) for supported OSCAL versions.
It is designed to exist as one class instance per for the entire application and to shared by each OSCAL instance; however, there should not be issues if this class is instantiated more than once.
JSON Native (Effective April 2026)
The OSCAL class uses JSON for processing of OSCAL Content internally.
Acquisition
Upon acquisition, OSCAL JSON and YAML are immediately converted to a Python dict.
JSON or YAML -> dict -> validation -> handle imports
Upon acquisition, OSCAL XML is initially converted to an ElementTree object, verified only as well-formed, then converted to dict equivalent to OSCAL JSON and validated.
XML -> ET -> -> converter -> dict (OSCAL JSON equivalent) -> validation -> handle imports
Exportation
All exports emit keys/elements in canonical NIST metaschema order (via oscal_resequence).
When exporting to OSCAL JSON or YAML, the Python dict is resequenced to canonical key order (best-effort — if no metaschema index is available it is emitted as-is) and serialized.
dict -> (resequence) -> JSON; or
dict -> (resequence) -> YAML
When exporting to OSCAL XML, the dict is converted to XML via the metaschema converter, which produces elements in the schema-required canonical order. The XML tree is transient: built on demand for serialization and released afterward.
dict -> converter -> XML
Metaschema Validation (Future)
For more complex metaschema validation requiring xPath 3.x processing, the dict is converted to XML, then converted to an ElemenetTree and processed using metaschema xPath (Metapath).
dict -> converter -> XML -> ET -> metaschema processing
This is only done when complete metaschema validation is triggered due to resource intensiveness.