Getting Started

The oscal library simplifies working with OSCAL content while providing fine-grained control when you need it. It handles loading, validation, format conversion, and content manipulation for all published OSCAL versions and models.


Installation

pip install oscal

Or add to pyproject.toml / requirements.txt:

oscal

For the latest unreleased code from the development branch:

git+https://github.com/brian-ruf/oscal-class.git@develop#egg=oscal

Importing

from oscal import (
    OSCAL,               # base class — use when model is unknown
    Catalog,
    Profile,
    Mapping,             # mapping-collection model
    ComponentDefinition,
    SSP,
    AssessmentPlan,
    AssessmentResults,
    POAM,
)

Loading Content

Three factory methods cover every loading scenario. Never instantiate model classes directly — always use one of these.

load — from a local file

from oscal import Catalog

catalog = Catalog.load("./catalog.xml")

Accepts a path string, pathlib.Path, or any file-like object with .read(). XML, JSON, and YAML are all supported; the format is detected automatically.

loads — from in-memory content

from oscal import Catalog

json_str = '{"catalog": {"uuid": "...", "metadata": {...}}}'
catalog  = Catalog.loads(json_str, href="memory://my-catalog")

# Also accepts a dict directly
catalog = Catalog.loads(catalog_dict)

href is optional and serves as a label for the source location.

acquire — by URI or reference

from oscal import OSCAL

# Remote URL
doc = OSCAL.acquire("https://raw.githubusercontent.com/.../catalog.json")

# Local file as a URI
doc = OSCAL.acquire("file:///data/oscal/catalog.xml")

# Reference dict (mirrors the OSCAL back-matter rlink shape)
doc = OSCAL.acquire({"href": "./catalog.xml"})

# Fallback list — first successful source wins
doc = OSCAL.acquire([
    "https://primary.example.com/catalog.xml",
    "./local-fallback/catalog.xml",
])

new — create from a template

Must be called on a specific model class, not on OSCAL directly.

from oscal import Catalog

catalog = Catalog.new(
    title="My Control Catalog",
    version="1.0.0",
    published="2026-06-01T00:00:00Z",
)

Checking the Load Result

All factory methods return an object even when loading fails — check the state before using the content. The object is truthy when content is valid:

catalog = Catalog.load("./catalog.xml")

if not catalog:
    print(f"Load failed. Content state: {catalog.content_state.name}")
else:
    print(f"Loaded: {catalog.title} ({catalog.model} {catalog.oscal_version})")

For finer-grained checks:

Property True when
catalog.is_acquired Content was retrieved (non-empty)
catalog.is_well_formed Content parsed successfully
catalog.is_minimally_valid Structurally sound (the bar for tree building & imports)
catalog.is_valid Passed L2 validation (structure + native value-quality; meets/exceeds the OSCAL JSON Schema)
catalog.is_fully_compliant L3 tri-state (None until validate_full() runs) — full metaschema conformance
catalog.imports_resolved All imported documents loaded

See Tiered Validation for the minimal / L2 / L3 tiers.

Inspecting validation errors

if not catalog.is_valid:
    print(catalog.validation_status)
    # {
    #   "well-formed":    True,
    #   "structure":      True,
    #   "data-types":     True,
    #   "allowed-values": False,
    #   "cardinality":    True,
    # }

    for err in catalog.validation_errors:
        print(err["error-type"], err["location"], err["field"], err["value"])

When the Model is Unknown

Use the base OSCAL class to load content of unknown model, then dispatch to the typed class:

from oscal import OSCAL, Catalog, Profile, SSP
# ... (import all model classes)

MODEL_CLASS_MAP = {
    "catalog":                       Catalog,
    "profile":                       Profile,
    "system-security-plan":          SSP,
    # ... add remaining models
}

def load_typed(path: str):
    generic = OSCAL.load(path)
    cls = MODEL_CLASS_MAP.get(generic.model)
    return cls.load(path) if cls else generic

doc = load_typed("./unknown-document.xml")
print(type(doc).__name__, doc.model)

Saving Content

dump — to a file

# Explicit path and format
catalog.dump("catalog.json", format="json", pretty_print=True)
catalog.dump("catalog.xml",  format="xml",  pretty_print=True)
catalog.dump("catalog.yaml", format="yaml")

# No arguments — saves to the original path in the original format
catalog.dump()

Conversion between formats happens automatically; no additional setup is required.

dumps — to a string

json_str = catalog.dumps(format="json", pretty_print=True)
xml_str  = catalog.dumps(format="xml")
yaml_str = catalog.dumps(format="yaml")

Convenience properties

catalog.json   # → JSON string
catalog.xml    # → XML string
catalog.yaml   # → YAML string

Querying Content

Two path-based query methods work on the internal JSON representation. Both return Python lists.

# query() — uses OSCAL XML element names (control, prop, part, ...)
ctrl  = catalog.query_one('//control[@id="ac-2"]')
title = catalog.query_one('/*/metadata/title')
props = catalog.query('//control[@id="ac-2"]/prop[@name="label"]')

# json_query() — uses JSON key names (controls, props, parts, ...)
ctrl  = catalog.json_query_one('//controls[id="ac-2"]')
title = catalog.json_query_one('/*/metadata/title')

query_one / json_query_one return the first match or None. See QUERY_CONTENT.md for the full path syntax.


Mutating Content

Content loaded from a local path is read-write by default. Content loaded remotely or from file-like objects is read-only.

if catalog.is_editable:
    catalog.set_metadata({"title": "Updated Title", "version": "1.1.0"})
    catalog.dump()   # save back to the original file

Getters and mutator returns are safe copies. Read accessors (e.g. get_control_by_id, get_group_by_id, query methods) and creation/mutation methods (create_control, create_control_group, add_part, set_title, set_label, …) all return a detached copy of the affected node. Editing that copy does not change the document — make persistent changes by calling another mutation method. The private _dict attribute is the only live-access hatch.

See CONTENT.md for append_child, append_resource, and other mutation methods.


End-to-End Example

from oscal import Catalog

# 1. Create a new catalog
catalog = Catalog.new("Quick Start Catalog", version="1.0.0")

# 2. Add a control group and controls (Catalog-specific methods)
catalog.create_control_group(
    parent_id="",
    id="ac",
    title="Access Control",
    props=[{"name": "label", "value": "AC"}],
)
catalog.create_control(
    parent_id="ac",
    id="ac-1",
    title="Access Control Policy",
    props=[{"name": "label", "value": "AC-1"}],
    statements=["Develop and disseminate an access control policy."],
)

# 3. Save to multiple formats
catalog.dump("my-catalog.json", format="json", pretty_print=True)
catalog.dump("my-catalog.xml",  format="xml",  pretty_print=True)

# 4. Load back and verify
loaded = Catalog.load("my-catalog.json")
print(loaded.title)          # "Quick Start Catalog"
print(loaded.is_valid)       # True

# 5. Query content
ctrl = loaded.query_one('//control[@id="ac-1"]')
print(ctrl["title"])         # "Access Control Policy"

Further Reading

Document Contents
CONTENT.md Complete class API: all factory methods, states, properties, mutation, and import handling
QUERY_CONTENT.md Full path syntax for query() and json_query()
IMPORTS.md Import resolution, failure codes, and retry patterns
CONVERTERS.md Format conversion internals (OSCALConverter)
SUPPORT_MODULE.md Support database: configuration, updating, and API
LOGGING.md Enabling Loguru logging within the library