Import Resolution
OSCAL documents reference other documents through import statements. A profile imports one or more catalogs; an SSP imports a profile; an assessment plan imports an SSP; and so on. The library resolves those references automatically when a document is loaded, and exposes the results through import_list and import_tree.
How imports are resolved
Whenever content is minimally valid — structurally sound, i.e. no blocking (structural) validation errors — the library calls resolve_imports() automatically. Full OSCAL validity is not required: a document whose only problems are value-quality (allowed-values / invalid-type) still resolves its imports. You can also call resolve_imports() manually at any time to force a fresh pass. See Tiered Validation for the minimal-vs-full distinction and the blocking/non-blocking error split.
Likewise, an imported document is accepted as a usable import (status READY) when it is minimally valid — so a published catalog or profile with deep allowed-values noise is still importable.
from oscal import OSCAL
ssp = OSCAL.load("my-ssp.xml")
# import_list is already populated after load
for entry in ssp.import_list:
print(entry["href_original"], entry["status"])
Import href forms
Every import statement carries an href attribute that is either a URI fragment or a full URI.
URI fragment (#uuid)
A fragment-only href like #051a77c1-b61d-4995-8275-dacfe688d510 refers to a resource in the document’s own back-matter section by UUID. The library looks up the resource, then attempts to load the content from each rlink in sequence.
<import href="#051a77c1-b61d-4995-8275-dacfe688d510"/>
<back-matter>
<resource uuid="051a77c1-b61d-4995-8275-dacfe688d510">
<title>NIST SP 800-53 Rev 5</title>
<description><p>NIST control catalog</p></description>
<rlink href="catalogs/nist-800-53-rev5.xml"/>
<rlink href="catalogs/nist-800-53-rev5.json"/>
</resource>
</back-matter>
rlinks are tried in document order. The library also automatically tries alternate OSCAL format extensions (.xml, .json, .yaml, .yml) for each rlink before moving to the next one.
Full URI
Any href that is not a bare fragment is treated as a URI pointing directly to the content.
<!-- Relative local path -->
<import href="catalogs/nist-800-53-rev5.xml"/>
<!-- Absolute local path -->
<import href="/data/oscal/catalogs/nist-800-53-rev5.xml"/>
<!-- Remote URL -->
<import href="https://raw.githubusercontent.com/usnistgov/oscal-content/main/.../catalog.json"/>
<!-- file:// URI -->
<import href="file:///data/oscal/catalogs/nist-800-53-rev5.xml"/>
Relative paths are resolved against the directory that contains the importing document (or the current working directory when content was loaded from memory).
Import entry structure
import_list is a flat list of dicts, one per import statement. Successful and failed entries share the same keys:
| Key | Type | Description |
|---|---|---|
href_original |
str |
The raw href from the import statement |
href_valid |
str |
The resolved href that successfully loaded (empty on failure) |
status |
ImportState |
READY, NOT_LOADED, INVALID, or EXPIRED |
is_valid |
bool |
True when the loaded import is usable — i.e. at least minimally valid (structurally sound). It does not require full OSCAL validity; value-quality issues (allowed-values / invalid-type) do not prevent an import from being READY. |
is_local |
bool \| None |
True for local file, False for remote |
is_remote |
bool \| None |
Inverse of is_local |
is_cached |
bool |
True when remote content has a local cache copy |
object |
OSCAL \| None |
The loaded OSCAL document (populated on success) |
failure |
ImportFailure \| None |
Failure detail (populated on failure; None on success) |
import_list is the internal source of truth and is the ONLY place the live
object is exposed. The import_tree and the failed_imports /
duplicate_imports / unresolved_imports getters return safe copies that
carry object_uuid instead of the live object (see below).
import_tree structure
import_tree is a recursive, wire-safe view of the import hierarchy. It is a
deep copy of an internally cached structure — mutating the returned tree does
not affect the document; call rebuild_import_tree() to force a fresh traversal.
The tree carries no live OSCAL objects (keeping large documents out of the
payload). Each node — the root and every import — has the import_list fields
above except object, plus:
| Key | Type | Description |
|---|---|---|
object_uuid |
str \| None |
The document’s root UUID, or None when not acquired. Pass to get_oscal_object() for the live object. |
model |
str |
Model type (e.g. "catalog") — "" when not acquired |
title |
str |
Metadata title — "" when not acquired |
oscal_version |
str |
OSCAL version, no v prefix (e.g. "1.1.3") — "" when not acquired |
version |
str |
Document metadata version — "" when not acquired |
published |
str |
Metadata publication timestamp (RFC-3339) — "" when not acquired |
last_modified |
str |
Metadata last-modified timestamp (RFC-3339) — "" when not acquired |
imports |
list[dict] |
Child import nodes (empty when none / unacquired) |
The six summary fields populate only when the object was successfully
acquired; otherwise each is an empty string. import_tree is the single source
of truth for this schema.
get_oscal_object(uuid)
Companion to import_tree: pass a node’s object_uuid to obtain the live
imported document (searches this document and its resolved imports depth-first,
de-duplicating objects shared across import paths). Returns None when not found.
node = profile.import_tree["imports"][0]
catalog = profile.get_oscal_object(node["object_uuid"]) # live OSCAL object, or None
Root-UUID collisions. Documents are identified by root
uuid. If an import shares its importer’s (or another loaded document’s) rootuuidbut is genuinely different content — a common defect when files are copied without changing the uuid — the library reassigns the colliding import a fresh uuid at load and logs a warning, so its content still resolves instead of aliasing back to the other document. Fix the source to use unique root UUIDs; note that.new()and every mutation now assign a fresh root uuid automatically (see CONTENT.md).
Import getters return the same node shape
failed_imports, duplicate_imports, and unresolved_imports return safe-copy
flat lists with the same per-node fields (without the recursive imports
key). Because failed and duplicate entries never carry a loaded object, in these
results object_uuid is always None and the six summary fields are always "".
Failure states
When an import cannot be resolved, entry["status"] is ImportState.INVALID and entry["failure"] is an ImportFailure instance.
ImportFailureCode values
Fragment / back-matter failures
| Code | Meaning |
|---|---|
FRAGMENT_INVALID_UUID |
The fragment (#...) is not a well-formed UUID |
RESOURCE_NOT_FOUND |
No back-matter/resource with that UUID exists in the document |
RESOURCE_NO_VIABLE_CONTENT |
The resource was found but has neither rlink nor base64 elements |
Full URI failures
| Code | Meaning |
|---|---|
LOCAL_NOT_FOUND |
The URI resolves to a local path that does not exist or is empty |
REMOTE_UNREACHABLE |
The remote host could not be reached (network error, DNS failure, HTTP 5xx) |
REMOTE_AUTH_REQUIRED |
The remote host returned HTTP 401 or 403 |
REMOTE_UNSUPPORTED |
The URI scheme is recognised but not yet supported (e.g. s3://, gs://, az://) |
Content failures
| Code | Meaning |
|---|---|
CONTENT_EMPTY |
The source responded successfully but returned no content |
CONTENT_INVALID |
Content was retrieved but failed structural (minimal) validation — a structural error (missing-required / cardinality / choice) makes it unusable as an import. Content that is structurally sound but has only value-quality issues still resolves. |
The ImportFailure dataclass
@dataclass
class ImportFailure:
code: ImportFailureCode # Specific failure reason
href_original: str # Raw href from the import statement
# Fragment / back-matter context (populated when href starts with "#")
resource_uuid: str # UUID from the fragment
resource_title: str # Title from the back-matter resource (if found)
resource_description: str # Description from the back-matter resource (if found)
rlinks_tried: list[str] # All hrefs that were attempted before giving up
# URI context (populated for full-URI failures)
uri: str # The specific URI that caused the final failure
message: str # Human-readable detail
The is_fragment_ref property returns True when href_original starts with #, making it easy to branch on failure type without inspecting the code:
for entry in doc.failed_imports:
f = entry["failure"]
if f.is_fragment_ref:
print(f"Back-matter resource {f.resource_uuid} ({f.resource_title}): {f.code.value}")
else:
print(f"URI {f.uri}: {f.code.value}")
Inspecting failures
failed_imports property
Returns only the import_list entries that have a non-None failure field:
profile = OSCAL.load("my-profile.xml")
if profile.failed_imports:
print(f"{len(profile.failed_imports)} import(s) could not be resolved:")
for entry in profile.failed_imports:
f = entry["failure"]
print(f" [{f.code.value}] {entry['href_original']} — {f.message}")
Branching by failure code
from oscal.oscal_content import ImportFailureCode
for entry in profile.failed_imports:
f = entry["failure"]
match f.code:
case ImportFailureCode.FRAGMENT_INVALID_UUID:
print(f"Bad UUID in import href: {entry['href_original']}")
case ImportFailureCode.RESOURCE_NOT_FOUND:
print(f"No back-matter resource with UUID {f.resource_uuid}")
case ImportFailureCode.RESOURCE_NO_VIABLE_CONTENT:
print(f"Resource '{f.resource_title}' ({f.resource_uuid}) has no rlinks or base64")
case ImportFailureCode.LOCAL_NOT_FOUND:
print(f"File not found: {f.uri}")
case ImportFailureCode.REMOTE_AUTH_REQUIRED:
print(f"Authentication required: {f.uri}")
case ImportFailureCode.REMOTE_UNREACHABLE:
print(f"Remote host unreachable: {f.uri}")
case ImportFailureCode.REMOTE_UNSUPPORTED:
print(f"Unsupported URI scheme: {f.uri}")
Retry (overview)
When an import fails, the calling module can supply a replacement source and call resolve_imports() again. The retry source can be any of the following:
- A URI fragment —
#uuidpointing to an alternative back-matter resource you have added to the document - A full URI — an alternate local path or remote URL where the content is available
- Inline content — the raw XML, JSON, or YAML string of the imported document
Full retry API details are covered in IMPORTING_CONTROLS.md.
Example: profile with back-matter imports
from oscal import OSCAL
from oscal.oscal_content import ImportFailureCode
profile = OSCAL.load("my-profile.xml")
# All imports already resolved — check for failures
if not profile.failed_imports:
print("All imports resolved successfully.")
else:
for entry in profile.failed_imports:
f = entry["failure"]
if f.code == ImportFailureCode.LOCAL_NOT_FOUND:
# The rlink pointed to a file that was moved; provide the new path
print(f"Suggest alternate path for: {f.href_original}")
elif f.code == ImportFailureCode.RESOURCE_NOT_FOUND:
# The document references a resource UUID that is not in back-matter
print(f"Missing resource UUID: {f.resource_uuid}")
elif f.code == ImportFailureCode.REMOTE_AUTH_REQUIRED:
# Need credentials — provide authenticated content directly
print(f"Auth needed for: {f.uri}")
Example: building a simple failure report
from oscal import OSCAL
def import_report(path: str) -> str:
doc = OSCAL.load(path)
lines = [f"Import report: {doc.title} ({doc.model})"]
lines.append(f" Total imports : {len(doc.import_list)}")
lines.append(f" Resolved : {sum(1 for e in doc.import_list if e['failure'] is None)}")
lines.append(f" Failed : {len(doc.failed_imports)}")
for entry in doc.failed_imports:
f = entry["failure"]
lines.append(f"\n ✗ {entry['href_original']}")
lines.append(f" code : {f.code.value}")
lines.append(f" message : {f.message}")
if f.is_fragment_ref and f.resource_title:
lines.append(f" resource: {f.resource_title} ({f.resource_uuid})")
elif f.uri:
lines.append(f" uri : {f.uri}")
if f.rlinks_tried:
lines.append(f" tried : {', '.join(f.rlinks_tried)}")
return "\n".join(lines)
print(import_report("profiles/fedramp-high.xml"))