OSCAL Class
A class for creation, management, validation, and format conversion of OSCAL content. All published OSCAL versions, formats, and models can be validated and converted. Creation and management targets OSCAL 1.2.1 and later.
OSCAL XML, JSON, and YAML formats are fully supported. XML is immediately converted to the internal JSON-native representation on load; XML output is produced on demand.
Model Classes
Eight model classes inherit from the base OSCAL class:
from oscal import (
OSCAL, # base class — use when model is unknown
Catalog,
Profile,
Mapping, # mapping-collection model
ComponentDefinition,
SSP,
AssessmentPlan,
AssessmentResults,
POAM,
)
All factory methods (load, loads, acquire, new) are available on every class.
Use a model-specific class when you know the model in advance; use OSCAL when you
don’t. The model attribute identifies the detected model after loading.
Factory Methods
Never instantiate model classes directly — always use one of these class methods.
loads — in-memory content
Use when you already have OSCAL content in memory (string or dict).
from oscal import Catalog
catalog_dict = {
"catalog": {
"uuid": "11111111-1111-1111-1111-111111111111",
"metadata": {
"title": "In-Memory Catalog",
"version": "0.1.0",
"oscal-version": "1.1.3",
},
"groups": [],
}
}
catalog = Catalog.loads(catalog_dict, href="memory://catalog")
href is optional and serves as a label identifying the content’s origin.
content may be a JSON/YAML str or a dict.
load — local file or file-like object
Use to read from a path on the local filesystem, or any file-like object with .read().
from oscal import Catalog
catalog = Catalog.load("./catalog.xml") # path string
catalog = Catalog.load(Path("./catalog.xml")) # pathlib.Path
catalog = Catalog.load(open("catalog.json")) # file-like object
The loaded content is read-only by default for file objects; it is set to read-write for plain path strings (local paths you own).
acquire — URI / reference resolution
Use for content that must be fetched by URI, or when you want to supply a fallback
source list. Accepts a URI string, a reference dict, an OscalRef, or a list of any
of these.
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 (same shape as back-matter rlinks)
doc = OSCAL.acquire({"href": "https://example.com/catalog.xml"})
# Fallback list — first successful source wins
doc = OSCAL.acquire([
"https://example.com/catalog.xml",
{"href": "./local-fallback/catalog.xml"},
])
new — create from template
Use to create a fresh OSCAL document from the built-in template for a specific model.
Must be called on a model subclass, not on OSCAL directly.
from oscal import Catalog, Profile
catalog = Catalog.new(
title="My New Catalog",
version="DRAFT-1.0",
published="2026-04-26T00:00:00Z",
)
profile = Profile.new(title="My New Profile")
Model-Aware Loading
When the model is not known in advance, load with OSCAL first, then dispatch:
from oscal import OSCAL, Catalog, Profile, Mapping, ComponentDefinition, SSP
from oscal import AssessmentPlan, AssessmentResults, POAM
MODEL_CLASS_MAP = {
"catalog": Catalog,
"profile": Profile,
"mapping-collection": Mapping,
"component-definition": ComponentDefinition,
"system-security-plan": SSP,
"assessment-plan": AssessmentPlan,
"assessment-results": AssessmentResults,
"plan-of-action-and-milestones": POAM,
}
def load_typed(path: str):
"""Return the most specific model class for the content at path."""
generic = OSCAL.load(path)
cls = MODEL_CLASS_MAP.get(generic.model)
return cls.load(path) if cls else generic
obj = load_typed("./example/catalog.xml")
print(type(obj).__name__) # Catalog
print(obj.model) # catalog
Content States
content_state / ContentState
A progressive enum that tracks how far through the validation pipeline the content has progressed. Each level implies all prior levels passed.
class ContentState(IntEnum):
NONE = -1 # No content / uninitialized
NOT_AVAILABLE = 0 # Unable to acquire content
ACQUIRED = 1 # Content was acquired (non-empty string)
WELL_FORMED = 2 # Content is well-formed XML, JSON, or YAML
VALID = 3 # Content passes OSCAL schema validation
IMPORTS_RESOLVED = 4 # All imported OSCAL documents resolved successfully
Boolean properties are provided for the most common checks:
| Property | True when |
|---|---|
.is_acquired |
content_state >= ACQUIRED |
.is_well_formed |
content_state >= WELL_FORMED |
.is_minimally_valid |
well-formed and no structural errors (missing-required / cardinality / choice) |
.is_valid |
L2 validity — all phases pass with native checks (content_state >= VALID) |
.is_fully_compliant |
L3 tri-state (bool \| None): False when not is_valid; None until validate_full() runs; then True/False |
.imports_resolved |
content_state >= IMPORTS_RESOLVED |
Validation is three-tiered: .is_minimally_valid (structural soundness) is the
operational bar — tree building and import resolution gate on it; .is_valid (L2)
adds the natively-evaluable value-quality phases (data types, native allowed-values) and
is designed to meet or exceed the OSCAL JSON Schema; .is_fully_compliant (L3) adds
the ancestor/cross-path-scoped constraints and the other rule families, evaluated against
XML by validate_full(). See Tiered Validation.
__bool__ returns True when is_valid is True, so objects can be used directly
in conditionals:
catalog = Catalog.load("catalog.xml")
if catalog:
print(catalog.title) # safe to access
else:
print("Load failed")
validation_status and validation_errors
After loading, validation_status records per-phase results and validation_errors
holds structured error dicts from the most recent validate() call:
print(catalog.validation_status)
# {
# "well-formed": True,
# "structure": True,
# "data-types": True,
# "allowed-values": False,
# "cardinality": True,
# }
for err in catalog.validation_errors:
# Every error is normalized to: error-type, location (JSON path), identifier
# (uuid/id of the nearest enclosing identifiable object, or None), field, value,
# plus error-type-specific detail (expected / min / max).
print(err["error-type"], err["location"], err["identifier"], err["value"])
validation_status reflects L2 validation (the allowed-values phase covers only
natively-evaluable constraints; scoped ones are deferred to validate_full). A document
can therefore have is_valid == False while still being minimally valid (structurally
sound) — e.g. the allowed-values phase above is False but structure/cardinality/choice
all pass. In that state validate() still builds summary trees and resolves imports
(import_list is populated), because those gate on minimal validity, not L2 validity. Use
import_blocking_errors to see what, if anything, is structural. See
Tiered Validation for the full error-type reference, the
minimal-vs-full tiers, and the block/allow rationale.
validate() — re-run validation
Call to re-validate after mutating content:
catalog.set_metadata({"title": "Updated Title"})
catalog.validate()
version_support / VersionSupport
A non-progressive qualifier (separate from content_state) recording how the content’s
declared OSCAL version was resolved against available support. When the declared version
isn’t in the local support database the library tries to acquire it (bundled DB, then
NIST) or substitutes the closest same-major version — see
SUPPORT_MODULE.md.
class VersionSupport(Enum):
EXACT = "exact" # declared version's support was available/acquired
CLOSEST_MATCH = "closest-match" # substituted the closest same-major version
UNSUPPORTED = "unsupported" # unavailable; content cannot pass WELL_FORMED
| Attribute | Meaning |
|---|---|
.version_support |
VersionSupport (defaults to EXACT) |
.requested_oscal_version |
The version the content declares (e.g. "v1.2.3") |
.resolved_oscal_version |
The version whose support was used (differs only for CLOSEST_MATCH) |
UNSUPPORTED leaves content_state at ACQUIRED (it never reaches WELL_FORMED).
Origin and Mutability States
| Property | Type | Description |
|---|---|---|
.is_local |
bool |
True for local file source, False for remote |
.is_remote |
bool |
Inverse of is_local |
.is_cached |
bool |
True when remote content has a local cache copy |
.is_read_only |
bool |
True when the content must not be mutated |
.is_unsaved |
bool |
True when mutations have not been written to disk |
.is_editable |
bool |
True when is_valid (L2 validity), is_local, and not is_read_only |
.is_fresh |
bool |
True when content is local or cached within its TTL |
.is_stale |
bool |
True when remote cached content has exceeded its TTL |
.origin_state |
OriginState |
LOCAL, REMOTE_UNCACHED, REMOTE_FRESH, or REMOTE_STALE |
.loaded |
datetime |
Timestamp of when content was acquired |
.ttl |
int |
Cache time-to-live in seconds (0 = never expire) |
is_editable vs. the mutation guard (_can_mutate)
Two related but distinct gates govern changes, and the difference matters:
_can_mutate(the enforcement gate). Every mutation method calls this internally before touching content and aborts if it returnsFalse. It is the minimum technical precondition for a change to proceed: the content is loaded (_dictis notNone) and not read-only. It does not require full validity or a local source.is_editable(an advisory signal). A stricter, public property for deciding whether to offer general editing (e.g. enabling an editor): it requires L2 validity (is_valid) andis_localand not read-only. It is not consulted by the mutation methods themselves.
Because mutation gates on _can_mutate, a document can be mutated while is_editable is
False — for example content that is only minimally valid (structurally sound but
with allowed-values / invalid-type issues), or content loaded from a remote source.
Convention (guidance, not enforced). When
_can_mutateisTruebutis_editableisFalse, mutations should be limited to resolving the issues that are blocking L2 validity — i.e. remediation towardis_valid— rather than general authoring. The library does not enforce this restriction; it is the caller’s responsibility to honor it. Once the document reaches L2 validity (and is local, not read-only),is_editablebecomesTrueand unrestricted editing is appropriate.
See Tiered Validation for the minimal-vs-full validity tiers.
Content Summary Attributes
These are populated after a successful load:
| Attribute | Description |
|---|---|
.model |
OSCAL model name (e.g. "catalog", "system-security-plan") |
.oscal_version |
OSCAL version from the content metadata (e.g. "v1.1.3") |
.title |
Document title from metadata |
.version |
Document version from metadata |
.published |
Publication date from metadata |
.last_modified |
Last-modified date from metadata |
.remarks |
Remarks from metadata |
.original_format |
Format the content was loaded from ("xml", "json", "yaml") |
.href |
Working href (may differ from href_original after redirect/retry) |
.href_original |
Original href as provided at load time |
Serialization
dump — write to file
# Save to a specific 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", pretty_print=True)
# Save to the original location in the original format
catalog.dump()
Returns True on success. If filename or format are omitted, dump() falls back
to the original source location and format.
dumps — serialize to string
json_str = catalog.dumps(format="json", pretty_print=True)
xml_str = catalog.dumps(format="xml", pretty_print=True)
yaml_str = catalog.dumps(format="yaml")
Canonical key/element ordering
All serialization (dump, dumps, and the json/xml/yaml properties) emits
keys/elements in the canonical NIST metaschema order (see
oscal_resequence):
- XML — element order is schema-significant, so it is always produced in canonical order. XML is (re)built from the current dict via the metaschema converter on each serialization, so the output reflects the latest edits.
- JSON/YAML — keys are ordered canonically on a best-effort basis. Key order in JSON/YAML is presentational, so if no metaschema index is available for the model/version the document is still emitted (in its current order) rather than failing.
Convenience properties
catalog.json # → JSON string (always pretty-printed, canonical key order)
catalog.xml # → XML string (rebuilt from dict; canonical element order)
catalog.yaml # → YAML string (always pretty-printed, canonical key order)
Querying Content
Two complementary path-based query methods work on the internal JSON representation. Both return Python lists. See QUERY_CONTENT.md for the full path syntax reference.
| Method | Step names | Notes |
|---|---|---|
query(path) / query_one(path) |
OSCAL XML element names (control, prop, part) |
Requires metaschema index |
json_query(path) / json_query_one(path) |
JSON key names (controls, props, parts) |
No index required |
# query() — XML element name syntax
ctrl = catalog.query_one('//control[@id="ac-2"]')
title = catalog.query_one('/*/metadata/title')
# json_query() — JSON key name syntax
ctrl = catalog.json_query_one('//controls[id="ac-2"]')
title = catalog.json_query_one('/*/metadata/title')
# Both accept an optional context dict to scope the search
parts = catalog.query('part[@name="statement"]', context=ctrl)
query_one and json_query_one return the first match or None (accepts an optional
default argument).
Safe-copy ownership. Public getters and query methods return detached copies, never live references into the internal
_dict— this includes query results and the node getters (get_control_by_id,get_group_by_id,get_control_list, andProfile.control). Mutating a returned value does not change the document; all mutation must go through the mutation methods below (which enforce the OSCAL standard). The private_dictattribute is the only sanctioned live-access escape hatch. The node getters also take an optionaldepthargument that prunes nested child groups/controls (None= full subtree,0= node only,N= N levels).
Mutating Content
All mutation methods require is_editable to be True (content is valid, local, and
not read-only). They return None and log an error when the guard fails. Methods that
return the created node return a safe copy of it — edit further via another method
call, not by mutating the return value.
Revision stamping. The OSCAL root
uuididentifies a specific instance of a document, so the library assigns a fresh rootuuidandmetadata/last-modifiedon every mutation — and on.new(), so a new document never carries the packaged stub template’s placeholder uuid. If a mutation explicitly setsuuidorlast-modified(e.g.set_metadata({"last-modified": ...})orput("uuid", ...)), that explicit value is honored instead of the auto-stamp.is_unsavedbecomesTrue.
set_metadata
Set scalar metadata fields:
catalog.set_metadata({
"title": "Updated Catalog",
"version": "1.1.0",
})
Complex metadata fields (roles, parties, locations, etc.) are not yet supported
and will log a warning if passed.
append_child
Append a dict to any list within the document:
catalog.append_child("back-matter/resources", {
"uuid": "aaaaaaaa-0000-4000-a000-000000000001",
"title": "My Reference",
"rlinks": [{"href": "https://example.com/ref.html"}],
})
The path is slash-separated, relative to the model root. The leaf key is created as an empty list if it does not yet exist.
append_resource
Convenience wrapper for adding back-matter resources:
catalog.append_resource(
title="NIST SP 800-53 Rev 5",
rlinks=[{"href": "catalogs/nist-800-53-rev5.xml"}],
)
update_resource(uuid, *, title=None, description=None, props=None, rlinks=None, remarks=None)
Update fields of an existing local back-matter resource (found by uuid). Each field is
optional: None leaves it unchanged, a scalar replaces it (empty string removes it), and
an array replaces the existing list wholesale ([] clears it). Returns a safe copy of
the updated resource, or None.
Warning — array replacement is total, not a merge. Whatever you pass for
props/rlinksbecomes the complete new list; entries you omit are permanently dropped (a resource may carry rlinks/hashes/props you didn’t author). Read the current resource withget_resource_by_uuid(uuid)first, edit that copy, then pass the full arrays back.
res = catalog.get_resource_by_uuid(uuid)
res["rlinks"].append({"href": "catalog.json", "media-type": "application/json"})
catalog.update_resource(uuid, rlinks=res["rlinks"]) # full list, nothing dropped
Import Handling
Imports are resolved automatically once content is minimally valid (structurally
sound — no blocking errors); full validity is not required. Results are available via
import_list. See IMPORTS.md and Tiered Validation for
full details.
import_list
Flat list of dicts, one per import statement found in the document:
{
"href_original": "<href as written in the document>",
"href_valid": "<resolved href that loaded successfully>",
"status": ImportState.READY, # READY | NOT_LOADED | INVALID | EXPIRED
"is_valid": True,
"is_local": False,
"is_remote": True,
"is_cached": False,
"object": <OSCAL object or None>,
"failure": None, # ImportFailure instance on failure
}
import_tree
Lazily-built recursive tree of the full import chain. Returns a root node dict with an
"imports" key holding the same structure recursively. Rebuilt on first access after
any change; call rebuild_import_tree() to force a fresh traversal.
failed_imports
Returns only the entries from import_list that have a non-None failure field:
for entry in doc.failed_imports:
f = entry["failure"]
print(f"[{f.code.value}] {entry['href_original']} — {f.message}")
resolve_imports(base_path="")
Re-runs import discovery and loading. Called automatically on valid content; call
manually to force a fresh pass or after calling retry_import.
retry_import(failed_href, replacement_href)
Retry a single failed import using an alternate source:
doc.retry_import(
failed_href="https://old-server.example.com/catalog.xml",
replacement_href="./local-catalog.xml",
)
walk_imports(visitor_fn, scope="successful")
Depth-first walk of the import tree. visitor_fn(entry, depth) is called for each
entry. scope is "successful" (default), "failed", or "all".
Modifying a document’s own imports
add_import / remove_import / update_import operate only on this document’s
first-level import statement(s), never on descendants. Each refreshes the import tree and
any derived state (e.g. a Profile’s controls_tree / resolved catalog, or a
ComponentDefinition’s / SSP’s implementation_tree). Legality is enforced per
model’s import cardinality:
| Model | Import | add / remove | update_import |
|---|---|---|---|
| catalog, mapping-collection | none | invalid | invalid |
| system-security-plan, assessment-plan, assessment-results | exactly 1 | invalid | ✓ (the way to change it) |
| plan-of-action-and-milestones | 0..1 | ✓ | ✓ |
| profile | 1..∞ | add ✓; remove ✓ (not the last) | invalid — use add/remove |
| component-definition | 0..∞ | ✓ | invalid — use add/remove |
add_import(href, uuid="", title="", description="", props=[], version="", remarks="", *, include_all=False) → ImportResult— adds an import backed by a back-matter resource (reusing an existing resource whoserlinktargetshref, else creating one viaappend_resource;versionis stored as aversionprop). Profile imports get an emptyinclude-controls/with-idsplaceholder (orinclude-allwheninclude_all=True). Returns anImportResult(status"added"/"replaced"/"duplicate"/"invalid"/"error";.ok/.is_invalid).remove_import(href) → bool— removes a first-level import (matched by literal href,#uuidfragment, or resolved target). Refused when it would drop below the model’s minimum. Back-matter resources are preserved.update_import(*, title=None, description=None, props=None, rlinks=None, remarks=None, new_resource=True) → ImportResult— for the single-import models (SSP/AP/AR/POA&M), changes the one import. Takes the same resource fields asupdate_resource. When the import references a#uuid,new_resource=True(default) points it at a new resource (preserving the old one, which other content may reference);new_resource=Falseedits the existing resource in place.
To change a profile or component-definition import, remove_import then add_import.
Use retry_import (below) to repair an import that failed to load.
Deprecated / Legacy Methods
The following methods exist for backward compatibility but are not the preferred API. They may be removed in a future major release.
open(source, *, href=None)
A universal constructor that inspects the source type and delegates to load() or
acquire(). Prefer using load() or acquire() directly, which are more explicit
about their behaviour:
open() routes to… |
When source is… |
|---|---|
load() |
A str path (no URI scheme), pathlib.Path, or file-like object |
acquire() |
A URI string with a scheme (http://, file://, etc.), OscalRef, dict, or list |
# Legacy — avoid in new code
obj = OSCAL.open("catalog.xml") # delegates to load()
obj = OSCAL.open("https://example.com/…") # delegates to acquire()
# Preferred equivalents
obj = OSCAL.load("catalog.xml")
obj = OSCAL.acquire("https://example.com/…")
from_string(content, *, href=None)
An explicit alias for loads(). Use loads() directly:
# Legacy
obj = OSCAL.from_string(json_str)
# Preferred
obj = OSCAL.loads(json_str)
retry_imports(failed_href, replacement_href)
Plural alias for retry_import(). Use retry_import() directly.