From 0aa0e7acbbbd26068bdd484134f1c262ddad3d16 Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Mon, 22 Aug 2022 19:08:49 -0400 Subject: [PATCH] Preliminary work on URI documentation to address #1249. --- docs/content/concepts/linking.md | 134 ++++++++++++++++++ .../oscal_assessment-common_metaschema.xml | 2 +- src/metaschema/oscal_metadata_metaschema.xml | 2 +- 3 files changed, 136 insertions(+), 2 deletions(-) create mode 100644 docs/content/concepts/linking.md diff --git a/docs/content/concepts/linking.md b/docs/content/concepts/linking.md new file mode 100644 index 0000000000..24ccccfb2c --- /dev/null +++ b/docs/content/concepts/linking.md @@ -0,0 +1,134 @@ +--- +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 is used extensively in OSCAL. + +## Uniform Resource Identifier Overview + +According to RFC 3986, a URI has the following syntax as represented in [Augmented Backus-Naur Form (ABNF)](https://www.rfc-editor.org/rfc/rfc5234.html). + +> ``` +> 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 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: + + > ``` + > relative-ref = relative-part [ "?" query ] [ "#" fragment ] + > + > relative-part = "//" authority path-abempty + > / path-absolute + > / path-noscheme + > / path-empty + > ``` + +- **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: + + > URI-reference = URI / relative-ref + +- **An 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 ] + > ``` + +Recognizing these URI forms is important in understanding how URIs are used in OSCAL. + +## 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 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. + +Data elements within OSCAL expecting a URI will use one of these two data types. + +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)) + +### Common OSCAL URI Use Cases + +URIs are used in OSCAL to provide pointers to resources in the following ways. + +1. Link 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 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*. + +1. 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. + + For example, the resource identified by the UUID `f5a2bdb3-55ad-431e-a7ea-c0fd28fc08a0` can be referenced as follows. + + ``` + + ``` + + 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. + +1. As a naming system identifier + + An absolute URI that identifies the naming system. + + 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. + + For example, the namespace `http://example.com/ns/oscal` is used in an OSCAL property as follows. + + ``` + + ``` + + 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. + diff --git a/src/metaschema/oscal_assessment-common_metaschema.xml b/src/metaschema/oscal_assessment-common_metaschema.xml index 7e30cf4d0e..6ceb8a58e3 100644 --- a/src/metaschema/oscal_assessment-common_metaschema.xml +++ b/src/metaschema/oscal_assessment-common_metaschema.xml @@ -853,7 +853,7 @@ Relevant Evidence Links this observation to relevant evidence. - + Relevant Evidence Reference A resolvable URL reference to relevant evidence. diff --git a/src/metaschema/oscal_metadata_metaschema.xml b/src/metaschema/oscal_metadata_metaschema.xml index c0d3b94b29..d2f8893e63 100644 --- a/src/metaschema/oscal_metadata_metaschema.xml +++ b/src/metaschema/oscal_metadata_metaschema.xml @@ -528,7 +528,7 @@ Resource link A URL-based pointer to an external resource with an optional hash for verification and change detection. - + Hypertext Reference A resolvable URL pointing to the referenced resource.