diff --git a/docs/content/concepts/linking.md b/docs/content/concepts/linking.md index 24ccccfb2c..83015ff91e 100644 --- a/docs/content/concepts/linking.md +++ b/docs/content/concepts/linking.md @@ -37,7 +37,7 @@ According to RFC 3986, a URI can be used as: - **A URI with a scheme:** As indicated above with the required scheme and path components. - **A relative reference:** Which 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). - According to RFC 3986, the [syntax of a relative reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2) is: + The [syntax of a relative reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2) is: > ``` > relative-ref = relative-part [ "?" query ] [ "#" fragment ] @@ -50,7 +50,7 @@ According to RFC 3986, a URI can be used as: - **A URI reference:** Which is a typical use of a URI, allowing a URI with a scheme or a relative reference to be used. - According to RFC 3986, the [syntax of a relative reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.1) is: + The [syntax of a URI reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.1) is: > URI-reference = URI / relative-ref @@ -72,24 +72,11 @@ The following sections discuss how URIs are used in OSCAL. OSCAL uses two data types for representing URIs. -1. [`uri`](/reference/datatypes/#uri) - A URI which must provided the required scheme and path components. A *relative-ref* is not allowed for this data type. -1. [`uri-reference`](/reference/datatypes/#uri-reference) - A URI reference, which may be a URI or a *relative-ref*. This allows all forms of 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. -Data elements within OSCAL expecting a URI will use one of these two data types. + The `uri` data type is used in cases where a *URI with a scheme* or an *absolute URI* is required. As a result, a *relative reference* or a *URI reference* is not allowed for use with this data type. -Examples of `uri` use include: - -- `ns` - ([JSON/YAML](https://pages.nist.gov/OSCAL/reference/latest/complete/json-index/#/ns)) ([XML](https://pages.nist.gov/OSCAL/reference/latest/complete/xml-index/#/@ns)) -- `system` - ([JSON/YAML](https://pages.nist.gov/OSCAL/reference/latest/complete/json-index/#/system)) ([XML](https://pages.nist.gov/OSCAL/reference/latest/complete/xml-index/#/@system)) -- `scheme` - ([JSON/YAML](https://pages.nist.gov/OSCAL/reference/latest/complete/json-index/#/scheme)) ([XML](https://pages.nist.gov/OSCAL/reference/latest/complete/xml-index/#/@scheme)) -- `threat-id` - ([JSON/YAML](https://pages.nist.gov/OSCAL/reference/latest/complete/json-index/#/threat-id)) ([XML](https://pages.nist.gov/OSCAL/reference/latest/complete/xml-index/#/@threat-id)) -- `url` - ([JSON/YAML](https://pages.nist.gov/OSCAL/reference/latest/complete/json-index/#/url)) ([XML](https://pages.nist.gov/OSCAL/reference/latest/complete/xml-index/#/urls)) - -Examples of `uri-reference` use include: - -- `href` - ([JSON/YAML](https://pages.nist.gov/OSCAL/reference/latest/complete/json-index/#/href)) ([XML](https://pages.nist.gov/OSCAL/reference/latest/complete/xml-index/#/@href)) -- `source` - ([JSON/YAML](https://pages.nist.gov/OSCAL/reference/latest/complete/json-index/#/source)) ([XML](https://pages.nist.gov/OSCAL/reference/latest/complete/xml-index/#/@source)) -- `filename` - ([JSON/YAML](https://pages.nist.gov/OSCAL/reference/latest/complete/json-index/#/filename)) ([XML](https://pages.nist.gov/OSCAL/reference/latest/complete/xml-index/#/@filename)) +2. [`uri-reference`](/reference/datatypes/#uri-reference) - A URI reference, which may be a URI or a *relative reference*. This allows all forms of URIs. ### Common OSCAL URI Use Cases @@ -99,14 +86,27 @@ URIs are used in OSCAL to provide pointers to resources in the following ways. URIs are used to point directly to a network resolvable resource. In such cases, the URI may be: - - A URI with a 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). - - A relative reference, pointing to a resource that can resolved using the current document resource as the *base URI*. + - A *URI with a 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*, 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. -1. Link to an OSCAL back-matter resource. + 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)) + + +2. Link to an OSCAL back-matter resource. A pointer to an OSCAL resource defined in the either the document's `back-matter` or an imported document's `back-matter`. - This approach uses a relative URI consisting of only a URI fragment containing the UUID of the referenced resource. + This approach uses a *relative URI* consisting of only a URI fragment containing the UUID of the referenced resource. Thus, data fields supporting this use case will have the `uri-reference` data type. For example, the resource identified by the UUID `f5a2bdb3-55ad-431e-a7ea-c0fd28fc08a0` can be referenced as follows. @@ -114,15 +114,21 @@ URIs are used in OSCAL to provide pointers to resources in the following ways. ``` - More information about the use of links to reference back-matter resources can be found in the [*Referencing Back-Matter Resources*](https://pages.nist.gov/OSCAL/learn/tutorials/general/extension/#referencing-back-matter-resources) section of the [*Extending OSCAL Models with Props and Links*](/learn/tutorials/general/extension/) tutorial. + 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. -1. As a naming system identifier +3. As a naming system identifier. - An absolute URI that identifies the naming system. + An absolute URI that identifies the naming system. 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 is used as the namespace identifier for these situations. - A key example of this approach is how property names are managed. + 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. @@ -130,5 +136,4 @@ URIs are used in OSCAL to provide pointers to resources in the following ways. ``` - To learn more about the namespacing of 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. - + 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.