Skip to content

Commit 988817c

Browse files
David Waltermireaj-stein-nistwendellpiezRene Tshiteya
committed
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>
1 parent e5fa65f commit 988817c

15 files changed

+1310
-658
lines changed

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ By design, OSCAL supports [*machine-oriented*](#machine-oriented) and [*human-or
2020

2121
[*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.
2222

23-
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).
23+
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.
2424
UUIDs were chosen because:
2525
- Programming interfaces exist in most programming environments to generate a UUID
2626
- UUIDs can be issued without a central authority
@@ -32,7 +32,7 @@ The [OSCAL XML Reference Index](/reference/latest/complete/xml-index/#/@uuid) an
3232

3333
#### Human-Oriented
3434

35-
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.
35+
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.
3636

3737
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).
3838

‎docs/content/concepts/uri-use.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
title: URI Usage
3+
description: Provides information on the use of URIs in OSCAL.
4+
weight: 40
5+
---
6+
7+
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.
8+
9+
## Uniform Resource Identifier Overview
10+
11+
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.
12+
13+
> ```
14+
> URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
15+
> hier-part = "//" authority path-abempty
16+
> / path-absolute
17+
> / path-rootless
18+
> / path-empty
19+
> ```
20+
>
21+
> 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.
22+
>
23+
> The following are two example URIs and their component parts:
24+
>
25+
> ```
26+
> foo://example.com:8042/over/there?name=ferret#nose
27+
> \_/ \______________/\_________/ \_________/ \__/
28+
> | | | | |
29+
> scheme authority path query fragment
30+
> | _____________________|__
31+
> / \ / \
32+
> urn:example:animal:ferret:nose
33+
> ```
34+
35+
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.
36+
37+
### URI with a Required Scheme
38+
39+
As indicated above with the required scheme and path components.
40+
41+
### Relative Reference
42+
43+
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).
44+
45+
The [syntax of a relative reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2) is:
46+
47+
> ```
48+
> relative-ref = relative-part [ "?" query ] [ "#" fragment ]
49+
>
50+
> relative-part = "//" authority path-abempty
51+
> / path-absolute
52+
> / path-noscheme
53+
> / path-empty
54+
> ```
55+
56+
### URI Reference
57+
58+
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.
59+
60+
The [syntax of a URI reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.1) is:
61+
62+
> URI-reference = URI / relative-ref
63+
64+
### Absolute URI
65+
66+
According to RFC 3986, the [syntax of an absolute URI](https://www.rfc-editor.org/rfc/rfc3986#section-4.3) is:
67+
68+
> ```
69+
> absolute-URI = scheme ":" hier-part [ "?" query ]
70+
> ```
71+
72+
## URI vs URL vs URN
73+
74+
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.
75+
76+
- To be a *locator*, the resource pointed to by a URI needs to have persistence.
77+
78+
- 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.
79+
80+
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")."
81+
82+
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.
83+
84+
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.
85+
86+
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*.
87+
88+
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.
89+
90+
## URIs in OSCAL
91+
92+
The following sections discuss how URIs are used in OSCAL.
93+
94+
### OSCAL URI Data Types
95+
96+
OSCAL uses two data types for representing URIs.
97+
98+
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.
99+
100+
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.
101+
102+
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.
103+
104+
### Common OSCAL URI Use Cases
105+
106+
URIs are used in OSCAL to provide pointers to resources in the following ways.
107+
108+
#### Linking to a network resolvable resource
109+
110+
URIs are used to point directly to a network resolvable resource.
111+
112+
In such cases, the URI may be:
113+
114+
- 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.
115+
116+
OSCAL examples include:
117+
118+
- `threat-id` - ([JSON/YAML](/reference/latest/complete/json-index/#/threat-id)) ([XML](/reference/latest/complete/xml-index/#/@threat-id))
119+
- `url` - ([JSON/YAML](/reference/latest/complete/json-index/#/url)) ([XML](/reference/latest/complete/xml-index/#/urls))
120+
121+
- 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.
122+
123+
OSCAL examples include:
124+
125+
- `href` - ([JSON/YAML](/reference/latest/complete/json-index/#/href)) ([XML](/reference/latest/complete/xml-index/#/@href))
126+
- `source` - ([JSON/YAML](/reference/latest/complete/json-index/#/source)) ([XML](/reference/latest/complete/xml-index/#/@source))
127+
- `filename` - ([JSON/YAML](/reference/latest/complete/json-index/#/filename)) ([XML](/reference/latest/complete/xml-index/#/@filename))
128+
129+
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.
130+
131+
#### Linking to another OSCAL object
132+
133+
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).
134+
135+
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.
136+
137+
URIs serving this purpose need to be used as a *locator*.
138+
139+
Any data fields supporting this use case will have the `uri-reference` data type.
140+
141+
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.
142+
143+
```
144+
<link rel="related" href="#f5a2bdb3-55ad-431e-a7ea-c0fd28fc08a0"/>
145+
```
146+
147+
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.
148+
149+
#### Use as a naming system identifier
150+
151+
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.
152+
153+
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.
154+
155+
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.
156+
157+
OSCAL examples include:
158+
159+
- `ns` - ([JSON/YAML](/reference/latest/complete/json-index/#/ns)) ([XML](/reference/latest/complete/xml-index/#/@ns))
160+
- `system` - ([JSON/YAML](/reference/latest/complete/json-index/#/system)) ([XML](/reference/latest/complete/xml-index/#/@system))
161+
- `scheme` - ([JSON/YAML](/reference/latest/complete/json-index/#/scheme)) ([XML](/reference/latest/complete/xml-index/#/@scheme))
162+
163+
A key example of this approach is how property names are partitioned using a `ns` data element.
164+
165+
For example, the namespace `http://example.com/ns/oscal` is used in an OSCAL property as follows.
166+
167+
```
168+
<prop ns="http://example.com/ns/oscal" name="example-name" value="example-value"/>
169+
```
170+
171+
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.

0 commit comments

Comments
 (0)