Developer Notes

Metapath

Dereferencing UUID-based URI Reference Lookups

If you want, for example, to write Metapath expression to use the UUID in a link/@href and "dereference" to look up the targets content with a UUID that follows after a #, you can one of the following approaches.

//link[starts-with(./@href, "#")]/tokenize(@href, "#")[2]

//link[starts-with(./@href, "#")]/substring-after(@href, "#")

The above code patterns remove the # from the UUID by splitting item or taking the content after the # and use that for a predicate that uses the UUID value for that next lookup.

Test expressions for conditionals must include parentheses

Suppose you have a constraint like the one below.

<!-- INCORRECT CONSTRAINT EXAMPLE -->
<?xml version="1.0" encoding="UTF-8"?>
<metaschema-meta-constraints xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://csrc.nist.gov/ns/oscal/metaschema/1.0 https://raw.githubusercontent.com/metaschema-framework/metaschema/refs/heads/develop/schema/xml/metaschema-meta-constraints.xsd">
    <context>
        <metapath target="/system-security-plan/metadata"/>
        <constraints>
            <expect id="oscal-version-required" target="oscal-version" test="if . = '1.1.2' then true() else false()" level="ERROR">
                <message>A FedRAMP document MUST have a valid version.</message>
            </expect>
        </constraints>
    </context>
</metaschema-meta-constraints>

You may want to validate it against the OSCAL SSP content below.

<?xml version="1.0" encoding="UTF-8"?>
<system-security-plan xmlns="http://csrc.nist.gov/ns/oscal/1.0"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                      xsi:schemaLocation="http://csrc.nist.gov/ns/oscal/1.0 https://github.com/usnistgov/OSCAL/releases/download/v1.1.2/oscal_ssp_schema.xsd"
                      uuid="12345678-1234-4321-8765-123456789012">
  <metadata>
    <oscal-version>1.1.2</oscal-version>
  </metadata>
</system-security-plan>

If you use the oscal-cli to validate this document, it will report an error with a constraint violation even though it is seemingly correct. As Metapath and XPath 3.1 require, the test expression after the if must be enclosed with parethenses. As of oscal-cli 2.3.1, if the expression is not properly enclosed in parentheses, even though it is seemingly correct, the evaluation will fail as the processor does not properly evaluate the expression and lead to a difficult to debug scenario based on a minor error in Metapath syntax.

Below is a corrected version of the constraint.

<!-- CORRECT CONSTRAINT EXAMPLE -->
<?xml version="1.0" encoding="UTF-8"?>
<metaschema-meta-constraints xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://csrc.nist.gov/ns/oscal/metaschema/1.0 https://raw.githubusercontent.com/metaschema-framework/metaschema/refs/heads/develop/schema/xml/metaschema-meta-constraints.xsd">
    <context>
        <metapath target="/system-security-plan/metadata"/>
        <constraints>
            <!-- Observe the expression to test the value of oscal-version is wrapped in parentheses. -->
            <expect id="oscal-version-required" target="oscal-version" test="if (. = '1.1.2') then true() else false()" level="ERROR">
                <message>A FedRAMP document MUST have a valid version.</message>
            </expect>
        </constraints>
    </context>
</metaschema-meta-constraints>