Querying OSCAL Content

OSCAL objects expose two complementary path-based query methods that work on the in-memory JSON representation of an OSCAL document. Both share the same path syntax and return Python lists. The difference is in how path steps are written.

Method Step names Requires index
query() / query_one() OSCAL XML element names (control, prop, part) Yes — metaschema index via support object
json_query() / json_query_one() JSON key names as they appear in the file (controls, props, parts) No

Results are safe copies. All four public query methods return detached copies of the matched nodes — mutating a result does not change the document. To make persistent changes, use the model’s mutation methods. (The live-reference variants _query() / _json_query() are private and for internal use only.)


Path Syntax

Both engines parse the same expression language.

Axes

Expression Meaning
name Relative path — navigate to name from the current context
/ Absolute path — anchor to the document root
/* Absolute path — wildcard over the root model object (skips the {"catalog": …} wrapper)
//name Descendant axis — find name at any depth below the current context
//name//child Chained descendant axes
* Wildcard — all direct children
@attr Attribute/flag value (in json_query, @key is a synonym for bare key)
text() Scalar value of the current node

Predicates

Predicates are written in […] brackets immediately after a step name. Multiple predicates on the same step are ANDed together.

Predicate Meaning
[@id='ac-2'] Attribute equality
[@id!='ac-2'] Attribute inequality
[@priority>3] Numeric comparison (<, >, <=, >=)
[select] Existence — node has a select child
[not(@withdrawn)] Negated existence
[prop[@name='label']] Path expression — has a prop child with name='label'
[@id='ac-1'][select] Multiple predicates — both must hold

Quoting

Predicate values may use single or double quotes: [@id="ac-2"] and [@id='ac-2'] are equivalent.


query() — XML Element Name Syntax

Uses the metaschema index to translate OSCAL XML element names into their JSON equivalents, resolving array grouping (controls, props, …) and BY_KEY structures automatically.

# Returns a list; empty list when nothing matches.
results = oscal_obj.query(path)
results = oscal_obj.query(path, context=some_sub_dict)

# Returns the first match, or None (or a supplied default).
value = oscal_obj.query_one(path)
value = oscal_obj.query_one(path, default="")

When to use: When you think in XML/OSCAL schema terms — the names from the OSCAL specification and its metaschemas.

Examples

# Find a control by ID anywhere in the document
ctrl = oscal_obj.query_one('//control[@id="ac-2"]')
# → {"id": "ac-2", "title": "Account Management", "params": […], …}

# Fetch the catalog title (absolute path, /* skips the {"catalog": …} wrapper)
title = oscal_obj.query_one('/*/metadata/title')
# → "NIST SP 800-53 Rev 5 …"

# Find all statement parts across the entire document
statements = oscal_obj.query('//part[@name="statement"]')
# → [{"id": "ac-1_smt", "name": "statement", …}, …]  (1016 items in SP 800-53)

# Find controls that have a prop with name="label" and value="AC-2"
ctrls = oscal_obj.query('//control[prop[@name="label"][@value="AC-2"]]')
# → [{"id": "ac-2", …}]

# All controls that have at least one parameter
ctrls = oscal_obj.query('//control[param]')

# Controls whose label starts with "AC" — not directly supported, but you can
# filter the full list in Python after querying
labels = oscal_obj.query('//prop[@name="label"]')

# Relative path — query within an already-fetched object
ctrl = oscal_obj.query_one('//control[@id="ac-2"]')
stmts = oscal_obj.query('part[@name="statement"]', context=ctrl)

# Find parameters that have a select/choice element
params = oscal_obj.query('//param[select]')

# Negation — controls that have NOT been withdrawn
active = oscal_obj.query('//control[not(prop[@name="status"][@value="withdrawn"])]')

# Scalar value via text()
version = oscal_obj.query_one('/*/metadata/oscal-version/text()')
# → "1.1.3"

XML → JSON Name Translation

The engine uses the metaschema index to map XML element names to JSON keys. Common examples for a catalog:

Path step (XML name) JSON key Container
control controls array
group groups array
param params array
prop props array
part parts array
link links array
metadata metadata object
set-parameter set-parameters BY_KEY (keyed by param-id)

Attribute/flag names are the same in XML and JSON (e.g., @id, @name, @value).


json_query() — JSON Key Name Syntax

Works directly on JSON key names with no index lookup. Arrays are iterated transparently: navigating to a key whose value is a list automatically yields each item.

# Returns a list; empty list when nothing matches.
results = oscal_obj.json_query(path)
results = oscal_obj.json_query(path, context=some_sub_dict)

# Returns the first match, or None (or a supplied default).
value = oscal_obj.json_query_one(path)
value = oscal_obj.json_query_one(path, default="")

When to use: When you already know the JSON structure, when working with non-catalog models without an index, or when the query is simpler to express in JSON terms.

Root Key Awareness

OSCAL JSON always has a root wrapper key matching the model name:

{ "catalog": { "metadata": {…}, "groups": […] } }

Relative paths start from this wrapper. Use /* or the model name explicitly to reach the content:

# These are equivalent for a catalog:
oscal_obj.json_query_one('/*/metadata/title')
oscal_obj.json_query_one('catalog/metadata/title')

# Descendant axis skips the wrapper automatically:
oscal_obj.json_query_one('//title')   # finds first title at any depth

Examples

# Find a control by ID anywhere in the document
ctrl = oscal_obj.json_query_one('//controls[id="ac-2"]')
# → {"id": "ac-2", "title": "Account Management", …}

# Catalog title — include the root key or use /*
title = oscal_obj.json_query_one('catalog/metadata/title')
title = oscal_obj.json_query_one('/*/metadata/title')

# All statement parts
statements = oscal_obj.json_query('//parts[name="statement"]')

# Controls with a prop named "label" equal to "AC-2"
ctrls = oscal_obj.json_query('//controls[props[name="label"][value="AC-2"]]')

# Parameters that have a select object
params = oscal_obj.json_query('//params[select]')

# Controls with no params (negated existence)
bare = oscal_obj.json_query('//controls[not(params)]')

# Relative path — query within a fetched object
ctrl = oscal_obj.json_query_one('//controls[id="ac-2"]')
parts = oscal_obj.json_query('parts', context=ctrl)

# Numeric comparison — links with rel="reference"
links = oscal_obj.json_query('//links[rel="reference"]')

# @ prefix is accepted as a synonym for a bare key
oscal_obj.json_query('//controls[@id="ac-2"]')   # same as [id="ac-2"]

# Chained descendant axes
oscal_obj.json_query('//controls//parts[name="item"]')

Choosing Between query and json_query

Use query (XML names) when:

Use json_query (JSON names) when:

Both methods return the same Python values (dicts, strings, lists, numbers) from the same underlying _dict.


Return Values

All query methods return Python objects from the parsed JSON:


Using the Engines Directly

Both engines can also be used without an OSCAL object:

from oscal.oscal_converter import OSCALPath, NativePath, native_path

# NativePath — module-level singleton, no setup needed
doc = json.loads(open("catalog.json").read())
ctrl = native_path.query_one('//controls[id="ac-2"]', doc)

# OSCALPath — requires a model index from the support object
engine = OSCALPath.from_support("catalog", "v1.1.3", support_obj)
ctrl = engine.query_one('//control[@id="ac-2"]', doc)