Updates to OSCAL Metaschema documentation and constraints (#1263)

* completed partial update of the Metadata object documentation.
* adjustments to roles
* adjusted the cardinality of location/address to make address optional.
* Improved documentation and constraints related to location and parties
* addressed the remainder of metadata and control feedback from @Rene2mt.
* Improved the introductory remarks for a profile to better describe what a profile is and what it does.
* Fixed a broken constraint that was not targeting the right node.
* started refining descriptions and adding properties to describe identifier attributes.
* Addressed feedback from AJ during 20220718-20220722. (#48)
* Week 30 feedback on SSP model. (#49)
* Proposed metaschema docs updates (#50)
* Addressed feedback based on #1392
* Adjustments based on model review feedback on 8/12.
* Removed outdated merge phase remarks. Created issue #53 to address this.
* Addressed A.J. Stein's Week 32 Feedback for Model Review (#52)
* Addressed AJ Stein's week 32 feedback for #1331.
* Addressed DRAFT: Update catalog & profile metaschema documentation (#51)
* Update catalog & profile metaschema documentation
* Add props to control identifier
* Fixed broken syntax and addressed consistency in wording within the Profile 'merge' construct.
* Adjustments to alter, moving to to an inline definition
* cleaned up empty remark.
* Removed redundant constraints
* removed some redundant constraints
* Preliminary work on URI documentation to address #1249.
* More work on document URI use in OSCAL
* Updating data types related to usnistgov/metaschema#224.
* Improved consistency of how URI concepts are discussed.
* Added note about party locations
* Updated Metaschema instances of `uri` and `uri-reference` data types to indicate their URI semantics. Resolves #1249.
* Added identifier props to control layer metaschemas (#55)
* Responding to #1066: metaschema edits; CSS enhancement (#56)
* Whitespace cleanup in metadata metaschema
* Apply suggestions from code review

Co-authored-by: Alexander Stein <alexander.stein@nist.gov>
Co-authored-by: Wendell Piez <wapiez@wendellpiez.com>
Co-authored-by: Rene Tshiteya <rene-claude.tshiteya@gsa.gov>

Author: 4 people

docs/content/concepts/identifier-use/_index.md

@@ -20,7 +20,7 @@ By design, OSCAL supports [*machine-oriented*](#machine-oriented) and [*human-or
 
 [*Machine-oriented*](#machine-oriented) identifiers provide a persistent identity for an entity within the OSCAL models, which can be used in other locations within related OSCAL models to reference the associated entity. 
 
-These identifiers are intended to be auto-generated by tools when the entity is initially created. In OSCAL, a machine-oriented identifier is implemented using a Universally Unique Identifier (UUID) as defined by [RFC 4122](https://tools.ietf.org/html/rfc4122). A UUID is represented in OSCAL using the [UUID datatype](/reference/datatypes/#uuid).
+These identifiers are intended to be auto-generated by tools when the entity is initially created. In OSCAL, a machine-oriented identifier is implemented using a Universally Unique Identifier (UUID) as defined by [RFC 4122](https://tools.ietf.org/html/rfc4122). A UUID is represented in OSCAL using the [`uuid`](/reference/datatypes/#uuid) data type.
 UUIDs were chosen because:
 - Programming interfaces exist in most programming environments to generate a UUID
 - UUIDs can be issued without a central authority
@@ -32,7 +32,7 @@ The [OSCAL XML Reference Index](/reference/latest/complete/xml-index/#/@uuid) an
 
 #### Human-Oriented
 
-A [*human-oriented*](#human-oriented) identifier incorporates semantic that support readability and processing by humans. OSCAL implements [*human-oriented*](#human-oriented) identifiers as [token](/reference/datatypes/#token) data types, which are non-colonized names.  For example, control identifiers in a catalog may use a nomenclature that is familiar to the intended audience, allowing them to quickly determine what security control is being referred to, simply by its identifier value.  
+A [*human-oriented*](#human-oriented) identifier supports readability and use by human consumers. OSCAL implements [*human-oriented*](#human-oriented) identifiers as [`token`](/reference/datatypes/#token) data types. For example, control identifiers in a catalog may use a nomenclature that is familiar to the intended audience, allowing them to quickly determine what security control is being referred to, simply by its identifier value.  
 
 The [OSCAL XML Reference Index](/reference/latest/complete/xml-index/#/@id) and [OSCAL JSON Reference Index](/reference/latest/complete/json-index/#/id) provide a comprehensive listing of the [*human-oriented*](#human-oriented) IDs in the core OSCAL models.  References to these IDs are typically named according to the referenced object type (e.g., control) followed by “-id”, as seen here in the [XML Reference Index](/reference/latest/complete/xml-index/#/@control-id) (and likewise [JSON Reference Index](/reference/latest/complete/json-index/#/control-id) in the JSON reference index).
 

docs/content/concepts/uri-use.md

@@ -0,0 +1,171 @@
+---
+title: URI Usage
+description: Provides information on the use of URIs in OSCAL.
+weight: 40
+---
+
+According to [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) a Uniform Resource Identifier (URI) "is a compact sequence of characters that identifies an abstract or physical resource." URIs are an important concept, which are used extensively in OSCAL.
+
+## Uniform Resource Identifier Overview
+
+According to RFC 3986, a URI has the following syntax, which is represented in [Augmented Backus-Naur Form (ABNF)](https://www.rfc-editor.org/rfc/rfc5234.html) below.
+
+> ```
+> URI         = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
+> hier-part   = "//" authority path-abempty
+>             / path-absolute
+>             / path-rootless
+>             / path-empty
+> ```
+> 
+>   The scheme and path components are required, though the path may be empty (no characters).  When authority is present, the path must either be empty or begin with a slash ("/") character.  When authority is not present, the path cannot begin with two slash characters ("//").  These restrictions result in five different ABNF rules for a path ([Section 3.3](https://www.rfc-editor.org/rfc/rfc3986#section-3.3)), only one of which will match any given URI reference.
+>
+> The following are two example URIs and their component parts:
+>
+> ```
+>   foo://example.com:8042/over/there?name=ferret#nose
+>   \_/   \______________/\_________/ \_________/ \__/
+>    |           |            |            |        |
+> scheme     authority       path        query   fragment
+>    |   _____________________|__
+>   / \ /                        \
+>   urn:example:animal:ferret:nose
+> ```
+
+According to RFC 3986, a URI can be used in a few different ways. Recognizing these URI forms is important in understanding how URIs are used in OSCAL.
+
+### URI with a Required Scheme
+
+As indicated above with the required scheme and path components.
+
+### Relative Reference
+
+A URI that is a relative reference, references a resource relative to another *[base URI](https://www.rfc-editor.org/rfc/rfc3986#section-5.1)*. Such a URI is resolved using [reference resolution](https://www.rfc-editor.org/rfc/rfc3986#section-5).
+
+The [syntax of a relative reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2) is:
+
+> ```
+> relative-ref  = relative-part [ "?" query ] [ "#" fragment ]
+>
+> relative-part = "//" authority path-abempty
+>               / path-absolute
+>               / path-noscheme
+>               / path-empty
+> ```
+
+### URI Reference
+
+A typical use of a URI, allowing a [URI with a required scheme](#uri-with-a-required-scheme) or a [relative reference](#relative-reference) to be used.
+
+The [syntax of a URI reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.1) is:
+
+> URI-reference = URI / relative-ref
+
+### Absolute URI
+
+According to RFC 3986, the [syntax of an absolute URI](https://www.rfc-editor.org/rfc/rfc3986#section-4.3) is:
+
+> ```
+> absolute-URI  = scheme ":" hier-part [ "?" query ]
+> ```
+
+## URI vs URL vs URN
+
+According to RFC 3986 section [1.1.3](https://www.rfc-editor.org/rfc/rfc3986#section-1.1.3), "a URI can be further classified as a *locator*, a *name*, or *both*." A given URI scheme is not limited to being only a name or a locator; both characteristics can be associated.
+
+- To be a *locator*, the resource pointed to by a URI needs to have persistence.
+
+- To be a *name*, the URI needs to be used consistently to refer to the thing that is named. A URI used only as a name is not required to resolve to a location. URIs schemes requiring an [*authority*](https://www.rfc-editor.org/rfc/rfc3986#section-3.2) element provide a means to use a registered DNS name to assert organizational control over a naming value space or namespace.
+
+A *Uniform Resource Locator (URL)* "refers to the subset of URIs that, in addition to identifying a resource, provide a means of locating the resource by describing its primary access mechanism (e.g., its network "location")."
+
+A URL, when applied consistently, can be used as a *name*. Optionally in such cases, the resource it resolves to can provide information about how to use the URL as a name.
+
+A *Uniform Resource Name (URN)* "has been used historically to refer to both URIs under the `urn` scheme [RFC2141](https://www.rfc-editor.org/rfc/rfc2141), which are required to remain globally unique and persistent even when the resource ceases to exist or becomes unavailable, and to any other URI with the properties of a name.
+
+A URN is often not a good fit for use as a *locator*, since it requires a secondary resolution process that maps the URN's *name* to a specific *location*.
+
+Due to the specific characteristics of a URL or URN, the term URI is often used to refer more broadly to all types of resource identifiers.
+
+## URIs in OSCAL
+
+The following sections discuss how URIs are used in OSCAL.
+
+### OSCAL URI Data Types
+
+OSCAL uses two data types for representing URIs.
+
+1. [`uri`](/reference/datatypes/#uri) - A URI which must provide the required scheme and path components. This means the URI will point directly to a resolvable resource.
+
+   The `uri` data type is used in cases where a [*URI with a required scheme*](#uri-with-a-required-scheme) or an *absolute URI* is required.  As a result, a [*relative reference*](#relative-reference) or a [*URI reference*](#uri-reference) is not allowed for use with this data type.
+
+2. [`uri-reference`](/reference/datatypes/#uri-reference) - A [*URI reference*](#uri-reference), which may be a [*URI with a required scheme*](#uri-with-a-required-scheme) or a [*relative reference*](#relative-reference). This allows all forms of URIs.
+
+### Common OSCAL URI Use Cases
+
+URIs are used in OSCAL to provide pointers to resources in the following ways.
+
+#### Linking to a network resolvable resource
+
+URIs are used to point directly to a network resolvable resource.
+
+In such cases, the URI may be:
+
+- A [*URI with a required scheme*](#uri-with-a-required-scheme), where the scheme will likely be `https` indicating the resource can be accessed using the [Hypertext Transfer Protocol](https://www.rfc-editor.org/rfc/rfc2616.html) (HTTP) using [Transport Layer Security](https://www.rfc-editor.org/rfc/rfc8446) (TLS). Data fields supporting only this use case will have the `uri` data type.
+
+   OSCAL examples include:
+
+   - `threat-id` - ([JSON/YAML](/reference/latest/complete/json-index/#/threat-id)) ([XML](/reference/latest/complete/xml-index/#/@threat-id))
+   - `url` - ([JSON/YAML](/reference/latest/complete/json-index/#/url)) ([XML](/reference/latest/complete/xml-index/#/urls))
+
+- A [*relative reference*](#relative-reference), pointing to a resource that can resolved using the current document resource as the *base URI*. Data fields supporting this use case will have the `uri-reference` data type.
+
+   OSCAL examples include:
+
+   - `href` - ([JSON/YAML](/reference/latest/complete/json-index/#/href)) ([XML](/reference/latest/complete/xml-index/#/@href))
+   - `source` - ([JSON/YAML](/reference/latest/complete/json-index/#/source)) ([XML](/reference/latest/complete/xml-index/#/@source))
+   - `filename` - ([JSON/YAML](/reference/latest/complete/json-index/#/filename)) ([XML](/reference/latest/complete/xml-index/#/@filename))
+
+URIs serving this purpose need to be used as a *locator*. URLs are typically used for this purpose since the URI must resolve to a specific location.
+
+#### Linking to another OSCAL object
+
+A pointer to an OSCAL object identified by the referenced identifier, may be a [human-oriented](/concepts/identifier-use/#human-oriented) [`token`](/reference/datatypes/#token) or a [machine-oriented](/concepts/identifier-use/#machine-oriented) [`uuid`](https://pages.nist.gov/OSCAL/reference/datatypes/#uuid).
+
+This approach uses a [*relative reference*](#relative-reference) consisting of only a URI *fragment* containing the identifier or UUID of the referenced object within the current documents effective data model. The effective data model of a document includes all objects identified with the document and any directly or transitively imported documents. Identifiers with a *cross-instance* [scope](/concepts/identifier-use/#scope) are available to importing documents.
+
+URIs serving this purpose need to be used as a *locator*. 
+
+Any data fields supporting this use case will have the `uri-reference` data type.
+
+A typical use of OSCAL object identifier linking is referencing a `resource` in the document's `back-matter` or an imported document's `back-matter`. For example, the back-matter resource identified by the UUID `f5a2bdb3-55ad-431e-a7ea-c0fd28fc08a0` can be referenced as follows.
+
+```
+<link rel="related" href="#f5a2bdb3-55ad-431e-a7ea-c0fd28fc08a0"/>
+```
+
+More information about the use of links to reference back-matter resources can be found in the [*Referencing Back-Matter Resources*](/learn/tutorials/general/extension/#referencing-back-matter-resources) section of the [*Extending OSCAL Models with Props and Links*](/learn/tutorials/general/extension/) tutorial.
+
+#### Use as a naming system identifier
+
+An absolute URI that identifies the naming system. URIs serving this purpose are used as a *name*. Data fields supporting this use case will have the `uri` data type.
+
+OSCAL supports a number of name/value and other controlled value collections. To allow independent organization to organize these value collections, namespaces are used to partition the value spaces on an organization-by-organization basis. An [*absolute URI*](#absolute-uri) is used as the namespace identifier for these situations.
+
+When used in this way, the authority component of the URI must use a value that the organization has control over. Typically, a DNS domain name controlled by the organization is used for this purpose.
+
+OSCAL examples include:
+
+- `ns` - ([JSON/YAML](/reference/latest/complete/json-index/#/ns)) ([XML](/reference/latest/complete/xml-index/#/@ns))
+- `system` - ([JSON/YAML](/reference/latest/complete/json-index/#/system)) ([XML](/reference/latest/complete/xml-index/#/@system))
+- `scheme` - ([JSON/YAML](/reference/latest/complete/json-index/#/scheme)) ([XML](/reference/latest/complete/xml-index/#/@scheme))
+
+A key example of this approach is how property names are partitioned using a `ns` data element.
+
+For example, the namespace `http://example.com/ns/oscal` is used in an OSCAL property as follows.
+
+```
+<prop ns="http://example.com/ns/oscal" name="example-name" value="example-value"/>
+```
+   
+To learn more about the use of namespaces in properties, refer to the [*Extending Existing Prop Values*](/learn/tutorials/general/extension/#extending-existing-prop-values) section of the [*Extending OSCAL Models with Props and Links*](/learn/tutorials/general/extension/) tutorial.

docs/content/learn/tutorials/general/extension.md

@@ -273,7 +273,7 @@ In XML Schema this is represented as a restriction on the built-in type [dateTim
 <xs:simpleType name="DateTimeDatatype">
   <xs:restriction base="xs:dateTime">
     <xs:pattern
-      value="(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T((2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\.[0-9]+)?)(Z|[+-][0-9]{2}:[0-9]{2})?"
+      value="(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\.[0-9]*[1-9])?(Z|(-((0[0-9]|1[0-2]):00|0[39]:30)|\+((0[0-9]|1[0-4]):00|(0[34569]|10):30|(0[58]|12):45)))?"
     />
   </xs:restriction>
 </xs:simpleType>
@@ -284,7 +284,7 @@ In JSON Schema, this is represented as:
 ```JSON
 {
   "type": "string",
-  "pattern": "^(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})?$"
+  "pattern": "^(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]*[1-9])?(Z|(-((0[0-9]|1[0-2]):00|0[39]:30)|\\+((0[0-9]|1[0-4]):00|(0[34569]|10):30|(0[58]|12):45)))?$"
 }
 ```
 
@@ -306,7 +306,7 @@ In XML Schema this is represented as a restriction on the built in type [dateTim
 <xs:simpleType name="DateWithTimezoneDatatype">
   <xs:restriction base="DateDatatype">
     <xs:pattern
-      value="(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))(Z|[+-][0-9]{2}:[0-9]{2})"
+      value="(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\.[0-9]*[1-9])?(Z|(-((0[0-9]|1[0-2]):00|0[39]:30)|\+((0[0-9]|1[0-4]):00|(0[34569]|10):30|(0[58]|12):45)))"
     />
   </xs:restriction>
 </xs:simpleType>
@@ -318,7 +318,7 @@ In JSON Schema, this is represented as:
 {
   "type": "string",
   "format": "date-time",
-  "pattern": "^(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})$"
+  "pattern": "^(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]*[1-9])?(Z|(-((0[0-9]|1[0-2]):00|0[39]:30)|\\+((0[0-9]|1[0-4]):00|(0[34569]|10):30|(0[58]|12):45)))$"
 }
 ```
 

docs/content/reference/datatypes.md

@@ -0,0 +1,159 @@
+METASCHEMA { font-family: Calibri, Verdana, sans-serif }
+
+* { display: block }
+
+pre { color: darkgrey }
+
+tag { color: black; font-family: monospace; font-size: 80%; font-weight: bold }
+
+METASCHEMA { }
+
+title { }
+
+import:before      
+ { content: 'import module ' oxy_urlChooser(edit, '@href', columns 60) }
+ 
+
+
+define-assembly,
+define-field,
+define-flag      { margin-top: 1ex; margin-bottom: 1ex; border: thin inset black; padding: 0.5em }
+
+
+define-assembly:before,
+define-field:before,
+define-flag:before      
+ { content:
+ oxy_name() 
+ oxy_textfield(edit, '@name', columns, 12) 
+    }
+
+root-name:before { content: "Root name: "  }
+
+
+prop:before      
+ { content: 'property '
+ oxy_textfield(edit, '@name', columns, 25)
+ oxy_textfield(edit, '@value', columns, 30) 
+    }
+
+
+define-assembly[group-as]:before,
+define-field[group-as]:before,
+define-flag[group-as]:before      
+ { content:
+ oxy_name() 
+ oxy_textfield(edit, '@name', columns, 12) }
+define-assembly *,
+define-field    *,
+define-flag     *  { margin: 0em }
+
+define-assembly > * { margin-top: 1em }
+
+pre { padding: 0.5em; background-color: gainsboro }
+
+define-assembly { }
+
+define-field { }
+
+define-flag { }
+
+flag { }
+
+formal-name { font-size: 120%; font-weight: bold; margin: 0.5em 0em }
+
+description, remarks {  max-width: 60em }
+
+remarks { border-left: thin solid black; padding-left: 1em; margin-left: 1em }
+remarks p { margin-top: 1em }
+
+
+example { }
+
+prose { }
+
+
+p { }
+
+code {  display: inline; font-family: monospace }
+q {  display: inline; background-color: lemonchiffon }
+em, i {  display: inline; font-style: italic }
+strong, b  {  display: inline; font-weight: bold }
+
+example { background-color: lavender; white-space: pre; }
+
+example *:before { content: '<' oxy_name() '>'; font-family: monospace; font-size: 80%  }
+example *:after { content: '</' oxy_name() '>'; font-family: monospace; font-size: 80%  }
+
+model { padding-left: 0.5em; border-left: medium solid blue; font-size: 80%; padding-right: 2em }
+
+model model { font-size: 100%; }
+
+flag:before { content:
+ oxy_name()
+  ' ref: ' oxy_textfield(edit, '@ref', columns, 12) 
+   }
+
+assembly:before, field:before {
+  content:
+    oxy_name() ' named '
+    oxy_textfield(edit, '@ref', columns, 12) }
+
+group-as { margin-left: 2em }
+
+group-as:before { content: 'group as '
+ oxy_textfield(edit, '@name', columns, 12) }
+
+
+choice:before { content:
+ 'a choice between'
+ }
+
+prose:before { font-weight: bold; content:
+ 'prose'
+ }
+
+choice > * { margin-left: 2em }
+
+a { display: inline; color: blue }
+a:before { content: oxy_urlChooser(        
+        edit, "@href",
+        columns 42); }
+
+
+/* CONSTRAINTS */
+
+constraint > * { border: thin solid black; padding: 0.6em }
+
+allowed-values:before { content: "Allowed values"
+  ' level: '  oxy_combobox(edit, '@level', editable, false, values, "ERROR, WARNING" ) }
+
+enum { margin-left: 2em; display: list-item;
+       font-size: 90%; padding-left: 1em }
+enum:before { content: oxy_textfield(edit, '@value', columns, 24); }
+
+index { }
+index:before {  content: "Index: "
+  ' name: ' oxy_textfield(edit, '@name', columns, 24)
+  ' target: ' oxy_textfield(edit, '@target', columns, 52)
+  ' level: '  oxy_combobox(edit, '@level', editable, false, values, "ERROR, WARNING" ); }
+
+key-field { margin-left: 2em }
+key-field:before {  content: "Key field "
+  ' target: ' oxy_textfield(edit, '@target', columns, 52)
+  ' level: '  oxy_combobox(edit, '@level', editable, false, values, "ERROR, WARNING" ); }
+
+expect { }
+expect:before  {  content: "Expect "
+  ' target: ' oxy_textfield(edit, '@target', columns, 52)
+  ' test: '   oxy_textfield(edit, '@test', columns, 36)
+  ' level: '  oxy_combobox(edit, '@level', editable, false, values, "ERROR, WARNING" ); }
+
+index-has-key { }
+
+index-has-key:before { content: "Index has key: "
+  ' name: ' oxy_textfield(edit, '@name', columns, 24)
+  ' target: ' oxy_textfield(edit, '@target', columns, 52)
+  ' level: '  oxy_combobox(edit, '@level', editable, false, values, "ERROR, WARNING" ); }
+
+

src/metaschema/metaschema-author.css

@@ -19,13 +19,16 @@
    <define-assembly name="import-ssp">
       <formal-name>Import System Security Plan</formal-name>
       <description>Used by the assessment plan and POA&amp;M to import information about the system.</description>
-      <define-flag name="href" required="yes" as-type="uri-reference">
+      <define-flag name="href" as-type="uri-reference" required="yes">
          <formal-name>System Security Plan Reference</formal-name>
          <description>A resolvable URL reference to the system security plan for the system being assessed.</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>
-            <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 <a href="/concepts/layer/assessment/assessment-plan/#key-concepts">within the scope of the containing OSCAL document</a>.</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>
+            <p>This value may be one of:</p>
+            <ol>
+               <li>an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that points to a network resolvable resource,</li>
+               <li>a <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#relative-reference">relative reference</a> pointing to a network resolvable resource whose base URI is the URI of the containing document, or</li>
+               <li>a bare URI fragment (i.e., `#uuid`) pointing to a <code>back-matter</code> resource in this or an imported document (see <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#linking-to-another-oscal-object">linking to another OSCAL object</a>).</li>
+            </ol>
          </remarks>
       </define-flag>
 
@@ -59,7 +62,7 @@
          <field ref="remarks" in-xml="WITH_WRAPPER" min-occurs="0" max-occurs="1"/>
       </model>
       <constraint>
-         <allowed-values target="part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]">
+         <allowed-values target="part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name">
             <enum value="objective" deprecated="1.0.1">**(deprecated)** Use 'assessment-objective' instead.</enum>
             <enum value="assessment" deprecated="1.0.1">**(deprecated)** Use 'assessment-method' instead.</enum>
             <enum value="assessment-objective">The part defines an assessment objective.</enum>
@@ -853,13 +856,16 @@
             <formal-name>Relevant Evidence</formal-name>
             <description>Links this observation to relevant evidence.</description>
             <group-as name="relevant-evidence" in-json="ARRAY"/>
-            <define-flag name="href" required="no" as-type="uri-reference">
+            <define-flag name="href" as-type="uri-reference">
                <formal-name>Relevant Evidence Reference</formal-name>
                <description>A resolvable URL reference to relevant evidence.</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>
-                  <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 <a href="/concepts/layer/assessment/assessment-plan/#key-concepts">within the scope of the containing OSCAL document</a>.</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>
+                  <p>This value may be one of:</p>
+                  <ol>
+                     <li>an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that points to a network resolvable resource,</li>
+                     <li>a <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#relative-reference">relative reference</a> pointing to a network resolvable resource whose base URI is the URI of the containing document, or</li>
+                     <li>a bare URI fragment (i.e., `#uuid`) pointing to a <code>back-matter</code> resource in this or an imported document (see <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#linking-to-another-oscal-object">linking to another OSCAL object</a>).</li>
+                  </ol>
                </remarks>
             </define-flag>
             <model>
@@ -1019,10 +1025,22 @@
                <enum value="http://fedramp.gov/ns/oscal">The value conforms to FedRAMP definitions.</enum>
             </allowed-values>
          </constraint>
+         <remarks>
+            <p>This value must be an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that serves as a <a href="/OSCAL/concepts/uri-use/#use-as-a-naming-system-identifier">naming system identifier</a>.</p>
+         </remarks>
       </define-flag>
       <define-flag name="href" as-type="uri-reference">
+         <!-- TODO: consider deprecating this in favor of a link -->
          <formal-name>Threat Information Resource Reference</formal-name>
          <description>An optional location for the threat data, from which this ID originates.</description>
+         <remarks>
+            <p>This value may be one of:</p>
+            <ol>
+               <li>an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that points to a network resolvable resource,</li>
+               <li>a <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#relative-reference">relative reference</a> pointing to a network resolvable resource whose base URI is the URI of the containing document, or</li>
+               <li>a bare URI fragment (i.e., `#uuid`) pointing to a <code>back-matter</code> resource in this or an imported document (see <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#linking-to-another-oscal-object">linking to another OSCAL object</a>).</li>
+            </ol>
+         </remarks>
       </define-flag>
    </define-field>
 
@@ -1299,6 +1317,9 @@
                      <enum value="http://www.first.org/cvss/v3.1"/>
                   </allowed-values>
                </constraint>
+               <remarks>
+                  <p>This value must be an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that serves as a <a href="/OSCAL/concepts/uri-use/#use-as-a-naming-system-identifier">naming system identifier</a>.</p>
+               </remarks>
             </define-flag>
             <define-flag name="value" as-type="string" required="yes">
                <formal-name>Facet Value</formal-name>
@@ -1640,13 +1661,12 @@
             </allowed-values>
          </constraint>
       </define-flag>
-      <define-flag name="ns" as-type="uri">
+      <define-flag name="ns" as-type="uri" default="http://csrc.nist.gov/ns/oscal">
          <!-- CHANGED: data type to uri -->
          <formal-name>Part Namespace</formal-name>
          <description>A namespace qualifying the part'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 text used in a part. This allows the semantics associated with a given name 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>This value must be an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that serves as a <a href="/OSCAL/concepts/uri-use/#use-as-a-naming-system-identifier">naming system identifier</a>.</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>

src/metaschema/oscal_assessment-common_metaschema.xml

@@ -322,11 +322,12 @@
       <formal-name>Assessment Plan Reference</formal-name>
       <description>A resolvable URL reference to the assessment plan governing the assessment activities.</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>
+        <p>This value may be one of:</p>
+        <ol>
+          <li>an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that points to a network resolvable resource,</li>
+          <li>a <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#relative-reference">relative reference</a> pointing to a network resolvable resource whose base URI is the URI of the containing document, or</li>
+          <li>a bare URI fragment (i.e., `#uuid`) pointing to a <code>back-matter</code> resource in this or an imported document (see <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#linking-to-another-oscal-object">linking to another OSCAL object</a>).</li>
+        </ol>
       </remarks>
     </define-flag>
     <model>

src/metaschema/oscal_assessment-results_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"/>
@@ -72,6 +78,14 @@
     <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>
+      <remarks>
+        <p>This value may be one of:</p>
+        <ol>
+          <li>an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that points to a network resolvable resource,</li>
+          <li>a <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#relative-reference">relative reference</a> pointing to a network resolvable resource whose base URI is the URI of the containing document, or</li>
+          <li>a bare URI fragment (i.e., `#uuid`) pointing to a <code>back-matter</code> resource in this or an imported document (see <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#linking-to-another-oscal-object">linking to another OSCAL object</a>).</li>
+        </ol>
+      </remarks>
     </define-flag>
   </define-assembly>
 
@@ -81,7 +95,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 +271,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 +308,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 comprising this capability.</description>
     <define-flag required="yes" name="component-uuid" as-type="uuid">
       <formal-name>Component Reference</formal-name>
       <!-- Identifier Reference -->
@@ -309,13 +334,25 @@
     <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 identify 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">
+    <define-flag name="source" as-type="uri-reference" required="yes">
+      <formal-name>Source Resource Reference</formal-name>
+      <description>A reference to an OSCAL catalog or profile providing the referenced control or subcontrol definition.</description>
       <remarks>
-        <p>A URL reference to the source catalog or profile for which this component is implementing controls for.</p>
+        <p>This value may be one of:</p>
+        <ol>
+          <li>an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that points to a network resolvable resource,</li>
+          <li>a <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#relative-reference">relative reference</a> pointing to a network resolvable resource whose base URI is the URI of the containing document, or</li>
+          <li>a bare URI fragment (i.e., `#uuid`) pointing to a <code>back-matter</code> resource in this or an imported document (see <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#linking-to-another-oscal-object">linking to another OSCAL object</a>).</li>
+        </ol>
       </remarks>
-    </flag>
+    </define-flag>
     <model>
       <define-field name="description" as-type="markup-multiline" min-occurs="1" in-xml="WITH_WRAPPER">
         <formal-name>Control Implementation Description</formal-name>
@@ -352,13 +389,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 suggestion from the supplier (e.g., component vendor or author) 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 +440,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>

src/metaschema/oscal_catalog_metaschema.xml

@@ -604,10 +604,7 @@
       </define-assembly>
 
 
-      <define-flag name="source" as-type="uri-reference">
-            <formal-name>Source Resource Reference</formal-name>
-            <description>A reference to an OSCAL catalog or profile providing the referenced control or subcontrol definition.</description>
-      </define-flag>
+
       <!--   <define-assembly name="only-statement">
       <formal-name>Specific Statement</formal-name>
       <description>Describes which specific statements are addressed by a requirement, by pointing to a specific requirement statement within a control.</description>
@@ -666,6 +663,13 @@
             <!-- This is an id because the idenfier is assigned and managed by humans. -->
             <formal-name>System Identification</formal-name>
             <!-- Identifier Declaration -->
+            <!-- 
+                  TODO: Given feedback, we need to update Metaschema with usnistgov/metaschema#222
+                  with props like in https://github.com/david-waltermire-nist/OSCAL/commit/3aafc080b3dc5f488c15b763f707326e77a61f5d#diff-4176d3cf694dd36b02a94207426934306ec0fdaecc54d1bb96f50f52cd7ceae6R27-R32.
+
+                  We need to determine if both identifier-type='machine-oriented' and identifier-type='human-oriented'.
+                  Option 2 is identifier-type='unspecified'.
+            -->
             <description>A <a href="/concepts/identifier-use/#human-oriented">human-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 system identification property elsewhere in <a href="/concepts/identifier-use/#scope">this or other OSCAL instances</a>. When referencing an externally defined <code>system identification</code>, the <code>system identification</code> must be used in the context of the external / imported OSCAL instance (e.g., uri-reference). This string should be assigned <a href="/concepts/identifier-use/#consistency">per-subject</a>, which means it should be consistently used to identify the same system across revisions of the document.</description>
             <json-value-key>id</json-value-key>
             <define-flag name="identifier-type" as-type="uri">
@@ -679,6 +683,9 @@
                               <enum value="http://ietf.org/rfc/rfc4122">A Universally Unique Identifier (UUID) as defined by RFC4122.</enum>
                         </allowed-values>
                   </constraint>
+                  <remarks>
+                        <p>This value must be an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that serves as a <a href="/OSCAL/concepts/uri-use/#use-as-a-naming-system-identifier">naming system identifier</a>.</p>
+                  </remarks>
             </define-flag>
       </define-field>
 

src/metaschema/oscal_component_metaschema.xml

@@ -28,11 +28,11 @@
                 <formal-name>Mapping Entry Relationship</formal-name>
                 <description>The relationship type for the mapping entry, which describes the relationship between the effective requirements of the specified source and target sets.</description>
                 <json-value-key>type</json-value-key>
-                <define-flag name="ns" as-type="uri">
+                <define-flag name="ns" as-type="uri" default="http://csrc.nist.gov/ns/oscal">
                     <formal-name>Relationship Value Namespace</formal-name>
                     <description>A namespace qualifying the relationship's value. This allows different organizations to associate distinct semantics for relationships with the same name.</description>
                     <remarks>
-                        <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>This value must be an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that serves as a <a href="/OSCAL/concepts/uri-use/#use-as-a-naming-system-identifier">naming system identifier</a>.</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>
@@ -90,7 +90,7 @@
 
     <define-assembly name="mapping-resource-reference">
         <formal-name>Mapped Resource Reference</formal-name>
-        <description>A reference to a back-matter resource that is either the source or target of a mapping.</description>
+        <description>A reference to a resource that is either the source or target of a mapping.</description>
         <define-flag name="type" as-type="token" required="yes">
             <formal-name>Resource Type</formal-name>
             <description>The semantic type of the resource.</description>
@@ -104,11 +104,12 @@
             <formal-name>Catalog or Profile Reference</formal-name>
             <description>A resolvable URL reference to the base catalog or profile that this profile is tailoring.</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 URL pointing to the location of the referenced resource. A relative URL will be resolved relative to the location of the document containing the link.</p>
+                <p>This value may be one of:</p>
+                <ol>
+                    <li>an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that points to a network resolvable resource,</li>
+                    <li>a <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#relative-reference">relative reference</a> pointing to a network resolvable resource whose base URI is the URI of the containing document, or</li>
+                    <li>a bare URI fragment (i.e., `#uuid`) pointing to a <code>back-matter</code> resource in this or an imported document (see <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#linking-to-another-oscal-object">linking to another OSCAL object</a>).</li>
+                </ol>
             </remarks>
         </define-flag>
         <model>

src/metaschema/oscal_control-common_metaschema.xml

@@ -57,12 +57,13 @@
       <formal-name>Profile Reference</formal-name>
       <description>A resolvable URL reference to the profile or catalog to use as the system's control baseline.</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. The identified resource will be used instead as the target resource.</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 target resource. A relative URI will be resolved relative to the location of the document containing the link.</p>
-        <p>If the resource is an OSCAL profile, it is expected that a tool will resolve the profile according to the OSCAL [profile resolution specification](https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/) to produce a resolved profile for use when processing the containing system security plan. This allows a system security plan processor to use the baseline as a catalog of controls.</p>
+        <p>This value may be one of:</p>
+        <ol>
+          <li>an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that points to a network resolvable resource,</li>
+          <li>a <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#relative-reference">relative reference</a> pointing to a network resolvable resource whose base URI is the URI of the containing document, or</li>
+          <li>a bare URI fragment (i.e., `#uuid`) pointing to a <code>back-matter</code> resource in this or an imported document (see <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#linking-to-another-oscal-object">linking to another OSCAL object</a>).</li>
+        </ol>
+        <p>If the resource is an OSCAL profile, it is expected that a tool will resolve the profile according to the OSCAL <a href="https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/">profile resolution specification</a> to produce a resolved profile for use when processing the containing system security plan. This allows a system security plan processor to use the baseline as a catalog of controls.</p>
         <p>While it is possible to reference a previously resolved OSCAL profile as a catalog, this practice is discouraged since the unresolved form of the profile communicates more information about selections and changes to the underlying catalog. Furthermore, the underlying catalog can be maintained separately from the profile, which also has maintenance advantages for distinct maintainers, ensuring that the best available information is produced through profile resolution.</p>
       </remarks>
     </define-flag>
@@ -88,6 +89,9 @@
       <define-field name="system-name-short" as-type="string">
         <formal-name>System Name - Short</formal-name>
         <description>A short name for the system, such as an acronym, that is suitable for display in a data table or summary list.</description>
+        <remarks>
+          <p>Since <code>system-name-short</code> is optional, if the <code>system-name-short</code> is not provided, the <code>system-name</code> can be used as a substitute.</p>
+        </remarks>
       </define-field>
       <define-field name="description" as-type="markup-multiline" min-occurs="1" in-xml="WITH_WRAPPER">
         <formal-name>System Description</formal-name>
@@ -218,6 +222,9 @@
                   <enum value="http://doi.org/10.6028/NIST.SP.800-60v2r1">Based on the section identifiers in NIST <a href="https://doi.org/10.6028/NIST.SP.800-60v2r1">Special Publication 800-60 Volume II Revision 1</a>.</enum>
                 </allowed-values>
               </constraint>
+              <remarks>
+                <p>This value must be an <a href="https://pages.nist.gov/OSCAL/concepts/uri-use/#absolute-uri">absolute URI</a> that serves as a <a href="/OSCAL/concepts/uri-use/#use-as-a-naming-system-identifier">naming system identifier</a>.</p>
+              </remarks>
             </define-flag>
             <model>
               <define-field name="information-type-id" as-type="string" max-occurs="unbounded">
@@ -274,6 +281,10 @@
       <index-has-key name="index-back-matter-resource" target="link[@rel='privacy-impact-assessment' and starts-with(@href,'#')]">
         <key-field target="@href" pattern="#(.*)"/>
       </index-has-key>
+      <!-- 
+        TODO: Per discussion in usnisgov/OSCAL#1331 review on 29 July 2022,
+        add the path target to security-sensitivity-level as well.
+      -->
       <matches target="link[@rel='privacy-impact-assessment']/@href[not(starts-with(.,'#'))]" datatype="uri"/>
       <allowed-values target="information-type/(confidentiality-impact|integrity-impact|availability-impact)/(base|selected)">
         <enum value="fips-199-low">A 'low' sensitivity level as defined in <a href="https://doi.org/10.6028/NIST.FIPS.199">FIPS-199</a>.
@@ -319,18 +330,19 @@
     <formal-name>Security Impact Level</formal-name>
     <description>The overall level of expected impact resulting from unauthorized disclosure, modification, or loss of access to information.</description>
     <model>
+      <!-- 
+        TODO: Per discussion in usnisgov/OSCAL#1331 review on 29 July 2022,
+        add the path target to security-impact-level as well for fips-199-low/mod/high.
+      -->
       <define-field name="security-objective-confidentiality" as-type="string" min-occurs="1">
-        <!-- CHANGED: cardinality to min 1 -->
         <formal-name>Security Objective: Confidentiality</formal-name>
         <description>A target-level of confidentiality for the system, based on the sensitivity of information within the system.</description>
       </define-field>
       <define-field name="security-objective-integrity" as-type="string" min-occurs="1">
-        <!-- CHANGED: cardinality to min 1 -->
         <formal-name>Security Objective: Integrity</formal-name>
         <description>A target-level of integrity for the system, based on the sensitivity of information within the system.</description>
       </define-field>
       <define-field name="security-objective-availability" as-type="string" min-occurs="1">
-        <!-- CHANGED: cardinality to min 1 -->
         <formal-name>Security Objective: Availability</formal-name>
         <description>A target-level of availability for the system, based on the sensitivity of information within the system.</description>
       </define-field>