diff --git a/docs/content/learn/tutorials/_index.md b/docs/content/learn/tutorials/_index.md index 95d795560b..4fa4117c77 100644 --- a/docs/content/learn/tutorials/_index.md +++ b/docs/content/learn/tutorials/_index.md @@ -6,5 +6,7 @@ suppresstopiclist: true The following tutorials provide a step-by-step walkthrough on explaining how to create OSCAL content of various types. - [Creating a Basic Control Catalog](/learn/tutorials/catalog/): A tutorial on creating a [catalog](/concepts/terminology/#catalog) of [controls](/concepts/terminology/#control) using the OSCAL [catalog model](/concepts/layer/control/catalog/). +- [Creating and Using Metadata in OSCAL](/learn/tutorials/metadata): A tutorial that covers the usage of the metadata section in OSCAL. +- [Extending OSCAL Models with Props and Links](/learn/tutorials/extensions): A tutorial on extending OSCAL models by using props and links. - [Creating a Basic Component Definition](/learn/tutorials/component-definition/): A tutorial on creating a component-definition using the OSCAL [component definition model](/concepts/layer/implementation/component-definition/). - [Representing Test Validation Information](/learn/tutorials/validation-modeling/): A mini-tutorial on providing test validation information (e.g., FIPS 140-2 validation) as an OSCAL component in a [component definition](/concepts/layer/implementation/component-definition/) or [system security plan](/concepts/layer/implementation/ssp/). diff --git a/docs/content/learn/tutorials/extensions/_index.md b/docs/content/learn/tutorials/extensions/_index.md index 5c4cabbdd3..17237ee6cc 100644 --- a/docs/content/learn/tutorials/extensions/_index.md +++ b/docs/content/learn/tutorials/extensions/_index.md @@ -17,46 +17,103 @@ This tutorial describes the mechanisms for extending basic OSCAL models. Before OSCAL is designed with the goal of simultaneously supporting multiple cybersecurity frameworks. The core OSCAL syntax achieves this goal by focusing on properties that are universal or have applicability across various frameworks. -In creating OSCAL, NIST anticipated the importance of extensibility for unique requirements when organizations implement their security compliance programs. It was important to establish extension mechanisms from the onset, to allow organizations (and other stakeholders) to tailor OSCAL for their specific needs. +In creating OSCAL, NIST anticipated the importance of extensibility for unique requirements when organizations implement their security compliance programs. It was important to establish extension mechanisms from the onset, to allow OSCAL content creators to tailor OSCAL for their specific (organizational) needs. Thus, OSCAL is designed with extensibility as one of its key principles, allowing the OSCAL models to be extended wherever there are prop or link properties in the core models. This tutorial describes both extension mechanisms, explaining when to utilize them and illustrating their proper use. +{{% callout note %}} +Ellipsis (...) is used throughout this tutorial's examples where sample code is omitted for sake of simplicity. +{{% /callout %}} + ## Props -The `prop` property in OSCAL is used to extend core models when 1) there is a need to capture information that is not in the core OSCAL model or 2) there is a need to accommodate for property values that are not in core OSCAL. Props are defined by their given `name`, namespace `ns`, `value`, and `class` attributes, although only `name` and `value` are always required. Below is a description of each attribute: +{{< tabs XML JSON YAML >}} +{{% tab %}} + +The `` element in OSCAL is used to extend core models when 1) there is a need to capture information that is not in the core OSCAL model or 2) there is a need to accommodate for property values that are not in core OSCAL. Here is a nominal example of a `` element. + +{{< highlight xml "linenos=table" >}} +... +{{< /highlight >}} + +Props are defined by their given `@name`, namespace `@ns`, `@value`, and `@class` attributes, although only `@name` and `@value` are always required. Below is a description of each attribute: -- `name` (Required) - The `name` attributed is required for every `prop` and should be a [token](/reference/datatypes/#token) data type. Depending on the OSCAL model data item, a `prop` may have OSCAL pre-defined names. For example, the OSCAL SSP model's system characteristics data item has a pre-defined `prop` named [`data-center`](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics/prop). Other data items, such as the OSCAL SSP security sensitivity level data item has its own pre-defined `props` (e.g., [`privacy-designation`](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics/security-sensitivity-level)). And in other cases, such as the SSP authorization boundary data item, `prop` does not have any pre-defined `name` values. OSCAL content authors need to determine whether to use the OSCAL prescribed prop names or to locally define their own. To view existing `prop` name values or determine if `name` can be defined locally, review the [model reference index](/reference/latest/complete/xml-index/#/prop). Requests and recommendations to add pre-defined `names` should be sent to the OSCAL NIST team (see the [Contact Us Page](/contact)). -- `ns` (Optional) - The optional `ns` attribute is used to specify the namespace for a `prop` and should be a [universal resource identifier (URI)](/reference/datatypes/#uri) formatted according to RFC3986. The default namespace `ns` attribute for OSCAL `props` is `http://csrc.nist.gov/ns/oscal`, and can be omitted when using OSCAL define pre-defined properties (e.g., [`data-center`](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics/prop)). Namespaces qualify a property's name. This allows different organizations to associate distinct semantics with the same name. Organizations and other stakeholders have the ability to extend OSCAL with their own properties, which could lead to naming conflicts, however, the namespace `ns` can be specified by OSCAL content authors to prevent name collisions. -- `value` (Required) - The `value` attribute is required for every `prop` and should be a [string](/reference/datatypes/#string) data type. Generally, OSCAL content authors may specify any `value` for a `prop`. However, when using props with pre-defined `name` values, there are usually some constraints on acceptable `value`. For example, the OSCAL SSP [system characteristics](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics) data item pre-defined property named "identity-assurance-level" must have a value of 1, 2, or 3 as defined by NIST SP 800-63-3. The ability to extend with additional values depends on the `prop` (see the [model reference index](/reference/latest/complete/xml-index/#/prop)). The constraints for these `prop` properties are defined within the [OSCAL Metaschemas](https://github.com/usnistgov/OSCAL/tree/main/src/metaschema). Where applicable, Metaschema defines the `allowed-values` for the `prop` properties. The `prop` properties that are extensible are defined with an `allow-other=yes` attribute in Metaschema. -- `class` (Optional) - Finally, the optional `class` attribute should be used in cases where a property needs the same `name` and `ns` namespace. It is a textual label that provides a sub-type or characterization of the property's name. This can be used to further distinguish or discriminate between the semantics of multiple properties of the same object with the same name and ns. The `class` attribute should be a [token](/reference/datatypes/#token) data type and can be used in those circumstances to enable the "overloading" of the `prop`. +- `@name` (Required) - The `@name` attribute is required for every `` and must be a [token](/reference/datatypes/#token) data type. Depending on the OSCAL model data item, a `` may have OSCAL pre-defined names. For example, the OSCAL SSP model's system characteristics data item has a pre-defined `` named [`data-center`](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics/prop). Other data items, such as the OSCAL SSP security sensitivity level data item has its own pre-defined `` elements (e.g., [`privacy-designation`](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics/security-sensitivity-level)). And in other cases, such as the SSP authorization boundary data item, `` does not have any pre-defined `@name` values. OSCAL content authors need to determine whether to use the OSCAL prescribed prop names or to locally define their own. To view existing `` name values or determine if `@name` can be defined locally, review the [model reference index](/reference/latest/complete/xml-index/#/prop). Requests and recommendations to add pre-defined `@name` values should be sent to the OSCAL NIST team (see the [Contact Us Page](/contact)). +- `@ns` (Optional) - The optional `@ns` attribute is used to specify the namespace for a `` and must be a [universal resource identifier (URI)](/reference/datatypes/#uri) formatted according to [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). The default namespace `@ns` attribute for OSCAL `` is `http://csrc.nist.gov/ns/oscal`, and can be omitted when using OSCAL define pre-defined properties (e.g., [`data-center`](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics/prop)). Namespaces qualify a property's name. This allows different organizations to associate distinct semantics with the same name. Organizations and other stakeholders have the ability to extend OSCAL with their own properties, which could lead to naming conflicts, however, the namespace `@ns` can be specified by OSCAL content authors to prevent name collisions. +- `@value` (Required) - The `@value` attribute is required for every `` and must be a [string](/reference/datatypes/#string) data type. Generally, OSCAL content authors may specify any `@value` for a ``. However, when using props with pre-defined `@name` values, there are usually some constraints on acceptable `value`. For example, the OSCAL SSP [system characteristics](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics) data item pre-defined property named "identity-assurance-level" must have a value of 1, 2, or 3 as defined by NIST SP 800-63-3. The ability to extend with additional values depends on the `` (see the [model reference index](/reference/latest/complete/xml-index/#/prop)). The constraints for these `` properties are defined within the [OSCAL Metaschemas](https://github.com/usnistgov/OSCAL/tree/main/src/metaschema). Where applicable, Metaschema defines the `allowed-values` for the `` properties. The `` properties that are extensible are defined with an `@allow-other=yes` attribute in Metaschema. +- `@class` (Optional) - Finally, the optional `@class` attribute should be used in cases where a property needs the same `@name` and `@ns` namespace. It is a textual label that provides a sub-type or characterization of the property's name. This can be used to further distinguish or discriminate between the semantics of multiple properties of the same object with the same name and ns. The `@class` attribute must be a [token](/reference/datatypes/#token) data type and can be used in those circumstances to enable the "overloading" of the ``. + +{{% /tab %}} +{{% tab %}} + +The `props` object array in OSCAL is used to extend core models when 1) there is a need to capture information that is not in the core OSCAL model or 2) there is a need to accommodate for property values that are not in core OSCAL. Here is a nominal example of a `props` object array. + +{{< highlight json "linenos=table" >}} +{ + "props": [ + { + "name":"...", + "ns":"...", + "value":"...", + "class":"..." + } + ] +} +{{< /highlight >}} + +Props are defined by their given `name`, namespace `ns`, `value`, and `class` properties, although only `name` and `value` are always required. Below is a description of each property: + +- `name` (Required) - The `name` property is required for every `prop` and must be a [token](/reference/datatypes/#token) data type. Depending on the OSCAL model data item, a `prop` may have OSCAL pre-defined names. For example, the OSCAL SSP model's system characteristics data item has a pre-defined `prop` named [`data-center`](/reference/latest/system-security-plan/json-reference/#/system-security-plan/system-characteristics/props). Other data items, such as the OSCAL SSP security sensitivity level data item has its own pre-defined `prop` objects (e.g., [`privacy-designation`](/reference/latest/system-security-plan/json-reference/#/system-security-plan/system-characteristics/security-sensitivity-level)). And in other cases, such as the SSP authorization boundary data item, `prop` does not have any pre-defined `name` values. OSCAL content authors need to determine whether to use the OSCAL prescribed prop names or to locally define their own. To view existing `prop` name values or determine if `name` can be defined locally, review the [model reference index](/reference/latest/complete/json-index/#/props). Requests and recommendations to add pre-defined `name` values should be sent to the OSCAL NIST team (see the [Contact Us Page](/contact)). +- `ns` (Optional) - The optional `ns` property is used to specify the namespace for a `prop` and must be a [universal resource identifier (URI)](/reference/datatypes/#uri) formatted according to [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). The default namespace `ns` property for OSCAL `prop` is `http://csrc.nist.gov/ns/oscal`, and can be omitted when using OSCAL define pre-defined properties (e.g., [`data-center`](/reference/latest/system-security-plan/json-reference/#/system-security-plan/system-characteristics/props)). Namespaces qualify a property's name. This allows different organizations to associate distinct semantics with the same name. Organizations and other stakeholders have the ability to extend OSCAL with their own properties, which could lead to naming conflicts, however, the namespace `ns` can be specified by OSCAL content authors to prevent name collisions. +- `value` (Required) - The `value` property is required for every `prop` and must be a [string](/reference/datatypes/#string) data type. Generally, OSCAL content authors may specify any `value` for a `prop`. However, when using props with pre-defined `name` values, there are usually some constraints on acceptable `value`. For example, the OSCAL SSP [system characteristics](/reference/latest/system-security-plan/json-reference/#/system-security-plan/system-characteristics) data item pre-defined property named "identity-assurance-level" must have a value of 1, 2, or 3 as defined by NIST SP 800-63-3. The ability to extend with additional values depends on the `prop` (see the [model reference index](/reference/latest/complete/json-index/#/props)). The constraints for these `prop` properties are defined within the [OSCAL Metaschemas](https://github.com/usnistgov/OSCAL/tree/main/src/metaschema). Where applicable, Metaschema defines the `allowed-values` for the `prop` properties. The `prop` properties that are extensible are defined with an `allow-other=yes` property in Metaschema. +- `class` (Optional) - Finally, the optional `class` property should be used in cases where a property needs the same `name` and `ns` namespace. It is a textual label that provides a sub-type or characterization of the property's name. This can be used to further distinguish or discriminate between the semantics of multiple properties of the same object with the same name and ns. The `class` property must be a [token](/reference/datatypes/#token) data type and can be used in those circumstances to enable the "overloading" of the `prop`. +{{% /tab %}} +{{% tab %}} +The `props` key-value pair array in OSCAL is used to extend core models when 1) there is a need to capture information that is not in the core OSCAL model or 2) there is a need to accommodate for key values that are not in core OSCAL. Here is a nominal example of a `props` key-value pair array. + +{{< highlight yaml "linenos=table" >}} + props: + - name: ... + ns: ... + value: ... + class: ... +{{< /highlight >}} + +Props are defined by their given `name`, namespace `ns`, `value`, and `class` keys, although only `name` and `value` are always required. Below is a description of each key: + +- `name` (Required) - The `name` key is required for every `prop` and must be a [token](/reference/datatypes/#token) data type. Depending on the OSCAL model data item, a `prop` may have OSCAL pre-defined names. For example, the OSCAL SSP model's system characteristics data item has a pre-defined `prop` named [`data-center`](/reference/latest/system-security-plan/json-reference/#/system-security-plan/system-characteristics/props). Other data items, such as the OSCAL SSP security sensitivity level data item has its own pre-defined `prop` objects (e.g., [`privacy-designation`](/reference/latest/system-security-plan/json-reference/#/system-security-plan/system-characteristics/security-sensitivity-level)). And in other cases, such as the SSP authorization boundary data item, `prop` does not have any pre-defined `name` values. OSCAL content authors need to determine whether to use the OSCAL prescribed prop names or to locally define their own. To view existing `prop` name values or determine if `name` can be defined locally, review the [model reference index](/reference/latest/complete/json-index/#/props). Requests and recommendations to add pre-defined `name` values should be sent to the OSCAL NIST team (see the [Contact Us Page](/contact)). +- `ns` (Optional) - The optional `ns` key is used to specify the namespace for a `prop` and must be a [universal resource identifier (URI)](/reference/datatypes/#uri) formatted according to [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). The default namespace `ns` key for OSCAL `prop` is `http://csrc.nist.gov/ns/oscal`, and can be omitted when using OSCAL define pre-defined keys (e.g., [`data-center`](/reference/latest/system-security-plan/json-reference/#/system-security-plan/system-characteristics/props)). Namespaces qualify a property's name. This allows different organizations to associate distinct semantics with the same name. Organizations and other stakeholders have the ability to extend OSCAL with their own keys, which could lead to naming conflicts, however, the namespace `ns` can be specified by OSCAL content authors to prevent name collisions. +- `value` (Required) - The `value` key is required for every `prop` and must be a [string](/reference/datatypes/#string) data type. Generally, OSCAL content authors may specify any `value` for a `prop`. However, when using props with pre-defined `name` values, there are usually some constraints on acceptable `value`. For example, the OSCAL SSP [system characteristics](/reference/latest/system-security-plan/json-reference/#/system-security-plan/system-characteristics) data item pre-defined key named "identity-assurance-level" must have a value of 1, 2, or 3 as defined by NIST SP 800-63-3. The ability to extend with additional values depends on the `prop` (see the [model reference index](/reference/latest/complete/json-index/#/props)). The constraints for these `prop` keys are defined within the [OSCAL Metaschemas](https://github.com/usnistgov/OSCAL/tree/main/src/metaschema). Where applicable, Metaschema defines the `allowed-values` for the `prop` keys. The `prop` keys that are extensible are defined with an `allow-other=yes` key-value in Metaschema. +- `class` (Optional) - Finally, the optional `class` key should be used in cases where a property needs the same `name` and `ns` namespace. It is a textual label that provides a sub-type or characterization of the property's name. This can be used to further distinguish or discriminate between the semantics of multiple keys of the same object with the same name and ns. The `class` key must be a [token](/reference/datatypes/#token) data type and can be used in those circumstances to enable the "overloading" of the `prop`. +{{% /tab %}} +{{% /tabs %}} ### Using an Existing Prop -This sections covers the basic use of a `prop` leveraging all of its attributes. The OSCAL SSP [metadata](/concepts/layer/overview/#metadata-overview) allows for zero or more `location` data items, each containing zero or more `props`. +{{< tabs XML JSON YAML >}} +{{% tab %}} +This sections covers the basic use of a `` leveraging all of its attributes. The OSCAL SSP [metadata](/concepts/layer/overview/#metadata-overview) allows for zero or more `` data items, each containing zero or more `` elements. {{% callout note %}} The [Metadata Tutorial](/learn/tutorials/metadata/) provides in-depth description and walk-through examples of creating OSCAL metadata. {{% /callout %}} -In this example, an organization needs to document their primary and alternate data center locations. This is achieved by specifying the `name`, `value`, and `class` of the properties for each location. - -{{< tabs XML JSON YAML >}} +In this example, an organization needs to document their primary and alternate data center locations. This is achieved by specifying the `@name`, `@value`, and `@class` of the properties for each location. -{{% tab %}} {{< highlight xml "linenos=table" >}} OSCAL Basic Prop Example - 2001-12-17T09:30:47Z - 20210812 + 2022-01-01T09:30:00-005 + 20220531 1.0.0 - .... + ... ... - .... + ... ... @@ -64,25 +121,31 @@ In this example, an organization needs to document their primary and alternate d ... ... -{{< /highlight >}} +{{< /highlight >}} The `@name` attribute is set to "type" which is an OSCAL pre-defined property. The `@value` attribute is set to "data-center" which is an [OSCAL pre-defined](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/metadata/location) value for location "type" properties. The `@class` attribute in this case is used to indicate a subclass of data-center, and is set the the appropriate [OSCAL pre-defined](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/metadata/location) values for data center location properties. Note that in this example, the `@ns` attribute is omitted because we are using a standard OSCAL defined `` element. - {{% /tab %}} - {{% tab %}} +This sections covers the basic use of a `prop` leveraging all of its properties. The OSCAL SSP [metadata](/concepts/layer/overview/#metadata-overview) allows for zero or more `location` objects, each containing zero or more `` objects. + +{{% callout note %}} +The [Metadata Tutorial](/learn/tutorials/metadata/) provides in-depth description and walk-through examples of creating OSCAL metadata. +{{% /callout %}} + +In this example, an organization needs to document their primary and alternate data center locations. This is achieved by specifying the `name`, `value`, and `class` of the key-value pairs for each location. + {{< highlight json "linenos=table" >}} { "system-security-plan": { "uuid": "ce16b9af-6853-4abe-9e27-b79d034c0adc", "metadata": { "title": "OSCAL Basic Prop Example", - "last-modified": "2001-12-17T09:30:47Z", - "version": 20210812, + "last-modified": "2022-01-01T09:30:00-005", + "version": 20220531, "oscal-version": "1.0.0", "locations": [ { - "title": "....", + "title": "...", "props": [ { "name":"type", @@ -92,7 +155,7 @@ The `@name` attribute is set to "type" which is an OSCAL pre-defined property. T ] }, { - "title": "....", + "title": "...", "props": [ { "name":"type", @@ -110,25 +173,31 @@ The `@name` attribute is set to "type" which is an OSCAL pre-defined property. T {{< /highlight >}} In the `props` object array, the prop object's `name` property is set to "type" which is an OSCAL pre-defined property. The `value` property is set to "data-center" which is an [OSCAL pre-defined](/reference/latest/system-security-plan/json-reference/#/system-security-plan/metadata/locations) value for location "type" properties. The `class` property in this case is used to indicate a subclass of data-center, and is set the the appropriate [OSCAL pre-defined](/reference/latest/system-security-plan/json-reference/#/system-security-plan/metadata/locations) values for data center location `prop`. Note that in this example, the `ns` property is omitted because we are using a standard OSCAL defined `prop` object. - {{% /tab %}} - {{% tab %}} +This sections covers the basic use of a `prop` leveraging all of its properties. The OSCAL SSP [metadata](/concepts/layer/overview/#metadata-overview) allows for zero or more `location` objects, each containing zero or more `` objects. + +{{% callout note %}} +The [Metadata Tutorial](/learn/tutorials/metadata/) provides in-depth description and walk-through examples of creating OSCAL metadata. +{{% /callout %}} + +In this example, an organization needs to document their primary and alternate data center locations. This is achieved by specifying the `name`, `value`, and `class` of the key-value pairs for each location. + {{< highlight yaml "linenos=table" >}} system-security-plan: uuid: ce16b9af-6853-4abe-9e27-b79d034c0adc metadata: title: OSCAL Basic Prop Example - last-modified: '2001-12-17T09:30:47Z' - version: 20210812 + last-modified: '2022-01-01T09:30:00-005' + version: 20220531 oscal-version: 1.0.0 locations: - - title: .... + - title: ... props: - name: type value: data-center class: primary - - title: .... + - title: ... props: - name: type value: data-center @@ -139,36 +208,33 @@ system-security-plan: {{< /highlight >}} In the `props` object array, the prop object's `name` property is set to "type" which is an OSCAL pre-defined property. The `value` property is set to "data-center" which is an [OSCAL pre-defined](/reference/latest/system-security-plan/json-reference/#/system-security-plan/metadata/locations) value for location "type" properties. The `class` property in this case is used to indicate a subclass of data-center, and is set the the appropriate [OSCAL pre-defined](/reference/latest/system-security-plan/json-reference/#/system-security-plan/metadata/locations) values for data center location `prop`. Note that in this example, the `ns` property is omitted because we are using a standard OSCAL defined `prop` object. - {{% /tab %}} - {{% /tabs %}} ### Extending Existing Prop Values -One of the most common scenarios for extending an OSCAL `prop` is when adding values to an existing OSCAL property. Again, if using an OSCAL defined `prop`, the `ns` namespace attribute does not need to be specified since the default OSCAL namespace applies. +{{< tabs XML JSON YAML >}} +{{% tab %}} +One of the most common scenarios for extending an OSCAL `` is when adding values to an existing OSCAL property. Again, if using an OSCAL defined ``, the `@ns` namespace attribute does not need to be specified since the default OSCAL namespace applies. -The following example demonstrates how to extend a SSP metadata location "type" `prop` with an additional value. +The following example demonstrates how to extend a SSP metadata location "type" `` with an additional value. {{% callout note %}} Again, for a detailed overview of how to implement metadata, please refer to the [Metadata Tutorial](/learn/tutorials/metadata/). {{% /callout %}} -Currently, the only OSCAL defined value for the SSP metadata location `prop` is "data-center". However, because this particular `prop` is defined with an `allow-other=yes` attribute (in Metaschema), additional "type" values can be specified as shown below on line #10. - -{{< tabs XML JSON YAML >}} +Currently, the only OSCAL defined value for the SSP metadata location `` is "data-center". However, because this particular `` is defined with an `@allow-other=yes` attribute (in Metaschema), additional "type" values can be specified as shown below on line #10. -{{% tab %}} {{< highlight xml "linenos=table" >}} OSCAL Basic Prop Example - 2001-12-17T09:30:47Z - 20210812 + 2022-01-01T09:30:00-005 + 20220531 1.0.0 - .... + ... ... @@ -181,20 +247,29 @@ Currently, the only OSCAL defined value for the SSP metadata location `prop` is The `@class` attribute was not specified but could be added if there was a need for semantic classification of "security operations center" (e.g., regional or global). {{% /tab %}} - {{% tab %}} +One of the most common scenarios for extending an OSCAL `prop` is when adding values to an existing OSCAL property. Again, if using an OSCAL defined `prop`, the `ns` namespace property does not need to be specified since the default OSCAL namespace applies. + +The following example demonstrates how to extend a SSP metadata location "type" `prop` with an additional value. + +{{% callout note %}} +Again, for a detailed overview of how to implement metadata, please refer to the [Metadata Tutorial](/learn/tutorials/metadata/). +{{% /callout %}} + +Currently, the only OSCAL defined value for the SSP metadata location `prop` is "data-center". However, because this particular `prop` is defined with an `allow-other=yes` property (in Metaschema), additional "type" values can be specified as shown below on line #14. + {{< highlight json "linenos=table" >}} { "system-security-plan": { "uuid": "ce16b9af-6853-4abe-9e27-b79d034c0adc", "metadata": { "title": "OSCAL Basic Prop Example", - "last-modified": "2001-12-17T09:30:47Z", - "version": 20210812, + "last-modified": "2022-01-01T09:30:00-005", + "version": 20220531, "oscal-version": "1.0.0", "locations": [ { - "title": "....", + "title": "...", "props": [ { "name":"type", @@ -213,18 +288,27 @@ The `@class` attribute was not specified but could be added if there was a need The `class` property was not specified but could be added if there was a need for semantic classification of "security operations center" (e.g., regional or global). {{% /tab %}} - {{% tab %}} +One of the most common scenarios for extending an OSCAL `prop` is when adding values to an existing OSCAL property. Again, if using an OSCAL defined `prop`, the `ns` namespace key-value does not need to be specified since the default OSCAL namespace applies. + +The following example demonstrates how to extend a SSP metadata location "type" `prop` with an additional value. + +{{% callout note %}} +Again, for a detailed overview of how to implement metadata, please refer to the [Metadata Tutorial](/learn/tutorials/metadata/). +{{% /callout %}} + +Currently, the only OSCAL defined value for the SSP metadata location `prop` is "data-center". However, because this particular `prop` is defined with an `allow-other=yes` key-value pair (in Metaschema), additional "type" values can be specified as shown below on line #12. + {{< highlight yaml "linenos=table" >}} system-security-plan: uuid: ce16b9af-6853-4abe-9e27-b79d034c0adc metadata: title: OSCAL Basic Prop Example - last-modified: '2001-12-17T09:30:47Z' - version: 20210812 + last-modified: '2022-01-01T09:30:00-005' + version: 20220531 oscal-version: 1.0.0 locations: - - title: .... + - title: ... props: - name: type value: security-operations-center @@ -241,21 +325,20 @@ The `class` property was not specified but could be added if there was a need fo ### Creating a New Prop -The previous examples leveraged an existing OSCAL `prop` to document location details (e.g., location "type") within an SSP. But what if there were other pertinent location details that needed to be captured as well? For example, some government organizations with distributed global physical locations may want to use [Geographic Locator Codes (GLC)](https://www.gsa.gov/reference/geographic-locator-codes-glcs-overview) to facilitate interchange of location data with other government agencies. The example below demonstrates how this could be documented by specifying a new GLC `prop` property (see lines #15-33). - {{< tabs XML JSON YAML >}} - {{% tab %}} +The previous examples leveraged an existing OSCAL `` to document location details (e.g., location "type") within an SSP. But what if there were other pertinent location details that needed to be captured as well? For example, some government organizations with distributed global physical locations may want to use [Geographic Locator Codes (GLC)](https://www.gsa.gov/reference/geographic-locator-codes-glcs-overview) to facilitate interchange of location data with other government agencies. The example below demonstrates how this could be documented by specifying a new GLC `` property (see lines #15-33). + {{< highlight xml "linenos=table" >}} OSCAL New Prop Example - 2001-12-17T09:30:47Z - 20210812 + 2022-01-01T09:30:00-005 + 20220531 1.0.0 - .... + ... @@ -291,20 +374,21 @@ A new GLC property was created by setting the `` element's `@name` attribu Props are prevalent throughout OSCAL models appearing not only in `` and ``, but in the majority of OSCAL data items. Regardless of which OSCAL element is being extended, the approach is consistent, as described in this section of the tutorial. {{% /tab %}} - {{% tab %}} +The previous examples leveraged an existing OSCAL `prop` to document location details (e.g., location "type") within an SSP. But what if there were other pertinent location details that needed to be captured as well? For example, some government organizations with distributed global physical locations may want to use [Geographic Locator Codes (GLC)](https://www.gsa.gov/reference/geographic-locator-codes-glcs-overview) to facilitate interchange of location data with other government agencies. The example below demonstrates how this could be documented by specifying a new GLC `prop` property (see lines #22-51). + {{< highlight json "linenos=table" >}} { "system-security-plan": { "uuid": "ce16b9af-6853-4abe-9e27-b79d034c0adc", "metadata": { "title": "OSCAL Basic Prop Example", - "last-modified": "2001-12-17T09:30:47Z", - "version": 20210812, + "last-modified": "2022-01-01T09:30:00-005", + "version": 20220531, "oscal-version": "1.0.0", "locations": [ { - "title": "....", + "title": "...", "props": [ { "name":"type", @@ -314,7 +398,7 @@ Props are prevalent throughout OSCAL models appearing not only in `` a ] }, { - "title": "....", + "title": "...", "props": [ { "name":"glc", @@ -325,7 +409,7 @@ Props are prevalent throughout OSCAL models appearing not only in `` a ] }, { - "title": "....", + "title": "...", "props": [ { "name":"glc", @@ -336,7 +420,7 @@ Props are prevalent throughout OSCAL models appearing not only in `` a ] }, { - "title": "....", + "title": "...", "props": [ { "name":"glc", @@ -359,35 +443,36 @@ A new GLC property was created by setting the `prop` object's `name` property to Props are prevalent throughout OSCAL models appearing not only in `metadata` and `back-matter` objects, but in the majority of OSCAL data items. Regardless of which OSCAL property is being extended, the approach is consistent, as described in this section of the tutorial. {{% /tab %}} - {{% tab %}} +The previous examples leveraged an existing OSCAL `prop` to document location details (e.g., location "type") within an SSP. But what if there were other pertinent location details that needed to be captured as well? For example, some government organizations with distributed global physical locations may want to use [Geographic Locator Codes (GLC)](https://www.gsa.gov/reference/geographic-locator-codes-glcs-overview) to facilitate interchange of location data with other government agencies. The example below demonstrates how this could be documented by specifying a new GLC `prop` property (see lines #15-31). + {{< highlight yaml "linenos=table" >}} system-security-plan: uuid: ce16b9af-6853-4abe-9e27-b79d034c0adc metadata: title: OSCAL Basic Prop Example - last-modified: '2001-12-17T09:30:47Z' - version: 20210812 + last-modified: '2022-01-01T09:30:00-005' + version: 20220531 oscal-version: 1.0.0 locations: - - title: .... + - title: ... props: - name: type value: security-operations-center class: regional - - title: .... + - title: ... props: - name: glc ns: http://federal-agency.gov/ns/oscal value: '11' class: state-code - - title: .... + - title: ... props: - name: glc ns: http://federal-agency.gov/ns/oscal value: '0010' class: city-code - - title: .... + - title: ... props: - name: glc ns: http://federal-agency.gov/ns/oscal @@ -402,41 +487,100 @@ system-security-plan: A new GLC property was created by setting the `prop` object's `name` property to "glc". The acronym "glc" could be used by other organizations (and have a completely different meaning) so a namespace `ns` was set. Lastly, GLCs have many data attributes including territory, country codes, state codes, county codes, city codes, and duty station codes, so this example defined a single "glc" `prop` but used `class` to provide context for the property's set `value`. Props are prevalent throughout OSCAL models appearing not only in `metadata` and `back-matter` objects, but in the majority of OSCAL data items. Regardless of which OSCAL property is being extended, the approach is consistent, as described in this section of the tutorial. - {{% /tab %}} - {{% /tabs %}} ## Links Links in OSCAL provide a form of indirection, allowing the referencing of local or remote content. Link can be particularly useful in referencing (external) information that is not represented in OSCAL format. This could include references to (cybersecurity) laws and regulations; references to organizational standards and guides; references to system bill of materials (SBOM) and more. Organizations can limit duplication of content, reduce the size of their OSCAL files, and maintain important content relationships by using links. -The `link` property is made available in specific OSCAL models and supports either URL or back matter resources. The `link` property has the following attributes: `href`, `rel`, `media-type`, and `text`. +{{< tabs XML JSON YAML >}} +{{% tab %}} +The `` element is made available in specific OSCAL models and supports either URL or back matter resources. The `` element has a `` sub-element, and the following attributes: `@href`, `@rel`, and `@media-type`. Here is a nominal example of a `` element. -- `href` (Required) - The `href` attribute is a required, [resolvable URL reference](/reference/datatypes/#uri-reference) to a resource. This can either be an internet resource or a fragment that point to a back matter resource in the same document. -- `rel` (Optional) - The optional `rel` attribute is a [token](/reference/datatypes/#token) datatype that can be used to describe the link's purpose. Some OSCAL link properties may have pre-defined `rel` values (e.g., reference), but generally, OSCAL content authors can specify any token value for a `rel` attribute. Although any string can be used in the `rel` attribute, OSCAL identifies five common link relationships that are frequently useful: +{{< highlight xml "linenos=table" >}} + + ... + +{{< /highlight >}} + +Below is description of `` attributes and sub-element: +- `@href` (Required) - The `@href` attribute is a required, [resolvable URL reference](/reference/datatypes/#uri-reference) to a resource. This can either be an internet resource or a fragment that point to a back matter resource in the same document. +- `@rel` (Optional) - The optional `@rel` attribute is a [token](/reference/datatypes/#token) datatype that can be used to describe the link's purpose. Some OSCAL link properties may have pre-defined `@rel` values (e.g., reference), but generally, OSCAL content authors can specify any token value for a `@rel` attribute. Although any string can be used in the `@rel` attribute, OSCAL identifies five common link relationships that are frequently useful: - canonical: The link identifies the authoritative location for this file. - alternate: The link identifies an alternative location or format for this file. - - latest-version: This link identifies a resource containing the latest version in the version history. Defined by RFC 5829. - - predecessor-version: This link identifies a resource containing the predecessor version in the version history. RFC 5829. - - successor-version: This link identifies a resource containing the predecessor version in the version history. RFC 5829. -- `media-type` (Optional) - The optional `media-type` attribute can be used to provide the consumer of the OSCAL content a hint about the type of data referenced in the link. Supported media types are as defined by the [Internet Assigned Numbers Authority (IANA)](https://www.iana.org/assignments/media-types/media-types.xhtml). The `media-type` attribute accepts [string](/reference/datatypes/#string) values. -- `text` (Optional) - Finally, the optional `text` sub-element can be used for as a textual label for the `link` and accepts [markup-line](/reference/datatypes/#markup-line) datatype. The subsequent sections demonstrate the proper use of links. + - latest-version: This link identifies a resource containing the latest version in the version history. Defined by [RFC 5829](https://datatracker.ietf.org/doc/html/rfc5829). + - predecessor-version: This link identifies a resource containing the predecessor version in the version history. Defined by [RFC 5829](https://datatracker.ietf.org/doc/html/rfc5829). + - successor-version: This link identifies a resource containing the predecessor version in the version history. Defined by [RFC 5829](https://datatracker.ietf.org/doc/html/rfc5829). +- `@media-type` (Optional) - The optional `@media-type` attribute can be used to provide the consumer of the OSCAL content a hint about the type of data referenced in the link. Supported media types are as defined by the [Internet Assigned Numbers Authority (IANA)](https://www.iana.org/assignments/media-types/media-types.xhtml). The `@media-type` attribute accepts [string](/reference/datatypes/#string) values. +- `` (Optional) - Finally, the optional `` sub-element can be used for as a textual label for the `` and accepts [markup-line](/reference/datatypes/#markup-line) datatype. The subsequent sections demonstrate the proper use of links. +{{% /tab %}} +{{% tab %}} +The `links` object array is made available in specific OSCAL models and supports either URL or back matter resources. The `link` object has the following properties: `href`, `rel`, `media-type`, and `text`. Here is a nominal example of a `links` object array. + +{{< highlight json "linenos=table" >}} +{ + "links": [ + { + "href": "...", + "rel": "...", + "media-type": "...", + "text": "..." + } + ] +} +{{< /highlight >}} + +Below is description of `links` properties: +- `href` (Required) - The `href` property is a required, [resolvable URL reference](/reference/datatypes/#uri-reference) to a resource. This can either be an internet resource or a fragment that point to a back matter resource in the same document. +- `rel` (Optional) - The optional `rel` property is a [token](/reference/datatypes/#token) datatype that can be used to describe the link's purpose. Some OSCAL link properties may have pre-defined `rel` values (e.g., reference), but generally, OSCAL content authors can specify any token value for a `rel` property. Although any string can be used in the `rel` attribute, OSCAL identifies five common link relationships that are frequently useful: + - canonical: The link identifies the authoritative location for this file. + - alternate: The link identifies an alternative location or format for this file. + - latest-version: This link identifies a resource containing the latest version in the version history. Defined by [RFC 5829](https://datatracker.ietf.org/doc/html/rfc5829)9. + - predecessor-version: This link identifies a resource containing the predecessor version in the version history. Defined by [RFC 5829](https://datatracker.ietf.org/doc/html/rfc5829). + - successor-version: This link identifies a resource containing the predecessor version in the version history. Defined by [RFC 5829](https://datatracker.ietf.org/doc/html/rfc5829). +- `media-type` (Optional) - The optional `media-type` property can be used to provide the consumer of the OSCAL content a hint about the type of data referenced in the link. Supported media types are as defined by the [Internet Assigned Numbers Authority (IANA)](https://www.iana.org/assignments/media-types/media-types.xhtml). The `media-type` property accepts [string](/reference/datatypes/#string) values. +- `text` (Optional) - Finally, the optional `text` property can be used for as a textual label for the `link` and accepts [markup-line](/reference/datatypes/#markup-line) datatype. The subsequent sections demonstrate the proper use of links. +{{% /tab %}} +{{% tab %}} +The `links` key-value pair array is made available in specific OSCAL models and supports either URL or back matter resources. The `link` object has the following properties: `href`, `rel`, `media-type`, and `text`. Here is a nominal example of a `links` key-value pair array. + +{{< highlight yaml "linenos=table" >}} + links: + - href: ... + rel: ... + media-type: ... + text: ... +{{< /highlight >}} + +Below is description of `links` key-values: +- `href` (Required) - The `href` key is a required, [resolvable URL reference](/reference/datatypes/#uri-reference) to a resource. This can either be an internet resource or a fragment that point to a back matter resource in the same document. +- `rel` (Optional) - The optional `rel` key is a [token](/reference/datatypes/#token) datatype that can be used to describe the link's purpose. Some OSCAL link properties may have pre-defined `rel` values (e.g., reference), but generally, OSCAL content authors can specify any token value for a `rel` key. Although any string can be used in the `rel` attribute, OSCAL identifies five common link relationships that are frequently useful: + - canonical: The link identifies the authoritative location for this file. + - alternate: The link identifies an alternative location or format for this file. + - latest-version: This link identifies a resource containing the latest version in the version history. Defined by [RFC 5829](https://datatracker.ietf.org/doc/html/rfc5829). + - predecessor-version: This link identifies a resource containing the predecessor version in the version history. Defined by [RFC 5829](https://datatracker.ietf.org/doc/html/rfc5829). + - successor-version: This link identifies a resource containing the predecessor version in the version history. Defined by [RFC 5829](https://datatracker.ietf.org/doc/html/rfc5829). +- `media-type` (Optional) - The optional `media-type` key can be used to provide the consumer of the OSCAL content a hint about the type of data referenced in the link. Supported media types are as defined by the [Internet Assigned Numbers Authority (IANA)](https://www.iana.org/assignments/media-types/media-types.xhtml). The `media-type` key accepts [string](/reference/datatypes/#string) values. +- `text` (Optional) - Finally, the optional `text` key can be used for as a textual label for the `link` and accepts [markup-line](/reference/datatypes/#markup-line) datatype. The subsequent sections demonstrate the proper use of links. +{{% /tab %}} +{{% /tabs %}} ### Link to internet URL Organizations may need their documentation (e.g., SSP) to reference external items, such applicable laws and regulations (e.g., HSPD-12) and other organizational items (e.g., official agency logos). This first example illustrates how an OSCAL SSP might make use of a link to an internet URL. {{< tabs XML JSON YAML >}} - {{% tab %}} {{< highlight xml "linenos=table" >}} OSCAL SSP Component Link Example - 2001-12-17T09:30:47Z - 20210707 + 2022-01-01T09:30:00-005 + 20220531 1.0.0 @@ -459,7 +603,6 @@ Line #11 demonstrates the use of `` to point to the organization's officia The next section demonstrates how to reference back matter resources with links. Specifying a fragment in the `@href` attribute indicates that the `` is referencing a `` `` in the same OSCAL document. {{% /tab %}} - {{% tab %}} {{< highlight json "linenos=table" >}} { @@ -467,7 +610,7 @@ The next section demonstrates how to reference back matter resources with links. "uuid": "ce16b9af-6853-4abe-9e27-b79d034c0adc", "metadata": { "title": "OSCAL SSP Component Link Example", - "last-modified": "2001-12-17T09:30:47Z", + "last-modified": "2022-01-01T09:30:00-005", "version": 20210707, "oscal-version": "1.0.0", "links": [ @@ -490,21 +633,20 @@ The next section demonstrates how to reference back matter resources with links. } {{< /highlight >}} -In this case, the `links` object array on line #8 provides a reference to HSPD-12 by specifying the URL in the `href` property. The OSCAL pre-defined "reference" value is used for the `rel`, providing context for the purpose of this specific `link`. The `text` property provides an associated label for the `link` which may be useful when rendering the SSP in other formats (e.g., html or office document formats). +In this case, the `links` object array on line #9 provides a reference to HSPD-12 by specifying the URL in the `href` property. The OSCAL pre-defined "reference" value is used for the `rel`, providing context for the purpose of this specific `link`. The `text` property provides an associated label for the `link` which may be useful when rendering the SSP in other formats (e.g., html or office document formats). -Lines #14-18 demonstrate the use of link to point to the organization's official logo. An absolute URI was used to point to the location of the referenced content, however, it should be noted that the `href` property also permits the use of relative URI paths. If the referenced resource is located is on the same machine or domain, then a relative URI path could be used. The `rel` property was set to "logo" to indicate the type of relationship provided by the specified `link`. The `media-type` property was included to let any rendering tools know that the logo content is a PNG image type. The optional `text` property was excluded for brevity of this example. +Lines #16-18 demonstrate the use of link to point to the organization's official logo. An absolute URI was used to point to the location of the referenced content, however, it should be noted that the `href` property also permits the use of relative URI paths. If the referenced resource is located is on the same machine or domain, then a relative URI path could be used. The `rel` property was set to "logo" to indicate the type of relationship provided by the specified `link`. The `media-type` property was included to let any rendering tools know that the logo content is a PNG image type. The optional `text` property was excluded for brevity of this example. The next section demonstrates how to reference back matter resources with links. Specifying a fragment in the `href` property indicates that the `link` is referencing a `back-matter` `resources` object array in the same OSCAL document. {{% /tab %}} - {{% tab %}} {{< highlight yaml "linenos=table" >}} system-security-plan: uuid: ce16b9af-6853-4abe-9e27-b79d034c0adc metadata: title: OSCAL SSP Component Link Example - last-modified: '2001-12-17T09:30:47Z' + last-modified: '2022-01-01T09:30:00-005' version: 20210707 oscal-version: 1.0.0 links: @@ -520,32 +662,29 @@ system-security-plan: {{< /highlight >}} -In this case, the `links` object array on line #7 provides a reference to HSPD-12 by specifying the URL in the `href` property. The OSCAL pre-defined "reference" value is used for the `rel`, providing context for the purpose of this specific `link`. The `text` property provides an associated label for the `link` which may be useful when rendering the SSP in other formats (e.g., html or office document formats). +In this case, the `links` object array on line #9 provides a reference to HSPD-12 by specifying the URL in the `href` property. The OSCAL pre-defined "reference" value is used for the `rel`, providing context for the purpose of this specific `link`. The `text` property provides an associated label for the `link` which may be useful when rendering the SSP in other formats (e.g., html or office document formats). Lines #11-13 demonstrate the use of link to point to the organization's official logo. An absolute URI was used to point to the location of the referenced content, however, it should be noted that the `href` property also permits the use of relative URI paths. If the referenced resource is located is on the same machine or domain, then a relative URI path could be used. The `rel` property was set to "logo" to indicate the type of relationship provided by the specified `link`. The `media-type` property was included to let any rendering tools know that the logo content is a PNG image type. The optional `text` property was excluded for brevity of this example. The next section demonstrates how to reference back matter resources with links. Specifying a fragment in the `href` property indicates that the `link` is referencing a `back-matter` `resources` object array in the same OSCAL document. - {{% /tab %}} - {{% /tabs %}} ### Referencing Back-Matter -When using `link` to reference `back-matter` `resources`, the `link` must use the resource's `uuid` attribute as the pointer. The `resource` property must have an `rlink` property that points to the (external) content via the `href` attribute. Optionally, the `rlink` property can also include a hash (e.g., to ensure the integrity of the referenced content), however, that is an advanced concept that is not covered in this tutorial. - -In the previous section, multiple `links` would need to be created in the SSP metadata for each applicable laws and regulations. However, another approach would be to specify one `link` in the metadata for all applicable laws, regulations, standards, and guides. Then a single `resource` (for the applicable laws, regulations, standards, and guides) with multiple `rlinks` could be set in the back-matter as illustrated below. - {{< tabs XML JSON YAML >}} - {{% tab %}} +When using `` to reference a back-matter ``, the `` must use the resource's `@uuid` attribute as the pointer. The `` property must have an `` sub-element that points to the (external) content via the `@href` attribute. Optionally, the `` property can also include a hash (e.g., to ensure the integrity of the referenced content), however, that is an advanced concept that is not covered in this tutorial. + +In the previous section, multiple `` elements would need to be created in the SSP metadata for each applicable laws and regulations. However, another approach would be to specify one `` in the metadata for all applicable laws, regulations, standards, and guides. Then a single `` (for the applicable laws, regulations, standards, and guides) with multiple `` could be set in the back-matter as illustrated below. + {{< highlight xml "linenos=table" >}} OSCAL SSP Link to Back Matter Resource Example - 2001-12-17T09:30:47Z - 20210707 + 2022-01-01T09:30:00-005 + 20220531 1.0.0 @@ -570,19 +709,22 @@ In the previous section, multiple `links` would need to be created in the SSP me {{< /highlight >}} -Notice that in this example, the `` element on line #8 only provides a fragment rather than a URL. OSCAL interprets this as a pointer to a back matter resource `@uuid` (see line #16). Within this `` element, several items are referenced (via ``). The `` must have a URI reference (`@href`). The third `` in this example provides a relative path. All of the other `` attributes (e.g., `@media-type` and `@hash`) are optional. Unlike ``, `` do not have any `@rel` attributes to provide additional context, nor do they have `` sub-elements. OSCAL content authors should consider these subtle differences when deciding whether to use `` or ``. +Notice that in this example, the `` element on line #8 only provides a fragment rather than a URL. OSCAL interprets this as a pointer to a back matter resource `@uuid` (see line #17). Within this `` element, several items are referenced (via ``). The `` must have a URI reference (`@href`). The third `` in this example provides a relative path. All of the other `` attributes (e.g., `@media-type` and `@hash`) are optional. Unlike ``, `` do not have any `@rel` attributes to provide additional context, nor do they have `` sub-elements. OSCAL content authors should consider these subtle differences when deciding whether to use `` or ``. {{% /tab %}} - {{% tab %}} +When using `links` to reference back-matter `resources`, the `link` must use the resource's `uuid` property as the pointer. The `resource` property must have an `rlinks` object array that points to the (external) content via the `href` property. Optionally, the `rlinks` can also include a hash (e.g., to ensure the integrity of the referenced content), however, that is an advanced concept that is not covered in this tutorial. + +In the previous section, multiple `link` objects would need to be created in the SSP metadata for each applicable laws and regulations. However, another approach would be to specify one `link` in the metadata for all applicable laws, regulations, standards, and guides. Then a single `resource` (for the applicable laws, regulations, standards, and guides) with multiple `rlink` objects could be set in the back-matter as illustrated below. + {{< highlight json "linenos=table" >}} { "system-security-plan": { "uuid": "ce16b9af-6853-4abe-9e27-b79d034c0adc", "metadata": { "title": "OSCAL SSP Link to Back Matter Resource Example", - "last-modified": "2001-12-17T09:30:47Z", - "version": 20210707, + "last-modified": "2022-01-01T09:30:00-005", + "version": 20220531, "oscal-version": "1.0.0", "links": { "href": "#a7584118-3d2d-46c8-b388-df747309c0fa", @@ -615,18 +757,21 @@ Notice that in this example, the `` element on line #8 only provides a fra } {{< /highlight >}} -Notice that in this example, the `links` object array on line #8 only provides a fragment rather than a URL. OSCAL interprets this as a pointer to a back matter resource `uuid` (see line #20). Within `resources`, several items are referenced (via `rlinks`). Each `rlink` must have a URI reference (`href`). The third `rlink` in this example provides a relative path. All of the other `rlink` properties (e.g., `media-type` and `hash`) are optional. Unlike `links`, `rlinks` do not have any `rel` properties to provide additional context, nor do they have `text` properties. OSCAL content authors should consider these subtle differences when deciding whether to use `links` or `rlinks`. +Notice that in this example, the `links` object array on line 9 only provides a fragment rather than a URL. OSCAL interprets this as a pointer to a back matter resource `uuid` (see line #21). Within `resources`, several items are referenced (via `rlinks`). Each `rlink` must have a URI reference (`href`). The third `rlink` in this example provides a relative path. All of the other `rlink` properties (e.g., `media-type` and `hash`) are optional. Unlike `links`, `rlinks` do not have any `rel` properties to provide additional context, nor do they have `text` properties. OSCAL content authors should consider these subtle differences when deciding whether to use `links` or `rlinks`. {{% /tab %}} - {{% tab %}} +When using `links` to reference back-matter `resources`, the `link` must use the resource's `uuid` key-value as the pointer. The `resource` key-value must have an `rlinks` array that points to the (external) content via the `href` key-value. Optionally, the `rlinks` can also include a hash (e.g., to ensure the integrity of the referenced content), however, that is an advanced concept that is not covered in this tutorial. + +In the previous section, multiple `link` key-value pairs would need to be created in the SSP metadata for each applicable laws and regulations. However, another approach would be to specify one `link` in the metadata for all applicable laws, regulations, standards, and guides. Then a single `resource` (for the applicable laws, regulations, standards, and guides) with multiple `rlink` key-value pairs could be set in the back-matter as illustrated below. + {{< highlight yaml "linenos=table" >}} system-security-plan: uuid: ce16b9af-6853-4abe-9e27-b79d034c0adc metadata: title: OSCAL SSP Link to Back Matter Resource Example - last-modified: '2001-12-17T09:30:47Z' - version: 20210707 + last-modified: '2022-01-01T09:30:00-005' + version: 20220531 oscal-version: 1.0.0 links: - href: '#a7584118-3d2d-46c8-b388-df747309c0fa' @@ -640,18 +785,14 @@ system-security-plan: uuid: a7584118-3d2d-46c8-b388-df747309c0fa rlinks: - href: https://www.dhs.gov/homeland-security-presidential-directive-12 - - href: >- - https://csrc.nist.gov/csrc/media/publications/fips/199/final/documents/fips-pub-199-final.pdf + - href: https://csrc.nist.gov/csrc/media/publications/fips/199/final/documents/fips-pub-199-final.pdf media-type: application/pdf - href: /security/standards/IT-Rules-of-Behavior.docx media-type: application/msword - {{< /highlight >}} -Notice that in this example, the `links` object array on line #7 only provides a fragment rather than a URL. OSCAL interprets this as a pointer to a back matter resource `uuid` (see line #16). Within `resources`, several items are referenced (via `rlinks`). Each `rlink` must have a URI reference (`href`). The third `rlink` in this example provides a relative path. All of the other `rlink` properties (e.g., `media-type` and `hash`) are optional. Unlike `links`, `rlinks` do not have any `rel` properties to provide additional context, nor do they have `text` properties. OSCAL content authors should consider these subtle differences when deciding whether to use `links` or `rlinks`. - +Notice that in this example, the `links` object array on line #8 only provides a fragment rather than a URL. OSCAL interprets this as a pointer to a back matter resource `uuid` (see line #17). Within `resources`, several items are referenced (via `rlinks`). Each `rlink` must have a URI reference (`href`). The third `rlink` in this example provides a relative path. All of the other `rlink` properties (e.g., `media-type` and `hash`) are optional. Unlike `links`, `rlinks` do not have any `rel` properties to provide additional context, nor do they have `text` properties. OSCAL content authors should consider these subtle differences when deciding whether to use `links` or `rlinks`. {{% /tab %}} - {{% /tabs %}} ## Summary diff --git a/docs/content/learn/tutorials/metadata/_index.md b/docs/content/learn/tutorials/metadata/_index.md index fe894d600f..402fd5dc7c 100644 --- a/docs/content/learn/tutorials/metadata/_index.md +++ b/docs/content/learn/tutorials/metadata/_index.md @@ -1,28 +1,26 @@ --- title: Creating and Using Metadata in OSCAL -description: A tutorial that covers the usage of the Metadata Section in OSCAL +description: A tutorial that covers the usage of the metadata section in OSCAL weight: 5 suppresstopiclist: true toc: enabled: true --- -This tutorial covers the basics of the common OSCAL Metadata Section, and provides a walk-through on creating one for a new OSCAL document. Before reading this tutorial you should: +This tutorial covers the basics of the common OSCAL metadata section, and provides a walk-through on creating `metadata` for a new OSCAL document. Before reading this tutorial you should: - Have some familiarity with the [XML](https://www.w3.org/standards/xml/core), [JSON](https://www.json.org/), or [YAML](https://yaml.org/spec/) formats. -- Have a basic understanding of OSCAL Models and their overall structure. ([OSCAL High-Level Overview](/concepts/layer/overview/)) +- Have a basic understanding of OSCAL models and their overall structure. ([OSCAL High-Level Overview](/concepts/layer/overview/)) ## What is the Metadata Section? -All OSCAL models share some common structure and elements, as discussed in [Common High-Level Structure](/concepts/layer/overview/#common-high-level-structure). The foremost of these is the Metadata Section, which includes important identifying and categorizing information. A number of mandatory fields inside of metadata are vital to the processing of OSCAL documents, and have stricter requirements that help ensure interoperability. A second, larger set of fields are optional, and designed to allow OSCAL content creators great flexibility in expressing additional information. These optional fields may enable extra functionality, utilize proprietary data, contain contact info, and more. +All OSCAL models share some common structure and elements, as discussed in [Common High-Level Structure](/concepts/layer/overview/#common-high-level-structure). The foremost of these is the metadata section, which includes important identifying and categorizing information. The metadata section contains several mandatory fields that are vital to the processing of OSCAL documents and follow requirements that help ensure interoperability, as well as optional fields that are designed to allow OSCAL content creators great flexibility in expressing additional information. -The definition of the Metadata Section is the same regardless of where it appears, so this tutorial is not bound to a single OSCAL Model. - -As with all parts of OSCAL, the Metadata Section provides machine-readable formats in XML, JSON, and YAML, which support representing an equivalent set of information. Examples in this tutorial are provided for XML, JSON, and YAML to show the equivalent representations. +As with all parts of OSCAL, the metadata section provides machine-readable formats in XML, JSON, and YAML, which support representing an equivalent set of information. Examples in this tutorial are provided for XML, JSON, and YAML to show the equivalent representations. ## Metadata Fields -Below is the high-level structure of the Metadata Section in XML, JSON, and YAML followed by a listing of each fields' definition with a brief description. +The OSCAL metaschema reference ([XML](/reference/latest/complete/xml-definitions/#/assembly/oscal-metadata/metadata) | [JSON](/reference/latest/complete/json-definitions/#/assembly/oscal-metadata/metadata)) provides a comprehensive listing of the metadata section fields. Below is the high-level structure of the metadata section in XML, JSON, and YAML followed by a listing of each fields' definition with a brief description. {{< tabs XML JSON YAML >}} {{% tab %}} @@ -55,9 +53,9 @@ Element definitions: - [``](/reference/latest/complete/xml-reference/#/catalog/metadata/version) (required) - A [simple String](/reference/datatypes/#string) that provides the version of the document instance. If any part of the document is changed, this version value should be incremented according to the versioning scheme used. - [``](/reference/latest/complete/xml-reference/#/catalog/metadata/oscal-version) (required) - The version of OSCAL that this document instance was written against, expressed as a [simple String](/reference/datatypes/#string). - [``](/reference/latest/complete/xml-reference/#/catalog/metadata/revisions/revision) (optional) - A list of revisions to the document to enable advanced change tracking. -- [``](/reference/latest/catalog/xml-reference/#/catalog/metadata/document-id) (zero to many) - A unique ID that identifies a document, and ties all separate instances of the document into one document series. The `@scheme` attribute provides a URI to identify the scheme used to generate the ID. See the later [section](#understanding-and-using-the-document-id) for more information and usage guidance. -- [``](/reference/latest/catalog/xml-reference/#/catalog/metadata/prop) (zero to many) - Represents some arbitrary "property" of the document. This flexible element provides an extension point for adding additional metadata. See the later [section](#using-props) for more information and usage guidance. -- [``](/reference/latest/catalog/xml-reference/#/catalog/metadata/link) (zero to many) - Provides a resolvable URI (the `@href` attribute) for some resource. The purpose of the link is given with the `@rel` attribute, and it's media type through the `@media-type` attribute. See the later [section](#using-link) for more information and usage guidance. +- [``](/reference/latest/catalog/xml-reference/#/catalog/metadata/document-id) (zero to many) - A unique ID that identifies a document, and ties all separate instances of the document into one document series. The `@scheme` attribute provides a URI to identify the scheme used to generate the ID. See the later [section](#using-the-document-id) for more information and usage guidance. +- [``](/reference/latest/catalog/xml-reference/#/catalog/metadata/prop) (zero to many) - Represents some arbitrary "property" of the document. This flexible element provides an extension point for adding additional metadata. See the later [section](#props) for more information and usage guidance. +- [``](/reference/latest/catalog/xml-reference/#/catalog/metadata/link) (zero to many) - Provides a resolvable URI (the `@href` attribute) for some resource. The purpose of the link is given with the `@rel` attribute, and it's media type through the `@media-type` attribute. See the later [section](#links) for more information and usage guidance. - [``](/reference/latest/catalog/xml-reference/#/catalog/metadata/role) (zero to many) - Defines a function or duty assumed or expected to be assumed by a party (i.e., person or organization) in a specific situation. - [``](/reference/latest/catalog/xml-reference/#/catalog/metadata/location) (zero to many) - A location, with associated metadata that can be referenced. - [``](/reference/latest/catalog/xml-reference/#/catalog/metadata/party) (zero to many) - A responsible entity which is either a person or an organization that can be referenced. @@ -97,9 +95,9 @@ Field definitions: - [`version`](/reference/latest/complete/json-reference/#/catalog/metadata/version) (required) - A [simple String](/reference/datatypes/#string) that provides the version of the document instance. If any part of the document is changed, this version value should be incremented according to the versioning scheme used. - [`oscal-version`](/reference/latest/complete/json-reference/#/catalog/metadata/oscal-version) (required) - The version of OSCAL that this document instance was written against, expressed as a [simple String](/reference/datatypes/#string). - [`revisions`](/reference/latest/complete/json-reference/#/catalog/metadata/revisions) (optional) - A list of revisions to the document to enable advanced change tracking. -- [`document-ids`](/reference/latest/catalog/json-reference/#/catalog/metadata/document-id) (optional, zero to many) - A unique ID that identifies a document, and ties all separate instances of the document into one document series. The `@scheme` attribute provides a URI to identify the scheme used to generate the ID. See the later [section](#understanding-and-using-the-document-id) for more information and usage guidance. -- [`props`](/reference/latest/catalog/json-reference/#/catalog/metadata/props) (optional, zero to many) - Represents some arbitrary "property" of the document. This flexible element provides an extension point for adding additional metadata. See the later [section](#using-props) for more information and usage guidance. -- [`links`](/reference/latest/catalog/json-reference/#/catalog/metadata/links) (optional, zero to many) - Provides a resolvable URI (the `href` property) to some resource. The purpose of the link is given with the `rel` attribute, and it's media type through the `media-type` property. See the later [section](#using-link) for more information and usage guidance. +- [`document-ids`](/reference/latest/catalog/json-reference/#/catalog/metadata/document-id) (optional, zero to many) - A unique ID that identifies a document, and ties all separate instances of the document into one document series. The `@scheme` attribute provides a URI to identify the scheme used to generate the ID. See the later [section](#using-the-document-id) for more information and usage guidance. +- [`props`](/reference/latest/catalog/json-reference/#/catalog/metadata/props) (optional, zero to many) - Represents some arbitrary "property" of the document. This flexible element provides an extension point for adding additional metadata. See the later [section](#props) for more information and usage guidance. +- [`links`](/reference/latest/catalog/json-reference/#/catalog/metadata/links) (optional, zero to many) - Provides a resolvable URI (the `href` property) to some resource. The purpose of the link is given with the `rel` attribute, and it's media type through the `media-type` property. See the later [section](#links) for more information and usage guidance. - [`roles`](/reference/latest/catalog/json-reference/#/catalog/metadata/roles) (optional, zero to many) - Defines a function or duty assumed or expected to be assumed by a party (i.e., person or organization) in a specific situation. - [`locations`](/reference/latest/catalog/json-reference/#/catalog/metadata/locations) (optional, zero to many) - A location, with associated metadata that can be referenced. - [`parties`](/reference/latest/catalog/json-reference/#/catalog/metadata/parties) (optional, zero to many) - A responsible entity which is either a person or an organization that can be referenced. @@ -109,7 +107,6 @@ Field definitions: {{% /tab %}} {{% tab %}} {{< highlight yaml "linenos=table" >}} ---- metadata : title: markup-line published: dateTime-with-timezone @@ -137,26 +134,29 @@ Field definitions: - [`version`](/reference/latest/complete/json-reference/#/catalog/metadata/version) (required) - A [simple String](/reference/datatypes/#string) that provides the version of the document instance. If any part of the document is changed, this version value should be incremented according to the versioning scheme used. - [`oscal-version`](/reference/latest/complete/json-reference/#/catalog/metadata/oscal-version) (required) - The version of OSCAL that this document instance was written against, expressed as a [simple String](/reference/datatypes/#string). - [`revisions`](/reference/latest/complete/json-reference/#/catalog/metadata/revisions) (optional) - A list of revisions to the document to enable advanced change tracking. -- [`document-ids`](/reference/latest/catalog/json-reference/#/catalog/metadata/document-id) (optional, zero to many) - A unique ID that identifies a document, and ties all separate instances of the document into one document series. The `@scheme` attribute provides a URI to identify the scheme used to generate the ID. See the later [section](#understanding-and-using-the-document-id) for more information and usage guidance. -- [`props`](/reference/latest/catalog/json-reference/#/catalog/metadata/props) (optional, zero to many) - Represents some arbitrary "property" of the document. This flexible element provides an extension point for adding additional metadata. See the later [section](#using-props) for more information and usage guidance. -- [`links`](/reference/latest/catalog/json-reference/#/catalog/metadata/links) (optional, zero to many) - Provides a resolvable URI (the `href` property) to some resource. The purpose of the link is given with the `rel` attribute, and it's media type through the `media-type` property. See the later [section](#using-link) for more information and usage guidance. +- [`document-ids`](/reference/latest/catalog/json-reference/#/catalog/metadata/document-id) (optional, zero to many) - A unique ID that identifies a document, and ties all separate instances of the document into one document series. The `@scheme` attribute provides a URI to identify the scheme used to generate the ID. See the later [section](#using-the-document-id) for more information and usage guidance. +- [`props`](/reference/latest/catalog/json-reference/#/catalog/metadata/props) (optional, zero to many) - Represents some arbitrary "property" of the document. This flexible element provides an extension point for adding additional metadata. See the later [section](#props) for more information and usage guidance. +- [`links`](/reference/latest/catalog/json-reference/#/catalog/metadata/links) (optional, zero to many) - Provides a resolvable URI (the `href` property) to some resource. The purpose of the link is given with the `rel` attribute, and it's media type through the `media-type` property. See the later [section](#links) for more information and usage guidance. - [`roles`](/reference/latest/catalog/json-reference/#/catalog/metadata/roles) (optional, zero to many) - Defines a function or duty assumed or expected to be assumed by a party (i.e., person or organization) in a specific situation. - [`locations`](/reference/latest/catalog/json-reference/#/catalog/metadata/locations) (optional, zero to many) - A location, with associated metadata that can be referenced. - [`parties`](/reference/latest/catalog/json-reference/#/catalog/metadata/parties) (optional, zero to many) - A responsible entity which is either a person or an organization that can be referenced. -- [`responsible-parties`](/reference/latest/catalog/json-reference/#/catalog/metadata/responsible-parties) (optional, zero to many) - A reference to a set of organizations or +- [`responsible-parties`](/reference/latest/catalog/json-reference/#/catalog/metadata/responsible-parties) (optional, zero to many) - A reference to a set of organizations or persons that have responsibility for performing a referenced role in the context of the containing object. +- [`remarks`](/reference/latest/catalog/json-reference/#/catalog/metadata/remarks) (optional) - Markup formatted text consisting of notes for human readers of the content. {{% /tab %}} {{% /tabs %}} ## Creating a Metadata Section -All OSCAL documents contain a required metadata section, which include a set of required basic elements. This tutorial will cover creating this section and populating the required elements. Also covered is a set of important optional fields, and how they can be used to support specific use cases. +Lets start with a nominal example of an OSCAL catalog document to demonstrate how to create the metadata section. -Lets start with a nominal example of an OSCAL Catalog document to demonstrate how to create the metadata section. +{{% callout note %}} +The data structure of the metadata section is identical in all OSCAL models, so the demonstrated constructs in this tutorial apply to all OSCAL models. +{{% /callout %}} ### Document UUID -UUIDs are a globally unique identifier randomly generated at the same time an OSCAL document is created. This provides a stable and unique way to refer to a given instance of an OSCAL document. +All OSCAL documents use a randomly generated globally unique identifier (UUID) to provide a stable and unique way to refer to a given instance of an OSCAL document. UUIDs are generated when the OSCAL document is created or revised. {{< tabs XML JSON YAML >}} {{% tab %}} @@ -164,34 +164,44 @@ UUIDs are a globally unique identifier randomly generated at the same time an OS {{< /highlight >}} -Although technically outside of the Metadata Section, the `@uuid` of a document is always given as an attribute on the root element, and shares its structure across all OSCAL document types. This is provided using the [uuid](/reference/datatypes/#uuid) datatype. Many tools provide easy ways to generate version 4 UUIDs. For our example we have generated one using a trivial UUIDv4 generator. +Although technically outside of the metadata section, the `@uuid` of a document is always given as an attribute on the root element, and shares its structure across all OSCAL document types. This is provided using the [uuid](/reference/datatypes/#uuid) datatype. Many tools provide easy ways to generate version 4 UUIDs. For our example we have generated one using a trivial UUIDv4 generator. {{% /tab %}} {{% tab %}} {{< highlight json "linenos=table" >}} { "catalog": { - "uuid": "c3da6d1d-c20c-4c7c-ae73-4010167a186" + "uuid": "c3da6d1d-c20c-4c7c-ae73-4010167a186b" } } {{< /highlight >}} -Although technically outside of the Metadata Section, the `uuid` of a document is always given as a field of the root element, and shares its structure across all OSCAL document types. This is provided using the [uuid](/reference/datatypes/#uuid) datatype. Many tools provide easy ways to generate version 4 UUIDs. For our example we have generated one using a trivial UUIDv4 generator. +Although technically outside of the metadata section, the `uuid` of a document is always given as a property of the root object, and shares its structure across all OSCAL document types. This is provided using the [uuid](/reference/datatypes/#uuid) datatype. Many tools provide easy ways to generate version 4 UUIDs. For our example we have generated one using a trivial UUIDv4 generator. {{% /tab %}} {{% tab %}} {{< highlight yaml "linenos=table" >}} --- catalog: - uuid: c3da6d1d-c20c-4c7c-ae73-4010167a186 + uuid: c3da6d1d-c20c-4c7c-ae73-4010167a186b {{< /highlight >}} -Although technically outside of the Metadata Section, the `uuid` of a document is always given as a field of the root element, and shares its structure across all OSCAL document types. This is provided using the [uuid](/reference/datatypes/#uuid) datatype. Many tools provide easy ways to generate version 4 UUIDs. For our example we have generated one using a trivial UUIDv4 generator. +Although technically outside of the metadata section, the `uuid` of a document is always given as a property of the root object, and shares its structure across all OSCAL document types. This is provided using the [uuid](/reference/datatypes/#uuid) datatype. Many tools provide easy ways to generate version 4 UUIDs. For our example we have generated one using a trivial UUIDv4 generator. {{% /tab %}} {{% /tabs %}} -### Required and Recommended Fields +### Creating Metadata Fields + +The metadata section contains fields which may be categorized as: +- required +- recommended +- extensions +- and other optional fields + +The subsequent tutorial sections demonstrates how the aforementioned field categories can be used to support specific use cases. + +#### Using Required and Optional Recommended Fields First, we start with the document's title, which is intended to be brief, human-readable text that will help a reader understand the context of the document. @@ -202,68 +212,24 @@ The following is an example of what a title might look like expressed in OSCAL: {{< highlight xml "linenos=table" >}} Example OSCAL Catalog {{< /highlight >}} -{{% /tab %}} -{{% tab %}} -{{< highlight json "linenos=table" >}} -{ -"title":"Example OSCAL Catalog" -} -{{< /highlight >}} -{{% /tab %}} -{{% tab %}} -{{< highlight yaml "linenos=table" >}} ---- -title:Example OSCAL Catalog -{{< /highlight >}} -{{% /tab %}} -{{% /tabs %}} -Next we have the published and last modified date/time fields that represent when the document was published for the first time and most recently changed respectively. These field values are expressed using the OSCAL [DataTime-with-timezone](/reference/datatypes/#date-with-timezone) data type, which requires that the time zone offset is included to provide a localized time. +Next, we have the published and last modified date/time fields that represent when the document was published for the first time and most recently changed respectively. These field values are expressed using the OSCAL [dataTime-with-timezone](/reference/datatypes/#datetime-with-timezone) data type, which requires that the time zone offset is included to provide a localized time. -If a document was: +Lets look at a scenario where an OSCAL document was: - published on January 1st, 2021 at "midnight" or 12:00AM with a time offset of 5 hours from Coordinated Universal Time (UTC) - updated on January 5th, 2021 at "midnight" or 12:00AM with a time offset of 5 hours from UTC -This information would be expressed in OSCAL as follows: +This information would be expressed in OSCAL as follows in the metadata section: -{{< tabs XML JSON YAML >}} -{{% tab %}} {{< highlight xml "linenos=table" >}} 2021-01-01T00:00:00-5:00 2021-01-05T00:00:00-5:00 {{< /highlight >}} -The `` element gives the date and time of when the document was published for the first time. This element is not required, but it is strongly recommended to include it to help the OSCAL document consumer understand when the document was orginally published. +The `` element gives the date and time of when the document was published for the first time. This element is not required, but it is strongly recommended to include it to help the OSCAL document consumer understand when the document was originally published. The `` element provides the the date and time of the most recent change to this document. If a document was never previously updated, the `` value should be identical to the one given by `published`. -{{% /tab %}} -{{% tab %}} -{{< highlight json "linenos=table" >}} -{ -"published": "2021-01-01T00:00:00-05:00", -"last-modified": "2021-01-05T00:00:00-05:00" -} -{{< /highlight >}} -The `published` property gives the date and time of when the document was published for the first time. This property is not required, but it is strongly recommended to include it to help the OSCAL document consumer understand when the document was orginally published. - -The `last-modified` property provides the the date and time of the most recent change to this document. If a document was never previously updated, the `last-modified` value should be identical to the one given by `published`. -{{% /tab %}} -{{% tab %}} -{{< highlight yaml "linenos=table" >}} ---- - published: 2021-01-01T00:00:00-05:00, - last-modified: 2021-01-05T00:00:00-05:00 -{{< /highlight >}} - -The `published` key gives the date and time of when the document was published for the first time. This key is not required, but it is strongly recommended to include it to help the OSCAL document consumer understand when the document was orginally published. - -The `last-modified` key provides the the date and time of the most recent change to this document. If a document was never previously updated, the `last-modified` value should be identical to the one given by `published`. -{{% /tab %}} -{{% /tabs %}} - -{{< tabs XML JSON YAML >}} -{{% tab %}} Thirdly, we must provide a `` element. This refers to the version of the OSCAL document itself, not the version of any other content. OSCAL does not place requirements on the version string itself, as versioning is a complicated process that differs from content creator to content creator. Since this is the first time we've created this document, some variation on a "1.0" would be appropriate. {{< highlight xml "linenos=false" >}} @@ -272,32 +238,56 @@ Thirdly, we must provide a `` element. This refers to the version of th This version will be incremented whenever the OSCAL document is updated. -Where possible, use well formatted versions with a clear and well defined syntax. The NIST OSCAL team uses [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) as the versioning scheme for all schema, Metaschema, and OSCAL documents we maintain. +Where possible, use well formatted versions with a clear and well defined syntax. The NIST OSCAL team uses [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) as the versioning scheme for all schema, metaschema, and OSCAL documents we maintain. The final required element is ``, which indicates what version of OSCAL was used to create this document. {{< highlight xml "linenos=table" >}} -1.0.0-rc2 +1.0.4 {{< /highlight >}} -We have now covered all required fields of the Metadata Section, and could publish our document as a valid OSCAL document. Here is what it would look like all together: +We have now covered all required fields of the metadata section, and could publish our document as a valid OSCAL document. Here is what it would look like all together: {{< highlight xml "linenos=table" >}} Example OSCAL Document 2021-01-01T00:00:00-5:00 - 2021-01-01T00:00:00-5:00 + 2021-01-05T00:00:00-5:00 1.0.0 - 1.0.0-rc2 + 1.0.4 ... {{< /highlight >}} {{% /tab %}} {{% tab %}} +{{< highlight json "linenos=table" >}} +{ +"title":"Example OSCAL Catalog" +} +{{< /highlight >}} + +Next we have the published and last modified date/time fields that represent when the document was published for the first time and most recently changed respectively. These field values are expressed using the OSCAL [dataTime-with-timezone](/reference/datatypes/#datetime-with-timezone) data type, which requires that the time zone offset is included to provide a localized time. + +Lets look at a scenario where an OSCAL document was: +- published on January 1st, 2021 at "midnight" or 12:00AM with a time offset of 5 hours from Coordinated Universal Time (UTC) +- updated on January 5th, 2021 at "midnight" or 12:00AM with a time offset of 5 hours from UTC + +This information would be expressed in OSCAL as follows in the metadata section: + +{{< highlight json "linenos=table" >}} +{ +"published": "2021-01-01T00:00:00-05:00", +"last-modified": "2021-01-05T00:00:00-05:00" +} +{{< /highlight >}} -Thirdly we must provide a `version` field. This refers to the version of the OSCAL document itself, not the version of any other content. OSCAL does not place requirements on the version string itself, as versioning is a complicated process that differs from content creator to content creator. Since this is the first time we've created this document, some variation on a "1.0" would be appropriate. +The `published` field gives the date and time of when the document was published for the first time. This field is not required, but it is strongly recommended to include it to help the OSCAL document consumer understand when the document was originally published. + +The `last-modified` field provides the the date and time of the most recent change to this document. If a document was never previously updated, the `last-modified` value should be identical to the one given by `published`. + +Thirdly we must provide a `version` field. This refers to the version of the OSCAL document itself, not the version of any other content. OSCAL does not place requirements on the version string itself, as versioning is a complicated process that differs from content creator to content creator. Since this is the first time we've created this document, some variation on a "1.0" would be appropriate. {{< highlight json "linenos=table" >}} { @@ -305,39 +295,59 @@ Thirdly we must provide a `version` field. This refers to the version of the OSC } {{< /highlight >}} +This version will be incremented whenever the OSCAL document is updated. + Where possible, use well formatted versions with clear and defined rules. This version will be incremented whenever the OSCAL document is updated. The final required field is `oscal-version`, which indicates what version of OSCAL was used to create this document. {{< highlight json "linenos=table" >}} { -"oscal-version":"1.0.0" +"oscal-version":"1.0.4" } {{< /highlight >}} -We have now covered all required fields of the Metadata Section, and could publish our document as a valid OSCAL document. Here is what it would look like all together: +We have now covered all required fields of the metadata section, and could publish our document as a valid OSCAL document. Here is what it would look like all together: {{< highlight json "linenos=table" >}} { "catalog": { - "uuid": "c3da6d1d-c20c-4c7c-ae73-4010167a186" + "uuid": "c3da6d1d-c20c-4c7c-ae73-4010167a186b" "metadata": { "title":"Example OSCAL Catalog", "published":"2021-01-01T00:00:00-5:00", - "last-modified":"2021-01-01T00:00:00-5:00", + "last-modified":"2021-01-05T00:00:00-5:00", "version":"1.0.0", - "oscal-version":"1.0.0" + "oscal-version":"1.0.4" } } } {{< /highlight >}} {{% /tab %}} {{% tab %}} +{{< highlight yaml "linenos=table" >}} + title: Example OSCAL Catalog +{{< /highlight >}} +Next we have the published and last modified date/time fields that represent when the document was published for the first time and most recently changed respectively. These field values are expressed using the OSCAL [dataTime-with-timezone](/reference/datatypes/#datetime-with-timezone) data type, which requires that the time zone offset is included to provide a localized time. -Thirdly we must provide a `version` field. This refers to the version of the OSCAL document itself, not the version of any other content. OSCAL does not place requirements on the version string itself, as versioning is a complicated process that differs from content creator to content creator. Since this is the first time we've created this document, some variation on a "1.0" would be appropriate. +Lets look at a scenario where an OSCAL document was: +- published on January 1st, 2021 at "midnight" or 12:00AM with a time offset of 5 hours from Coordinated Universal Time (UTC) +- updated on January 5th, 2021 at "midnight" or 12:00AM with a time offset of 5 hours from UTC + +This information would be expressed in OSCAL as follows in the metadata section: + +{{< highlight yaml "linenos=table" >}} + published: 2021-01-01T00:00:00-05:00 + last-modified: 2021-01-05T00:00:00-05:00 +{{< /highlight >}} + +The `published` key gives the date and time of when the document was published for the first time. This key is not required, but it is strongly recommended to include it to help the OSCAL document consumer understand when the document was originally published. + +The `last-modified` key provides the the date and time of the most recent change to this document. If a document was never previously updated, the `last-modified` value should be identical to the one given by `published`. + +Thirdly we must provide a `version` field. This refers to the version of the OSCAL document itself, not the version of any other content. OSCAL does not place requirements on the version string itself, as versioning is a complicated process that differs from content creator to content creator. Since this is the first time we've created this document, some variation on a "1.0" would be appropriate. {{< highlight yaml "linenos=table" >}} ---- version: 1.0.0 {{< /highlight >}} @@ -346,31 +356,28 @@ Where possible, use well formatted versions with clear and defined rules. This v The final required field is `oscal-version`, which indicates what version of OSCAL was used to create this document. {{< highlight yaml "linenos=table" >}} ---- -{ -oscal-version: 1.0.0 -} + oscal-version: 1.0.4 {{< /highlight >}} -We have now covered all required fields of the Metadata Section, and could publish our document as a valid OSCAL document. Here is what it would look like all together: +We have now covered all required fields of the metadata section, and could publish our document as a valid OSCAL document. Here is what it would look like all together: {{< highlight yaml "linenos=table" >}} --- - catalog: - uuid: c3da6d1d-c20c-4c7c-ae73-4010167a186, - metadata: - title: Example OSCAL Catalog, - published: 2021-01-01T00:00:00-5:00, - last-modified: 2021-01-01T00:00:00-5:00, - version: 1.0.0, - oscal-version: 1.0.0 + catalog: + uuid: c3da6d1d-c20c-4c7c-ae73-4010167a186b + metadata: + title: Example OSCAL Catalog + published: 2021-01-01T00:00:00-5:00 + last-modified: 2021-01-05T00:00:00-5:00 + version: 1.0.0 + oscal-version: 1.0.4 {{< /highlight >}} {{% /tab %}} {{% /tabs %}} -However, the Metadata Section has several other optional but important fields which we will cover in the following sections. +However, the metadata section has several other optional but important fields which we will cover in the following sections. -### Understanding and Using the Document-Id +#### Using the Document-Id OSCAL documents, by their nature, may often require updates of varying impact. It is important to track these updates in a way that can be automated and managed by a wide array of systems and users. To that end, we must cover the concepts of "Document Series" and "Document Instances". @@ -383,7 +390,7 @@ A "Document Instance" is defined as a single document that is part of a "Documen In OSCAL we use `` to track "Document Series", and `@uuid` to track "Document Instance". -Continuing with our OSCAL Catalog example, we have already generated a uuid to identify the particular instance that we are publishing. Since we are publishing the first document in a series, we should also define a ``. The `@scheme` attribute is a [URI](/reference/datatypes/#uri) that identifies the naming scheme we are using for the ID. While there are no strict requirements around the scheme and the ID, it is recommended that an existing identification scheme is used. For our example we will use [DOI](https://www.doi.org/). +Continuing with our OSCAL catalog example, we have already generated a uuid to identify the particular instance that we are publishing. Since we are publishing the first document in a series, we should also define a ``. The `@scheme` attribute is a [URI](/reference/datatypes/#uri) that identifies the naming scheme we are using for the ID. While there are no strict requirements around the scheme and the ID, it is recommended that an existing identification scheme is used. For our example we will use [DOI](https://www.doi.org/). {{< highlight xml "linenos=table" >}} 10.1000/182 @@ -400,7 +407,7 @@ Multiple `` elements denote that a document is a part of multiple D In OSCAL we use `document-ids` to track "Document Series", and `uuid` to track "Document Instance". -Continuing with our OSCAL Catalog example, we have already generated a uuid to identify the particular instance that we are publishing. Since we are publishing the first document in a series, we should also define a `document-ids`. The `scheme` field is a [URI](/reference/datatypes/#uri) that identifies the naming scheme we are using for the ID. While there are no strict requirements around the scheme and the ID, it is recommended that an existing identification scheme is used. For our example we will use [DOI](https://www.doi.org/). +Continuing with our OSCAL catalog example, we have already generated a uuid to identify the particular instance that we are publishing. Since we are publishing the first document in a series, we should also define a `document-ids`. The `scheme` field is a [URI](/reference/datatypes/#uri) that identifies the naming scheme we are using for the ID. While there are no strict requirements around the scheme and the ID, it is recommended that an existing identification scheme is used. For our example we will use [DOI](https://www.doi.org/). {{< highlight json "linenos=table" >}} { @@ -422,10 +429,9 @@ In the case that a document does not explicitly provide at least one object insi In OSCAL we use `document-id` to track "Document Series", and `uuid` to track "Document Instance". -Continuing with our OSCAL Catalog example, we have already generated a uuid to identify the particular instance that we are publishing. Since we are publishing the first document in a series, we should also define a `document-id`. The `scheme` field is a [URI](/reference/datatypes/#uri) that identifies the naming scheme we are using for the ID. While there are no strict requirements around the scheme and the ID, it is recommended that an existing identification scheme is used. For our example we will use [DOI](https://www.doi.org/). +Continuing with our OSCAL catalog example, we have already generated a uuid to identify the particular instance that we are publishing. Since we are publishing the first document in a series, we should also define a `document-id`. The `scheme` field is a [URI](/reference/datatypes/#uri) that identifies the naming scheme we are using for the ID. While there are no strict requirements around the scheme and the ID, it is recommended that an existing identification scheme is used. For our example we will use [DOI](https://www.doi.org/). {{< highlight yaml "linenos=table" >}} ---- document-ids: - scheme: https://www.doi.org/ value: 10.1000/182 @@ -437,10 +443,12 @@ In the case that a document does not explicitly provide a `document-id` value, i {{% /tab %}} {{% /tabs %}} -### Using Props +### Using Optional Extensions + +#### Props {{< tabs XML JSON YAML >}} {{% tab %}} -The Metadata Section may include any number of `` elements. The `` element provides a key-value pairing to provide additional information alongside the well-defined elements of the Metadata Section. Some common use cases include labels, sorting tags, and classification. There are no restrictions on using custom `@name` and `@value` pairs making `` an excellent place to do extension of the OSCAL model to meet proprietary use cases. The Metadata Section may include any number of `` elements. +The metadata section may include any number of `` elements. The `` element provides a key-value pairing to provide additional information alongside the well-defined elements of the metadata section. Some common use cases include labels, sorting tags, and classification. There are no restrictions on using custom `@name` and `@value` pairs making `` an excellent place to extend OSCAL models to meet proprietary use cases. The metadata section may include any number of `` elements. {{% callout note %}} More information on the use of `` is provided in the [Props and Links tutorial](/learn/tutorials/extensions/#props). @@ -457,7 +465,7 @@ The [Props and Links tutorial](/learn/tutorials/extensions/#using-an-existing-pr {{% /tab %}} {{% tab %}} -The `props` object array provides any number of key-value pairing to provide additional information alongside the well-defined fields of the Metadata Section. Some common use cases include labels, sorting tags, and classification. There are no restrictions on using custom `name` and `value` pairs making `props` an excellent place to do extension of the OSCAL model to meet proprietary use cases. +The `props` object array provides any number of key-value pairing to provide additional information alongside the well-defined fields of the metadata section. Some common use cases include labels, sorting tags, and classification. There are no restrictions on using custom `name` and `value` pairs making `props` an excellent place to do extension of the OSCAL model to meet proprietary use cases. {{% callout note %}} More information on the use of `props` is provided in the [Props and Links tutorial](/learn/tutorials/extensions/#props). @@ -481,16 +489,14 @@ The `name` field is the key, and the `value` field is the value. Together they f {{% /tab %}} {{% tab %}} -The `props` array provides any number of key-value pairings to provide additional information alongside the well-defined fields of the Metadata Section. Some common use cases include labels, sorting tags, and classification. There are no restrictions on using custom `name` and `value` pairs making `prop` an excellent place to do extension of the OSCAL model to meet proprietary use cases. +The `props` array provides any number of key-value pairings to provide additional information alongside the well-defined fields of the metadata section. Some common use cases include labels, sorting tags, and classification. There are no restrictions on using custom `name` and `value` pairs making `prop` an excellent place to do extension of the OSCAL model to meet proprietary use cases. {{% callout note %}} -More information on the use of `props` is provided in the [Props and Links tutorial](/learn/tutorials/extensions/#props). {{% /callout %}} For this example, we will create a `props` to mark an OSCAL document with a [Traffic Light Protocol (TLP)](https://en.wikipedia.org/wiki/Traffic_Light_Protocol) classification. {{< highlight yaml "linenos=table" >}} ---- props: - name: marking value: red @@ -502,11 +508,11 @@ The `name` field is the key, and the `value` field is the value. Together they f {{% /tab %}} {{% /tabs %}} -### Using Link +#### Links {{< tabs XML JSON YAML >}} {{% tab %}} -Alongside the `` element, `` is way of providing additional information in the Metadata section that is not covered by the other elements. Each `` must contain a single `@href` attribute, which contains a resolvable URI. Each `` should also include a `@rel` attribute, which describes the type of relationship provided by the `@href`. +Alongside the `` element, `` is a way of providing additional information in the metadata section that is not covered by the other elements. Each `` must contain a single `@href` attribute, which contains a resolvable URI. Each `` should also include a `@rel` attribute, which describes the type of relationship provided by the `@href`. {{% callout note %}} The [Props and Links tutorial](/learn/tutorials/extensions/#links) provides comprehensive examples of how to implement a ``. @@ -521,7 +527,7 @@ For this example, we will create a "latest-version" link, which provides a stati The "predecessor-version" and "successor-version" links could be used in tandem with the above to create a navigable web of document versions. -By using other custom `@rel` values, any relevant or related resource can be described and linked to in the OSCAL Document's Metadata Section. +By using other custom `@rel` values, any relevant or related resource can be described and linked to in the OSCAL document's metadata section. {{% /tab %}} @@ -547,7 +553,7 @@ For this example, we will create a "latest-version" link, which provides a stati The "predecessor-version" and "successor-version" links could be used in tandem with the above to create a navigable web of document versions. -By using other custom `rel` values, any relevant or related resource can be described and linked to in the OSCAL Document's Metadata Section. +By using other custom `rel` values, any relevant or related resource can be described and linked to in the OSCAL document's metadata section. {{% /tab %}} @@ -561,86 +567,87 @@ The [Props and Links tutorial](/learn/tutorials/extensions/#links) provides comp For this example, we will create a "latest-version" link, which provides a static link to the latest version of this Document Series. By pointing to a static URL, but updating the contents of that URL as the document is updated, any user that has an old version of the document can quickly and easily update. {{< highlight yaml "linenos=table" >}} ---- links: - - rel: latest-version, + - rel: latest-version href: https://www.examplecompany.com/catalog/exampleoscalcatalog/latest {{< /highlight >}} The "predecessor-version" and "successor-version" links could be used in tandem with the above to create a navigable web of document versions. -By using other custom `rel` values, any relevant or related resource can be described and linked to in the OSCAL Document's Metadata Section. +By using other custom `rel` values, any relevant or related resource can be described and linked to in the OSCAL document's metadata section. {{% /tab %}} {{% /tabs %}} -### Using Other Optional Elements +### Using Other Optional Fields {{< tabs XML JSON YAML >}} {{% tab %}} -The remainder of this tutorial briefly covers the other optional elements inside the Metadata Section. While not required by the specification, these elements provide invaluable information, particularly for providence and authorship data. This information is declared in the Metadata Section, and is often passed by-reference to other parts of the OSCAL Document. Each element can be clicked to get additional information. +The remainder of this tutorial briefly covers the other optional elements inside the metadata section. While not required by the specification, these elements provide invaluable information, particularly for provenance and authorship data. This information is declared in the metadata section, and is often passed by-reference to other parts of the OSCAL document. Each element can be clicked to get additional information. -[``](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/xml-schema/#global_role) - Roles define some function or purpose that is to be assigned to some entity later in the document. Role elements have a `id` attribute with a [NCName](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#ncname) that is used to reference the role elsewhere in the OSCAL document. A number of pre-defined roles exist in OSCAL, but differ depending on context. In the Metadata Section they are as follows: +[``](/reference/latest/catalog/xml-reference/#/catalog/metadata/role) - Roles define some function or purpose that is to be assigned to some entity later in the document. Role elements have an `id` attribute with a [NCName](/reference/datatypes/#ncname) that is used to reference the role elsewhere in the OSCAL document. A number of pre-defined roles exist in OSCAL, but differ depending on context. In the metadata section they are as follows: - prepared-by: Indicates the organization that created this content. - prepared-for: Indicates the organization for which this content was created. - content-approver: Indicates the organization responsible for all content represented in the "document". Other roles can be locally defined by the content creator. -[``](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/xml-schema/#global_location) - Geographic data defined by a street address. Locations have a `@uuid` attribute that allow them to be referenced elsewhere in the OSCAL Document. Includes elements to describe a variety of data describing the location in question. +[``](/reference/latest/catalog/xml-reference/#/catalog/metadata/location) - Geographic data defined by a street address. Locations have a `@uuid` attribute that allow them to be referenced elsewhere in the OSCAL document. Includes elements to describe a variety of data describing the location in question. -[``](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/xml-schema/#global_party) - Defines some entity, either a person or an organization. Has a `@uuid` attribute that allows for references this party elsewhere in the OSCAL Document. Includes elements to describe a variety of data describing the party in question, including a location uuid. +[``](/reference/latest/catalog/xml-reference/#/catalog/metadata/party) - Defines some entity, either a person or an organization. Has a `@uuid` attribute that allows for references to this party elsewhere in the OSCAL document. Includes elements to describe a variety of data describing the party in question, including a location uuid. -[``](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/xml-schema/#global_party) - Explicitly declares a party that is responsible for this OSCAL document. The `@role-id` attribute references the role that the party is fulfilling, and is either a custom role locally defined or one of the pore-defined roles; see the `` section above for details. Uses a Party's uuid to link the given role to the given party. +[``](/reference/latest/catalog/xml-reference/#/catalog/metadata/responsible-party) - Explicitly declares a party that is responsible for a given role. The `@role-id` attribute references the role that the party is fulfilling, and is either a custom role locally defined or one of the core-defined roles; see the `` section above for details. Uses a party's uuid to link the given role to the given party. -`` - [Markup](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#markup-multiline) formatted plaintext with notes and remarks regarding the Metadata Section of this document. +[``]((/reference/latest/catalog/xml-reference/#/catalog/metadata/remarks)) - [Markup](/reference/datatypes/#markup-data-types) formatted plaintext with notes and remarks regarding the metadata section of this document. {{% /tab %}} {{% tab %}} -The remainder of this tutorial will briefly cover the other optional objects inside the Metadata Section. While not required by the specification, these objects provide invaluable information, particularly for providence and authorship data. This information is declared in the Metadata Section, and is often passed by-reference to other parts of the OSCAL Document. Each object can be clicked to get additional information. +The remainder of this tutorial will briefly cover the other optional objects inside the metadata section. While not required by the specification, these objects provide invaluable information, particularly for provenance and authorship data. This information is declared in the metadata section, and is often passed by-reference to other parts of the OSCAL document. Each object can be clicked to get additional information. -[`roles`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_role) - An array of Role objects. Roles define some function or purpose that is to be assigned to some entity later in the document. Role objects have a `id` field with a [NCName](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#ncname) that is used to reference the role elsewhere in the OSCAL document. A number of pre-defined roles exist in OSCAL, but differ depending on context. In the Metadata Section they are as follows: +[`roles`](/reference/latest/catalog/json-reference/#/catalog/metadata/roles) - An array of Role objects. Roles define some function or purpose that is to be assigned to some entity later in the document. Role objects have an `id` field with a [NCName](/reference/datatypes/#ncname) that is used to reference the role elsewhere in the OSCAL document. A number of pre-defined roles exist in OSCAL, but differ depending on context. In the metadata section they are as follows: - prepared-by: Indicates the organization that created this content. - prepared-for: Indicates the organization for which this content was created. - content-approver: Indicates the organization responsible for all content represented in the "document". Other roles can be locally defined by the content creator. -[`locations`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_location) - An array of Location objects. Geographic data defined by a street address. Locations have a `uuid` field that allow them to be referenced elsewhere in the OSCAL Document. Includes fields to describe a variety of data describing the location in question. +[`locations`](/reference/latest/catalog/json-reference/#/catalog/metadata/locations) - An array of location objects. Geographic data defined by a street address. Locations have a `uuid` field that allow them to be referenced elsewhere in the OSCAL document. Includes fields to describe a variety of data describing the location in question. -[`parties`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_party) - An array of Party objects. Defines some entity, either a person or an organization. Has a `uuid` field that allows for references this party elsewhere in the OSCAL Document. Includes fields to describe a variety of data describing the party in question, including a location uuid. +[`parties`](/reference/latest/catalog/json-reference/#/catalog/metadata/parties) - An array of party objects. Defines some entity, either a person or an organization. Has a `uuid` field that allows for references to this party elsewhere in the OSCAL document. Includes fields to describe a variety of data describing the party in question, including a location uuid. -[`responsible-parties`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_party) - An array of Responsible-Party objects. Explicitly declares a party that is responsible for this OSCAL document. The `role-id` field references the role that the party is fulfilling, and is either a custom role locally defined or one of the pore-defined roles; see the `roles` section above for details. Uses a Party's uuid to link the given role to the given party. +[`responsible-parties`](/reference/latest/catalog/json-reference/#/catalog/metadata/responsible-parties) - An array of responsible-party objects. Explicitly declares a party that is responsible for this a given role. The `role-id` field references the role that the party is fulfilling, and is either a custom role locally defined or one of the core-defined roles; see the `roles` section above for details. Uses a party's uuid to link the given role to the given party. -`remarks` - [Markup](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#markup-multiline) formatted plaintext with notes and remarks regarding the Metadata Section of this document. +[`remarks`](/reference/latest/catalog/json-reference/#/catalog/metadata/remarks) - [Markup](/reference/datatypes/#markup-data-types) formatted plaintext with notes and remarks regarding the metadata section of this document. {{% /tab %}} {{% tab %}} -The remainder of this tutorial will briefly cover the other optional objects inside the Metadata Section. While not required by the specification, these objects provide invaluable information, particularly for providence and authorship data. This information is declared in the Metadata Section, and is often passed by-reference to other parts of the OSCAL Document. Each object can be clicked to get additional information. +The remainder of this tutorial will briefly cover the other optional objects inside the metadata section. While not required by the specification, these objects provide invaluable information, particularly for provenance and authorship data. This information is declared in the metadata section, and is often passed by-reference to other parts of the OSCAL document. Each object can be clicked to get additional information. -[`roles`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_role) - Roles define some function or purpose that is to be assigned to some entity later in the document. Role objects have a `id` field with a [NCName](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#ncname) that is used to reference the role elsewhere in the OSCAL document. A number of pre-defined roles exist in OSCAL, but differ depending on context. In the Metadata Section they are as follows: +[`roles`](/reference/latest/catalog/json-reference/#/catalog/metadata/roles) - Roles define some function or purpose that is to be assigned to some entity later in the document. Role objects have an `id` field with a [NCName](/reference/datatypes/#ncname) that is used to reference the role elsewhere in the OSCAL document. A number of pre-defined roles exist in OSCAL, but differ depending on context. In the metadata section they are as follows: - prepared-by: Indicates the organization that created this content. - prepared-for: Indicates the organization for which this content was created. - content-approver: Indicates the organization responsible for all content represented in the "document". Other roles can be locally defined by the content creator. -[`locations`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_location) - Geographic data defined by a street address. Locations have a `uuid` field that allow them to be referenced elsewhere in the OSCAL Document. Includes fields to describe a variety of data describing the location in question. +[`locations`](/reference/latest/catalog/json-reference/#/catalog/metadata/locations) - Geographic data defined by a street address. Locations have a `uuid` field that allow them to be referenced elsewhere in the OSCAL document. Includes fields to describe a variety of data describing the location in question. -[`parties`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_party) - Defines some entity, either a person or an organization. Has a `uuid` field that allows for references this party elsewhere in the OSCAL Document. Includes fields to describe a variety of data describing the party in question, including a location uuid. +[`parties`](/reference/latest/catalog/json-reference/#/catalog/metadata/parties) - Defines some entity, either a person or an organization. Has a `uuid` field that allows for references to this party elsewhere in the OSCAL document. Includes fields to describe a variety of data describing the party in question, including a location uuid. -[`responsible-parties`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_party) - Explicitly declares a party that is responsible for this OSCAL document. The `role-id` field references the role that the party is fulfilling, and is either a custom role locally defined or one of the pore-defined roles; see the `role` section above for details. Uses a Party's uuid to link the given role to the given party. +[`responsible-parties`](/reference/latest/catalog/json-reference/#/catalog/metadata/responsible-parties) - Explicitly declares a party that is responsible for a given role. The `role-id` field references the role that the party is fulfilling, and is either a custom role locally defined or one of the core-defined roles; see the `role` section above for details. Uses a party's uuid to link the given role to the given party. -`remarks` - [Markup](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#markup-multiline) formatted plaintext with notes and remarks regarding the Metadata Section of this document. +[`remarks`](/reference/latest/catalog/json-reference/#/catalog/metadata/remarks) - [Markup](/reference/datatypes/#markup-data-types) formatted plaintext with notes and remarks regarding the metadata section of this document. {{% /tab %}} {{% /tabs %}} ## Putting It All Together +Finally, we have a basic example of an OSCAL metadata section below: + {{< tabs XML JSON YAML >}} {{% tab %}} {{< highlight xml "linenos=table" >}} @@ -648,9 +655,9 @@ Other roles can be locally defined by the content creator. Example OSCAL Document 2021-01-01T00:00:00-5:00 - 2021-01-01T00:00:00-5:00 + 2021-01-05T00:00:00-5:00 1.0.0 - 1.0.0 + 1.0.4 10.1000/182 }} { "catalog": { - "uuid": "c3da6d1d-c20c-4c7c-ae73-4010167a186", + "uuid": "c3da6d1d-c20c-4c7c-ae73-4010167a186b", "metadata": { "title":"Example OSCAL Catalog", "published":"2021-01-01T00:00:00-5:00", - "last-modified":"2021-01-01T00:00:00-5:00", + "last-modified":"2021-01-05T00:00:00-5:00", "version":"1.0.0", - "oscal-version":"1.0.0", + "oscal-version":"1.0.4", "document-ids": [ { "scheme":"https://www.doi.org/", @@ -718,29 +725,29 @@ Other roles can be locally defined by the content creator. {{< highlight yaml "linenos=table" >}} --- catalog: - uuid: c3da6d1d-c20c-4c7c-ae73-4010167a186, + uuid: c3da6d1d-c20c-4c7c-ae73-4010167a186b metadata: - title: Example OSCAL Catalog, - published: 2021-01-01T00:00:00-5:00, - last-modified: 2021-01-01T00:00:00-5:00, - version: 1.0.0, - oscal-version: 1.0.0, + title: Example OSCAL Catalog + published: 2021-01-01T00:00:00-5:00 + last-modified: 2021-01-05T00:00:00-5:00 + version: 1.0.0 + oscal-version: 1.0.4 document-ids: - - scheme: https://www.doi.org/, + - scheme: https://www.doi.org/ value: 10.1000/182 props: - - name: marking, - value: red, + - name: marking + value: red class: TLP links: - - rel: latest-version, + - rel: latest-version href: https://www.examplecompany.com/catalog/exampleoscalcatalog/latest parties: - - uuid: 15d2e37c-0452-4695-9c6a-ddc1ff15397b, - type: organization, + - uuid: 15d2e37c-0452-4695-9c6a-ddc1ff15397b + type: organization name: Example Company responsible-parties: - - role-id: prepared-by, + - role-id: prepared-by party-uuid: 15d2e37c-0452-4695-9c6a-ddc1ff15397b {{< /highlight >}} {{% /tab %}} @@ -750,7 +757,7 @@ Other roles can be locally defined by the content creator. This concludes the tutorial. At this point you should be familiar with: -- The basic structure of the Metadata Section. +- The basic structure of the metadata section. - How to provide the basic metadata required to be included in an OSCAL document. - How to use and understand UUIDs and document-ids to track document instances -- How to use optional fields to express additional metadata and extend the Metadata Section +- How to use optional fields to express additional metadata and extend the metadata section