oscal_metadata_metaschema.xml

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="../../build/metaschema/toolchains/xslt-M4/validate/metaschema-composition-check.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<!-- OSCAL CATALOG METASCHEMA -->
<!-- validate with XSD and Schematron (linked) -->
<METASCHEMA xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0" xsi:schemaLocation="http://csrc.nist.gov/ns/oscal/metaschema/1.0 ../../build/metaschema/toolchains/xslt-M4/validate/metaschema.xsd" abstract="yes">
    <schema-name>OSCAL Document Metadata Description</schema-name>
    <schema-version>1.0.4</schema-version>
    <short-name>oscal-metadata</short-name>
    <namespace>http://csrc.nist.gov/ns/oscal/1.0</namespace>
    <json-base-uri>http://csrc.nist.gov/ns/oscal</json-base-uri>

    <!-- ############################################### -->
    <!-- # Metadata Assembly and supporting constructs # -->
    <!-- ############################################### -->
    <define-assembly name="metadata">
        <formal-name>Publication metadata</formal-name>
        <description>Provides information about the publication and availability of the containing document.</description>
        <model>
            <define-field name="title" as-type="markup-line" min-occurs="1">
                <formal-name>Document Title</formal-name>
                <description>A name given to the document, which may be used by a tool for display and navigation.</description>
            </define-field>
            <field ref="published"/>
            <field ref="last-modified" min-occurs="1"/>
            <field ref="version" min-occurs="1"/>
            <field ref="oscal-version" min-occurs="1"/>
            <assembly ref="revision" max-occurs="unbounded">
                <!-- CHANGED: "revision-history" to "revisions" -->
                <!-- QUESTION: Should this be grouped in XML? -->
                <group-as name="revisions" in-xml="GROUPED" in-json="ARRAY"/>
            </assembly>
            <!-- CHANGED from "doc-id" to "document-id" -->
            <field ref="document-id" max-occurs="unbounded">
                <group-as name="document-ids" in-json="ARRAY"/>
            </field>
            <assembly ref="property" max-occurs="unbounded">
                <group-as name="props" in-json="ARRAY"/>
            </assembly>
            <assembly ref="link" max-occurs="unbounded">
                <group-as name="links" in-json="ARRAY"/>
            </assembly>
            <assembly ref="role" max-occurs="unbounded">
                <group-as name="roles" in-json="ARRAY"/>
            </assembly>
            <assembly ref="location" max-occurs="unbounded">
                <group-as name="locations" in-json="ARRAY"/>
            </assembly>
            <assembly ref="party" max-occurs="unbounded">
                <group-as name="parties" in-json="ARRAY"/>
            </assembly>
            <assembly ref="responsible-party" max-occurs="unbounded">
                <group-as name="responsible-parties" in-json="ARRAY"/>
            </assembly>
            <field ref="remarks" in-xml="WITH_WRAPPER"/>
        </model>
        <constraint>
            <index id="index-metadata-roles" name="index-metadata-role-ids" target="role">
                <key-field target="@id"/>
            </index>
            <is-unique id="unique-metadata-doc-id" target="document-id">
                <!--  CHANGE: Fixing field name @type -> @scheme   -->
                <key-field target="@scheme"/>
                <key-field target="."/>
            </is-unique>
            <is-unique id="unique-metadata-property" target="prop">
                <key-field target="@name"/>
                <key-field target="@ns"/>
                <key-field target="@class"/>
                <key-field target="@value"/>
            </is-unique>
            <index id="index-metadata-property-uuid" name="index-metadata-property-uuid" target=".//prop">
                <key-field target="@uuid"/>
            </index>
            <is-unique id="unique-metadata-link" target="link">
                <key-field target="@href"/>
                <key-field target="@rel"/>
                <key-field target="@media-type"/>
            </is-unique>
            <index id="index-metadata-role-id" name="index-metadata-role-id" target="role">
                <key-field target="@id"/>
                <!--            <builtin>
               <o:role id="prepared-by">
                  <o:title>Document Preparer</o:title>
               </o:role>
            </builtin>
-->            </index>
            <index id="index-metadata-location-uuid" name="index-metadata-location-uuid" target="location">
                <key-field target="@uuid"/>
            </index>
            <index id="index-metadata-party-uuid" name="index-metadata-party-uuid" target="party">
                <key-field target="@uuid"/>
            </index>
            <index id="index-metadata-party-organizations-uuid" name="index-metadata-party-organizations-uuid" target="party[@type='organization']">
                <key-field target="@uuid"/>
            </index>
            <is-unique id="unique-metadata-responsible-party" target="responsible-party">
                <key-field target="@role-id"/>
                <remarks>
                    <p>Since <code>responsible-party</code> associates multiple <code>party-uuid</code> entries with a single <code>role-id</code>, each role-id must be referenced only once.</p>
                </remarks>
            </is-unique>
            <allowed-values id="allowed-metadata-responsibe-party-role-ids" target="responsible-party/@role-id" allow-other="yes">
                <enum value="creator">Indicates the organization that created this content.</enum>
                <enum value="prepared-by">Indicates the organization that prepared this content.</enum>
                <enum value="prepared-for">Indicates the organization for which this content was created.</enum>
                <enum value="content-approver">Indicates the organization responsible for all content represented in the "document".</enum>
                <enum value="contact">Indicates the organization to contact for questions or support related to this content.</enum>
            </allowed-values>
            <allowed-values target="prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name">
                <enum value="keywords">The value identifies a comma-seperated listing of keywords associated with this content. These keywords may be used as search terms for indexing and other applications.</enum>
            </allowed-values>
            <allowed-values target="link/@rel" allow-other="yes">
                <enum value="canonical">The link identifies the authoritative location for this file. Defined by <a href="https://tools.ietf.org/html/rfc6596">RFC 6596</a>.</enum>
                <enum value="alternate">The link identifies an alternative location or format for this file. Defined by <a href="https://html.spec.whatwg.org/multipage/links.html#linkTypes">the HTML Living Standard</a></enum>
                <enum value="latest-version">This link identifies a resource containing the latest version in the version history. Defined by <a href="https://tools.ietf.org/html/rfc5829">RFC 5829</a>.</enum>
                <enum value="predecessor-version">This link identifies a resource containing the predecessor version in the version history. Defined by  <a href="https://tools.ietf.org/html/rfc5829">RFC 5829</a>.</enum>
                <enum value="successor-version">This link identifies a resource containing the predecessor version in the version history. Defined by <a href="https://tools.ietf.org/html/rfc5829">RFC 5829</a>.</enum>
            </allowed-values>
        </constraint>
    </define-assembly>

    <define-assembly name="revision" scope="local">
        <formal-name>Revision History Entry</formal-name>
        <description>An entry in a sequential list of revisions to the containing document in reverse chronological order (i.e., most recent previous revision first).</description>
        <model>
            <define-field name="title" as-type="markup-line">
                <formal-name>Document Title</formal-name>
                <description>A name given to the document revision, which may be used by a tool for display and navigation.</description>
            </define-field>
            <field ref="published" />
            <field ref="last-modified"/>
            <field ref="version" min-occurs="1"/>
            <field ref="oscal-version"/>
            <assembly ref="property" max-occurs="unbounded">
                <group-as name="props" in-json="ARRAY"/>
            </assembly>
            <assembly ref="link" max-occurs="unbounded">
                <group-as name="links" in-json="ARRAY"/>
            </assembly>
            <field ref="remarks" in-xml="WITH_WRAPPER"/>
        </model>
        <constraint>
<!-- TODO: consider making this a warning
            <has-cardinality target="published|last-modified|link[@rel='canonical']" min-occurs="1"/>
-->
            <allowed-values target="link/@rel" allow-other="yes">
                <enum value="canonical">The link identifies the authoritative location for this file. Defined by <a href="https://tools.ietf.org/html/rfc6596">RFC 6596</a>.</enum>
                <enum value="alternate">The link identifies an alternative location or format for this file. Defined by <a href="https://html.spec.whatwg.org/multipage/links.html#linkTypes">the HTML Living Standard</a></enum>
                <enum value="predecessor-version">This link identifies a resource containing the predecessor version in the version history. Defined by  <a href="https://tools.ietf.org/html/rfc5829">RFC 5829</a>.</enum>
                <enum value="successor-version">This link identifies a resource containing the predecessor version in the version history. Defined by <a href="https://tools.ietf.org/html/rfc5829">RFC 5829</a>.</enum>
            </allowed-values>
        </constraint>
        <remarks>
            <p>While <code>published</code>, <code>last-modified</code>, <code>oscal-version</code>, and <code>version</code> are not required, values for these entries should be provided if the information is known. For a revision entry to be considered valid, at least one of the following items must be provided: <code>published</code>, <code>last-modified</code>, <code>version</code>, or a <code>link</code> with a <code>rel</code> of <q>source</q>.</p>
        </remarks>
    </define-assembly>

    <define-assembly name="location">
        <formal-name>Location</formal-name>
        <description>A location, with associated metadata that can be referenced.</description>
        <define-flag name="uuid" as-type="uuid" required="yes">
            <formal-name>Location Universally Unique Identifier</formal-name>
            <!-- identifier declaration -->
            <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a>, <a href="/concepts/identifier-use/#globally-unique">globally unique</a> identifier with <a href="/concepts/identifier-use/#cross-instance">cross-instance</a> scope that can be used to reference this defined location elsewhere in <a href="/concepts/identifier-use/#scope">this or other OSCAL instances</a>. The locally defined <em>UUID</em> of the <code>location</code> can be used to reference the data item locally or globally (e.g., from an importing OSCAL instance). This UUID should be assigned <a href="/concepts/identifier-use/#consistency">per-subject</a>, which means it should be consistently used to identify the same subject across revisions of the document.</description>
        </define-flag>
        <model>
            <define-field name="title" as-type="markup-line">
                <formal-name>Location Title</formal-name>
                <description>A name given to the location, which may be used by a tool for display and navigation.</description>
            </define-field>
            <assembly ref="address" min-occurs="1">
                <remarks>
                    <p>Typically, the physical address of the location will be used here. If this information is sensitive, then a mailing address can be used instead.</p>
                </remarks>
            </assembly>
            <!-- CHANGE: "email" to "email-address" -->
            <field ref="email-address" max-occurs="unbounded">
                <group-as name="email-addresses" in-json="ARRAY"/>
                <remarks>
                    <p>This is a contact email associated with the location.</p>
                </remarks>
            </field>
            <!-- CHANGE: "phone" to "telephone-number" -->
            <field ref="telephone-number" max-occurs="unbounded">
                <group-as name="telephone-numbers" in-json="ARRAY"/>
                <remarks>
                    <p>A phone number used to contact the location.</p>
                </remarks>
            </field>
            <define-field name="url" as-type="uri" max-occurs="unbounded">
                <formal-name>Location URL</formal-name>
                <description>The uniform resource locator (URL) for a web site or Internet presence associated with the location.</description>
                <!-- CHANGE: changed case from "URLs" to "urls" -->
                <group-as name="urls" in-json="ARRAY"/>
            </define-field>
            <assembly ref="property" max-occurs="unbounded">
                <group-as name="props" in-json="ARRAY"/>
            </assembly>
            <assembly ref="link" max-occurs="unbounded">
                <group-as name="links" in-json="ARRAY"/>
            </assembly>
            <field ref="remarks" in-xml="WITH_WRAPPER"/>
        </model>
        <constraint>
            <allowed-values target="prop/@name" allow-other="yes">
                <enum value="type">Characterizes the kind of location.</enum>
            </allowed-values>
            <allowed-values target="prop[@name='type']/@value" allow-other="yes">
                <enum value="data-center">A location that contains computing assets. A <code>class</code> can be used to indicate the sub-type of data-center as <em>primary</em> or <em>alternate</em>.</enum>
            </allowed-values>
            <allowed-values target="prop[@name='type' and @value='data-center']/@class" allow-other="yes">
                <enum value="primary">The location is a data-center used for normal operations.</enum>
                <enum value="alternate">The location is a data-center used for fail-over or backup operations.</enum>
            </allowed-values>
        </constraint>
    </define-assembly>

    <define-flag name="location-uuid" as-type="uuid">
        <formal-name>Location Reference</formal-name>
        <!-- identifier reference -->
        <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a> identifier reference to a <code>location</code> defined in the <code>metadata</code> section of this or another OSCAL instance. The <em>UUID</em> of the <code>location</code> in the source OSCAL instance is sufficient to reference the data item locally or globally (e.g., in an imported OSCAL instance).
        </description>
        <constraint>
            <!-- TODO: Dave to resolve syntax error. Likely requires updated metaschema schema -->
            <index-has-key name="index-metadata-location-uuid">
                <!-- TODO: This is impacted by cross-document cross-references We need to relocate or localize this constraint. -->
                <key-field target="."/>
            </index-has-key>
        </constraint>
    </define-flag>

    <define-field name="location-uuid" as-type="uuid">
        <formal-name>Location Reference</formal-name>
        <!-- identifier reference -->
        <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a> identifier reference to a <code>location</code> defined in the <code>metadata</code> section of this or another OSCAL instance. The <em>UUID</em> of the <code>location</code> in the source OSCAL instance is sufficient to reference the data item locally or globally (e.g., in an imported OSCAL instance).
        </description>
        <constraint>
            <index-has-key name="index-metadata-location-uuid" target=".">
                <!-- TODO: This is impacted by cross-document cross-references We need to relocate or localize this constraint. -->
                <key-field target="."/>
            </index-has-key>
        </constraint>
        <remarks>
            <p>See the <a href="/concepts/identifier-use/#scope">Concepts - Identifier Use</a> page for additional information about the referenced identifier's scope.</p>
          </remarks>
    </define-field>

    <define-assembly name="party">
        <formal-name>Party (organization or person)</formal-name>
        <description>A responsible entity which is either a person or an organization.</description>
        <define-flag name="uuid" as-type="uuid" required="yes">
            <formal-name>Party Universally Unique Identifier</formal-name>
            <!-- identifier declaration -->
            <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a>, <a href="/concepts/identifier-use/#globally-unique">globally unique</a> identifier with <a href="/concepts/identifier-use/#cross-instance">cross-instance</a> scope that can be used to reference this defined party elsewhere in <a href="/concepts/identifier-use/#scope">this or other OSCAL instances</a>. The locally defined <em>UUID</em> of the <code>party</code> can be used to reference the data item locally or globally (e.g., from an importing OSCAL instance). This UUID should be assigned <a href="/concepts/identifier-use/#consistency">per-subject</a>, which means it should be consistently used to identify the same subject across revisions of the document.</description>
        </define-flag>
        <define-flag name="type" as-type="string" required="yes">
            <formal-name>Party Type</formal-name>
            <description>A category describing the kind of party the object describes.</description>
            <constraint>
                <allowed-values allow-other="no">
                    <enum value="person">An individual.</enum>
                    <enum value="organization">A group of individuals formed for a specific purpose.</enum>
                </allowed-values>
            </constraint>
        </define-flag>
        <model>
            <!-- CHANGE: changed from "party-name" to "name" -->
            <define-field name="name">
                <formal-name>Party Name</formal-name>
                <description>The full name of the party. This is typically the legal name associated with the party.</description>
            </define-field>
            <define-field name="short-name">
                <formal-name>Party Short Name</formal-name>
                <description>A short common name, abbreviation, or acronym for the party.</description>
            </define-field>
            <define-field name="external-id" max-occurs="unbounded">
                <!-- This is an id because the idenfier is assigned and managed externally by humans. -->
                <formal-name>Party External Identifier</formal-name>
                <description>An identifier for a person or organization using a designated scheme. e.g. an Open Researcher and Contributor ID (ORCID)</description>
                <json-value-key>id</json-value-key>
                <group-as name="external-ids" in-json="ARRAY"/>
                <!-- CHANGED: "type" to "scheme" -->
                <define-flag name="scheme" as-type="uri" required="yes">
                    <formal-name>External Identifier Schema</formal-name>
                    <description>Indicates the type of external identifier.</description>
                    <constraint>
                        <allowed-values allow-other="yes">
                            <enum value="http://orcid.org/">The identifier is Open Researcher and Contributor ID (ORCID).</enum>
                        </allowed-values>
                    </constraint>
                </define-flag>
            </define-field>
            <assembly ref="property" max-occurs="unbounded">
                <group-as name="props" in-json="ARRAY"/>
            </assembly>
            <assembly ref="link" max-occurs="unbounded">
                <group-as name="links" in-json="ARRAY"/>
            </assembly>
            <!-- CHANGE: "email" to "email-address" -->
            <field ref="email-address" max-occurs="unbounded">
                <group-as name="email-addresses" in-json="ARRAY"/>
                <remarks>
                    <p>This is a contact email associated with the party.</p>
                </remarks>
            </field>
            <!-- CHANGE: "phone" to "telephone-number" -->
            <field ref="telephone-number" max-occurs="unbounded">
                <group-as name="telephone-numbers" in-json="ARRAY"/>
                <remarks>
                    <p>A phone number used to contact the party.</p>
                </remarks>
            </field>
            <!-- CHANGE: ordering of address inside party and made use of address and location-uuid mutually exclusive. -->
            <choice>
                <assembly ref="address" max-occurs="unbounded">
                    <group-as name="addresses" in-json="ARRAY"/>
                </assembly>
                <field ref="location-uuid" max-occurs="unbounded">
                    <group-as name="location-uuids" in-json="ARRAY"/>
                </field>
            </choice>
            <define-field name="member-of-organization" as-type="uuid" max-occurs="unbounded">
                <formal-name>Organizational Affiliation</formal-name>
                <!-- identifier reference -->
                <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a> identifier reference to another <code>party</code> (<code>person</code> or <code>organization</code>) that this subject is associated with. The <em>UUID</em> of the <code>party</code> in the source OSCAL instance is sufficient to reference the data item locally or globally (e.g., in an imported OSCAL instance).
                </description>
                <group-as name="member-of-organizations" in-json="ARRAY"/>
                <constraint>
                    <index-has-key name="index-metadata-party-organizations-uuid" target=".">
                        <key-field target="."/>
                    </index-has-key>
                </constraint>
                <remarks>
                    <p>Parties of both the <code>person</code> or <code>organization</code> type can be associated with an organization using the <code>member-of-organization</code>.</p>
                </remarks>
            </define-field>
            <field ref="remarks" in-xml="WITH_WRAPPER"/>
        </model>
        <constraint>
            <allowed-values target="prop/@name">
                <enum value="mail-stop">A mail stop associated with the party.</enum>
                <enum value="office">The name or number of the party's office.</enum>
                <enum value="job-title">The formal job title of a person.</enum>
            </allowed-values>
        </constraint>
    </define-assembly>

    <define-field name="party-uuid" as-type="uuid">
        <formal-name>Party Reference</formal-name>
        <!-- identifier reference -->
        <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a> identifier reference to another <code>party</code> defined in <code>metadata</code>. The <em>UUID</em> of the <code>party</code> in the source OSCAL instance is sufficient to reference the data item locally or globally (e.g., in an imported OSCAL instance).
        </description>
        <constraint>
            <index-has-key name="index-metadata-party-uuid" target=".">
                <!-- TODO: This is impacted by cross-document cross-references We need to relocate or localize this constraint. -->
                <key-field target="."/>
            </index-has-key>
        </constraint>
        <remarks>
            <p>See the <a href="/concepts/identifier-use/#scope">Concepts - Identifier Use</a> page for additional information about the referenced identifier's scope.</p>
          </remarks>
    </define-field>

    <define-assembly name="role">
        <formal-name>Role</formal-name>
        <description>Defines a function assumed or expected to be assumed by a party in a specific situation.</description>
        <define-flag name="id" as-type="token" required="yes">
            <!-- This is an id because the idenfier is assigned and managed by humans. -->
            <!-- identifier declarations -->
            <formal-name>Role Identifier</formal-name>
            <description>A <a href="/concepts/identifier-use/#human-oriented">human-oriented</a>, <a href="/concepts/identifier-use/#locally-unique">locally unique</a> identifier with <a href="/concepts/identifier-use/#cross-instance">cross-instance</a> scope that can be used to reference this defined role elsewhere in <a href="/concepts/identifier-use/#scope">this or other OSCAL instances</a>. When referenced from another OSCAL instance, the locally defined <em>ID</em> of the <code>Role</code> from the imported OSCAL instance must be referenced in the context of the containing resource (e.g., import, import-component-definition, import-profile, import-ssp or import-ap). This ID should be assigned <a href="/concepts/identifier-use/#consistency">per-subject</a>, which means it should be consistently used to identify the same subject across revisions of the document.</description>
        </define-flag>
        <model>
            <define-field name="title" as-type="markup-line" min-occurs="1">
                <formal-name>Role Title</formal-name>
                <description>A name given to the role, which may be used by a tool for display and navigation.</description>
            </define-field>
            <define-field name="short-name">
                <formal-name>Role Short Name</formal-name>
                <description>A short common name, abbreviation, or acronym for the role.</description>
            </define-field>
            <!-- CHANGE "desc" to "description" -->
            <define-field name="description" in-xml="WITH_WRAPPER" as-type="markup-multiline">
                <formal-name>Role Description</formal-name>
                <description>A summary of the role's purpose and associated responsibilities.</description>
            </define-field>
            <assembly ref="property" max-occurs="unbounded">
                <group-as name="props" in-json="ARRAY"/>
            </assembly>
            <assembly ref="link" max-occurs="unbounded">
                <group-as name="links" in-json="ARRAY"/>
            </assembly>
            <field ref="remarks" in-xml="WITH_WRAPPER"/>
        </model>
        <remarks>
            <p>Permissible values to be determined closer to the application (e.g. by a receiving authority).</p>
                <p>OSCAL has defined a set of standardized roles for consistent use in OSCAL documents. This allows tools consuming OSCAL content to infer specific semantics when these roles are used. These roles are documented in the specific contexts of their use (e.g., responsible-party, responsible-role). When using such a role, it is necessary to define these roles in this list, which will then allow such a role to be referenced.</p>
            </remarks>
    </define-assembly>

    <define-field name="role-id" as-type="token">
        <formal-name>Role Identifier Reference</formal-name>
        <!-- identifier reference -->
        <description>A <a href="/concepts/identifier-use/#human-oriented">human-oriented</a> identifier reference to <code>roles</code> served by the user.</description>
        <constraint>
            <index-has-key name="index-metadata-role-id" target=".">
                <!-- TODO: This is impacted by cross-document cross-references We need to relocate or localize this constraint. -->
                <key-field target="."/>
            </index-has-key>
        </constraint>
    </define-field>

    <!-- ############################################### -->
    <!-- # Back Matter Assembly and related constructs # -->
    <!-- ############################################### -->
    <define-assembly name="back-matter">
        <formal-name>Back matter</formal-name>
        <description>A collection of resources, which may be included directly or by reference.</description>
        <model>
            <define-assembly name="resource" max-occurs="unbounded">
                <formal-name>Resource</formal-name>
                <description>A resource associated with content in the containing document. A resource may be directly included in the document base64 encoded or may point to one or more equivalent internet resources.</description>
                <group-as name="resources" in-json="ARRAY"/>
                <define-flag name="uuid" as-type="uuid" required="yes">
                    <formal-name>Resource Universally Unique Identifier</formal-name>
                    <!-- identifier declaration -->
                    <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a>, <a href="/concepts/identifier-use/#globally-unique">globally unique</a> identifier with <a href="/concepts/identifier-use/#cross-instance">cross-instance</a> scope that can be used to reference this defined resource elsewhere in <a href="/concepts/identifier-use/#scope">this or other OSCAL instances</a>. This UUID should be assigned <a href="/concepts/identifier-use/#consistency">per-subject</a>, which means it should be consistently used to identify the same subject across revisions of the document.</description>
                </define-flag>
                <model>
                    <define-field name="title" as-type="markup-line">
                        <formal-name>Resource Title</formal-name>
                        <description>A name given to the resource, which may be used by a tool for display and navigation.</description>
                    </define-field>
                    <define-field name="description" in-xml="WITH_WRAPPER" as-type="markup-multiline">
                        <!-- CHANGED from "desc" to "description" -->
                        <formal-name>Resource Description</formal-name>
                        <description>A short summary of the resource used to indicate the purpose of the resource.</description>
                    </define-field>
                    <assembly ref="property" max-occurs="unbounded">
                        <group-as name="props" in-json="ARRAY"/>
                    </assembly>
                    <field ref="document-id" max-occurs="unbounded">
                        <!-- CHANGED "doc-id" to "document-id" -->
                        <group-as name="document-ids" in-json="ARRAY"/>
                    </field>
                    <define-assembly name="citation">
                        <formal-name>Citation</formal-name>
                        <description>A citation consisting of end note text and optional structured bibliographic data.</description>
                        <model>
                            <define-field name="text" as-type="markup-line" min-occurs="1">
                                <formal-name>Citation Text</formal-name>
                                <description>A line of citation text.</description>
                            </define-field>
                            <assembly ref="property" max-occurs="unbounded">
                                <group-as name="props" in-json="ARRAY"/>
                            </assembly>
                            <assembly ref="link" max-occurs="unbounded">
                                <group-as name="links" in-json="ARRAY"/>
                            </assembly>
                            
<!--                            <define-assembly name="biblio">
                                <formal-name>Bibliographic Definition</formal-name>
                                <description>A container for structured bibliographic information. The model of this information is undefined by OSCAL.</description>
                                <model>
                                    <any/>
                                </model>
                            </define-assembly>
-->                        </model>
                        <remarks>
                            <p>The <code>text</code> is used to define the endnote text, without any required bibliographic structure. If structured bibliographic data is needed, then the <code>biblio</code> can be used for this purpose.</p>
                            <p>A <code>biblio</code> can be used to capture a structured bibliographical citation in an appropriate format.</p>
                        </remarks>
                    </define-assembly>
                    <define-assembly name="rlink" max-occurs="unbounded">
                        <formal-name>Resource link</formal-name>
                        <description>A pointer to an external resource with an optional hash for verification and change detection.</description>
                        <group-as name="rlinks" in-json="ARRAY"/>
                        <define-flag name="href" as-type="uri-reference" required="yes">
                            <formal-name>Hypertext Reference</formal-name>
                            <description>A resolvable URI reference to a resource.</description>
                        </define-flag>
                        <flag ref="media-type"/>
                        <model>
                            <field ref="hash" max-occurs="unbounded">
                                <group-as name="hashes" in-json="ARRAY"/>
                                <remarks>
                                    <p>When appearing as part of a <code>resource/rlink</code>, the hash applies to the resource referenced by the <code>href</code>.
                                    </p>
                                </remarks>
                            </field>
                        </model>
                        <remarks>
                            <p>This construct is different from <code>link</code>, which makes no provision for a hash or formal title.</p>
                            <p>Multiple <code>rlink</code> can be included for a resource. In such a case, all provided <code>rlink</code> items are intended to be equivalent in content, but may differ in structure. A <code>media-type</code> is used to identify the format of a given rlink, and can be used to differentiate a items in a collection of rlinks. The <code>media-type</code> also provides a hint to the OSCAL document consumer about the structure of the resource referenced by the <code>rlink</code>.
                            </p>
                        </remarks>
                    </define-assembly>

                    <define-field name="base64" as-type="base64Binary">
                        <formal-name>Base64</formal-name>
                        <description>The Base64 alphabet in RFC 2045 - aligned with XSD.</description>
                        <json-value-key>value</json-value-key>
                        <define-flag name="filename" as-type="uri-reference">
                            <formal-name>File Name</formal-name>
                            <description>Name of the file before it was encoded as Base64 to be embedded in a <code>resource</code>. This is the name that will be assigned to the file when the file is decoded.</description>
                        </define-flag>
                        <flag ref="media-type"/>
                    </define-field>
                    <field ref="remarks" in-xml="WITH_WRAPPER"/>
                    <!-- <any/> -->
                </model>
                <constraint>
                    <allowed-values target="prop/@name">
                        <enum value="type">Identifies the type of resource represented.</enum>
                        <enum value="version">For resources representing a published document, this represents the version number of that document.</enum>
                        <enum value="published">For resources representing a published document, this represents the publication date of that document.</enum>
                    </allowed-values>
                    <matches target="prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name='published']/@value" datatype="dateTime"/>
                    <!-- CHANGED: Added enumerated choices for the resource type property -->
                    <allowed-values target="prop[@name='type']/@value" allow-other="yes">
                        <!-- More general. Applies across all models. -->
                        <enum value="logo">Indicates the resource is an organization's logo.</enum>
                        <enum value="image">Indicates the resource represents an image.</enum>
                        <enum value="screen-shot">Indicates the resource represents an image of screen content. </enum>
                        <enum value="law">Indicates the resource represents an applicable law.</enum>
                        <enum value="regulation">Indicates the resource represents an applicable regulation.</enum>
                        <enum value="standard">Indicates the resource represents an applicable standard.</enum>
                        <enum value="external-guidance">Indicates the resource represents applicable guidance.</enum>
                        <enum value="acronyms">Indicates the resource provides a list of relevant acronyms.</enum>
                        <enum value="citation">Indicates the resource cites relevant information.</enum>
                        <!-- More related to implementation layer. -->
                        <enum value="policy">Indicates the resource is a policy.</enum>
                        <enum value="procedure">Indicates the resource is a procedure.</enum>
                        <enum value="system-guide">Indicates the resource is guidance document related to the subject system of an SSP.</enum>
                        <enum value="users-guide">Indicates the resource is guidance document a user's guide or administrator's guide.</enum>
                        <enum value="administrators-guide">Indicates the resource is guidance document a administrator's guide.</enum>
                        <enum value="rules-of-behavior">Indicates the resource represents rules of behavior content.</enum>
                        <enum value="plan">Indicates the resource represents a plan.</enum>
                        <!-- More related to assessment layers. -->
                        <enum value="artifact">Indicates the resource represents an artifact, such as may be reviewed by an assessor.</enum>
                        <enum value="evidence">Indicates the resource represents evidence, such as to support an assessment findiing.</enum>
                        <enum value="tool-output">Indicates the resource represents output from a tool.</enum>
                        <enum value="raw-data">Indicates the resource represents machine data, which may require a tool or analysis for interpretation or presentation.</enum>
                        <enum value="interview-notes">Indicates the resource represents notes from an interview, such as may be collected during an assessment.</enum>
                        <enum value="questionnaire">Indicates the resource is a set of questions, possibly with responses.</enum>
                        <enum value="report">Indicates the resource is a report.</enum>
                        <enum value="agreement">Indicates the resource is a formal agreement between two or more parties.</enum>
                    </allowed-values>
                    <has-cardinality level="WARNING" target="rlink|base64" min-occurs="1"/>
                    <is-unique id="unique-resource-rlink-href" target="rlink">
                        <key-field target="@href"/>
                        <remarks>
                            <p>Ensures that each rlink item references a unique resource.</p>
                        </remarks>
                    </is-unique>
                    <is-unique id="unique-resource-base64-filename" target="base64">
                        <key-field target="@filename"/>
                        <remarks>
                            <p>Ensures that all base64 resources have a unique <code>filename</code>.
                            </p>
                        </remarks>
                    </is-unique>
                    <expect target=".[citation]" test="title">
                        <remarks>
                            <p>A <code>title</code> is required when a citation is provided.</p>
                        </remarks>
                    </expect>
                </constraint>
                <remarks>
                    <p>A resource can be used in two ways. 1) it may point to an specific retrievable network resource using a <code>rlink</code>, or 2) it may be included as an attachment using a <code>base64</code>. A resource may contain multiple <code>rlink</code> and <code>base64</code> entries that represent alternative download locations (rlink) and attachments (base64) for the same resource. Both rlink and base64 allow for a <code>media-type</code> to be specified, which is used to distinguish between different representations of the same resource (e.g., Microsoft Word, PDF). When multiple <code>rlink</code> and <code>base64</code> items are included for a given resource, all items must contain equivalent information. This allows the document consumer to choose a preferred item to process based on a the selected item's <code>media-type</code>. This is extremely important when the items represent OSCAL content that is represented in alternate formats (i.e., XML, JSON, YAML), allowing the same OSCAL data to be processed from any of the available formats indicated by the items.</p>
                    <p>When a resource includes a citation, then the <code>title</code> and <code>citation</code> properties must both be included.</p>
                </remarks>
            </define-assembly>
        </model>
        <constraint>
            <index name="index-back-matter-resource" target="resource">
                <key-field target="@uuid"/>
            </index>
        </constraint>
        <remarks>
            <p>Provides a collection of identified <code>resource</code> objects that can be referenced by a <code>link</code> with a <code>rel</code> value of "reference" and an <code>href</code> value that is a fragment "#" followed by a reference to a reference identifier. Other specialized link "rel" values also use this pattern when indicated in that context of use.</p>
        </remarks>
        <example>
            <!-- TODO: revisit this example -->
            <description>Use of link, citation, and resource</description>
            <remarks>
                <p>The following is a contrived example to show the use of link, citation, and resource.</p>
            </remarks>
            <o:profile xmlns:o="http://csrc.nist.gov/ns/oscal/example">
                <o:metadata>
                    <o:link rel="citation" href="#resource1">My citation</o:link>
                </o:metadata>
                <o:back-matter>
                    <o:resource id="resource1">
                        <o:rlink href="https://example.org/some-resource"/>
                    </o:resource>
                </o:back-matter>
            </o:profile>
        </example>
    </define-assembly>

    <!-- ##################### -->
    <!-- # Global constructs # -->
    <!-- ##################### -->
    <define-assembly name="property">
        <formal-name>Property</formal-name>
        <description>An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.</description>
        <use-name>prop</use-name>
        <define-flag name="name" as-type="token" required="yes">
            <formal-name>Property Name</formal-name>
            <description>A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.</description>
            <constraint>
                <allowed-values allow-other="yes">
                    <enum value="marking">A label or descriptor that is tied to a sensitivity or classification marking system. An optional class can be used to define the specific marking system used for the associated value.</enum>
                </allowed-values>
            </constraint>
        </define-flag>
        <define-flag name="uuid" as-type="uuid">
            <formal-name>Property Universally Unique Identifier</formal-name>
            <!-- identifier declaration -->
            <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a>, <a href="/concepts/identifier-use/#globally-unique">globally unique</a> identifier with <a href="/concepts/identifier-use/#cross-instance">cross-instance</a> scope that can be used to reference this defined property elsewhere in <a href="/concepts/identifier-use/#scope">this or other OSCAL instances</a>. This UUID should be assigned <a href="/concepts/identifier-use/#consistency">per-subject</a>, which means it should be consistently used to identify the same subject across revisions of the document.</description>
        </define-flag>
        <!-- CHANGED: data type to uri -->
        <define-flag name="ns" as-type="uri">
            <!-- CHANGED: data type to uri -->
            <formal-name>Property Namespace</formal-name>
            <description>A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.</description>
            <remarks>
                <p>Provides a means to segment the value space for the <code>name</code>, so that different organizations and individuals can assert control over the allowed names and associated values used in a property. This allows the semantics associated with a given name/value pair to be defined on an organization-by-organization basis.</p>
                <p>An organization MUST use a URI that they have control over. e.g., a domain registered to the organization in a URI, a registered uniform resource names (URN) namespace.</p>
                <p>When a <code>ns</code> is not provided, its value should be assumed to be <code>http://csrc.nist.gov/ns/oscal</code> and the name should be a name defined by the associated OSCAL model.</p>
            </remarks>
        </define-flag>
        <define-flag name="value" as-type="string" required="yes">
            <formal-name>Property Value</formal-name>
            <description>Indicates the value of the attribute, characteristic, or quality.</description>
        </define-flag>
        <define-flag name="class" as-type="token">
            <formal-name>Property Class</formal-name>
            <description>A textual label that provides a sub-type or characterization of the property's <code>name</code>. This can be used to further distinguish or discriminate between the semantics of multiple properties of the same object with the same <code>name</code> and <code>ns</code>.
            </description>
            <remarks>
                <p>A <code>class</code> can be used in validation rules to express extra constraints over named items of a specific <code>class</code> value.</p>
            </remarks>
        </define-flag>
        <model>
            <field ref="remarks" in-xml="WITH_WRAPPER"/>
        </model>
        <remarks>
            <p>Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.</p>
            <p>Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.</p>
        </remarks>
    </define-assembly>

    <define-assembly name="link">
        <formal-name>Link</formal-name>
        <description>A reference to a local or remote resource</description>
        <define-flag name="href" as-type="uri-reference" required="yes">
            <formal-name>Hypertext Reference</formal-name>
            <description>A resolvable URL reference to a resource.</description>
            <remarks>
                <p>The value of the <code>href</code> can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a <code>back-matter</code>
                    <code>resource</code> in the same document.</p>
                <!-- TODO: Add a link to "within the scope of the containing OSCAL document" to point to documentation of identification scopes" -->
                <p>If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references an identified <code>resource</code> in the document's <code>back-matter</code> or another object that is within the scope of the containing OSCAL document.</p>
                <p>If an internet resource is used, the <code>href</code> value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.</p>
            </remarks>
        </define-flag>
        <define-flag name="rel" as-type="token">
            <formal-name>Relation</formal-name>
            <description>Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.</description>
            <constraint>
                <allowed-values allow-other="yes">
                    <enum value="reference">Reference</enum>
                </allowed-values>
            </constraint>
        </define-flag>
        <flag ref="media-type">
            <remarks>
                <p>The <code>media-type</code> provides a hint about the content model of the referenced resource. A valid entry from the <a href="https://www.iana.org/assignments/media-types/media-types.xhtml">IANA Media Types registry</a> SHOULD be used.</p>
            </remarks>
        </flag>
        <model>
            <define-field name="text" as-type="markup-line">
                <formal-name>Link Text</formal-name>
                <description>A textual label to associate with the link, which may be used for presentation in a tool.</description>
            </define-field>
        </model>
        <constraint>
            <matches target=".[@rel=('reference') and starts-with(@href,'#')]/@href" datatype="uri-reference"/>
            <index-has-key name="index-back-matter-resource" target=".[@rel=('reference') and starts-with(@href,'#')]">
                <key-field target="@href" pattern="#(.*)"/>
            </index-has-key>
            <matches target=".[@rel=('reference') and not(starts-with(@href,'#'))]/@href" datatype="uri"/>
        </constraint>
        <remarks>
            <p>To provide a cryptographic hash for a remote target resource, a local reference to a back matter <code>resource</code> is needed. The resource allows one or more hash values to be provided using the <code>rlink/hash</code> object.</p>
            <p>The OSCAL <code>link</code> is a roughly based on the HTML <a href="https://www.w3.org/TR/html401/struct/links.html#edef-LINK">link element</a>.
            </p>
        </remarks>
        <example>
            <description>Providing for link integrity</description>
            <remarks>
                <p>The following is a contrived example to show the use of link, citation, and resource.</p>
            </remarks>
            <o:oscal xmlns:o="http://csrc.nist.gov/ns/oscal/example">
                <o:link rel="reference" href="#resource1">My Hashed Resource</o:link>
        ...snip...
                <o:back-matter>
                    <o:resource id="resource1">
                        <o:rlink href="https://example.org/some-resource">
                            <o:hash algorithm="sha512">C2E9C1..snip..F88D2E</o:hash>
                        </o:rlink>
                    </o:resource>
                </o:back-matter>
            </o:oscal>
        </example>
    </define-assembly>

    <define-assembly name="responsible-party">
        <formal-name>Responsible Party</formal-name>
        <description>A reference to a set of organizations or persons that have responsibility for performing a referenced role in the context of the containing object.</description>
        <define-flag required="yes" name="role-id" as-type="token">
            <formal-name>Responsible Role</formal-name>
            <!-- identifier reference -->
            <description>A <a href="/concepts/identifier-use/#human-oriented">human-oriented</a> identifier reference to <code>roles</code> served by the user.</description>
        </define-flag>
        <model>
            <field ref="party-uuid" min-occurs="1" max-occurs="unbounded">
                <group-as name="party-uuids" in-json="ARRAY"/>
                <remarks>
                    <p>Specifies one or more parties that are responsible for performing the associated <code>role</code>.
                    </p>
                </remarks>
            </field>
            <assembly ref="property" max-occurs="unbounded">
                <group-as name="props" in-json="ARRAY"/>
            </assembly>
            <assembly ref="link" max-occurs="unbounded">
                <group-as name="links" in-json="ARRAY"/>
            </assembly>
            <field ref="remarks" in-xml="WITH_WRAPPER"/>
        </model>
        <constraint>
            <index-has-key name="index-metadata-role-id" target=".">
                <key-field target="@role-id"/>
            </index-has-key>
            <index-has-key name="index-metadata-party-uuid" target="party-uuid">
                <key-field target="."/>
            </index-has-key>
        </constraint>
    </define-assembly>
    <define-assembly name="responsible-role">
        <formal-name>Responsible Role</formal-name>
        <description>A reference to one or more roles with responsibility for performing a function relative to the containing object.</description>
        <define-flag name="role-id" as-type="token" required="yes">
            <formal-name>Responsible Role ID</formal-name>
            <!-- identifier reference -->
            <description>A <a href="/concepts/identifier-use/#human-oriented">human-oriented</a> identifier reference to <code>roles</code> responsible for the business function.</description>
        </define-flag>
        <model>
            <assembly ref="property" max-occurs="unbounded">
                <group-as name="props" in-json="ARRAY"/>
            </assembly>
            <assembly ref="link" max-occurs="unbounded">
                <group-as name="links" in-json="ARRAY"/>
            </assembly>
            <field ref="party-uuid" max-occurs="unbounded">
                <group-as name="party-uuids" in-json="ARRAY"/>
            </field>
            <field ref="remarks" in-xml="WITH_WRAPPER"/>
        </model>
    </define-assembly>

    <define-field name="hash">
        <!-- TODO: need a hex binary type. Maybe base64 binary? -->
        <formal-name>Hash</formal-name>
        <description>A representation of a cryptographic digest generated over a resource using a specified hash algorithm.</description>
        <json-value-key>value</json-value-key>
        <define-flag name="algorithm" as-type="string" required="yes">
            <formal-name>Hash algorithm</formal-name>
            <description>Method by which a hash is derived</description>
            <constraint>
                <allowed-values allow-other="yes">
                    <enum value="SHA-224">The SHA-224 algorithm as defined by <a href="https://doi.org/10.6028/NIST.FIPS.180-4">NIST FIPS 180-4</a>.
                    </enum>
                    <enum value="SHA-256">The SHA-256 algorithm as defined by <a href="https://doi.org/10.6028/NIST.FIPS.180-4">NIST FIPS 180-4</a>.
                    </enum>
                    <enum value="SHA-384">The SHA-384 algorithm as defined by <a href="https://doi.org/10.6028/NIST.FIPS.180-4">NIST FIPS 180-4</a>.
                    </enum>
                    <enum value="SHA-512">The SHA-512 algorithm as defined by <a href="https://doi.org/10.6028/NIST.FIPS.180-4">NIST FIPS 180-4</a>.
                    </enum>
                    <enum value="SHA3-224">The SHA3-224 algorithm as defined by <a href="https://doi.org/10.6028/NIST.FIPS.202">NIST FIPS 202</a>.
                    </enum>
                    <enum value="SHA3-256">The SHA3-256 algorithm as defined by <a href="https://doi.org/10.6028/NIST.FIPS.202">NIST FIPS 202</a>.
                    </enum>
                    <enum value="SHA3-384">The SHA3-384 algorithm as defined by <a href="https://doi.org/10.6028/NIST.FIPS.202">NIST FIPS 202</a>.
                    </enum>
                    <enum value="SHA3-512">The SHA3-512 algorithm as defined by <a href="https://doi.org/10.6028/NIST.FIPS.202">NIST FIPS 202</a>.
                    </enum>
                </allowed-values>
            </constraint>
            <remarks>
                <p>Any other value used MUST be a value defined in the W3C <a href="http://www.w3.org/TR/xmlsec-algorithms/#digest-method">XML Security Algorithm Cross-Reference</a> Digest Methods (W3C, April 2013) or <a href="https://tools.ietf.org/html/rfc6931#section-2.1.5">RFC 6931 Section 2.1.5</a> New SHA Functions.</p>
            </remarks>
        </define-flag>
        <remarks>
            <p>A hash value can be used to authenticate that a referenced resource is the same resources as was pointed to by the author of the reference.</p>
        </remarks>
    </define-field>

    <define-flag name="media-type" as-type="string">
        <formal-name>Media Type</formal-name>
        <description>Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) <a href="https://www.iana.org/assignments/media-types/media-types.xhtml">Media Types Registry</a>.
        </description>
        <remarks>
            <p>The IANA Media Types Registry should be used, but currently there is no official media type for YAML. OSCAL documents should specify <code>application/yaml</code> for general YAML content, or <code>application/oscal+yaml</code> for YAML-based OSCAL content. This approach aligns with use of a structured name suffix, per <a href="https://www.rfc-editor.org/rfc/rfc6838.html#section-4.2.8">RFC 6838 Section 4.2.8</a>.</p>
        </remarks>
    </define-flag>

    <define-field name="remarks" as-type="markup-multiline">
        <formal-name>Remarks</formal-name>
        <description>Additional commentary on the containing object.</description>
    </define-field>

    <!-- #################### -->
    <!-- # Local constructs # -->
    <!-- #################### -->
    <define-field name="published" as-type="dateTime-with-timezone" scope="local">
        <formal-name>Publication Timestamp</formal-name>
        <description>The date and time the document was published. The date-time value must be formatted according to <a href="https://tools.ietf.org/html/rfc3339">RFC 3339</a> with full time and time zone included.</description>
        <remarks>
            <p>This value represents the point in time when the OSCAL document was published. Typically, this date value will be machine generated at the time the containing document is published.</p>
            <p>In some cases, an OSCAL document may be derived from some source material in a different format. In such a case, the <code>published</code> value should indicate when the OSCAL document was published, not the source material. Where necessary, the publication date of the original source material can be captured as a named property or custom metadata construct.</p>
            <p>A publisher of OSCAL content can use this data point along with its siblings <code>last-modified</code> and <code>version</code> to establish a sequence of successive revisions of a given OSCAL-based publication. The metadata for previous revisions can be represented as a <code>revision</code> in this object.</p>
        </remarks>
    </define-field>

    <define-field name="last-modified" as-type="dateTime-with-timezone" scope="local">
        <formal-name>Last Modified Timestamp</formal-name>
        <description>The date and time the document was last modified. The date-time value must be formatted according to <a href="https://tools.ietf.org/html/rfc3339">RFC 3339</a> with full time and time zone included.</description>
        <remarks>
            <p>This value represents the point in time when the OSCAL document was last updated, or at the point of creation the creation date. Typically, this date value will be machine generated at time of creation or modification.</p>
            <p>In some cases, an OSCAL document may be derived from some source material in a different format. In such a case, the <code>last-modified</code> value should indicate the modification time of the OSCAL document, not the source material.</p>
            <p>A publisher of OSCAL content can use this data point along with its siblings <code>published</code> and <code>version</code> to establish a sequence of successive revisions of a given OSCAL-based publication. The metadata for previous revisions can be represented as a <code>revision</code> in this object.</p>
        </remarks>
    </define-field>
    <define-field name="version" scope="local">
        <formal-name>Document Version</formal-name>
        <description>A string used to distinguish the current version of the document from other previous (and future) versions.</description>
        <remarks>
            <p>A version string may be a release number, sequence number, date, or other identifier suffcient to distinguish between different document versions. This version is typically set by the document owner or by the tool used to maintain the content.</p>
            <p>While not required, it is recommended that OSCAL content authors use <a href="https://semver.org/spec/v2.0.0.html">Semantic Versioning</a> as a format for version strings. This allows for the easy identification of a version tree consisting of major, minor, and patch numbers.</p>
            <p>A publisher of OSCAL content can use this data point along with its siblings <code>published</code> and <code>last-modified</code> to establish a sequence of successive revisions of a given OSCAL-based publication. The metadata for previous revisions can be represented as a <code>revision</code> in this object.</p>
        </remarks>
    </define-field>
    <define-field name="oscal-version" scope="local">
        <formal-name>OSCAL version</formal-name>
        <description>The OSCAL model version the document was authored against.</description>
        <remarks>
            <p>Indicates the version of the OSCAL model to which this data set conforms, for example <q>1.1.0</q> or <q>1.0.0-M1</q>. That can be used as a hint by a tool to indicate which version of the OSCAL XML or JSON schema to use for validation.</p>
        </remarks>
    </define-field>

    <define-field name="email-address" as-type="email" scope="local">
        <formal-name>Email Address</formal-name>
        <description>An email address as defined by <a href="https://tools.ietf.org/html/rfc5322#section-3.4.1">RFC 5322 Section 3.4.1</a>.
        </description>
    </define-field>

    <define-field name="telephone-number" scope="local">
        <formal-name>Telephone Number</formal-name>
        <description>Contact number by telephone.</description>
        <json-value-key>number</json-value-key>
        <define-flag name="type">
            <formal-name>type flag</formal-name>
            <description>Indicates the type of phone number.</description>
            <constraint>
                <allowed-values allow-other="yes">
                    <enum value="home">A home phone number.</enum>
                    <enum value="office">An office phone number.</enum>
                    <enum value="mobile">A mobile phone number.</enum>
                </allowed-values>
            </constraint>
        </define-flag>
    </define-field>

    <define-assembly name="address" scope="local">
        <formal-name>Address</formal-name>
        <description>A postal address for the location.</description>
        <flag ref="location-type">
            <use-name>type</use-name>
        </flag>
        <model>
            <field ref="addr-line" max-occurs="unbounded">
                <!-- CHANGE: "postal-address" to "addr-lines" -->
                <group-as name="addr-lines" in-json="ARRAY"/>
            </field>
            <define-field name="city">
                <formal-name>City</formal-name>
                <description>City, town or geographical region for the mailing address.</description>
            </define-field>
            <define-field name="state">
                <formal-name>State</formal-name>
                <description>State, province or analogous geographical region for mailing address</description>
            </define-field>
            <define-field name="postal-code">
                <formal-name>Postal Code</formal-name>
                <description>Postal or ZIP code for mailing address</description>
            </define-field>
            <define-field name="country">
                <formal-name>Country Code</formal-name>
                <description>The ISO 3166-1 alpha-2 country code for the mailing address.</description>
                <constraint>
                    <matches target="." regex="[A-Z]{2}"/>
                </constraint>
            </define-field>
            <!-- More address stuff -->
        </model>
    </define-assembly>
    <define-field name="addr-line" scope="local">
        <formal-name>Address line</formal-name>
        <description>A single line of an address.</description>
    </define-field>

    <define-flag name="location-type" as-type="token" scope="local">
        <formal-name>Address Type</formal-name>
        <description>Indicates the type of address.</description>
        <constraint>
            <allowed-values allow-other="yes">
                <enum value="home">A home address.</enum>
                <enum value="work">A work address.</enum>
            </allowed-values>
        </constraint>
    </define-flag>

    <define-field name="document-id" scope="local">
        <!-- This is an id because the idenfier is assigned and managed externally by humans. -->
        <formal-name>Document Identifier</formal-name>
        <!-- identifier declaration -->
        <description>A document identifier qualified by an identifier <code>scheme</code>. A document identifier provides a <a href="/concepts/identifier-use/#globally-unique">globally unique</a> identifier with a <a href="/concepts/identifier-use/#cross-instance">cross-instance</a> scope that is used for a group of documents that are to be treated as different versions of the same document. If this element does not appear, or if the value of this element is empty, the value of "document-id" is equal to the value of the "uuid" flag of the top-level root element.</description>
        <json-value-key>identifier</json-value-key>
        <!-- CHANGE: "type" to "scheme" -->
        <!-- CHANGE: "Required" to "no" -->
        <define-flag name="scheme" as-type="uri" required="no">
            <formal-name>Document Identification Scheme</formal-name>
            <description>Qualifies the kind of document identifier using a URI. If the scheme is not provided the value of the element will be interpreted as a string of characters. </description>
            <constraint>
                <allowed-values allow-other="yes">
                    <enum value="http://www.doi.org/">A <a href="https://www.doi.org/hb.html">Digital Object Identifier</a> (DOI); use is preferred, since this allows for retrieval of a full bibliographic record.</enum>
                </allowed-values>
            </constraint>
        </define-flag>
        <remarks>
            <p>This element is optional, but it will always have a valid value, as if it is missing the value of "document-id" is assumed to be equal to the UUID of the root. This requirement allows for document creators to retroactively link an update to the original version, by providing a document-id on the new document that is equal to the uuid of the original document.</p>
        </remarks>
    </define-field>


    <!--   <define-field name="description" as-type="markup-multiline">
      <formal-name>Description</formal-name>
      <description>A description supporting the parent item.</description>
   </define-field>
-->
</METASCHEMA>