DRAFT: Update catalog & profile metaschema documentation (#51)

Adjustments based on model review. * Update catalog & profile metaschema documentation * Add props to control identifier Co-authored-by: David Waltermire <[email protected]>
david-waltermire · Aug 23, 2022 · d15a163 · d15a163
1 parent c7e73ee
commit d15a163
Show file tree

Hide file tree

Showing 3 changed files with 76 additions and 33 deletions.
diff --git a/src/metaschema/oscal_catalog_metaschema.xml b/src/metaschema/oscal_catalog_metaschema.xml
@@ -53,9 +53,11 @@
             <constraint>
                   <allowed-values target="metadata/prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name">
                         <enum value="resolution-tool">The tool used to produce a resolved profile.</enum>
+                        <enum value="source-profile-uuid">The document-level <code>uuid</code> of the source profile from which the catalog was produced by <a href="https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/">profile resolution</a>.</enum>
                   </allowed-values>
                   <allowed-values target="metadata/link/@rel">
                         <enum value="source-profile">The profile from which the catalog was produced by <a href="https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/">profile resolution</a>.</enum>
+                        <enum value="source-profile-uuid">The document-level <code>uuid</code> of the profile from which the catalog was produced by <a href="https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/">profile resolution</a>.</enum>
                   </allowed-values>
                   <index name="catalog-parts" target="//part" >
                         <key-field target="@id"/>
@@ -146,8 +148,8 @@
                   </allowed-values>
             </constraint>
             <remarks>
-                  <p>Catalogs can use a <code>group</code> to collect related controls into a single grouping. That can be useful to group controls into a family or other logical grouping.</p>
-                  <p>A <code>group</code> may have its own properties, statements, parameters, and references, which are inherited by all members of that group.</p>
+                  <p>Catalogs can use the catalog <code>group</code> construct to organize related controls into a single grouping, such as a family of controls or other logical organizational structure.</p>
+                  <p>A <code>group</code> may have its own properties, statements, parameters, and references, which are inherited by all controls of that are a member of the group.</p>
             </remarks>
             <example>
                   <group xmlns="http://csrc.nist.gov/ns/oscal/1.0" id="xyz">
@@ -166,7 +168,12 @@
                   <!-- This is an id because the idenfier is managed externally. -->
                   <formal-name>Control Identifier</formal-name>
                   <!-- Identifier Declaration -->
-                  <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/#instance">instance</a> scope that can be used to reference this control elsewhere <a href="/concepts/identifier-use/#catalog-identifiers">in this and other OSCAL instances (e.g., profiles)</a>. 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 control across revisions of the document.</description>
+                  <description>Identifies a control such that it can be referenced in the defining catalog and other OSCAL instances (e.g., profiles).</description>
+                  <prop name="value-type" value="identifier"/>
+                  <prop name="identifier-type" value="human-oriented"/>
+                  <prop name="identifier-uniqueness" value="local"/>
+                  <prop name="identifier-scope" value="instance"/>
+                  <prop name="identifier-persistence" value="per-subject"/>
             </define-flag>
             <define-flag name="class" as-type="token">
                   <formal-name>Control Class</formal-name>
@@ -232,7 +239,14 @@
                         <enum value="required">The link identifies another control that must be present if this control is present.</enum>
                         <enum value="incorporated-into">The link identifies other control content where this control content is now addressed.</enum>
                         <enum value="moved-to">The containing control definition was moved to the referenced control.</enum>
+                        <remark>
+                              <!-- 
+                                    TODO: Clarify that link@rel (e.g., where value is related, required, incorporated-into, moved-to) is only intended for control-to-control associations.
+                                    Add a corresponding constraint.
+                              -->
+                        </remark>
                   </allowed-values>
+                  <!-- TODO: add constraint for link/@rel controls (where value is either related, required, incorporated-into, moved-to) to ensure the control exists in current or linked catalog -->
                   <!-- TODO: add expect constraint to check for controls that reference themselves -->
                   <index-has-key name="catalog-controls" target="link[@rel=('related','required','incorporated-into','moved-to') and starts-with(@href,'#')]">
                         <key-field target="@href" pattern="#(.*)"/>

diff --git a/src/metaschema/oscal_component_metaschema.xml b/src/metaschema/oscal_component_metaschema.xml
@@ -19,10 +19,11 @@
   <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>
+    <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>.</p>
+    <p>A technical component is a component that is implemented in hardware (physical or virtual) or software. Suppliers may document components in an OSCAL component definition that describes the implementation of controls in their hardware and software.</p>
+    <p>A documentary component is a component implemented for a documented process, procedure, or policy.  Suppliers may document components in an OSCAL component definition that describes the implementation of controls in their process, procedure, or policy.</p>
+    <p>The information provided by a technical or documentary component can be used by component consumers to provide starting narratives for documenting control implementations in an OSCAL SSP.</p>
+    <p>The root of the OSCAL Implementation Layer Component Definition model is <code>component-definition</code>.</p>
   </remarks>
 
   <import href="oscal_implementation-common_metaschema.xml"/>
@@ -34,7 +35,12 @@
     <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>
+      <description>Provides a globally unique means to identify a given component definition instance.</description>
+      <prop name="value-type" value="identifier"/>
+      <prop name="identifier-type" value="machine-oriented"/>
+      <prop name="identifier-uniqueness" value="global"/>
+      <prop name="identifier-scope" value="cross-instance"/>
+      <prop name="identifier-persistence" value="change-on-write"/>
     </define-flag>
     <model>
       <assembly ref="metadata" min-occurs="1"/>
@@ -81,7 +87,12 @@
     <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>
+      <description>Provides a globally unique means to identify a given component.</description>
+      <prop name="value-type" value="identifier"/>
+      <prop name="identifier-type" value="machine-oriented"/>
+      <prop name="identifier-uniqueness" value="global"/>
+      <prop name="identifier-scope" value="cross-instance"/>
+      <prop name="identifier-persistence" value="per-subject"/>
     </define-flag>
     <flag ref="defined-component-type" required="yes">
       <use-name>type</use-name>
@@ -252,7 +263,12 @@
     <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>
+      <description>Provides a globally unique means to identify a given capability.</description>
+      <prop name="value-type" value="identifier"/>
+      <prop name="identifier-type" value="machine-oriented"/>
+      <prop name="identifier-uniqueness" value="global"/>
+      <prop name="identifier-scope" value="cross-instance"/>
+      <prop name="identifier-persistence" value="per-subject"/>
     </define-flag>
     <define-flag name="name" as-type="string" required="yes">
       <formal-name>Capability Name</formal-name>
@@ -284,12 +300,13 @@
           <p>A given <code>component</code> must not be referenced more than once within the same <code>capability</code>.</p>
         </remarks>
       </is-unique>
+      <!-- Feature Request: add constraint ensuring a capability's incorporates-component references //component-definition/component/@uuid in the same component definition instance or an imported instance-->
     </constraint>
   </define-assembly>
   <define-assembly name="incorporates-component">
     <formal-name>Incorporates Component</formal-name>
     <!-- TODO: needs a description -->
-    <description>TBD</description>
+    <description>The collection of components that this capability is comprised of.</description>
     <define-flag required="yes" name="component-uuid" as-type="uuid">
       <formal-name>Component Reference</formal-name>
       <!-- Identifier Reference -->
@@ -309,7 +326,12 @@
     <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>
+      <description>Provides a means to idenfy a set of control implementations that are supported by a given component or capability.</description>
+      <prop name="value-type" value="identifier"/>
+      <prop name="identifier-type" value="machine-oriented"/>
+      <prop name="identifier-uniqueness" value="global"/>
+      <prop name="identifier-scope" value="cross-instance"/>
+      <prop name="identifier-persistence" value="per-subject"/>
     </define-flag>
     <flag ref="source" required="yes">
       <remarks>
@@ -352,13 +374,18 @@
     <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>
+      <description>Provides a globally unique means to identify a given control implementation by a component.</description>
+      <prop name="value-type" value="identifier"/>
+      <prop name="identifier-type" value="machine-oriented"/>
+      <prop name="identifier-uniqueness" value="global"/>
+      <prop name="identifier-scope" value="cross-instance"/>
+      <prop name="identifier-persistence" value="per-subject"/>
     </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 suggestion for how the specified control may be implemented if the containing component or capability is instantiated in a system security plan.</description>
+        <description>A supplier (e.g., component vendor or author) suggestion for how the specified control may be implemented if the containing component or capability is instantiated in a system security plan.</description>
       </define-field>
       <assembly ref="property" max-occurs="unbounded">
         <group-as name="props" in-json="ARRAY"/>
@@ -398,7 +425,7 @@
       </is-unique>
     </constraint>
     <remarks>
-      <p>Implemented requirements within a component or capability in a component definition provide a means to suggest possible control implementation details, which may be used by a different party when authoring a system security plan. Thus, these requirements defined in a component definition are only a suggestion of how to implement, which may be adopted wholesale, changed, or ignored by a person defining an information system implementation.</p>
+      <p>Implemented requirements within a component or capability in a component definition provide a means for component suppliers to suggest possible control implementation details, which may be used by a different party (e.g., component consumers) when authoring a system security plan. Thus, these requirements defined in a component definition are only a suggestion of how to implement, which may be adopted wholesale, changed, or ignored by a person defining an information system implementation.</p>
       <p>Use of <code>set-parameter</code> in this context, sets the parameter for the referenced control and any associated statements.</p>
     </remarks>
   </define-assembly>