oscal_component_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"?>
<!DOCTYPE METASCHEMA [
  <!ENTITY allowed-values-responsible-roles-operations SYSTEM "./shared-constraints/allowed-values-responsible-roles-operations.ent">
  <!ENTITY allowed-values-responsible-roles-component-production SYSTEM "./shared-constraints/allowed-values-responsible-roles-component-production.ent">
  <!ENTITY allowed-values-property-name-asset-type-values SYSTEM "./shared-constraints/allowed-values-property-name-asset-type-values.ent">
  <!ENTITY allowed-values-component_component_property-name SYSTEM "./shared-constraints/allowed-values-component_component_property-name.ent">
  <!ENTITY allowed-values-component_component_software SYSTEM "./shared-constraints/allowed-values-component_component_software.ent">
  <!ENTITY allowed-values-component_component_service SYSTEM "./shared-constraints/allowed-values-component_component_service.ent">
  <!ENTITY allowed-values-component_inventory-item_property-name SYSTEM "./shared-constraints/allowed-values-component_inventory-item_property-name.ent">
  <!ENTITY allowed-values-component_component_link-rel SYSTEM "./shared-constraints/allowed-values-component_component_link-rel.ent">
  <!ENTITY allowed-values-component-type SYSTEM "./shared-constraints/allowed-values-component-type.ent">
]>
<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">
  <schema-name>OSCAL Component Definition Model</schema-name>
  <schema-version>1.0.0</schema-version>
  <short-name>oscal-component-definition</short-name>
  <namespace>http://csrc.nist.gov/ns/oscal/1.0</namespace>
  <json-base-uri>http://csrc.nist.gov/ns/oscal</json-base-uri>
  <remarks>
    <p>The OSCAL Component Definition Model can be used to describe the implementation of controls in a <code>component</code> or a set of components grouped as a <code>capability</code>. A component can be either a <em>technical component</em>, or a <em>documentary component</em>. A technical component is a component that is implemented in hardware (physical or virtual) or software. A documentary component is a component implemented in a document, such as a process, procedure, or policy.</p>
    <p>The root of the OSCAL Implementation Component format is <code>component-definition</code>.
    </p>
    <p>NOTE: This documentation is a work in progress. As a result, documentation for many of the information elements is missing or incomplete.</p>
  </remarks>

  <import href="oscal_implementation-common_metaschema.xml"/>

  <define-assembly name="component-definition">
    <formal-name>Component Definition</formal-name>
    <description>A collection of component descriptions, which may optionally be grouped by capability.</description>
    <root-name>component-definition</root-name>
    <define-flag name="uuid" as-type="uuid" required="yes">
      <formal-name>Component Definition 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 component definition elsewhere in <a href="/concepts/identifier-use/#component-definition-identifiers">this or other OSCAL instances</a>. The locally defined <em>UUID</em> of the <code>component definition</code> can be used to reference the data item locally or globally (e.g., in an imported 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>
      <assembly ref="metadata" min-occurs="1"/>
      <assembly ref="import-component-definition" max-occurs="unbounded">
        <group-as name="import-component-definitions" in-json="ARRAY"/>
      </assembly>
      <assembly ref="defined-component" max-occurs="unbounded">
        <use-name>component</use-name>
        <group-as name="components" in-json="ARRAY"/>
      </assembly>
      <assembly ref="capability" max-occurs="unbounded">
        <group-as name="capabilities" in-json="ARRAY"/>
      </assembly>
      <assembly ref="back-matter"/>
    </model>
    <constraint>
      <index name="index-system-component-uuid" target="component">
        <key-field target="@uuid"/>
        <remarks>
          <p>Since multiple <code>component</code> entries can be provided, each component must have a unique <code>uuid</code>.</p>
        </remarks>
      </index>
      <is-unique id="unique-component-definition-capability" target="capability">
        <key-field target="@uuid"/>
        <remarks>
          <p>A given <code>component</code> must not be referenced more than once within the same <code>capability</code>.</p>
        </remarks>
      </is-unique>
    </constraint>
  </define-assembly>

  <define-assembly name="import-component-definition">
    <formal-name>Import Component Definition</formal-name>
    <description>Loads a component definition from another resource.</description>
    <define-flag name="href" as-type="uri-reference" required="yes">
      <formal-name>Hyperlink Reference</formal-name>
      <description>A link to a resource that defines a set of components and/or capabilities to import into this collection.</description>
    </define-flag>
  </define-assembly>

  <define-assembly name="defined-component">
    <formal-name>Component</formal-name>
    <description>A defined component that can be part of an implemented system.</description>
    <define-flag name="uuid" as-type="uuid" required="yes">
      <formal-name>Component 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 component elsewhere in <a href="/concepts/identifier-use/#component-definition-identifiers">this or other OSCAL instances</a>. The locally defined <em>UUID</em> of the <code>component</code> can be used to reference the data item locally or globally (e.g., in an imported 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>
    <flag ref="defined-component-type" required="yes">
      <use-name>type</use-name>
    </flag>
    <model>
      <define-field name="title" as-type="markup-line" min-occurs="1">
        <formal-name>Component Title</formal-name>
        <description>A human readable name for the component.</description>
      </define-field>
      <define-field name="description" as-type="markup-multiline" min-occurs="1" in-xml="WITH_WRAPPER">
        <formal-name>Component Description</formal-name>
        <description>A description of the component, including information about its function.</description>
      </define-field>
      <define-field name="purpose" as-type="markup-line">
        <formal-name>Purpose</formal-name>
        <description>A summary of the technological or business purpose of the component.</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>
      <assembly ref="responsible-role" max-occurs="unbounded">
        <group-as name="responsible-roles" in-json="ARRAY"/>
      </assembly>
      <assembly ref="protocol" max-occurs="unbounded">
        <group-as name="protocols" in-json="ARRAY"/>
        <remarks>
          <p>Used for <code>service</code> components to define the protocols supported by the service.</p>
        </remarks>
      </assembly>

      <assembly ref="control-implementation" max-occurs="unbounded">
        <group-as name="control-implementations" in-json="ARRAY"/>
      </assembly>
      <!--
         <assembly ref="configuration" max-occurs="unbounded">
           <group-as name="configurations" in-json="BY_KEY" />
         </assembly>
         <assembly ref="artifact" max-occurs="unbounded">
           <group-as name="artifacts" in-json="BY_KEY" />
         </assembly>
-->
      <field ref="remarks" in-xml="WITH_WRAPPER"/>
    </model>
    <constraint>
      <allowed-values target="prop/@name" allow-other="yes">
        <!-- ========================================================================================================== -->
        <!-- = Changes to the following values need to be synced with component in the SSP and component metaschemas. = -->
        <!-- CHANGED (BJR): Done -->
        <!-- ========================================================================================================== -->
            &allowed-values-component_component_property-name;
            &allowed-values-component_inventory-item_property-name;

                    <!-- CHANGE: @name="date-released" changed to @name="release-date" -->
      </allowed-values>

      <allowed-values target="link/@rel" allow-other="yes">
        <!-- ========================================================================================================== -->
        <!-- = Changes to the following values need to be synced with component in the SSP and component metaschemas. = -->
        <!-- CHANGED (BJR): Done -->
        <!-- ========================================================================================================== -->
            &allowed-values-component_component_link-rel;
        <enum value="uses-network">This component uses the network provided by the identified network component.</enum>
      </allowed-values>

      <allowed-values target="responsible-role/@role-id|control-implementation/implemented-requirement/responsible-role/@role-id|control-implementation/implemented-requirement/statement/responsible-role/@role-id" allow-other="yes">
        <!-- ========================================================================================================== -->
        <!-- = Changes to the following values need to be synced with component in the SSP and component metaschemas. = -->
        <!-- CHANGED (BJR): Done -->
        <!-- ========================================================================================================== -->
            &allowed-values-responsible-roles-operations;
            &allowed-values-responsible-roles-component-production;
      </allowed-values>

      <allowed-values target="prop[@name='asset-type']/@value">
            &allowed-values-property-name-asset-type-values;
      </allowed-values>

      <!-- ========================================================================================================== -->
      <!-- = TODO: The following was copied from implementation-common as-is and should probably be setup with  = -->
      <!-- =       shared constraints; however, the values are highly static (yes/no, internal/external). -->
      <!-- =       Can be changed later with no breaking impact. -->
      <allowed-values target="prop[@name='allows-authenticated-scan']/@value">
        <enum value="yes">The component allows an authenticated scan.</enum>
        <enum value="no">The component does not allow an authenticated scan.</enum>
      </allowed-values>

      <allowed-values target="prop[@name='virtual']/@value">
        <enum value="yes">The component is virtualized.</enum>
        <enum value="no">The component is not virtualized.</enum>
      </allowed-values>

      <allowed-values target="prop[@name='public']/@value">
        <enum value="yes">The component is publicly accessible.</enum>
        <enum value="no">The component is not publicly accessible.</enum>
      </allowed-values>

      <allowed-values target="prop[@name='implementation-point']/@value">
        <enum value="internal">The component is implemented within the system boundary.</enum>
        <enum value="external">The component is implemented outside the system boundary.</enum>
      </allowed-values>
      <!-- ========================================================================================================== -->

      <index-has-key name="index-metadata-location-uuid" target="prop[@name='physical-location']">
        <key-field target="@value"/>
      </index-has-key>

      <matches target="prop[@name='inherited-uuid']/@value" datatype="uuid" />
      <matches target="prop[@name='release-date']/@value" datatype="date"/>

      <!-- ========================================================================================================== -->
      <!-- = Changes to the following values need to be synced with component in the SSP and component metaschemas. = -->
      <!-- CHANGED (BJR): Done -->
      <!-- ========================================================================================================== -->

      <!-- ========================================================================================================== -->
      <!-- = SOFTWARE: type='software' constraints                        = -->
      <!-- ========================================================================================================== -->
      <allowed-values target="(.)[@type='software']/prop/@name" allow-other="yes">
            &allowed-values-component_component_software;
      </allowed-values>

      <!-- ========================================================================================================== -->
      <!-- = SERVICE: type='service' constraints                        = -->
      <!-- ========================================================================================================== -->
      <allowed-values target="(.)[@type='service']/link/@rel" allow-other="yes">
            &allowed-values-component_component_service;
      </allowed-values>

      <expect target="." test="not(exists((.)[not(@type='service')]/protocol))"/>

      <!-- ========================================================================================================== -->
      <!-- = TODO: Consider whether INTERCONNECTION constraints are appropriate here.      = -->
      <!-- =       I'm not sure I see a use case for this, but doesn't break to add later. = -->
      <!-- =       If interconnection is not appropriate for component-defintion, we'll need different = -->
      <!-- =           component-type lists for the two models.                                        = -->
      <!-- ========================================================================================================== -->
      <is-unique id="unique-defined-component-responsible-role" target="responsible-role">
        <key-field target="@role-id"/>
        <remarks>
          <p>Since <code>responsible-role</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>
    </constraint>
    <remarks>
      <p>Components may be products, services, APIs, policies, processes, plans, guidance, standards, or other tangible items that enable security and/or privacy.</p>
      <p>The <code>type</code> indicates which of these component types is represented.</p>
      <p>A group of components may be aggregated into a <code>capability</code>. For example, an account management capability that consists of an account management process, and a Lightweight Directory Access Protocol (LDAP) software implementation.</p>
      <p>Capabilities are expressed by combining one or more components.</p>
    </remarks>
  </define-assembly>

  <define-flag name="defined-component-type" as-type="string">
    <formal-name>Component Type</formal-name>
    <description>A category describing the purpose of the component.</description>
    <constraint>
      <allowed-values allow-other="yes">
            &allowed-values-component-type;
      </allowed-values>
    </constraint>
  </define-flag>

  <define-assembly name="capability">
    <formal-name>Capability</formal-name>
    <description>A grouping of other components and/or capabilities.</description>
    <define-flag required="yes" name="uuid" as-type="uuid">
      <formal-name>Capability 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 capability elsewhere in <a href="/concepts/identifier-use/#component-definition-identifiers">this or other OSCAL instances</a>. The locally defined <em>UUID</em> of the <code>capability</code> can be used to reference the data item locally or globally (e.g., in an imported 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="name" as-type="string" required="yes">
      <formal-name>Capability Name</formal-name>
      <description>The capability's human-readable name.</description>
    </define-flag>
    <model>
      <define-field name="description" as-type="markup-multiline" min-occurs="1" in-xml="WITH_WRAPPER">
        <formal-name>Capability Description</formal-name>
        <description>A summary of the capability.</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>
      <assembly ref="incorporates-component" max-occurs="unbounded">
        <group-as name="incorporates-components" in-json="ARRAY"/>
      </assembly>
      <assembly ref="control-implementation" max-occurs="unbounded">
        <group-as name="control-implementations" in-json="ARRAY"/>
      </assembly>
      <field ref="remarks" in-xml="WITH_WRAPPER"/>
    </model>
    <constraint>
      <is-unique id="unique-component-definition-capability-incorporates-component" target="incorporates-component">
        <key-field target="@component-uuid"></key-field>
        <remarks>
          <p>A given <code>component</code> must not be referenced more than once within the same <code>capability</code>.</p>
        </remarks>
      </is-unique>
    </constraint>
  </define-assembly>
  <define-assembly name="incorporates-component">
    <formal-name>Incorporates Component</formal-name>
    <!-- TODO: needs a description -->
    <description>TBD</description>
    <define-flag required="yes" name="component-uuid" as-type="uuid">
      <formal-name>Component Reference</formal-name>
      <!-- Identifier Reference -->
      <description>A <a href="/concepts/identifier-use/#machine-oriented">machine-oriented</a> identifier reference to a <code>component</code>.</description>
    </define-flag>
    <model>
      <define-field name="description" as-type="markup-multiline" min-occurs="1" in-xml="WITH_WRAPPER">
        <formal-name>Component Description</formal-name>
        <description>A description of the component, including information about its function.</description>
      </define-field>
    </model>
  </define-assembly>

  <define-assembly name="control-implementation" scope="local">
    <formal-name>Control Implementation Set</formal-name>
    <description>Defines how the component or capability supports a set of controls.</description>
    <define-flag name="uuid" as-type="uuid" required="yes">
      <formal-name>Control Implementation Set 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 a set of implemented controls elsewhere in <a href="/concepts/identifier-use/#component-definition-identifiers">this or other OSCAL instances</a>. The locally defined <em>UUID</em> of the <code>control implementation set</code> can be used to reference the data item locally or globally (e.g., in an imported 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>
    <flag ref="source" required="yes">
      <remarks>
        <p>A URL reference to the source catalog or profile for which this component is implementing controls for.</p>
      </remarks>
    </flag>
    <model>
      <define-field name="description" as-type="markup-multiline" min-occurs="1" in-xml="WITH_WRAPPER">
        <formal-name>Control Implementation Description</formal-name>
        <description>A description of how the specified set of controls are implemented for the containing component or capability.</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>
      <assembly ref="set-parameter" max-occurs="unbounded">
        <group-as name="set-parameters" in-json="ARRAY"/>
      </assembly>
      <assembly ref="implemented-requirement" min-occurs="1" max-occurs="unbounded">
        <group-as name="implemented-requirements" in-json="ARRAY"/>
      </assembly>
    </model>
    <constraint>
      <is-unique id="unique-component-definition-control-implementation-set-parameter" target="set-parameter">
        <key-field target="@param-id"/>
        <remarks>
          <p>Since multiple <code>set-parameter</code> entries can be provided, each parameter must be set only once.</p>
        </remarks>
      </is-unique>
    </constraint>
    <remarks>
      <p>Use of <code>set-parameter</code> in this context, sets the parameter for all related controls referenced in an <code>implemented-requirement</code>. If the same parameter is also set in a specific <code>implemented-requirement</code>, then the new value will override this value.</p>
    </remarks>
  </define-assembly>
  <define-assembly name="implemented-requirement" scope="local">
    <formal-name>Control Implementation</formal-name>
    <description>Describes how the containing component or capability implements an individual control.</description>
    <define-flag name="uuid" as-type="uuid" required="yes">
      <formal-name>Control Implementation 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 a specific control implementation elsewhere in <a href="/concepts/identifier-use/#component-definition-identifiers">this or other OSCAL instances</a>. The locally defined <em>UUID</em> of the <code>control implementation</code> can be used to reference the data item locally or globally (e.g., in an imported 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>
    <flag ref="control-id" required="yes"/>
    <model>
      <define-field name="description" as-type="markup-multiline" min-occurs="1" in-xml="WITH_WRAPPER">
        <formal-name>Control Implementation Description</formal-name>
        <description>A description of how the specified control is implemented for the containing component or capability.</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>
      <assembly ref="set-parameter" max-occurs="unbounded">
        <group-as name="set-parameters" in-json="ARRAY"/>
      </assembly>
      <assembly ref="responsible-role" max-occurs="unbounded">
        <group-as name="responsible-roles" in-json="ARRAY"/>
      </assembly>
      <assembly ref="statement" max-occurs="unbounded">
        <group-as name="statements" in-json="ARRAY"/>
      </assembly>
      <field ref="remarks" in-xml="WITH_WRAPPER"/>
    </model>
    <constraint>
      <is-unique id="unique-component-definition-implemented-requirement-set-parameter" target="set-parameter">
        <key-field target="@param-id"/>
        <remarks>
          <p>Since multiple <code>set-parameter</code> entries can be provided, each parameter must be set only once.</p>
        </remarks>
      </is-unique>
      <is-unique id="unique-component-definition-implemented-requirement-responsible-role" target="responsible-role">
        <key-field target="@role-id"/>
        <remarks>
          <p>Since <code>responsible-role</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>
      <is-unique id="unique-component-definition-implemented-requirement-statement" target="statement">
        <key-field target="@statement-id"/>
        <remarks>
          <p>Since <code>statement</code> entries can be referenced using the statement's statement-id, each statement must be referenced only once.</p>
        </remarks>
      </is-unique>
    </constraint>
  </define-assembly>
  <define-assembly name="statement" scope="local">
    <formal-name>Control Statement Implementation</formal-name>
    <description>Identifies which statements within a control are addressed.</description>
    <flag ref="statement-id" required="yes">
      <remarks>
        <p>A reference to the specific implemented statement associated with a control.</p>
      </remarks>
    </flag>
    <define-flag name="uuid" as-type="uuid" required="yes">
      <formal-name>Control Statement Reference Universally Unique Identifier</formal-name>
      <!-- Identifier Reference -->
      <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 control statement elsewhere in <a href="/concepts/identifier-use/#component-definition-identifiers">this or other OSCAL instances</a>. The <em>UUID</em> of the <code>control statement</code> in the source OSCAL instance is sufficient to reference the data item locally or globally (e.g., in an imported OSCAL instance).</description>
    </define-flag>
    <model>
      <define-field name="description" as-type="markup-multiline" min-occurs="1" in-xml="WITH_WRAPPER">
        <formal-name>Statement Implementation Description</formal-name>
        <description>A summary of how the containing control statement is implemented by the component or capability.</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>
      <assembly ref="responsible-role" max-occurs="unbounded">
        <group-as name="responsible-roles" in-json="ARRAY"/>
      </assembly>
      <field ref="remarks" in-xml="WITH_WRAPPER"/>
    </model>
    <constraint>
      <is-unique id="unique-component-definition-statement-responsible-role" target="responsible-role">
        <key-field target="@role-id"/>
        <remarks>
          <p>Since <code>responsible-role</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>
    </constraint>
  </define-assembly>
</METASCHEMA>