diff --git a/build/config/.lycheeignore b/build/config/.lycheeignore index f19524e86e..260b61e7e0 100644 --- a/build/config/.lycheeignore +++ b/build/config/.lycheeignore @@ -1,4 +1,6 @@ https://defense.gov/ +https://federal-agency.gov/.* +http://federal-agency.gov/ns/oscal http://fedramp.gov/ns/oscal https://fedramp.gov/ns/oscal http://www.first.org/cvss/v2.0 @@ -10,3 +12,4 @@ http://csrc.nist.gov/oscal https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/xxxx https://cdn.telos.com/wp-content/uploads/2021/06/22150746/Xacta-360-EULA-US.pdf https://search.usa.gov/search +https://example.com/.* diff --git a/docs/assets/scss/hugo-uswds-custom.scss b/docs/assets/scss/hugo-uswds-custom.scss index b936903f26..a6ed3b1383 100644 --- a/docs/assets/scss/hugo-uswds-custom.scss +++ b/docs/assets/scss/hugo-uswds-custom.scss @@ -21,3 +21,8 @@ float: inherit; } } + +div.highlight .chroma .err { + color: gray; + background-color: inherit; +} \ No newline at end of file diff --git a/docs/content/concepts/layer/validation/_index.md b/docs/content/concepts/validation/_index.md similarity index 99% rename from docs/content/concepts/layer/validation/_index.md rename to docs/content/concepts/validation/_index.md index 8637d9b7d1..c6c67e67cf 100644 --- a/docs/content/concepts/layer/validation/_index.md +++ b/docs/content/concepts/validation/_index.md @@ -4,6 +4,8 @@ weight: 50 description: Explanation of well-formedness, validation, and how they relate to OSCAL aliases: [] suppresstopiclist: true +aliases: +- /concepts/layer/validation/ --- ## Who is this document for? diff --git a/docs/content/concepts/layer/validation/oscal-wellformed-valid.svg b/docs/content/concepts/validation/oscal-wellformed-valid.svg similarity index 100% rename from docs/content/concepts/layer/validation/oscal-wellformed-valid.svg rename to docs/content/concepts/validation/oscal-wellformed-valid.svg diff --git a/docs/content/learn/tutorials/_index.md b/docs/content/learn/tutorials/_index.md index 95d795560b..45e3ad1828 100644 --- a/docs/content/learn/tutorials/_index.md +++ b/docs/content/learn/tutorials/_index.md @@ -3,8 +3,18 @@ title: Walkthrough Tutorials suppresstopiclist: true --- -The following tutorials provide a step-by-step walkthrough on explaining how to create OSCAL content of various types. +The following tutorials provide step-by-step walk-throughs 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 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/). +## [General Topics](general/) + +- [Using the metadata section](general/metadata/): Explains use of the `metadata` section that is required to be provided in all OSCAL content. +- [Extending OSCAL models](general/extension/): Discusses how to use OSCAL properties and links to provided extended data in OSCAL content. + +## [Control Layer Topics](control/) + +- [Creating a Basic Control Catalog](control/basic-catalog/): Explains how to create a [catalog](/concepts/terminology/#catalog) of [controls](/concepts/terminology/#control) using the OSCAL [catalog model](/concepts/layer/control/catalog/). + +## [Implementation Layer Topics](implementation/) + +- [Creating a Basic Component Definition](implementation/basic-component-definition/): Teaches how to create a component-definition using the OSCAL [component definition](/concepts/layer/implementation/component-definition/) model. +- [Representing test validation information](implementation/validation-modeling/): Describes how to represent test validation information (e.g., FIPS-140-2) using a component in an OSCAL [component definition](/concepts/layer/implementation/component-definition/) or [system security plan](/concepts/layer/implementation/ssp/). diff --git a/docs/content/learn/tutorials/control/_index.md b/docs/content/learn/tutorials/control/_index.md new file mode 100644 index 0000000000..0a18caf24d --- /dev/null +++ b/docs/content/learn/tutorials/control/_index.md @@ -0,0 +1,13 @@ +--- +title: Control Layer Topics +heading: Tutorials that apply to the OSCAL control layer models +description: A set of tutorials that apply to the OSCAL [control layer](/concepts/layer/control/) models. +weight: 20 +suppresstopiclist: true +toc: + enabled: false +--- + +The following tutorial covers topics that apply to the OSCAL [control layer](/concepts/layer/control/) models. + +- [Creating a Basic Control Catalog](basic-catalog/): A tutorial on creating a [catalog](/concepts/terminology/#catalog) of [controls](/concepts/terminology/#control) using the OSCAL [catalog model](/concepts/layer/control/catalog/). diff --git a/docs/content/learn/tutorials/catalog/_index.md b/docs/content/learn/tutorials/control/basic-catalog.md similarity index 99% rename from docs/content/learn/tutorials/catalog/_index.md rename to docs/content/learn/tutorials/control/basic-catalog.md index f8c3747d76..e0229956fd 100644 --- a/docs/content/learn/tutorials/catalog/_index.md +++ b/docs/content/learn/tutorials/control/basic-catalog.md @@ -1,15 +1,18 @@ --- title: Creating a Control Catalog description: A tutorial on creating an OSCAL control catalog. -weight: 5 +weight: 20 suppresstopiclist: true toc: enabled: true aliases: - /tutorials/catalog/ + - /learn/tutorials/catalog/ --- -This tutorial covers creating a basic OSCAL control catalog. Before reading this tutorial you should: +This tutorial covers creating a basic OSCAL control catalog. + +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. - Read the OSCAL control layer [overview](/concepts/layer/control/). diff --git a/docs/content/learn/tutorials/general/_index.md b/docs/content/learn/tutorials/general/_index.md new file mode 100644 index 0000000000..768b4a8d52 --- /dev/null +++ b/docs/content/learn/tutorials/general/_index.md @@ -0,0 +1,14 @@ +--- +title: General Topics +heading: Tutorials that apply to OSCAL as a whole +description: A set of tutorials that apply to all OSCAL models. +weight: 10 +suppresstopiclist: true +toc: + enabled: false +--- + +The following tutorials cover general topics that apply to all of the OSCAL [models](/concepts/layer/). + +- [Using the metadata section](metadata/): Explains use of the `metadata` section that is required to be provided in all OSCAL content. +- [Extending OSCAL models](extension/): A discussion of how to use OSCAL properties and links to provided extended data in OSCAL content. diff --git a/docs/content/learn/tutorials/general/extension.md b/docs/content/learn/tutorials/general/extension.md new file mode 100644 index 0000000000..06514ab975 --- /dev/null +++ b/docs/content/learn/tutorials/general/extension.md @@ -0,0 +1,772 @@ +--- +title: Extending OSCAL Models +heading: Extending OSCAL Models with Props and Links +description: A tutorial on extending OSCAL models by using props and links. +weight: 10 +suppresstopiclist: true +toc: + enabled: true +alias: +- /learn/tutorials/extensions/ +--- + +This tutorial describes the mechanisms for extending basic OSCAL models. 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. +- Review the [OSCAL Layers and Models](/concepts/layer/) documentation. +- Review the latest [OSCAL Reference](/reference/latest/complete/). + +## What are the OSCAL Extension Mechanisms? + +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 and privacy risk management programs. It was important to establish extension mechanisms from the onset, to allow OSCAL content creators to adapt 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 OSCAL 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 OSCAL property is a primary method for providing extended data in OSCAL. A property is a namespaced name and value pair, which appears on many of the key fields within an OSCAL model. The following section provides details around the use of OSCAL properties. + +### Syntax + +The following examples illustrate the syntax of an OSCAL property in XML, JSON, and YAML. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} +... +{{< /highlight >}} + +A property in OSCAL XML is represented using the `` element, which can be repeated in a sequence multiple times to define multiple OSCAL properties. + +Below is a description of each attribute of the `` element. + +- `@name` (Required) - The *name* of the OSCAL property that must be a [token](/reference/datatypes/#token) data type. +- `@ns` (Optional) - The *namespace* of the OSCAL property that must be a [universal resource identifier (URI)](/reference/datatypes/#uri) formatted according to [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). +- `@value` (Required) - The *value* of the OSCAL property that must be a [string](/reference/datatypes/#string) value. +- `@class` (Optional) - The *class* of the OSCAL property that must be a [string](/reference/datatypes/#string) value, which can be used to further qualify the property's value. +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "props": [ + { + "name":"...", + "ns":"...", + "value":"...", + "class":"..." + } + ] +} +{{< /highlight >}} + +A listing of properties in OSCAL JSON are represented using the `props` object array, with each property defined as an individual JSON object array member. + +Each *property* object can have the following JSON property names. + +- `name` (Required) - The *name* of the OSCAL property that must be a [token](/reference/datatypes/#token) data type. +- `ns` (Optional) - The *namespace* of the OSCAL property that must be a [universal resource identifier (URI)](/reference/datatypes/#uri) formatted according to [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). +- `value` (Required) - The *value* of the OSCAL property that must be a [string](/reference/datatypes/#string) value. +- `class` (Optional) - The *class* of the OSCAL property that must be a [string](/reference/datatypes/#string) value, which can be used to further qualify the value that must be a [string](/reference/datatypes/#string) value, which can be used to further qualify the property's value. +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +props: +- name: ... + ns: ... + value: ... + class: ... +{{< /highlight >}} + +A `props` list in YAML contains individual OSCAL property items. + +Each property item can have the following keys: + +- `name` (Required) - The *name* of the OSCAL property that must be a [token](/reference/datatypes/#token) data type. +- `ns` (Optional) - The *namespace* of the OSCAL property that must be a [universal resource identifier (URI)](/reference/datatypes/#uri) formatted according to [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). +- `value` (Required) - The *value* of the OSCAL property that must be a [string](/reference/datatypes/#string) value. +- `class` (Optional) - The *class* of the OSCAL property that must be a [string](/reference/datatypes/#string) value, which can be used to further qualify the value that must be a [string](/reference/datatypes/#string) value, which can be used to further qualify the property's value. +{{% /tab %}} +{{% /tabs %}} + +### Concepts + +Now that the syntax of a property is more clear, let's discuss how the property's *namespace*, *name*, *value*, and *class* are used to extend OSCAL. + +#### Context + +As we mentioned earlier, a property is a *namespaced name* and *value* pair, which appears on many of the key fields within an OSCAL model. The OSCAL field on which the property is declared is considered the property's *context*. A property's context establishes the subject of the property: the thing the property is about. + +#### Namespace + +A property's *namespace* defines the value space of possible names for a property. Each namespace is represented by a Uniform Resource Identifier (URI), which is defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). Namespaces allow the same property name to be used for different purposes or to have different meanings for each namespace it is defined in. + +The default namespace for an OSCAL property is `http://csrc.nist.gov/ns/oscal`, which is used as the namespace when no namespace is provided. + +A namespace is managed by a given organization or individual. Using a namespace, different organizations can assign a unique semantic meaning to the use of a property name within their namespace; thus, the different meaning of two properties with the same name can be easily determined by identifying the associated namespaces. This allows different organizations to assign names within their own namespace, without coordinating with other organizations, avoiding naming conflicts. This provides a low-effort means to ensure that naming clashes are avoided. + +#### Name + +The *name* of a property defines the semantic meaning or topical nature of the value. The topic a name relates to is often associated with the property's *context*. + +For example, the property name "marking" might identify some information sensitivity classification scheme for the context data field, while the property name "label" might refer to a textual label for the context data field. + +In OSCAL, many data fields have pre-defined names defined in the OSCAL namespace `http://csrc.nist.gov/ns/oscal`, which is the default value for the namespace when no namespace is provided. These pre-defined property names provided for standardized naming of properties, which can be recognized by multiple consumers to have a consistent meaning. The namespace can be omitted when using a property name pre-defined by OSCAL. + +For example, the OSCAL SSP model's system characteristics data field has a pre-defined property name `data-center` \[[XML](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics/prop)\] \[[JSON/YAML](/reference/latest/system-security-plan/json-reference/#/system-security-plan/system-characteristics/props)\]. + +OSCAL content authors need to determine whether to use a pre-defined property name in a given situation or to define their own name in their own namespace. To view existing property names, review the model index \[[XML](/reference/latest/complete/xml-index/#/prop)\] \[[JSON/YAML](/reference/latest/complete/json-index/#/props)\]. + +New pre-defined names will be added to OSCAL over time as needed. To suggest or request the addition of a new pre-defined name in the OSCAL namespace, please [open an issue](https://github.com/usnistgov/OSCAL/issues/new?assignees=&labels=User+Story%2Cenhancement&template=feature_request.yaml) in the OSCAL GitHub repository. + +#### Value + +A property's *name* defines a value space, while the property's *value* provides a specific member of that value space. The value space for a given name may contain a set of identifier reference values, an enumerated set of values, or allow for open-ended values. Defining the rules for allowed values in a value space is a critical part of defining a new property name within a given namespace. + +Many of the OSCAL pre-defined property names have a constrained set of values. The allowed values may be further constrained by the context data field. Which values are allowed depends on the context of use, name and namespace of the property. The constraints for these properties are defined within the [OSCAL Metaschemas](https://github.com/usnistgov/OSCAL/tree/main/src/metaschema). Where applicable, a given Metaschema defines the `allowed-values` that can be used for a property name in a given context of use. The properties that are extensible are defined with an `@allow-other=yes` attribute in Metaschema. + +#### Class + +The *class* of a property is a textual label that provides a sub-type or characterization of the property's name and/or value. This can be used to further distinguish or discriminate between the semantics of multiple properties in a given context with the same name and namespace. + +### Using an Existing Prop + +This sections covers the basic use of a property leveraging all of its attributes. + +The OSCAL SSP [metadata](/concepts/layer/overview/#metadata-overview) allows for zero or more location data items, each allowing for properties to be defined. In this example, an organization needs to document their primary and alternate data center locations. This is achieved by specifying properties for each location. + +{{% callout note %}} +The [Metadata Tutorial](../metadata/) provides in-depth description and walk-through examples of creating OSCAL metadata. +{{% /callout %}} + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + + + OSCAL Basic Prop Example + 2022-01-01T09:30:00-005 + 20220531 + 1.0.4 + + ... + + + + ... + + + + ... + ... + ... + +{{< /highlight >}} + +The `@name` attribute is set to "type" which is an OSCAL pre-defined property for locations. 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 to one of the appropriate [OSCAL pre-defined](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/metadata/location) values for data center location class. + +Note that in this example, the `@ns` attribute is omitted because we are using a pre-defined property name in the OSCAL namespace. +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "system-security-plan": { + "uuid": "ce16b9af-6853-4abe-9e27-b79d034c0adc", + "metadata": { + "title": "OSCAL Basic Prop Example", + "last-modified": "2022-01-01T09:30:00-005", + "version": 20220531, + "oscal-version": "1.0.4", + "locations": [ + { + "title": "...", + "props": [ + { + "name":"type", + "value":"data-center", + "class":"primary" + } + ] + }, + { + "title": "...", + "props": [ + { + "name":"type", + "value":"data-center", + "class":"alternate" + } + ] + }] + }, + "import-profile": "...", + "system-characteristics": "...", + "system-implementation": "..." + } +} +{{< /highlight >}} + +In the `props` object array, the prop object's `name` property is set to "type" which is an OSCAL pre-defined property for locations. 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` JSON property in this case is used to indicate a subclass of data-center, and is set to one of the appropriate [OSCAL pre-defined](/reference/latest/system-security-plan/json-reference/#/system-security-plan/metadata/locations) values for data center location class. + +Note that in this example, the `ns` JSON property is omitted because we are using a pre-defined property name in the OSCAL namespace. +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +system-security-plan: + uuid: ce16b9af-6853-4abe-9e27-b79d034c0adc + metadata: + title: OSCAL Basic Prop Example + last-modified: '2022-01-01T09:30:00-005' + version: 20220531 + oscal-version: 1.0.04 + locations: + - title: ... + props: + - name: type + value: data-center + class: primary + - title: ... + props: + - name: type + value: data-center + class: alternate + import-profile: ... + system-characteristics: ... + system-implementation: ... +{{< /highlight >}} + +In the `props` list, the item's `name` key is set to "type" which is an OSCAL pre-defined property for locations. The `value` key 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` key in this case is used to indicate a subclass of data-center, and is set to one of the appropriate [OSCAL pre-defined](/reference/latest/system-security-plan/json-reference/#/system-security-plan/metadata/locations) values for data center location class. + +Note that in this example, the `ns` key 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 property is using a new value for 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" `` with an additional value. + +Currently, the only OSCAL pre-defined value for the SSP metadata location property is "data-center". However, because this particular property allows other values to be defined (with an `@allow-other=yes` attribute in Metaschema), additional "type" values can be specified as shown below. + +{{% callout note %}} +Again, for a detailed overview of how to implement metadata, please refer to the [Metadata Tutorial](../metadata/). +{{% /callout %}} + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + + + OSCAL Basic Prop Example + 2022-01-01T09:30:00-005 + 20220531 + 1.0.0 + + ... + + + + ... + ... + ... + +{{< /highlight >}} + +The example above defines a new "type" property `@value` "security-operations-center" on line 10. + +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 %}} +{{< highlight json "linenos=table" >}} +{ + "system-security-plan": { + "uuid": "ce16b9af-6853-4abe-9e27-b79d034c0adc", + "metadata": { + "title": "OSCAL Basic Prop Example", + "last-modified": "2022-01-01T09:30:00-005", + "version": 20220531, + "oscal-version": "1.0.0", + "locations": [ + { + "title": "...", + "props": [ + { + "name":"type", + "value":"security-operations-center" + } + ] + }] + }, + "import-profile": "...", + "system-characteristics": "...", + "system-implementation": "..." + } +} +{{< /highlight >}} + +The example above defines a new "type" property `value` "security-operations-center" on line 15. + +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 %}} +{{< highlight yaml "linenos=table" >}} +system-security-plan: + uuid: ce16b9af-6853-4abe-9e27-b79d034c0adc + metadata: + title: OSCAL Basic Prop Example + last-modified: '2022-01-01T09:30:00-005' + version: 20220531 + oscal-version: 1.0.0 + locations: + - title: ... + props: + - name: type + value: security-operations-center + import-profile: ... + system-characteristics: ... + system-implementation: ... +{{< /highlight >}} + +The example above defines a new "type" property `value` "security-operations-center" on line 12. + +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 %}} +{{% /tabs %}} + +### Creating a New Prop + +The previous examples leveraged an existing OSCAL property 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. + +We will create this new property in the `http://example.com/ns/oscal` namespace. Using a URI based on a domain name has the advantage of allowing the organization creating a new prop to use something they control as the namespace, which is in this case the domain name. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + + + OSCAL New Prop Example + 2022-01-01T09:30:00-005 + 20220531 + 1.0.0 + + ... + + + + + + + ... + ... + ... + +{{< /highlight >}} + +A new GLC property was created by setting the `` element's `@name` attribute 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" `` but used `@class` to provide context for the property's set `@value`. + +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 %}} +{{< highlight json "linenos=table" >}} +{ + "system-security-plan": { + "uuid": "ce16b9af-6853-4abe-9e27-b79d034c0adc", + "metadata": { + "title": "OSCAL Basic Prop Example", + "last-modified": "2022-01-01T09:30:00-005", + "version": 20220531, + "oscal-version": "1.0.0", + "locations": [ + { + "title": "...", + "props": [ + { + "name":"type", + "value":"security-operations-center", + "class":"regional" + }, + { + "name":"glc", + "ns":"http://example.com/ns/oscal", + "value":"11", + "class":"state-code" + }, + { + "name":"glc", + "ns":"http://example.com/ns/oscal", + "value":"0010", + "class":"city-code" + }, + { + "name":"glc", + "ns":"http://example.com/ns/oscal", + "value":"840", + "class":"country-code" + } + ] + }] + }, + "import-profile": "...", + "system-characteristics": "...", + "system-implementation": "..." + } +} +{{< /highlight >}} + +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 %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +system-security-plan: + uuid: ce16b9af-6853-4abe-9e27-b79d034c0adc + metadata: + title: OSCAL Basic Prop Example + last-modified: '2022-01-01T09:30:00-005' + version: 20220531 + oscal-version: 1.0.0 + locations: + - title: ... + props: + - name: type + value: security-operations-center + class: regional + - name: glc + ns: http://example.com/ns/oscal + value: '11' + class: state-code + - name: glc + ns: http://example.com/ns/oscal + value: '0010' + class: city-code + - name: glc + ns: http://example.com/ns/oscal + value: '840' + class: country-code + import-profile: ... + system-characteristics: ... + system-implementation: ... +{{< /highlight >}} + +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 means to reference an arbitrary resource, which allows local or remote content to be referenced. Links are available to use on many of the key fields in the OSCAL models. + +A link can: + +1. Reference (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 a software bill of materials (SBOM), and more. +2. Reference objects within the current OSCAL document. + +Organizations can limit duplication of content, reduce the size of their OSCAL files, and maintain important content relationships by using links. + +Here is a nominal example of a link in OSCAL. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + ... + +{{< /highlight >}} + +Below is description of `` attributes and sub-element: +- `@href` (Required) - The `@href` attribute, or "hypertext reference", is a required, [resolvable URL reference](/reference/datatypes/#uri-reference) to a resource. This can either be an internet resource or a fragment that points to a back matter resource in the same document. +- `@rel` (Optional) - The `@rel` attribute is a [token](/reference/datatypes/#token) datatype that can be used to describe the link's purpose. Some OSCAL links may have pre-defined `@rel` values (e.g., reference), but generally, OSCAL content authors can specify any token value for a `@rel` attribute. +- `@media-type` (Optional) - The `@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 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 `` 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 %}} +{{< highlight json "linenos=table" >}} +{ +"links": [ + { + "href": "...", + "rel": "...", + "media-type": "...", + "text": "..." + } ] +} +{{< /highlight >}} + +The `links` object array represents a collection of links. + +Below is description of properties of a link object: +- `href` (Required) - The `href` property, or "hypertext reference", is a required, [resolvable URL reference](/reference/datatypes/#uri-reference) to a resource. This can either be an internet resource or a fragment that points to a back matter resource in the same document. +- `rel` (Optional) - The `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. +- `media-type` (Optional) - The `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 `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 %}} +{{< highlight yaml "linenos=table" >}} +links: +- href: ... + rel: ... + media-type: ... + text: ... +{{< /highlight >}} + +The `links` list contains individual link items. + +Below is description of `links` key-values: +- `href` (Required) - The `href` key, or "hypertext reference", is a required, [resolvable URL reference](/reference/datatypes/#uri-reference) to a resource. This can either be an internet resource or a fragment that points to a back matter resource in the same document. +- `rel` (Optional) - The `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. +- `media-type` (Optional) - The `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 `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 resources, 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 to reference a government policy and an agency logo. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + + + OSCAL SSP Component Link Example + 2022-01-01T09:30:00-005 + 20220531 + 1.0.0 + + HSPD-12 + + + + ... + ... + ... + +{{< /highlight >}} + +In this case, the `` element on line 8 provides a reference to Homeland Security Policy Directive (HSPD) 12 by specifying the URL in the `@href` attribute. The OSCAL pre-defined "reference" value is used for the `@rel` attribute, providing some context for the purpose of this specific ``. The `` sub-element provides an associated label for the `` which may be useful when rendering the SSP in other formats (e.g., HTML, PDF). + +Line 11 demonstrates the use of `` to point to the organization's official logo. An absolute URL was used to point to the location of the referenced content, however, it should be noted that the `@href` attribute also permits the use of relative URL paths. If the referenced resource is located on the same host, then a relative URL path could be used. The `@rel` attribute was set to "logo" to indicate that the `` is to a logo image. The `@media-type` attribute was included to let any rendering tools know that the logo content is a Portable Network Graphics (PNG) image type. The optional `` sub-element was excluded for brevity of this example. +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "system-security-plan": { + "uuid": "ce16b9af-6853-4abe-9e27-b79d034c0adc", + "metadata": { + "title": "OSCAL SSP Component Link Example", + "last-modified": "2022-01-01T09:30:00-005", + "version": 20210707, + "oscal-version": "1.0.0", + "links": [ + { + "href": "https://www.dhs.gov/homeland-security-presidential-directive-12", + "rel": "reference", + "text": "HSPD-12" + }, + { + "href": "http://federal-agency.gov/img/official-agency-logo.png", + "rel": "logo", + "media-type": "image/png" + } + ] + }, + "import-profile": "...", + "system-characteristics": "...", + "system-implementation": "..." + } +} +{{< /highlight >}} + +In this case, the `links` object array on line 9 provides a reference to Homeland Security Policy Directive (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, PDF). + +Lines 16-18 demonstrate the use of link to point to the organization's official logo. An absolute URL 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 URL paths. If the referenced resource is located is on the same host, then a relative URL path could be used. The `rel` property was set to "logo" to indicate the link is to a logo image. The `media-type` property was included to let any rendering tools know that the logo content is a Portable Network Graphics (PNG) image type. The optional `text` property was excluded for brevity of this example. +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +system-security-plan: + uuid: ce16b9af-6853-4abe-9e27-b79d034c0adc + metadata: + title: OSCAL SSP Component Link Example + last-modified: '2022-01-01T09:30:00-005' + version: 20210707 + oscal-version: 1.0.0 + links: + - href: https://www.dhs.gov/homeland-security-presidential-directive-12 + rel: reference + text: HSPD-12 + - href: http://federal-agency.gov/img/official-agency-logo.png + rel: logo + media-type: image/png + import-profile: ... + system-characteristics: ... + system-implementation: ... + +{{< /highlight >}} + +In this case, the `links` object array on line 9 provides a reference to Homeland Security Policy Directive (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, PDF). + +Lines 11-13 demonstrate the use of link to point to the organization's official logo. An absolute URL 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 URL paths. If the referenced resource is located is on the same host, then a relative URL path could be used. The `rel` property was set to "logo" to indicate the link is to a logo image. The `media-type` property was included to let any rendering tools know that the logo content is a Portable Network Graphics (PNG) image type. The optional `text` property was excluded for brevity of this example. +{{% /tab %}} +{{% /tabs %}} + +As a final note, providing link text is not required. Link text should only be provided as a way to include additional context and can be omitted when a link is self-explanatory. + +### Referencing Back-Matter + +This section demonstrates how to reference back matter resources with links. + +In OSCAL specifying a URI fragment in a link's hypertext reference, represented as `#fragment-id`, indicates that the link is referencing an identified object in the OSCAL document's data model. This allows a resource to be referenced in the OSCAL document's back matter using the UUID of the back matter resource. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + + + OSCAL SSP Link to Back Matter Resource Example + 2022-01-01T09:30:00-005 + 20220531 + 1.0.0 + + Applicable Laws and Regulations, Standards, and Guides + + + ... + ... + ... + + + + + + + + +{{< /highlight >}} + +When using `` to reference a back-matter ``, the `` must use the resource's `@uuid` attribute as the pointer. The `` property may have an `` sub-element that points to the (external) content via the `@href` attribute. Optionally, the `` element 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. + +Notice that in this example, the `` element on line 8 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 URL 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 %}} +{{< 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": "2022-01-01T09:30:00-005", + "version": 20220531, + "oscal-version": "1.0.0", + "links": { + "href": "#a7584118-3d2d-46c8-b388-df747309c0fa", + "rel": "reference", + "text": "Applicable Laws and Regulations, Standards, and Guides" + } + }, + "import-profile": "...", + "system-characteristics": "...", + "control-implementation": "...", + "back-matter": { + "resources": + { + "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", + "media-type": "application/pdf" + }, + { + "href": "/security/standards/IT-Rules-of-Behavior.docx", + "media-type": "application/msword" + }] + } + } + } +} +{{< /highlight >}} +When using `links` to reference a back-matter `resources`, the `link` must use the resource's `uuid` property as the pointer. The `resource` property may have an `rlinks` object array that points to the (external) content via the `href` property. Optionally, the `rlinks` 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. + +Notice that in this example, the `links` object array on line 9 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 URL 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 %}} +{{< 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: '2022-01-01T09:30:00-005' + version: 20220531 + oscal-version: 1.0.0 + links: + - href: '#a7584118-3d2d-46c8-b388-df747309c0fa' + rel: reference + text: Applicable Laws and Regulations, Standards, and Guides + import-profile: ... + system-characteristics: ... + control-implementation: ... + back-matter: + resources: + 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 + media-type: application/pdf + - href: /security/standards/IT-Rules-of-Behavior.docx + media-type: application/msword +{{< /highlight >}} +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 item 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. + +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 URL 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 + +This concludes the tutorial. You should now be familiar with: + +- The basic use of OSCAL props +- How to use props to extend OSCAL models +- The basic use of OSCAL links +- How to specify local and remote links for indirection diff --git a/docs/content/learn/tutorials/general/metadata.md b/docs/content/learn/tutorials/general/metadata.md new file mode 100644 index 0000000000..134f358637 --- /dev/null +++ b/docs/content/learn/tutorials/general/metadata.md @@ -0,0 +1,829 @@ +--- +title: Creating and Using Metadata +heading: Creating and Using Metadata in OSCAL +description: A tutorial that covers the usage of the metadata section in OSCAL +weight: 5 +suppresstopiclist: true +toc: + enabled: true +alias: +- /learn/tutorials/metadata/ +--- + +This tutorial provides a walkthrough for creating the `metadata` section of an OSCAL document, which appears in all OSCAL documents. + +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 the OSCAL models and their [overall structure](/concepts/layer/overview/). + + +Document metadata in OSCAL appears in two locations: + +1. The document's [universally unique identifier](#document-uuid) (UUID). +2. The document's [metadata section](#what-is-the-metadata-section). + +This tutorial explores both of these topics. + +## Document UUID + +All OSCAL documents use a UUID [RFC4122](https://www.rfc-editor.org/rfc/rfc4122.html) 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. + +While not strictly part of the `metadata` section of an OSCAL document, this document identifier is part of the OSCAL document's core metadata. + +OSCAL supports two types of UUIDs: + +- [Version 4](https://www.rfc-editor.org/rfc/rfc4122.html#section-4.4): A randomly or pseudo-randomly generated UUID. +- [Version 5](https://www.rfc-editor.org/rfc/rfc4122.html#section-4.3): A name-based UUID based on SHA-1 hashing. + +The OSCAL program recommends using a version 4 (random) UUID as the document identifier, which is highly resistant to [collisions](https://en.wikipedia.org/wiki/Universally_unique_identifier#Collisions). + +Many tools and programming APIs provide easy ways to generate version 4 and 5 UUIDs. + +For our example we have generated the UUID `c3da6d1d-c20c-4c7c-ae73-4010167a186b` using a trivial UUIDv4 generator. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=false" >}} + +{{< /highlight >}} + +An OSCAL document's UUID is provided by the `@uuid` attribute, based on the [uuid](/reference/datatypes/#uuid) datatype, on the document's root element. In this example, the root element is `catalog`. + +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "catalog": { + "uuid": "c3da6d1d-c20c-4c7c-ae73-4010167a186b" + } +} +{{< /highlight >}} + +An OSCAL document's UUID is provided by the `uuid` property, based on the [uuid](/reference/datatypes/#uuid) datatype, on the document's top-level object. In this example, the top-level object is identified by the property `catalog`. + +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +--- +catalog: + uuid: c3da6d1d-c20c-4c7c-ae73-4010167a186b + +{{< /highlight >}} + +An OSCAL document's UUID is provided by the `uuid` key, based on the [uuid](/reference/datatypes/#uuid) datatype, at the document's top-level. In this example, the top-level key is named `catalog`. +{{% /tab %}} +{{% /tabs %}} + +## 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 for an OSCAL document. The metadata section contains several mandatory fields that are vital to the processing of OSCAL documents and help ensure interoperability, as well as optional fields that are designed to provide OSCAL content creators flexibility in expressing additional information. + +As with all parts of OSCAL, the metadata section can be represented in XML, JSON, and YAML, which each 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 + +The OSCAL metaschema reference ([XML](/reference/latest/complete/xml-definitions/#/assembly/oscal-metadata/metadata) | [JSON/YAML](/reference/latest/complete/json-definitions/#/assembly/oscal-metadata/metadata)) provides a comprehensive listing of the metadata section's data fields. Below is the high-level structure of the metadata section in XML, JSON, and YAML followed by a listing of each field's purpose. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + markup-line [1] + datetime-with-timezone [0 or 1] + datetime-with-timezone [1] + string [1] + string [1] + … [0 or 1] + string [0 to ∞] + … [0 to ∞] + markup-line [0 to ∞] + … [0 to ∞] + … [0 to ∞] + … [0 to ∞] + … [0 to ∞] + markup-multiline [0 or 1] + +{{< /highlight >}} + +Element definitions: + +- [``](/reference/latest/complete/xml-reference/#/catalog/metadata/title) (required) - A human-readable title for the document instance, expressed as [markup content](/reference/datatypes/#markup-line). +- [`<published>`](/reference/latest/complete/xml-reference/#/catalog/metadata/published) (optional) - The date and time that this document instance was originally published, expressed as a [datetime-with-timezone](/reference/datatypes/#datetime-with-timezone). +- [`<last-modified>`](/reference/latest/complete/xml-reference/#/catalog/metadata/last-modified) (required) - The date and time that this document instance was last modified, expressed as a [datetime-with-timezone](/reference/datatypes/#datetime-with-timezone). If any part of the document is changed, this value should be updated to the current date and time. +- [`<version>`](/reference/latest/complete/xml-reference/#/catalog/metadata/version) (required) - A [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/xml-reference/#/catalog/metadata/oscal-version) (required) - The version of OSCAL that this document instance is considered [valid](/concepts/validation/) against, expressed as a [string](/reference/datatypes/#string). +- [`<revisions>`](/reference/latest/complete/xml-reference/#/catalog/metadata/revisions/revision) (zero to many) - A list of revisions providing a history of changes to the document. +- [`<document-id>`](/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 a single 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. +- [`<prop>`](/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. +- [`<link>`](/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 its media type through the `@media-type` attribute. See the later [section](#links) for more information and usage guidance. +- [`<role>`](/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. +- [`<location>`](/reference/latest/catalog/xml-reference/#/catalog/metadata/location) (zero to many) - A location, with associated metadata that can be referenced. +- [`<party>`](/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. +- [`<responsible-party>`](/reference/latest/catalog/xml-reference/#/catalog/metadata/responsible-party) (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/xml-reference/#/catalog/metadata/remarks) (optional) - Markup formatted text consisting of notes for human readers of the content. + +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ +"metadata" : { + "title": "markup-line", + "published": "dateTime-with-timezone", + "last-modified": "dateTime-with-timezone", + "version": "string", + "oscal-version": "string", + "revisions": [ … ] [0 or 1], + "document-ids": [ { + "scheme": "uri" [0 or 1], + "identifier": "string" [1] + }, … ] [0 or 1], + "props": [ { + "uuid": "uuid" [0 or 1], + "ns": "uri" [0 or 1], + "name": "token" [1], + "value": "string" [1], + "class": "token" [0 or 1], + … + }, … ] [0 or 1], + "links": [ { + "rel": "token" [0 or 1], + "href": "uri-reference" [0 or 1], + "media-type": "string" [0 or 1], + "text": "markup-line" [0 or 1] + }, … ] [0 or 1], + "roles": [ { + "id": "token" [1], + … + }, … ] [0 or 1], + "locations": [ { + "uuid": "uuid" [1], + … + }, … ] [0 or 1], + "parties": [ { + "uuid": "uuid" [1], + "type": "string" [1], + … + }, … ] [0 or 1], + "responsible-parties": [ { + "role-id": "token" [1], + … + }, … ] [0 or 1], + "remarks": "markup-multiline" + } +} +{{< /highlight >}} + +Note that in JSON, any objects that may appear multiple times are contained in a JSON Array. + +Field definitions: + +- [`title`](/reference/latest/complete/json-reference/#/catalog/metadata/title) (required) - A human-readable title for the document, expressed as [Markdown content](/reference/datatypes/#markup-line). +- [`published`](/reference/latest/complete/json-reference/#/catalog/metadata/published) (optional) - The date and time that this document was originally published, expressed as a [datetime-with-timezone](/reference/datatypes/#datetime-with-timezone). +- [`last-modified`](/reference/latest/complete/json-reference/#/catalog/metadata/last-modified) (required) - The date and time that this document instance was last modified, expressed as a [datetime-with-timezone](/reference/datatypes/#datetime-with-timezone). If any part of the document is changed, this value should be updated to the current date and time. +- [`version`](/reference/latest/complete/json-reference/#/catalog/metadata/version) (required) - A [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 is considered [valid](/concepts/validation/) against, expressed as a [string](/reference/datatypes/#string). +- [`revisions`](/reference/latest/complete/json-reference/#/catalog/metadata/revisions) (optional) - A list of revisions providing a history of changes to the document. +- [`document-ids`](/reference/latest/catalog/json-reference/#/catalog/metadata/document-id) (optional, zero to many) - A set of unique IDs that identifies a document, tying all separate instances of the document into a single document series. The `scheme` property defines the identification scheme used based on a URI associated with 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 its 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 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 %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +metadata : + title: markup-line [1] + published: dateTime-with-timezone [0 or 1] + last-modified: dateTime-with-timezone [1] + version: string [1] + oscal-version: string [1] + revisions: … [0 to ∞] + document-ids: [0 to ∞] + - scheme: uri [0 or 1] + identifier: string [1] + props: … [0 to ∞] + - uuid: uuid [0 or 1] + ns: uri [0 or 1] + name: token [1] + value: string [1] + class: token [0 or 1] + … + links: … [0 to ∞] + - rel: token [0 or 1] + href: uri-reference [0 or 1] + media-type: string [0 or 1] + text: markup-line [0 or 1] + roles: … [0 to ∞] + - id: token [1] + … + locations: … [0 to ∞] + uuid: uuid [1] + … + parties: … [0 to ∞] + - uuid: uuid [1] + type: string [1] + … + responsible-parties: … [0 to ∞] + - role-id: token [1] + … + remarks: markup-multiline +{{< /highlight >}} + +Note that in YAML, any objects that may appear multiple times are contained in a YAML array. + +Field definitions: + +- [`title`](/reference/latest/complete/json-reference/#/catalog/metadata/title) (required) - A human-readable title for the document, expressed as [Markdown content](/reference/datatypes/#markup-line). +- [`published`](/reference/latest/complete/json-reference/#/catalog/metadata/published) (optional) - The date and time that this document was originally published, expressed as a [datetime-with-timezone](/reference/datatypes/#datetime-with-timezone). +- [`last-modified`](/reference/latest/complete/json-reference/#/catalog/metadata/last-modified) (required) - The date and time that this document instance was last modified, expressed as a [datetime-with-timezone](/reference/datatypes/#datetime-with-timezone). If any part of the document is changed, this value should be updated to the current date and time. +- [`version`](/reference/latest/complete/json-reference/#/catalog/metadata/version) (required) - A [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 is considered [valid](/concepts/validation/) against, expressed as a [string](/reference/datatypes/#string). +- [`revisions`](/reference/latest/complete/json-reference/#/catalog/metadata/revisions) (zero to many) - A list of revisions providing a history of changes to the document. +- [`document-ids`](/reference/latest/catalog/json-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. +- [`props`](/reference/latest/catalog/json-reference/#/catalog/metadata/props) (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) (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 its 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) (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) (zero to many) - A location, with associated metadata that can be referenced. +- [`parties`](/reference/latest/catalog/json-reference/#/catalog/metadata/parties) (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) (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 + +Let's 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 %}} + +The metadata section contains fields which may be categorized as: +- required +- recommended +- extensions +- and other optional fields + +The following sections demonstrate how the aforementioned field categories can be used to support specific use cases. + +### Using Required and 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. + +The following is an example of what a title might look like expressed in OSCAL: + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} +<title>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 %}} + +As you can see, the title is expressed in a very similar way across the different formats. + +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. By providing a localized timezone, the local time in any timezone can be calculated when using this information. + +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: + +{{< 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 including it is strongly recommended 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 published and then never updated, the `` value should be identical to the one given by ``. +{{% /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 field is not required, but including it is strongly recommended to help the OSCAL document consumer understand when the document was originally published. + + +The `last-modified` property provides the the date and time of the most recent change to this document. If a document was published and then never 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 including it is strongly recommended 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 published and then never updated, the `last-modified` value should be identical to the one given by `published`. +{{% /tab %}} +{{% /tabs %}} + +Next, we must provide the version of the content. This refers to the version of the OSCAL document instance 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. Where possible, it is recommended to 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, which is a generally accepted best practice for versioning. + +Since this is the first time we've created this document, we will use the semantic version "1.0.0". + +This information would be expressed in OSCAL as follows in the metadata section: + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=false" >}} +1.0.0 +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "version":"1.0.0" +} +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +version: 1.0.0 +{{< /highlight >}} +{{% /tab %}} +{{% /tabs %}} + +This version will be incremented whenever the OSCAL document is updated. + +Finally, it is required to specify the version of OSCAL that was used when creating the document. This value provides an indicator to tools processing the data, which version of OSCAL to consider the data [valid](/concepts/validation/) with. + +The OSCAL version is expressed in OSCAL as follows in the metadata section: + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} +1.0.4 +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "oscal-version":"1.0.4" +} +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +oscal-version: 1.0.4 +{{< /highlight >}} +{{% /tab %}} +{{% /tabs %}} + +We have now covered all required and recommended fields of the metadata section, and could publish our document as a valid OSCAL document. Here is what it would look like all together: + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + + Example OSCAL Document + 2021-01-01T00:00:00-5:00 + 2021-01-05T00:00:00-5:00 + 1.0.0 + 1.0.4 + + … + +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "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 %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +--- +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. + +### Providing additional document identifiers + +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 Series Instances". + +A "Document Series" consists of all formats, updates and versions of a given document. In more human terms, if a content author writes "Document 1 version 1", "Document 1 version 2", and "Document 1 version 3.4", we could say that the "Document Series" is simply "Document 1". Furthermore, if a document author produces PDF, OSCAL JSON, and other formats of the same information, it may be useful to identify the entire collection of formats and versions in a single "Document Series". + +A "Document Series Instance" is a discrete document instance that is part of a "Document Series". Using the above example, "Document 1 version 2 represented in OSCAL JSON" is a "Document Series Instance". + +In OSCAL we use a document identifier to identify that a document is a member of a "Document Series" and a document UUID to identify a "Document Series Instance". + +In the following example, we illustrate how to include a document identifier using the [Digital Object Identifier](https://www.doi.org/driven_by_DOI.html) (DOI) System using the identifier `10.1000/182`. This DOI points to the [DOI Handbook](https://www.doi.org/10.1000/182) and is used here as an example only. In a typical OSCAL use case, the referenced DOI will point to the actual OSCAL document instead. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + + + Example OSCAL Document + 2021-01-01T00:00:00-5:00 + 2021-01-05T00:00:00-5:00 + 1.0.0 + 1.0.4 + 10.1000/182 + + … + +{{< /highlight >}} + +In the above example, OSCAL we add a `` to track the "Document Series" identified by the DOI `10.1000/182`. + +The DOI System is indicated using the `@scheme` attribute value `http://www.doi.org/`, which is standardized in OSCAL ([XML](/reference/latest/complete/xml-definitions/#/field/oscal-metadata/document-id/scheme), [JSON/YAML](/reference/latest/complete/json-definitions/#/field/oscal-metadata/document-id/scheme)). A scheme is required to be a [URI](/reference/datatypes/#uri). +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "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", + "document-ids": [ + { + "scheme": "http://www.doi.org/", + "value": "10.1000/182" + } + ] + } + } +} +{{< /highlight >}} + +In the above example, OSCAL we add an object to the `document-ids` array to track the "Document Series" identified by the DOI `10.1000/182`. + +The DOI System is indicated using the `scheme` property value `http://www.doi.org/`, which is standardized in OSCAL ([XML](/reference/latest/complete/xml-definitions/#/field/oscal-metadata/document-id/scheme), [JSON/YAML](/reference/latest/complete/json-definitions/#/field/oscal-metadata/document-id/scheme)). A scheme is required to be a [URI](/reference/datatypes/#uri). +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +--- +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 + document-ids: + - scheme: http://www.doi.org/ + value: 10.1000/182 +{{< /highlight >}} + +In the above example, OSCAL we add an object to the `document-ids` list to track the "Document Series" identified by the DOI `10.1000/182`. + +The DOI System is indicated using the `scheme` property value `http://www.doi.org/`, which is standardized in OSCAL ([XML](/reference/latest/complete/xml-definitions/#/field/oscal-metadata/document-id/scheme), [JSON/YAML](/reference/latest/complete/json-definitions/#/field/oscal-metadata/document-id/scheme)). A scheme is required to be a [URI](/reference/datatypes/#uri). +{{% /tab %}} +{{% /tabs %}} + +In the future, any updated versions of this document that are produced will have the same "Document Series" identifier, but a different document identifier. + +In the case that a document does not explicitly provide a "Document Series" identifier as above, it is given one implicitly that is equal to it's document identifier. This means that if we publish a new document without a ``, then later need to publish an update to it, we can tie it back to the original document. + +Multiple "Document Series" identifiers can be provided for a document instance to denote that a document is a part of multiple Document Series. + +### Using Optional Extensions + +Like most OSCAL objects, the metadata section provides for the ability to define [properties](#properties) and link relationships. + +#### Properties + +In OSCAL properties are namespaced, key/value pairs that allow additional information to provided that annotate the containing object. In the metadata section, properties are used to provide document-level annotations. Common use cases for properties includes providing keywords, tags, and classifications. + +{{% callout note %}} +More information on the use of properties is provided in the [Props and Links tutorial](../extension/#props). +{{% /callout %}} + +For this example, we will create a property named `marking` in the default OSCAL namespace `http://csrc.nist.gov/ns/oscal` to mark an OSCAL document with a [Traffic Light Protocol (TLP)](https://www.first.org/tlp/) classification of `red`. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + +{{< /highlight >}} + +The `` element above declares the desired property. The `@name` attribute is the property's key, which is in the default OSCAL namespace `http://csrc.nist.gov/ns/oscal`, since no `@ns` is provided. The `@value` attribute is the property's value. + +Together they form a key-value pair to facilitate automated data lookup. Here we use the optional `@class` attribute to provide an additional layer of information, noting that the marking we are using is the TLP protocol, as indicated using the `http://www.first.org/tlp` scheme. +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "props": [ + { + "name": "marking", + "value": "red", + "class": "http://www.first.org/tlp" + } + ] +} +{{< /highlight >}} + +We add an object to the `props` array to declare the desired property. The `name` field is the property's key, which is in the default OSCAL namespace `http://csrc.nist.gov/ns/oscal`, since no `ns` field is provided. The `value` field is the property's value. + +Together they form a key-value pair to facilitate automated data lookup. Here we use the optional `class` field to provide an additional layer of information, noting that the marking we are using is the TLP protocol, as indicated using the `http://www.first.org/tlp` scheme. +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +props: +- name: marking + value: red + class: http://www.first.org/tlp +{{< /highlight >}} + +We add an item to the `props` list to declare the desired property. The `name` field is the property's key, which is in the default OSCAL namespace `http://csrc.nist.gov/ns/oscal`, since no `ns` field is provided. The `value` field is the property's value. + +Together they form a key-value pair to facilitate automated data lookup. Here we use the optional `class` field to provide an additional layer of information, noting that the marking we are using is the TLP protocol, as indicated using the `http://www.first.org/tlp` scheme. +{{% /tab %}} +{{% /tabs %}} + +This completes defining the marking property. + +#### Links + +Alongside properties, links are another way of providing additional information in the metadata section that is not covered by the other fields. Links are a means to establish a relationship between an OSCAL object and another OSCAL objects or web resource. + +{{% callout note %}} +The [Props and Links tutorial](../extension/#links) provides comprehensive examples of how to implement a ``. +{{% /callout %}} + +The following example illustrates how to establish a `latest-version` link to the latest version of the OSCAL document. This link will reference a static URL whose contents can be updated to reflect the latest revision of the document, which makes it easy for consumers to quickly and easily update their content. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +{{< highlight xml "linenos=table" >}} + +{{< /highlight >}} + +The `@rel` attribute establishes `latest-version` as the type of relationship. The `@href` attribute provides a URI that can be used to access, also called "resolve", the associated resource. +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "links": [ + { + "rel": "latest-version", + "href": "https://www.example.com/catalog/example-oscal-catalog/latest" + } + ] +} +{{< /highlight >}} + +By adding a new object to the `links` array property, the `rel` field establishes `latest-version` as the type of relationship. The `href` field provides a URI that can be used to access, also called "resolve", the associated resource. +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +links: +- rel: latest-version + href: https://www.example.com/catalog/example-oscal-catalog/latest +{{< /highlight >}} + +By adding a new item to the `links` list, `rel` field establishes `latest-version` as the type of relationship. The `href` field provides a URI that can be used to access, also called "resolve", the associated resource. +{{% /tab %}} +{{% /tabs %}} + +The `predecessor-version` and `successor-version` link relationships can be used in tandem with the above to create a navigable web of document versions. By using these and other custom relationship values, any relevant or related resource can be described and linked to in the OSCAL document's metadata section. + +### Using Other Optional Fields + +The remainder of this tutorial will briefly cover the other optional fields inside the metadata section. While not required by the specification, these fields provide invaluable information, particularly around the provenance and authorship of the data contained in an OSCAL document, or to define referencable roles, locations, or parties. This information is declared in the metadata section, and is often passed by-reference to other parts of the OSCAL document or other OSCAL documents importing that document. Each field can be expanded to get additional information. + +{{< tabs XML JSON YAML >}} +{{% tab %}} +- [``](/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 [Token](/reference/datatypes/#token) 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: + + - **creator:** Indicates the organization or person that created this content. + - **prepared-by:** Indicates the organization or person that created this content. + - **prepared-for:** Indicates the organization or person for which this content was created. + - **content-approver:** Indicates the organization or person responsible for all content represented in the "document". + - **contact:** Indicates the organization or person to contact for questions or support related to this content. + + Other roles can be locally defined by the content creator. + +- [``](/reference/latest/catalog/xml-reference/#/catalog/metadata/location) - Geographic data associated with a street, mailing, or email address, or phone number. 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/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. + +- [``](/reference/latest/catalog/xml-reference/#/catalog/metadata/responsible-party) - Explicitly declares a party that is responsible for a given role relative to the 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 core-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/remarks)) - [markup-multiline](/reference/datatypes/#markup-data-types) formatted text providing notes and comments regarding the document. +{{% /tab %}} +{{% tab %}} + +- [`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 [Token](/reference/datatypes/#token) 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: + + - **creator:** Indicates the organization or person that created this content. + - **prepared-by:** Indicates the organization or person that created this content. + - **prepared-for:** Indicates the organization or person for which this content was created. + - **content-approver:** Indicates the organization or person responsible for all content represented in the "document". + - **contact:** Indicates the organization or person to contact for questions or support related to this content. + + Other roles can be locally defined by the content creator. + +- [`locations`](/reference/latest/catalog/json-reference/#/catalog/metadata/locations) - An array of location objects. Geographic data associated with a street, mailing, or email address, or phone number. 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`](/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`](/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`](/reference/latest/catalog/json-reference/#/catalog/metadata/remarks) - [markup-multiline](/reference/datatypes/#markup-data-types) formatted text providing notes and comments regarding the document. +{{% /tab %}} + +{{% tab %}} +- [`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 [Token](/reference/datatypes/#token) 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: + + - **creator:** Indicates the organization or person that created this content. + - **prepared-by:** Indicates the organization or person that created this content. + - **prepared-for:** Indicates the organization or person for which this content was created. + - **content-approver:** Indicates the organization or person responsible for all content represented in the "document". + - **contact:** Indicates the organization or person to contact for questions or support related to this content. + + Other roles can be locally defined by the content creator. + +- [`locations`](/reference/latest/catalog/json-reference/#/catalog/metadata/locations) - Geographic data associated with a street, mailing, or email address, or phone number. 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`](/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`](/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`](/reference/latest/catalog/json-reference/#/catalog/metadata/remarks) - [markup-multiline](/reference/datatypes/#markup-data-types) formatted text providing notes and comments regarding the 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" >}} + + + Example OSCAL Document + 2021-01-01T00:00:00-5:00 + 2021-01-05T00:00:00-5:00 + 1.0.0 + 1.0.4 + 10.1000/182 + + + + Example Company + + + 15d2e37c-0452-4695-9c6a-ddc1ff15397b + + + +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "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", + "document-ids": [ + { + "scheme": "http://www.doi.org/", + "value": "10.1000/182" + } + ], + "props": [ + { + "name": "marking", + "value": "red", + "class": "http://www.first.org/tlp" + } + ], + "links": [ + { + "rel": "latest-version", + "href": "https://www.example.com/catalog/example-oscal-catalog/latest" + } + ], + "parties": [ + { + "uuid": "15d2e37c-0452-4695-9c6a-ddc1ff15397b", + "type": "organization", + "name": "Example Company" + } + ], + "responsible-parties":[ + { + "role-id": "prepared-by", + "party-uuid": "15d2e37c-0452-4695-9c6a-ddc1ff15397b" + } + ] + } + } +} +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +--- +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 + document-ids: + - scheme: http://www.doi.org/ + value: 10.1000/182 + props: + - name: marking + value: red + class: http://www.first.org/tlp + links: + - rel: latest-version + href: https://www.example.com/catalog/example-oscal-catalog/latest + parties: + - uuid: 15d2e37c-0452-4695-9c6a-ddc1ff15397b + type: organization + name: Example Company + responsible-parties: + - role-id: prepared-by + party-uuid: 15d2e37c-0452-4695-9c6a-ddc1ff15397b +{{< /highlight >}} +{{% /tab %}} +{{% /tabs %}} + +## Summary + +This concludes the tutorial. At this point you should be familiar with: + +- 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 diff --git a/docs/content/learn/tutorials/implementation/_index.md b/docs/content/learn/tutorials/implementation/_index.md new file mode 100644 index 0000000000..ed5f2a75c6 --- /dev/null +++ b/docs/content/learn/tutorials/implementation/_index.md @@ -0,0 +1,14 @@ +--- +title: Implementation Layer Topics +heading: Tutorials for the OSCAL implementation layer models +description: A set of tutorials that apply to the OSCAL component definition and system security plan models. +weight: 30 +suppresstopiclist: true +toc: + enabled: false +--- + +The following tutorial covers topics that apply to the OSCAL [implementation layer](/concepts/layer/implementation/) models. + +- [Creating a Basic Component Definition](basic-component-definition/): Teaches how to create a component-definition using the OSCAL [component definition](/concepts/layer/implementation/component-definition/) model. +- [Representing test validation information](validation-modeling/): Describes how to represent test validation information (e.g., FIPS-140-2) using a component in an OSCAL [component definition](/concepts/layer/implementation/component-definition/) or [system security plan](/concepts/layer/implementation/ssp/). diff --git a/docs/content/learn/tutorials/component-definition/_index.md b/docs/content/learn/tutorials/implementation/simple-component-definition.md similarity index 97% rename from docs/content/learn/tutorials/component-definition/_index.md rename to docs/content/learn/tutorials/implementation/simple-component-definition.md index 5eb2406df5..f8d4de159d 100644 --- a/docs/content/learn/tutorials/component-definition/_index.md +++ b/docs/content/learn/tutorials/implementation/simple-component-definition.md @@ -1,10 +1,12 @@ --- title: Creating a Component Definition description: A tutorial on creating an OSCAL component definition. -weight: 6 +weight: 40 suppresstopiclist: true toc: enabled: true +alias: +- /learn/tutorials/component-definition/ --- This tutorial covers creating a basic OSCAL component definition. Before reading this tutorial you should: @@ -57,9 +59,9 @@ The root of the OSCAL component definition model is [``](/ A `` contains the following elements: -- `` (required) - Provides document metadata for the component definition. This is covered in the [next section](/learn/tutorials/component-definition/#defining-the-component-definitions-metadata) to a limited extent. The metadata used here is similar to metadata for other OSCAL models, therefor is not described extensively in this tutorial. +- `` (required) - Provides document metadata for the component definition. This is covered in the [next section](#defining-the-component-definitions-metadata) to a limited extent. The metadata used here is similar to metadata for other OSCAL models, therefor is not described extensively in this tutorial. - `` (optional) – Identifies a collection of external component definitions from other resources from which related information is referenced within this component definition. Use of `` is not covered in this tutorial. -- `` (optional) - Defines a given component in the component definition. Zero or more `` elements may be used. Use of this element is [discussed later](/learn/tutorials/component-definition/#defining-the-mongodb-component) in this tutorial. +- `` (optional) - Defines a given component in the component definition. Zero or more `` elements may be used. Use of this element is [discussed later](#defining-the-mongodb-component) in this tutorial. - `` (optional) - Defines a given capability in the component definition. Zero or more `` elements may be used. Capabilities are not covered in this tutorial. - `` (optional) – Contains resources which are referenced within the component definition. Use of `` is not covered in this tutorial. {{% /tab %}} @@ -81,9 +83,9 @@ The root of the OSCAL component definition model is [`component-definition`](/re A `component-definition` contains the following properties: -- `metadata` (required) - Provides document metadata for the component definition. This is covered in the [next section](/learn/tutorials/component-definition/#defining-the-component-definitions-metadata) to a limited extent. The metadata used here is similar to metadata for other OSCAL models, therefor is not described extensively in this tutorial. +- `metadata` (required) - Provides document metadata for the component definition. This is covered in the [next section](#defining-the-component-definitions-metadata) to a limited extent. The metadata used here is similar to metadata for other OSCAL models, therefor is not described extensively in this tutorial. - `import-component-definitions` (optional) – Identifies a collection of external component definitions from other resources from which related information is referenced within this component definition. Use of `import-component-definitions` is not covered in this tutorial. -- `components` (optional) - Groups `component` objects which each define a given component in the component definition. One or more `component` objects may be provided. Use of this property is [discussed later](/learn/tutorials/component-definition/#defining-the-mongodb-component) in this tutorial. +- `components` (optional) - Groups `component` objects which each define a given component in the component definition. One or more `component` objects may be provided. Use of this property is [discussed later](#defining-the-mongodb-component) in this tutorial. - `capabilities` (optional) - Defines a group of given capabilities in the component definition. One or more `capability` objects may be used. Capabilities are not covered in this tutorial. - `back-matter` (optional) – Contains references which are referenced within the component definition. Use of `back-matter` is not covered in this tutorial. {{% /tab %}} @@ -104,9 +106,9 @@ The root of the OSCAL component definition model is [`component-definition`](/re A `component-definition` contains the following keys: -- `metadata` (required) - Provides document metadata for the component definition. This is covered in the [next section](/learn/tutorials/component-definition/#defining-the-component-definitions-metadata) to a limited extent. The metadata used here is similar to metadata for other OSCAL models, therefor is not described extensively in this tutorial. +- `metadata` (required) - Provides document metadata for the component definition. This is covered in the [next section](#defining-the-component-definitions-metadata) to a limited extent. The metadata used here is similar to metadata for other OSCAL models, therefor is not described extensively in this tutorial. - `import-component-definitions` (optional) – Identifies a collection of external component definitions from other resources from which related information is referenced within this component definition. Use of `import-component-definitions` is not covered in this tutorial. -- `components` (optional) - Groups `component` items which define given component(s) in the component definition. One or more `component` items may be used. Use of this key is [discussed later](/learn/tutorials/component-definition/#defining-the-mongodb-component) in this tutorial. +- `components` (optional) - Groups `component` items which define given component(s) in the component definition. One or more `component` items may be used. Use of this key is [discussed later](#defining-the-mongodb-component) in this tutorial. - `capabilities` (optional) - Defines a group of given capabilities in the component definition. One or more `capability` items may be used. Capabilities are not covered in this tutorial. - `back-matter` (optional) – Contains references which are referenced within the component definition. Use of `back-matter` is not covered in this tutorial. {{% /tab %}} diff --git a/docs/content/learn/tutorials/validation-modeling.md b/docs/content/learn/tutorials/implementation/validation-modeling.md similarity index 97% rename from docs/content/learn/tutorials/validation-modeling.md rename to docs/content/learn/tutorials/implementation/validation-modeling.md index 4e5d91b5bd..db852ce519 100644 --- a/docs/content/learn/tutorials/validation-modeling.md +++ b/docs/content/learn/tutorials/implementation/validation-modeling.md @@ -2,7 +2,7 @@ title: Representing Test Validation Information heading: "Representing Test Validation Information for Components" summary: "A mini-tutorial on providing test validation information (e.g., FIPS 140-2 validation) as an OSCAL component." -weight: 60 +weight: 90 toc: enabled: true sidenav: @@ -10,9 +10,12 @@ sidenav: inactiverenderdepth: 2 aliases: - /documentation/schema/implementation-layer/validation-modeling/ + - /learn/tutorials/validation-modeling/ --- -This tutorial covers describing test validation information (e.g., FIPS-140-2) using an OSCAL component. Before reading this tutorial you should: +This tutorial covers describing test validation information (e.g., FIPS-140-2) using an OSCAL component. + +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. - Read the OSCAL implementation layer [overview](/concepts/layer/implementation/).