Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DRAFT: Update catalog & profile metaschema documentation #51

Merged
merged 7 commits into from
Aug 19, 2022
Merged

DRAFT: Update catalog & profile metaschema documentation #51

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
fd49ca8
Update catalog & profile metaschema documentation
Rene2mt Aug 11, 2022
f115fcf
Apply updates to CDEF model documentation
Rene2mt Aug 12, 2022
79c6c16
Add props to control identifier
Rene2mt Aug 12, 2022
23f745d
Apply suggestions from code review
david-waltermire Aug 19, 2022
24f25a6
Apply suggestions from code review
david-waltermire Aug 19, 2022
5508ddb
Merge branch 'issue1066-metaschema-updates' into issue1066-metaschema…
david-waltermire Aug 19, 2022
1c490de
Apply suggestions from code review
david-waltermire Aug 19, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 16 additions & 3 deletions src/metaschema/oscal_catalog_metaschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@
<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>
</allowed-values>
<!-- Feature Request: prop for source-profile-uuid. we have 'resolution-source' link but prop with UUID would be even greater for traceability -->
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
<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>
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
</allowed-values>
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
Expand Down Expand Up @@ -145,8 +146,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 a <code>group</code> to categorize related controls into a single grouping, such as a family of controls or other logical grouping.</p>
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
<p>A <code>group</code> may have its own properties, statements, parameters, and references, which are inherited by all member controls of that group.</p>
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
</remarks>
<example>
<group xmlns="http://csrc.nist.gov/ns/oscal/1.0" id="xyz">
Expand All @@ -165,7 +166,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>
Expand Down Expand Up @@ -214,7 +220,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>
<!--
Clarify that link@rel (e.g., where value is related, required, incorporated-into, moved-to) is only intended for control-to-control associations.
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
Add a corresponding constraint.
-->
</remark>
</allowed-values>
<!-- Feature Requst: 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 -->
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
<!-- 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="#(.*)"/>
Expand Down
50 changes: 38 additions & 12 deletions src/metaschema/oscal_component_metaschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@
<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. Hardware and software vendors/manufacturers are responsible for creating component definitions that component consumers can use when documenting control implementations in an OSCAL SSP.</p>
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
<p>A documentary component is a component implemented in a document, such as a process, procedure, or policy. In this case, the document author is responsible for creating component definitions that can be utilized by component consumers when documenting control implementations in an OSCAL SSP</p>
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
<p>The root of the OSCAL Implementation Component format is <code>component-definition</code>.</p>
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
</remarks>

<import href="oscal_implementation-common_metaschema.xml"/>
Expand All @@ -34,7 +34,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"/>
Expand Down Expand Up @@ -81,7 +86,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="change-on-write"/>
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
</define-flag>
<flag ref="defined-component-type" required="yes">
<use-name>type</use-name>
Expand Down Expand Up @@ -252,7 +262,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="change-on-write"/>
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
</define-flag>
<define-flag name="name" as-type="string" required="yes">
<formal-name>Capability Name</formal-name>
Expand Down Expand Up @@ -284,12 +299,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 -->
Expand All @@ -309,7 +325,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="change-on-write"/>
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
</define-flag>
<flag ref="source" required="yes">
<remarks>
Expand Down Expand Up @@ -352,13 +373,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="change-on-write"/>
david-waltermire marked this conversation as resolved.
Show resolved Hide resolved
</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"/>
Expand Down Expand Up @@ -398,7 +424,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>
Expand Down
Loading