Skip to content

Commit

Permalink
Updates to OSCAL Metaschema documentation and constraints (#1263)
Browse files Browse the repository at this point in the history
* 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>
  • Loading branch information
4 people committed Jul 10, 2023
1 parent e5fa65f commit 988817c
Show file tree
Hide file tree
Showing 15 changed files with 1,310 additions and 658 deletions.
4 changes: 2 additions & 2 deletions docs/content/concepts/identifier-use/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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).

Expand Down
171 changes: 171 additions & 0 deletions docs/content/concepts/uri-use.md
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit 988817c

Please sign in to comment.