diff --git a/docs/content/learn/tutorials/extensions/_index.md b/docs/content/learn/tutorials/extensions/_index.md index d17b1aeb46..5c4cabbdd3 100644 --- a/docs/content/learn/tutorials/extensions/_index.md +++ b/docs/content/learn/tutorials/extensions/_index.md @@ -23,25 +23,29 @@ Thus, OSCAL is designed with extensibility as one of its key principles, allowin ## Props -The `prop` property in OSCAL is used to extend core models when 1) there is a need to capture information that is not in the core OSCAL model or 2) there is a need to accommodate for property values that are not in core OSCAL. Props are defined by their given `name`, namespace `ns`, `value`, and `class` attributes, although only `name` and `value` are always required. +The `prop` property in OSCAL is used to extend core models when 1) there is a need to capture information that is not in the core OSCAL model or 2) there is a need to accommodate for property values that are not in core OSCAL. Props are defined by their given `name`, namespace `ns`, `value`, and `class` attributes, although only `name` and `value` are always required. Below is a description of each attribute: -The `name` attributed is required for every `prop` and should be a [token](/reference/datatypes/#token) data type. Depending on the OSCAL model data item, a `prop` may have OSCAL pre-defined names. For example, the OSCAL SSP model's system characteristics data item has a pre-defined `prop` named [`data-center`](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics/prop). Other data items, such as the OSCAL SSP security sensitivity level data item has its own pre-defined `props` (e.g., [`privacy-designation`](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics/security-sensitivity-level)). And in other cases, such as the SSP authorization boundary data item, `prop` does not have any pre-defined `name` values. OSCAL content authors need to determine whether to use the OSCAL prescribed prop names or to locally define their own. To view existing `prop` name values or determine if `name` can be defined locally, review the [model reference index](/reference/latest/complete/xml-index/#/prop). Requests and recommendations to add pre-defined `names` should be sent to the OSCAL NIST team (see the [Contact Us Page](/contact)). +- `name` (Required) - The `name` attributed is required for every `prop` and should be a [token](/reference/datatypes/#token) data type. Depending on the OSCAL model data item, a `prop` may have OSCAL pre-defined names. For example, the OSCAL SSP model's system characteristics data item has a pre-defined `prop` named [`data-center`](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics/prop). Other data items, such as the OSCAL SSP security sensitivity level data item has its own pre-defined `props` (e.g., [`privacy-designation`](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics/security-sensitivity-level)). And in other cases, such as the SSP authorization boundary data item, `prop` does not have any pre-defined `name` values. OSCAL content authors need to determine whether to use the OSCAL prescribed prop names or to locally define their own. To view existing `prop` name values or determine if `name` can be defined locally, review the [model reference index](/reference/latest/complete/xml-index/#/prop). Requests and recommendations to add pre-defined `names` should be sent to the OSCAL NIST team (see the [Contact Us Page](/contact)). +- `ns` (Optional) - The optional `ns` attribute is used to specify the namespace for a `prop` and should be a [universal resource identifier (URI)](/reference/datatypes/#uri) formatted according to RFC3986. The default namespace `ns` attribute for OSCAL `props` is `http://csrc.nist.gov/ns/oscal`, and can be omitted when using OSCAL define pre-defined properties (e.g., [`data-center`](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics/prop)). Namespaces qualify a property's name. This allows different organizations to associate distinct semantics with the same name. Organizations and other stakeholders have the ability to extend OSCAL with their own properties, which could lead to naming conflicts, however, the namespace `ns` can be specified by OSCAL content authors to prevent name collisions. +- `value` (Required) - The `value` attribute is required for every `prop` and should be a [string](/reference/datatypes/#string) data type. Generally, OSCAL content authors may specify any `value` for a `prop`. However, when using props with pre-defined `name` values, there are usually some constraints on acceptable `value`. For example, the OSCAL SSP [system characteristics](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics) data item pre-defined property named "identity-assurance-level" must have a value of 1, 2, or 3 as defined by NIST SP 800-63-3. The ability to extend with additional values depends on the `prop` (see the [model reference index](/reference/latest/complete/xml-index/#/prop)). The constraints for these `prop` properties are defined within the [OSCAL Metaschemas](https://github.com/usnistgov/OSCAL/tree/main/src/metaschema). Where applicable, Metaschema defines the `allowed-values` for the `prop` properties. The `prop` properties that are extensible are defined with an `allow-other=yes` attribute in Metaschema. +- `class` (Optional) - Finally, the optional `class` attribute should be used in cases where a property needs the same `name` and `ns` namespace. It is a textual label that provides a sub-type or characterization of the property's name. This can be used to further distinguish or discriminate between the semantics of multiple properties of the same object with the same name and ns. The `class` attribute should be a [token](/reference/datatypes/#token) data type and can be used in those circumstances to enable the "overloading" of the `prop`. -The optional `ns` attribute is used to specify the namespace for a `prop` and should be a [universal resource identifier (URI)](/reference/datatypes/#uri) formatted according to RFC3986. The default namespace `ns` attribute for OSCAL `props` is `http://csrc.nist.gov/ns/oscal`, and can be omitted when using OSCAL define pre-defined properties (e.g., [`data-center`](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics/prop)). Organizations and other stakeholders have the ability to extend OSCAL with their own properties, which could lead to naming conflicts, however, the namespace `ns` can be specified by OSCAL content authors to prevent name collisions. +### Using an Existing Prop -The `value` attribute is required for every `prop` and should be a [string](/reference/datatypes/#string) data type. Generally, OSCAL content authors may specify any `value` for a `prop`. However, when using props with pre-defined `name` values, there are usually some constraints on acceptable `value`. For example, the OSCAL SSP [system characteristics](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/system-characteristics) data item pre-defined property named "identity-assurance-level" must have a value of 1, 2, or 3 as defined by NIST SP 800-63-3. The ability to extend with additional values depends on the `prop` (see the [model reference index](/reference/latest/complete/xml-index/#/prop)). The constraints for these `prop` properties are defined within the [OSCAL Metaschemas](https://github.com/usnistgov/OSCAL/tree/main/src/metaschema). Where applicable, Metaschema defines the `allowed-values` for the `prop` properties. The `prop` properties that are extensible are defined with an `allow-other=yes` attribute in Metaschema. +This sections covers the basic use of a `prop` leveraging all of its attributes. The OSCAL SSP [metadata](/concepts/layer/overview/#metadata-overview) allows for zero or more `location` data items, each containing zero or more `props`. -Finally, the optional `class` attribute should be used in cases where a property needs the same `name` and `ns` namespace. The `class` attribute should be a [token](/reference/datatypes/#token) data type and can be used in those circumstances to enable the "overloading" of the `prop`. +{{% callout note %}} +The [Metadata Tutorial](/learn/tutorials/metadata/) provides in-depth description and walk-through examples of creating OSCAL metadata. +{{% /callout %}} -### Using an Existing Prop +In this example, an organization needs to document their primary and alternate data center locations. This is achieved by specifying the `name`, `value`, and `class` of the properties for each location. -This sections covers the basic use of a `prop` leveraging all of its attributes. The OSCAL SSP metadata allows for zero or more `location` data items, each containing zero or more `props`. In this example, an organization needs to document their primary and alternate data center locations. This is achieved by specifying the `name`, `value`, and `class` of the properties (on lines #10 and #14) for each location. +{{< tabs XML JSON YAML >}} -{{< tabs XML >}} {{% tab %}} {{< highlight xml "linenos=table" >}} - + OSCAL Basic Prop Example 2001-12-17T09:30:47Z @@ -49,134 +53,482 @@ This sections covers the basic use of a `prop` leveraging all of its attributes. 1.0.0 .... - + ... .... - + ... - - - + ... + ... + ... {{< /highlight >}} + +The `@name` attribute is set to "type" which is an OSCAL pre-defined property. The `@value` attribute is set to "data-center" which is an [OSCAL pre-defined](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/metadata/location) value for location "type" properties. The `@class` attribute in this case is used to indicate a subclass of data-center, and is set the the appropriate [OSCAL pre-defined](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/metadata/location) values for data center location properties. Note that in this example, the `@ns` attribute is omitted because we are using a standard OSCAL defined `` element. + {{% /tab %}} -{{% /tabs %}} -The `name` is set to "type" which is an OSCAL pre-defined property. The `value` is set to "data-center" which is an OSCAL pre-defined value for location "type" properties. The `class` attribute in this case is used to indicate a subclass of data-center, and is set the the appropriate OSCAL pre-defined values for data center location properties. Note that in this example, the `ns` attribute is omitted because we are using a standard OSCAL defined `prop`. +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "system-security-plan": { + "uuid": "ce16b9af-6853-4abe-9e27-b79d034c0adc", + "metadata": { + "title": "OSCAL Basic Prop Example", + "last-modified": "2001-12-17T09:30:47Z", + "version": 20210812, + "oscal-version": "1.0.0", + "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. The `value` property is set to "data-center" which is an [OSCAL pre-defined](/reference/latest/system-security-plan/json-reference/#/system-security-plan/metadata/locations) value for location "type" properties. The `class` property in this case is used to indicate a subclass of data-center, and is set the the appropriate [OSCAL pre-defined](/reference/latest/system-security-plan/json-reference/#/system-security-plan/metadata/locations) values for data center location `prop`. Note that in this example, the `ns` property is omitted because we are using a standard OSCAL defined `prop` object. + +{{% /tab %}} + +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +system-security-plan: + uuid: ce16b9af-6853-4abe-9e27-b79d034c0adc + metadata: + title: OSCAL Basic Prop Example + last-modified: '2001-12-17T09:30:47Z' + version: 20210812 + oscal-version: 1.0.0 + 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. The `value` property is set to "data-center" which is an [OSCAL pre-defined](/reference/latest/system-security-plan/json-reference/#/system-security-plan/metadata/locations) value for location "type" properties. The `class` property in this case is used to indicate a subclass of data-center, and is set the the appropriate [OSCAL pre-defined](/reference/latest/system-security-plan/json-reference/#/system-security-plan/metadata/locations) values for data center location `prop`. Note that in this example, the `ns` property is omitted because we are using a standard OSCAL defined `prop` object. + +{{% /tab %}} + +{{% /tabs %}} ### Extending Existing Prop Values One of the most common scenarios for extending an OSCAL `prop` is when adding values to an existing OSCAL property. Again, if using an OSCAL defined `prop`, the `ns` namespace attribute does not need to be specified since the default OSCAL namespace applies. -The following example demonstrates how to extend a SSP metadata location "type" `prop` with an additional value. Currently, the only OSCAL defined value for this `prop` is "data-center". However, because this particular `prop` is defined with an `allow-other=yes` attribute (in Metaschema), additional "type" values can be specified as shown below on line #10. +The following example demonstrates how to extend a SSP metadata location "type" `prop` with an additional value. + +{{% callout note %}} +Again, for a detailed overview of how to implement metadata, please refer to the [Metadata Tutorial](/learn/tutorials/metadata/). +{{% /callout %}} + +Currently, the only OSCAL defined value for the SSP metadata location `prop` is "data-center". However, because this particular `prop` is defined with an `allow-other=yes` attribute (in Metaschema), additional "type" values can be specified as shown below on line #10. + +{{< tabs XML JSON YAML >}} -{{< tabs XML >}} {{% tab %}} {{< highlight xml "linenos=table" >}} - + OSCAL Basic Prop Example 2001-12-17T09:30:47Z 20210812 1.0.0 - + .... - + ... - - - + ... + ... + ... {{< /highlight >}} + +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 %}} -{{% /tabs %}} -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 %}} +{{< highlight json "linenos=table" >}} +{ + "system-security-plan": { + "uuid": "ce16b9af-6853-4abe-9e27-b79d034c0adc", + "metadata": { + "title": "OSCAL Basic Prop Example", + "last-modified": "2001-12-17T09:30:47Z", + "version": 20210812, + "oscal-version": "1.0.0", + "locations": [ + { + "title": "....", + "props": [ + { + "name":"type", + "value":"security-operations-center" + } + ] + }] + }, + "import-profile": "...", + "system-characteristics": "...", + "system-implementation": "..." + } +} +{{< /highlight >}} + +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: '2001-12-17T09:30:47Z' + version: 20210812 + oscal-version: 1.0.0 + locations: + - title: .... + props: + - name: type + value: security-operations-center + import-profile: ... + system-characteristics: ... + system-implementation: ... +{{< /highlight >}} + +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 `prop` to document location details (e.g., location "type") within an SSP. But what if there were other pertinent location details that needed to be captured as well? For example, some government organizations with distributed global physical locations may want to use [Geographic Locator Codes (GLC)](https://www.gsa.gov/reference/geographic-locator-codes-glcs-overview) to facilitate interchange of location data with other government agencies. The example below demonstrates how this could be documented by specifying a new GLC `prop` property (see lines #11-13). +The previous examples leveraged an existing OSCAL `prop` to document location details (e.g., location "type") within an SSP. But what if there were other pertinent location details that needed to be captured as well? For example, some government organizations with distributed global physical locations may want to use [Geographic Locator Codes (GLC)](https://www.gsa.gov/reference/geographic-locator-codes-glcs-overview) to facilitate interchange of location data with other government agencies. The example below demonstrates how this could be documented by specifying a new GLC `prop` property (see lines #15-33). + +{{< tabs XML JSON YAML >}} -{{< tabs XML >}} {{% tab %}} {{< highlight xml "linenos=table" >}} - + OSCAL New Prop Example 2001-12-17T09:30:47Z 20210812 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 %}} -{{% /tabs %}} -A new GLC property was created by setting the props `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" `prop` but used `class` to provide more context for the property's set `value`. +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "system-security-plan": { + "uuid": "ce16b9af-6853-4abe-9e27-b79d034c0adc", + "metadata": { + "title": "OSCAL Basic Prop Example", + "last-modified": "2001-12-17T09:30:47Z", + "version": 20210812, + "oscal-version": "1.0.0", + "locations": [ + { + "title": "....", + "props": [ + { + "name":"type", + "value":"security-operations-center", + "class":"regional" + } + ] + }, + { + "title": "....", + "props": [ + { + "name":"glc", + "ns":"http://federal-agency.gov/ns/oscal", + "value":"11", + "class":"state-code" + } + ] + }, + { + "title": "....", + "props": [ + { + "name":"glc", + "ns":"http://federal-agency.gov/ns/oscal", + "value":"0010", + "class":"city-code" + } + ] + }, + { + "title": "....", + "props": [ + { + "name":"glc", + "ns":"http://federal-agency.gov/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`, 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. +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. -## Links +{{% /tab %}} -Links in OSCAL provide a form of indirection, allowing the referencing of local or remote content. Link can be particularly useful in referencing (external) information that is not represented in OSCAL format. This could include references to (cybersecurity) laws and regulations; references to organizational standards and guides; references to system bill of materials (SBOM) and more. Organizations can limit duplication of content, reduce the size of their OSCAL files, and maintain important content relationships by using links. +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +system-security-plan: + uuid: ce16b9af-6853-4abe-9e27-b79d034c0adc + metadata: + title: OSCAL Basic Prop Example + last-modified: '2001-12-17T09:30:47Z' + version: 20210812 + oscal-version: 1.0.0 + locations: + - title: .... + props: + - name: type + value: security-operations-center + class: regional + - title: .... + props: + - name: glc + ns: http://federal-agency.gov/ns/oscal + value: '11' + class: state-code + - title: .... + props: + - name: glc + ns: http://federal-agency.gov/ns/oscal + value: '0010' + class: city-code + - title: .... + props: + - name: glc + ns: http://federal-agency.gov/ns/oscal + value: '840' + class: country-code + import-profile: ... + system-characteristics: ... + system-implementation: ... -The `link` property is made available in specific OSCAL models and supports either URL or back matter resources. The `link` property has the following attributes: `href`, `rel`, `media-type`, and `text`. +{{< /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`. -The `href` attribute is a required, [resolvable URL reference](/reference/datatypes/#uri-reference) to a resource. This can either be an internet resource or a fragment that point to a back matter resource in the same document. +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. -The optional `rel` attribute is a [token](/reference/datatypes/#token) datatype that can be used to describe the link's purpose. Some OSCAL link properties may have pre-defined `rel` values (e.g., reference), but generally, OSCAL content authors can specify any token value for a `rel` attribute. +{{% /tab %}} -The optional `media-type` attribute can be used to provide the consumer of the OSCAL content a hint about the type of data referenced in the link. Supported media types are as defined by the [Internet Assigned Numbers Authority (IANA)](https://www.iana.org/assignments/media-types/media-types.xhtml). The `media-type` attribute accepts [string](/reference/datatypes/#string) values. +{{% /tabs %}} -Finally, the optional `text` sub-element can be used for as a textual label for the `link` and accepts [markup-line](/reference/datatypes/#markup-line) datatype. The subsequent sections demonstrate the proper use of links. +## Links + +Links in OSCAL provide a form of indirection, allowing the referencing of local or remote content. Link can be particularly useful in referencing (external) information that is not represented in OSCAL format. This could include references to (cybersecurity) laws and regulations; references to organizational standards and guides; references to system bill of materials (SBOM) and more. Organizations can limit duplication of content, reduce the size of their OSCAL files, and maintain important content relationships by using links. + +The `link` property is made available in specific OSCAL models and supports either URL or back matter resources. The `link` property has the following attributes: `href`, `rel`, `media-type`, and `text`. + +- `href` (Required) - The `href` attribute is a required, [resolvable URL reference](/reference/datatypes/#uri-reference) to a resource. This can either be an internet resource or a fragment that point to a back matter resource in the same document. +- `rel` (Optional) - The optional `rel` attribute is a [token](/reference/datatypes/#token) datatype that can be used to describe the link's purpose. Some OSCAL link properties may have pre-defined `rel` values (e.g., reference), but generally, OSCAL content authors can specify any token value for a `rel` attribute. Although any string can be used in the `rel` attribute, OSCAL identifies five common link relationships that are frequently useful: + - canonical: The link identifies the authoritative location for this file. + - alternate: The link identifies an alternative location or format for this file. + - latest-version: This link identifies a resource containing the latest version in the version history. Defined by RFC 5829. + - predecessor-version: This link identifies a resource containing the predecessor version in the version history. RFC 5829. + - successor-version: This link identifies a resource containing the predecessor version in the version history. RFC 5829. +- `media-type` (Optional) - The optional `media-type` attribute can be used to provide the consumer of the OSCAL content a hint about the type of data referenced in the link. Supported media types are as defined by the [Internet Assigned Numbers Authority (IANA)](https://www.iana.org/assignments/media-types/media-types.xhtml). The `media-type` attribute accepts [string](/reference/datatypes/#string) values. +- `text` (Optional) - Finally, the optional `text` sub-element can be used for as a textual label for the `link` and accepts [markup-line](/reference/datatypes/#markup-line) datatype. The subsequent sections demonstrate the proper use of links. ### Link to internet URL Organizations may need their documentation (e.g., SSP) to reference external items, such applicable laws and regulations (e.g., HSPD-12) and other organizational items (e.g., official agency logos). This first example illustrates how an OSCAL SSP might make use of a link to an internet URL. -{{< tabs XML >}} +{{< tabs XML JSON YAML >}} + {{% tab %}} {{< highlight xml "linenos=table" >}} - + OSCAL SSP Component Link Example 2001-12-17T09:30:47Z 20210707 1.0.0 - + HSPD-12 - + - - - + ... + ... + ... {{< /highlight >}} + +In this case, the `` element on line #8 provides a reference to 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 or office document formats). + +Line #11 demonstrates the use of `` to point to the organization's official logo. An absolute URI was used to point to the location of the referenced content, however, it should be noted that the `@href` attribute also permits the use of relative URI paths. If the referenced resource is located is on the same machine or domain, then a relative URI path could be used. The `@rel` attribute was set to "logo" to indicate the type of relationship provided by the specified ``. The `@media-type` attribute was included to let any rendering tools know that the logo content is a PNG image type. The optional `` sub-element was excluded for brevity of this example. + +The next section demonstrates how to reference back matter resources with links. Specifying a fragment in the `@href` attribute indicates that the `` is referencing a `` `` in the same OSCAL document. + +{{% /tab %}} + +{{% tab %}} +{{< highlight json "linenos=table" >}} +{ + "system-security-plan": { + "uuid": "ce16b9af-6853-4abe-9e27-b79d034c0adc", + "metadata": { + "title": "OSCAL SSP Component Link Example", + "last-modified": "2001-12-17T09:30:47Z", + "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 #8 provides a reference to HSPD-12 by specifying the URL in the `href` property. The OSCAL pre-defined "reference" value is used for the `rel`, providing context for the purpose of this specific `link`. The `text` property provides an associated label for the `link` which may be useful when rendering the SSP in other formats (e.g., html or office document formats). + +Lines #14-18 demonstrate the use of link to point to the organization's official logo. An absolute URI was used to point to the location of the referenced content, however, it should be noted that the `href` property also permits the use of relative URI paths. If the referenced resource is located is on the same machine or domain, then a relative URI path could be used. The `rel` property was set to "logo" to indicate the type of relationship provided by the specified `link`. The `media-type` property was included to let any rendering tools know that the logo content is a PNG image type. The optional `text` property was excluded for brevity of this example. + +The next section demonstrates how to reference back matter resources with links. Specifying a fragment in the `href` property indicates that the `link` is referencing a `back-matter` `resources` object array in the same OSCAL document. + {{% /tab %}} -{{% /tabs %}} -In this case, the `link` on line #8 provides a reference to HSPD-12 by specifying the URL in the `href` attribute. The OSCAL pre-defined "reference" value is used for the `rel`, providing some context for the purpose of this specific `link`. The `text` sub-element provides an associated label for the `link` which may be useful when rendering the SSP in other formats (e.g., html or office document formats). +{{% tab %}} +{{< highlight yaml "linenos=table" >}} +system-security-plan: + uuid: ce16b9af-6853-4abe-9e27-b79d034c0adc + metadata: + title: OSCAL SSP Component Link Example + last-modified: '2001-12-17T09:30:47Z' + 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: ... -Line #11 demonstrates the use of link to point to the organization's official logo. An absolute URI was used to point to the location of the referenced content, however, it should be noted that the `href` attribute also permits the use of relative URI paths. If the referenced resource is located is on the same machine or domain, then a relative URI path could be used. The `rel` property was set to "logo" to indicate the type of relationship provided by the specified `link`. The `media-type` attribute was included to let any rendering tools know that the logo content is a PNG image type. The optional `text` was excluded for brevity of this example. +{{< /highlight >}} -The next section demonstrates how to reference back matter resources with links. Specifying a fragment in the href attribute indicates that the `link` is referencing a `back-matter` `resource` in the same OSCAL document. +In this case, the `links` object array on line #7 provides a reference to HSPD-12 by specifying the URL in the `href` property. The OSCAL pre-defined "reference" value is used for the `rel`, providing context for the purpose of this specific `link`. The `text` property provides an associated label for the `link` which may be useful when rendering the SSP in other formats (e.g., html or office document formats). + +Lines #11-13 demonstrate the use of link to point to the organization's official logo. An absolute URI was used to point to the location of the referenced content, however, it should be noted that the `href` property also permits the use of relative URI paths. If the referenced resource is located is on the same machine or domain, then a relative URI path could be used. The `rel` property was set to "logo" to indicate the type of relationship provided by the specified `link`. The `media-type` property was included to let any rendering tools know that the logo content is a PNG image type. The optional `text` property was excluded for brevity of this example. + +The next section demonstrates how to reference back matter resources with links. Specifying a fragment in the `href` property indicates that the `link` is referencing a `back-matter` `resources` object array in the same OSCAL document. + +{{% /tab %}} + +{{% /tabs %}} ### Referencing Back-Matter @@ -184,36 +536,123 @@ When using `link` to reference `back-matter` `resources`, the `link` must use th In the previous section, multiple `links` would need to be created in the SSP metadata for each applicable laws and regulations. However, another approach would be to specify one `link` in the metadata for all applicable laws, regulations, standards, and guides. Then a single `resource` (for the applicable laws, regulations, standards, and guides) with multiple `rlinks` could be set in the back-matter as illustrated below. -{{< tabs XML >}} +{{< tabs XML JSON YAML >}} + {{% tab %}} {{< highlight xml "linenos=table" >}} - + OSCAL SSP Link to Back Matter Resource Example 2001-12-17T09:30:47Z 20210707 - 1.0.0"" - + 1.0.0 + Applicable Laws and Regulations, Standards, and Guides - - + ... + ... ... - - - + + + {{< /highlight >}} + +Notice that in this example, the `` element on line #8 only provides a fragment rather than a URL. OSCAL interprets this as a pointer to a back matter resource `@uuid` (see line #16). Within this `` element, several items are referenced (via ``). The `` must have a URI reference (`@href`). The third `` in this example provides a relative path. All of the other `` attributes (e.g., `@media-type` and `@hash`) are optional. Unlike ``, `` do not have any `@rel` attributes to provide additional context, nor do they have `` sub-elements. OSCAL content authors should consider these subtle differences when deciding whether to use `` or ``. + {{% /tab %}} -{{% /tabs %}} -Notice that in this example, the `link` on line #8 only provides a fragment rather than a URL. OSCAL interprets this as a pointer to a back matter resource `uuid` (see line #16). Within this `resource`, several items are referenced (via `rlinks`). The `rlinks` must have a URI reference (`href`). The third `rlink` in this example provides a relative path. All of the other `rlink` attributes (e.g., `mediat-type` and `hash`) are optional. Unlike `links`, `rlinks` do not have any `rel` attributes to provide additional context, nor do they have `text` sub-elements. OSCAL content authors should consider these subtle differences when deciding whether to use `links` or `rlinks`. +{{% 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": "2001-12-17T09:30:47Z", + "version": 20210707, + "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 >}} + +Notice that in this example, the `links` object array on line #8 only provides a fragment rather than a URL. OSCAL interprets this as a pointer to a back matter resource `uuid` (see line #20). Within `resources`, several items are referenced (via `rlinks`). Each `rlink` must have a URI reference (`href`). The third `rlink` in this example provides a relative path. All of the other `rlink` properties (e.g., `media-type` and `hash`) are optional. Unlike `links`, `rlinks` do not have any `rel` properties to provide additional context, nor do they have `text` properties. OSCAL content authors should consider these subtle differences when deciding whether to use `links` or `rlinks`. + +{{% /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: '2001-12-17T09:30:47Z' + version: 20210707 + 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 >}} + +Notice that in this example, the `links` object array on line #7 only provides a fragment rather than a URL. OSCAL interprets this as a pointer to a back matter resource `uuid` (see line #16). Within `resources`, several items are referenced (via `rlinks`). Each `rlink` must have a URI reference (`href`). The third `rlink` in this example provides a relative path. All of the other `rlink` properties (e.g., `media-type` and `hash`) are optional. Unlike `links`, `rlinks` do not have any `rel` properties to provide additional context, nor do they have `text` properties. OSCAL content authors should consider these subtle differences when deciding whether to use `links` or `rlinks`. + +{{% /tab %}} + +{{% /tabs %}} ## Summary diff --git a/docs/content/learn/tutorials/metadata/_index.md b/docs/content/learn/tutorials/metadata/_index.md index 597cd8d90c..c04a5e8140 100644 --- a/docs/content/learn/tutorials/metadata/_index.md +++ b/docs/content/learn/tutorials/metadata/_index.md @@ -3,24 +3,26 @@ title: 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 --- -This tutorial covers the basics of the common Metadata Section, and provides a walk-through on creating one for a new document. Before reading this tutorial you should: +This tutorial covers the basics of the common OSCAL Metadata Section, and provides a walk-through on creating one for a new OSCAL document. Before reading this tutorial you should: - Have some familiarity with the [XML](https://www.w3.org/standards/xml/core), [JSON](https://www.json.org/), or [YAML](https://yaml.org/spec/) formats. - Have a basic understanding of OSCAL Models and their overall structure. ([OSCAL High-Level Overview](/concepts/layer/overview/)) ## What is the Metadata Section? -All OSCAL Models share some common structure and elements, as discussed in [Common High-Level Structure](/concepts/layer/overview/#common-high-level-structure). The foremost of these is the Metadata section, which includes important identifying and categorizing information. A number of mandatory fields inside of Metadata are vital to the processing of OSCAL documents, and have stricter requirements that help ensure interoperability. A second, larger set of fields are optional, and designed to allow OSCAL content creators great flexibility in expressing additional information. These optional fields may enable extra functionality, utilize proprietary data, contain contact info, and more. +All OSCAL models share some common structure and elements, as discussed in [Common High-Level Structure](/concepts/layer/overview/#common-high-level-structure). The foremost of these is the Metadata Section, which includes important identifying and categorizing information. A number of mandatory fields inside of metadata are vital to the processing of OSCAL documents, and have stricter requirements that help ensure interoperability. A second, larger set of fields are optional, and designed to allow OSCAL content creators great flexibility in expressing additional information. These optional fields may enable extra functionality, utilize proprietary data, contain contact info, and more. The definition of the Metadata Section is the same regardless of where it appears, so this tutorial is not bound to a single OSCAL Model. As with all parts of OSCAL, the Metadata Section provides machine-readable formats in XML, JSON, and YAML, which support representing an equivalent set of information. Examples in this tutorial are provided for XML, JSON, and YAML to show the equivalent representations. -## The Fields of Metadata +## Metadata Fields -The widget below shows the high-level structure of the Metadata Section in XML, JSON, and YAML. Below, each field is defined and briefly explained. +Below is the high-level structure of the Metadata Section in XML, JSON, and YAML followed by a listing of each fields' definition with a brief description. {{< tabs XML JSON YAML >}} {{% tab %}} @@ -33,8 +35,10 @@ The widget below shows the high-level structure of the Metadata Section in XML, string [1] … [0 or 1] string [0 to ∞] - … [0 to ∞] - … [0 to ∞] + … [0 to ∞] + … [0 to ∞] … [0 to ∞] … [0 to ∞] … [0 to ∞] @@ -44,22 +48,22 @@ The widget below shows the high-level structure of the Metadata Section in XML, {{< /highlight >}} Element definitions: + - [``](/reference/latest/complete/xml-reference/#/catalog/metadata/title) (Required) - A human-readable title for the document. Expressed as [Markdown content](/reference/datatypes/#markup-line). - [`<published>`](/reference/latest/complete/xml-reference/#/catalog/metadata/published) (Optional) - The date and time that this document was originally published. Expressed as a [DateTime](/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. If any part of the document is changed, this should be updated to the current date and time. Expressed as a [DateTime](/reference/datatypes/#datetime-with-timezone). - [`<version>`](/reference/latest/complete/xml-reference/#/catalog/metadata/version) (Required) - A string that provides a version for this document instance. If any part of the document is changed, this version should be incremented according to some standardized scheme. A [simple String](/reference/datatypes/#string). - [`<oscal-version>`](/reference/latest/complete/xml-reference/#/catalog/metadata/oscal-version) (Required) - The version of OSCAL that this document instance was written against. A [simple String](/reference/datatypes/#string) - [`<revision>`](/reference/latest/catalog/xml-reference/#/catalog/metadata/revision) (Optional) - A list of revisions to this document to enable advanced change tracking. -- [`<document-id>`](/reference/latest/catalog/xml-reference/#/catalog/metadata/document-id) (Optionally 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 for more information and usage guidance. +- [`<document-id>`](/reference/latest/catalog/xml-reference/#/catalog/metadata/document-id) (Optionally 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 for more information and usage guidance. - [`<prop>`](/reference/latest/catalog/xml-reference/#/catalog/metadata/prop) (Optionally Many) - Represents some arbitrary "property" of the document. This flexible element provides an extension point for adding additional metadata. See TODO for more information and usage guidance. -- [`<link>`](/reference/latest/catalog/xml-reference/#/catalog/metadata/link) (Optionally Many) - Provides a resolvable URI (the `href` attribute) to some resource. The purpose of the link is given with the `rel` attribute, and it's media type through the `media-type` attribute. See [here](#understanding-and-using-document-id) for more information and usage guidance. +- [`<link>`](/reference/latest/catalog/xml-reference/#/catalog/metadata/link) (Optionally Many) - Provides a resolvable URI (the `@href` attribute) to some resource. The purpose of the link is given with the `@rel` attribute, and it's media type through the `@media-type` attribute. See [here](#understanding-and-using-document-id) for more information and usage guidance. - [`<role>`](/reference/latest/catalog/xml-reference/#/catalog/metadata/role) (Optionally Many) - Defines a function assumed or expected to be assumed by a party in a specific situation. - [`<location>`](/reference/latest/catalog/xml-reference/#/catalog/metadata/location) (Optionally Many) - A location, with associated metadata that can be referenced. - [`<party>`](/reference/latest/catalog/xml-reference/#/catalog/metadata/party) (Optionally Many) - A responsible entity which is either a person or an organization. - [`<responsible-party>`](/reference/latest/catalog/xml-reference/#/catalog/metadata/responsible-party) (Optionally 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 plaintext with notes for human readers of the content. - {{% /tab %}} {{% tab %}} {{< highlight json "linenos=table" >}} @@ -85,21 +89,21 @@ Element definitions: 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](/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. If any part of the document is changed, this should be updated to the current date and time. Expressed as a [DateTime](/reference/datatypes/#datetime-with-timezone). -- [`<version>`](/reference/latest/complete/json-reference/#/catalog/metadata/version) (Required) - A string that provides a version for this document instance. If any part of the document is changed, this version should be incremented according to some standardized scheme. A [simple String](/reference/datatypes/#string). -- [`<oscal-version>`](/reference/latest/complete/json-reference/#/catalog/metadata/oscal-version) (Required) - The version of OSCAL that this document instance was written against. A [simple String](/reference/datatypes/#string) -- [`<revision>`](/reference/latest/catalog/json-reference/#/catalog/metadata/revision) (Optional) - A list of revisions to this document to enable advanced change tracking. -- [`<document-id>`](/reference/latest/catalog/json-reference/#/catalog/metadata/document-id) (Optionally 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 for more information and usage guidance. -- [`<prop>`](/reference/latest/catalog/json-reference/#/catalog/metadata/props) (Optionally Many) - Represents some arbitrary "property" of the document. This flexible element provides an extension point for adding additional metadata. See TODO for more information and usage guidance. -- [`<link>`](/reference/latest/catalog/json-reference/#/catalog/metadata/links) (Optionally Many) - Provides a resolvable URI (the `href` attribute) to some resource. The purpose of the link is given with the `rel` attribute, and it's media type through the `media-type` attribute. See [here](#understanding-and-using-document-id) for more information and usage guidance. -- [`<role>`](/reference/latest/catalog/json-reference/#/catalog/metadata/roles) (Optionally Many) - Defines a function assumed or expected to be assumed by a party in a specific situation. -- [`<location>`](/reference/latest/catalog/json-reference/#/catalog/metadata/locations) (Optionally Many) - A location, with associated metadata that can be referenced. -- [`<party>`](/reference/latest/catalog/json-reference/#/catalog/metadata/parties) (Optionally Many) - A responsible entity which is either a person or an organization. -- [`<responsible-party>`](/reference/latest/catalog/json-reference/#/catalog/metadata/responsible-parties) (Optionally 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 plaintext with notes for human readers of the content. +- [`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](/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. If any part of the document is changed, this should be updated to the current date and time. Expressed as a [DateTime](/reference/datatypes/#datetime-with-timezone). +- [`version`](/reference/latest/complete/json-reference/#/catalog/metadata/version) (Required) - A string that provides a version for this document instance. If any part of the document is changed, this version should be incremented according to some standardized scheme. A [simple String](/reference/datatypes/#string). +- [`oscal-version`](/reference/latest/complete/json-reference/#/catalog/metadata/oscal-version) (Required) - The version of OSCAL that this document instance was written against. A [simple String](/reference/datatypes/#string) +- [`revision`](/reference/latest/catalog/json-reference/#/catalog/metadata/revision) (Optional) - A list of revisions to this document to enable advanced change tracking. +- [`document-ids`](/reference/latest/catalog/json-reference/#/catalog/metadata/document-id) (Optionally 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 for more information and usage guidance. +- [`props`](/reference/latest/catalog/json-reference/#/catalog/metadata/props) (Optionally Many) - Represents some arbitrary "property" of the document. This flexible element provides an extension point for adding additional metadata. See TODO for more information and usage guidance. +- [`links`](/reference/latest/catalog/json-reference/#/catalog/metadata/links) (Optionally Many) - Provides a resolvable URI (the `href` property) to some resource. The purpose of the link is given with the `rel` attribute, and it's media type through the `media-type` property. See [here](#understanding-and-using-document-id) for more information and usage guidance. +- [`roles`](/reference/latest/catalog/json-reference/#/catalog/metadata/roles) (Optionally Many) - Defines a function assumed or expected to be assumed by a party in a specific situation. +- [`locations`](/reference/latest/catalog/json-reference/#/catalog/metadata/locations) (Optionally Many) - A location, with associated metadata that can be referenced. +- [`parties`](/reference/latest/catalog/json-reference/#/catalog/metadata/parties) (Optionally Many) - A responsible entity which is either a person or an organization. +- [`responsible-parties`](/reference/latest/catalog/json-reference/#/catalog/metadata/responsible-parties) (Optionally 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 plaintext with notes for human readers of the content. {{% /tab %}} {{% tab %}} @@ -111,56 +115,57 @@ metadata : last-modified: dateTime-with-timezone version: string oscal-version: string - revisions: … - document-ids: … - props: … - links: … - roles: … - locations: … - parties: … - responsible-parties: … + revisions: … + document-ids: … + props: … + links: … + roles: … + locations: … + parties: … + responsible-parties: … 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](/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. If any part of the document is changed, this should be updated to the current date and time. Expressed as a [DateTime](/reference/datatypes/#datetime-with-timezone). -- [`<version>`](/reference/latest/complete/json-reference/#/catalog/metadata/version) (Required) - A string that provides a version for this document instance. If any part of the document is changed, this version should be incremented according to some standardized scheme. A [simple String](/reference/datatypes/#string). -- [`<oscal-version>`](/reference/latest/complete/json-reference/#/catalog/metadata/oscal-version) (Required) - The version of OSCAL that this document instance was written against. A [simple String](/reference/datatypes/#string) -- [`<revision>`](/reference/latest/catalog/json-reference/#/catalog/metadata/revision) (Optional) - A list of revisions to this document to enable advanced change tracking. -- [`<document-id>`](/reference/latest/catalog/json-reference/#/catalog/metadata/document-id) (Optionally 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 for more information and usage guidance. -- [`<prop>`](/reference/latest/catalog/json-reference/#/catalog/metadata/props) (Optionally Many) - Represents some arbitrary "property" of the document. This flexible element provides an extension point for adding additional metadata. See TODO for more information and usage guidance. -- [`<link>`](/reference/latest/catalog/json-reference/#/catalog/metadata/links) (Optionally Many) - Provides a resolvable URI (the `href` attribute) to some resource. The purpose of the link is given with the `rel` attribute, and it's media type through the `media-type` attribute. See [here](#understanding-and-using-document-id) for more information and usage guidance. -- [`<role>`](/reference/latest/catalog/json-reference/#/catalog/metadata/roles) (Optionally Many) - Defines a function assumed or expected to be assumed by a party in a specific situation. -- [`<location>`](/reference/latest/catalog/json-reference/#/catalog/metadata/locations) (Optionally Many) - A location, with associated metadata that can be referenced. -- [`<party>`](/reference/latest/catalog/json-reference/#/catalog/metadata/parties) (Optionally Many) - A responsible entity which is either a person or an organization. -- [`<responsible-party>`](/reference/latest/catalog/json-reference/#/catalog/metadata/responsible-parties) (Optionally 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 plaintext with notes for human readers of the content. +- [`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](/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. If any part of the document is changed, this should be updated to the current date and time. Expressed as a [DateTime](/reference/datatypes/#datetime-with-timezone). +- [`version`](/reference/latest/complete/json-reference/#/catalog/metadata/version) (Required) - A string that provides a version for this document instance. If any part of the document is changed, this version should be incremented according to some standardized scheme. A [simple String](/reference/datatypes/#string). +- [`oscal-version`](/reference/latest/complete/json-reference/#/catalog/metadata/oscal-version) (Required) - The version of OSCAL that this document instance was written against. A [simple String](/reference/datatypes/#string) +- [`revision`](/reference/latest/catalog/json-reference/#/catalog/metadata/revision) (Optional) - A list of revisions to this document to enable advanced change tracking. +- [`document-ids`](/reference/latest/catalog/json-reference/#/catalog/metadata/document-id) (Optionally Many) - A unique ID that identifies a document, and ties all separate instances of the document into one document series. The `scheme` property provides a URI to identify the scheme used to generate the ID. See for more information and usage guidance. +- [`props`](/reference/latest/catalog/json-reference/#/catalog/metadata/props) (Optionally Many) - Represents some arbitrary "property" of the document. This flexible element provides an extension point for adding additional metadata. See TODO for more information and usage guidance. +- [`links`](/reference/latest/catalog/json-reference/#/catalog/metadata/links) (Optionally Many) - Provides a resolvable URI (the `href` property) to some resource. The purpose of the link is given with the `rel` attribute, and it's media type through the `media-type` property. See [here](#understanding-and-using-document-id) for more information and usage guidance. +- [`roles`](/reference/latest/catalog/json-reference/#/catalog/metadata/roles) (Optionally Many) - Defines a function assumed or expected to be assumed by a party in a specific situation. +- [`locations`](/reference/latest/catalog/json-reference/#/catalog/metadata/locations) (Optionally Many) - A location, with associated metadata that can be referenced. +- [`parties`](/reference/latest/catalog/json-reference/#/catalog/metadata/parties) (Optionally Many) - A responsible entity which is either a person or an organization. +- [`responsible-parties`](/reference/latest/catalog/json-reference/#/catalog/metadata/responsible-parties) (Optionally 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 plaintext with notes for human readers of the content. {{% /tab %}} {{% /tabs %}} + ## Creating a Metadata Section -All OSCAL documents require a Metadata section with a number of basic elements. This tutorial will cover creating this section and populating the required elements. We will also cover several important optional elements, and how they can be used to achieve specialized use cases. +All OSCAL documents require a Metadata Section with a number of basic elements. This tutorial will cover creating this section and populating the required elements. We will also cover several important optional fields, and how they can be used to achieve specialized use cases. -Lets start with a nominal example OSCAL document to explain how you would create Metadata. +Lets start with a nominal example of an OSCAL Catalog document to demonstrate how to create Metadata. -This OSCAL document is a Catalog, called "Example OSCAL Catalog". It was created today (1/1/2021) by me, Example Person, employee of Example Company. +### Document UUID -## The `uuid` of the Document +UUIDs are a globally unique identifier randomly generated at the same time an OSCAL document is created. This provides a stable and unique way to refer to a given instance of an OSCAL document. {{< tabs XML JSON YAML >}} {{% tab %}} {{< highlight xml "linenos=table" >}} -<catalog uuid=c3da6d1d-c20c-4c7c-ae73-4010167a186b> +<catalog uuid="c3da6d1d-c20c-4c7c-ae73-4010167a186b"> {{< /highlight >}} -Although technically outside of the Metadata Section, the `uuid` of a document is always given as an attribute on the root element, and shares its structure across all OSCAL document types. This is provided using the [uuid](/reference/datatypes/#uuid) datatype. UUIDs are a globally unique identifier randomly generated at the same time an OSCAL document is created. This provides a stable and unique way to refer to a given instance of an OSCAL document. Many tools provide easy ways to generate version 4 UUIDs. For our example we have generated one using a trivial UUIDv4 generator. +Although technically outside of the Metadata Section, the `@uuid` of a document is always given as an attribute on the root element, and shares its structure across all OSCAL document types. This is provided using the [uuid](/reference/datatypes/#uuid) datatype. Many tools provide easy ways to generate version 4 UUIDs. For our example we have generated one using a trivial UUIDv4 generator. {{% /tab %}} {{% tab %}} @@ -172,90 +177,81 @@ Although technically outside of the Metadata Section, the `uuid` of a document i } {{< /highlight >}} -Although technically outside of the Metadata Section, the `uuid` of a document is always given as a field of the root element, and shares its structure across all OSCAL document types. This is provided using the [uuid](/reference/datatypes/#uuid) datatype. UUIDs are a globally unique identifier randomly generated at the same time an OSCAL document is created. This provides a stable and unique way to refer to a given instance of an OSCAL document. Many tools provide easy ways to generate version 4 UUIDs. For our example we have generated one using a trivial UUIDv4 generator. +Although technically outside of the Metadata Section, the `uuid` of a document is always given as a field of the root element, and shares its structure across all OSCAL document types. This is provided using the [uuid](/reference/datatypes/#uuid) datatype. Many tools provide easy ways to generate version 4 UUIDs. For our example we have generated one using a trivial UUIDv4 generator. {{% /tab %}} {{% tab %}} {{< highlight yaml "linenos=table" >}} --- - catalog: uuid: c3da6d1d-c20c-4c7c-ae73-4010167a186 {{< /highlight >}} -Although technically outside of the Metadata Section, the `uuid` of a document is always given as a field of the root element, and shares its structure across all OSCAL document types. This is provided using the [uuid](/reference/datatypes/#uuid) datatype. UUIDs are a globally unique identifier randomly generated at the same time an OSCAL document is created. This provides a stable and unique way to refer to a given instance of an OSCAL document. Many tools provide easy ways to generate version 4 UUIDs. For our example we have generated one using a trivial UUIDv4 generator. +Although technically outside of the Metadata Section, the `uuid` of a document is always given as a field of the root element, and shares its structure across all OSCAL document types. This is provided using the [uuid](/reference/datatypes/#uuid) datatype. Many tools provide easy ways to generate version 4 UUIDs. For our example we have generated one using a trivial UUIDv4 generator. {{% /tab %}} {{% /tabs %}} - -## Starting Simple with Required Elements - +### Starting with Required and Recommended Fields {{< tabs XML JSON YAML >}} - {{% tab %}} -First, we start with the `<title>` element. This should be populated with a human-readable title that is exactly or closely matches the existing name of the document. +First, we start with the `<title>` element. This should be populated with a human-readable title that is exactly or closely matches the existing name of the document. For our example, this would look like: {{< highlight xml "linenos=table" >}} -<title> Example OSCAL Catalog +Example OSCAL Catalog {{< /highlight >}} - -Next we have two date-based elements. This uses the OSCAL DataTime data type as defined here: [date-with-timezone](/reference/datatypes/#date-with-timezone). `` gives the DateTime of when the document was published for the first time. Since we are publishing this document for the first time today (1/1/2021), the published date will be today, and the time is the moment (or near to it) that this document was published. `` provides the DateTime of the most recent change to this document. As we have never published this particular document before, the DateTime should be identical to the one given by ``. In our example, this will look like: - +Next we have two date-based elements. This uses the OSCAL DataTime data type as defined here: [date-with-timezone](/reference/datatypes/#date-with-timezone). The `` element is not required but is strongly recommended. It gives the DateTime of when the document was published for the first time. For this example, we'll presume the document was published for the first time on January 1st, 2021, and the time was the moment (or near to it) that this document was published. The `` element provides the DateTime of the most recent change to this document. Since this document was never previously published, the DateTime should be identical to the one given by ``. In our example, this will look like: {{< highlight xml "linenos=table" >}} - 2021-01-01T00:00:00-5:00 - 2021-01-01T00:00:00-5:00 +2021-01-01T00:00:00-5:00 +2021-01-01T00:00:00-5:00 {{< /highlight >}} -Note that `` is not required, but is strongly recommended. - -Thirdly we must provide a `` element. This refers to the version of the OSCAL document itself, not the version of any other content. OSCAL does not place requirements on the version string itself, as versioning is a complicated process that differs from content creator to content creator. Since this is the first time we've created this document, some variation on a "1.0" would be appropriate. +Thirdly, we must provide a `` element. This refers to the version of the OSCAL document itself, not the version of any other content. OSCAL does not place requirements on the version string itself, as versioning is a complicated process that differs from content creator to content creator. Since this is the first time we've created this document, some variation on a "1.0" would be appropriate. {{< highlight xml "linenos=table" >}} - 1.0.0 + 1.0.0 {{< /highlight >}} Where possible, use well formatted versions with clear and defined rules. This version will be incremented whenever the OSCAL document is updated. -The final required element is ``, which provides consumers of the document that the version of OSCAL that was used to create this document. +The final required element is ``, which indicates what version of OSCAL was used to create this document. {{< highlight xml "linenos=table" >}} 1.0.0-rc2 {{< /highlight >}} -We have now covered all required fields of the Metadata Section, and could now publish our document as a valid OSCAL document. Lets take a look at what it would look like all together: +We have now covered all required fields of the Metadata Section, and could publish our document as a valid OSCAL document. Here is what it would look like all together: {{< highlight xml "linenos=table" >}} - + - Example OSCAL Document - 2021-01-01T00:00:00-5:00 - 2021-01-01T00:00:00-5:00 - 1.0.0 + Example OSCAL Document + 2021-01-01T00:00:00-5:00 + 2021-01-01T00:00:00-5:00 + 1.0.0 1.0.0-rc2 ... {{< /highlight >}} -However, the Metadata Section has several other optional fields of importance, which we will cover in the following sections. +However, the Metadata Section has several other optional but important fields which we will cover in the following sections. {{% /tab %}} - {{% tab %}} -First, we start with the `"title"` field. This should be populated with a human-readable title that exactly or closely matches an existing name of the document. +First, we start with the `title` field. This should be populated with a human-readable title that exactly or closely matches an existing name of the document. For our example, this would look like: @@ -265,8 +261,7 @@ For our example, this would look like: } {{< /highlight >}} -Next we have two date based fields. This uses the OSCAL DataTime data type as defined here: [date-with-timezone](/reference/datatypes/#date-with-timezone). `"published"` gives the DateTime of when the document was published for the first time. Since we are publishing this document for the first time today (1/1/2021), the published date will be today, and the time is the moment (or near to it) that this document was published. `"last-modified"` provides the DateTime of the most recent change to this document. As we have never published this particular document before, the DateTime should be identical to the one given by `"published"`. In our example, this will look like: - +Next we have two date-based elements. This uses the OSCAL DataTime data type as defined here: [date-with-timezone](/reference/datatypes/#date-with-timezone). The `published` field is not required but is strongly recommended. It gives the DateTime of when the document was published for the first time. For this example, we'll presume the document was published for the first time on January 1st, 2021, and the time was the moment (or near to it) that this document was published. The `last-modified` field provides the DateTime of the most recent change to this document. Since this document was never previously published, the DateTime should be identical to the one given by `published`. In our example, this will look like: {{< highlight json "linenos=table" >}} { @@ -275,9 +270,7 @@ Next we have two date based fields. This uses the OSCAL DataTime data type as de } {{< /highlight >}} -Note that `"published"` is not required, but is strongly recommended. - -Thirdly we must provide a `"version"` field. This refers to the version of the OSCAL document itself, not the version of any other content. OSCAL does not place requirements on the version string itself, as versioning is a complicated process that differs from content creator to content creator. Since this is the first time we've created this document, some variation on a "1.0" would be appropriate. +Thirdly we must provide a `version` field. This refers to the version of the OSCAL document itself, not the version of any other content. OSCAL does not place requirements on the version string itself, as versioning is a complicated process that differs from content creator to content creator. Since this is the first time we've created this document, some variation on a "1.0" would be appropriate. {{< highlight json "linenos=table" >}} { @@ -287,7 +280,7 @@ Thirdly we must provide a `"version"` field. This refers to the version of the O Where possible, use well formatted versions with clear and defined rules. This version will be incremented whenever the OSCAL document is updated. -The final required field is `"oscal-version"`, which provides consumers of the document that the version of OSCAL that was used to create this document. +The final required field is `oscal-version`, which indicates what version of OSCAL was used to create this document. {{< highlight json "linenos=table" >}} { @@ -295,7 +288,7 @@ The final required field is `"oscal-version"`, which provides consumers of the d } {{< /highlight >}} -We have now covered all required fields of the Metadata Section, and could now publish our document as a valid OSCAL document. Lets take a look at what it would look like all together: +We have now covered all required fields of the Metadata Section, and could publish our document as a valid OSCAL document. Here is what it would look like all together: {{< highlight json "linenos=table" >}} { @@ -312,13 +305,12 @@ We have now covered all required fields of the Metadata Section, and could now p } {{< /highlight >}} -However, the Metadata Section has several other optional fields of importance, which we will cover in the following sections. +However, the Metadata Section has several other optional but important fields which we will cover in the following sections. {{% /tab %}} - {{% tab %}} -First, we start with the `title` field. This should be populated with a human-readable title that is exactly or closely matches the existing name of the document. +First, we start with the `title` field. This should be populated with a human-readable title that is exactly or closely matches the existing name of the document. For our example, this would look like: @@ -329,8 +321,7 @@ title:Example OSCAL Catalog {{< /highlight >}} -Next we have two date based fields. This uses the OSCAL DataTime data type as defined here: [date-with-timezone](/reference/datatypes/#date-with-timezone). `published` gives the DateTime of when the document was published for the first time. Since we are publishing this document for the first time today (1/1/2021), the published date will be today, and the time is the moment (or near to it) that this document was published. `last-modified` provides the DateTime of the most recent change to this document. As we have never published this particular document before, the DateTime should be identical to the one given by `published`. In our example, this will look like: - +Next we have two date-based elements. This uses the OSCAL DataTime data type as defined here: [date-with-timezone](/reference/datatypes/#date-with-timezone). The `published` field is not required but is strongly recommended. It gives the DateTime of when the document was published for the first time. For this example, we'll presume the document was published for the first time on January 1st, 2021, and the time was the moment (or near to it) that this document was published. The `last-modified` field provides the DateTime of the most recent change to this document. Since this document was never previously published, the DateTime should be identical to the one given by `published`. In our example, this will look like: {{< highlight yaml "linenos=table" >}} --- @@ -338,8 +329,6 @@ Next we have two date based fields. This uses the OSCAL DataTime data type as de last-modified: 2021-01-01T00:00:00-5:00 {{< /highlight >}} -Note that `published` is not required, but is strongly recommended. - Thirdly we must provide a `version` field. This refers to the version of the OSCAL document itself, not the version of any other content. OSCAL does not place requirements on the version string itself, as versioning is a complicated process that differs from content creator to content creator. Since this is the first time we've created this document, some variation on a "1.0" would be appropriate. {{< highlight yaml "linenos=table" >}} @@ -349,7 +338,7 @@ Thirdly we must provide a `version` field. This refers to the version of the OSC Where possible, use well formatted versions with clear and defined rules. This version will be incremented whenever the OSCAL document is updated. -The final required field is `oscal-version`, which provides consumers of the document that the version of OSCAL that was used to create this document. +The final required field is `oscal-version`, which indicates what version of OSCAL was used to create this document. {{< highlight yaml "linenos=table" >}} --- @@ -358,7 +347,7 @@ oscal-version: 1.0.0 } {{< /highlight >}} -We have now covered all required fields of the Metadata Section, and could now publish our document as a valid OSCAL document. Lets take a look at what it would look like all together: +We have now covered all required fields of the Metadata Section, and could publish our document as a valid OSCAL document. Here is what it would look like all together: {{< highlight yaml "linenos=table" >}} --- @@ -372,44 +361,41 @@ We have now covered all required fields of the Metadata Section, and could now p oscal-version: 1.0.0 {{< /highlight >}} -However, the Metadata Section has several other optional fields of importance, which we will cover in the following sections. +However, the Metadata Section has several other optional but important fields which we will cover in the following sections. {{% /tab %}} {{% /tabs %}} -## Understanding and Using `document-id` +### Understanding and Using the Document-Id + +OSCAL documents, by their nature, may often require updates of varying impact. It is important to track these updates in a way that can be automated and managed by a wide array of systems and users. To that end, we must cover the concepts of "Document Series" and "Document Instances". + +A "Document Series" is defined as a document and all of its updates and versions. 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". + +A "Document Instance" is defined as a single document that is part of a "Document Series". Using the above example, "Document 1 version 2" is a "Document Instance". {{< tabs XML JSON YAML >}} {{% tab %}} -OSCAL documents, by their nature, will often receive updates of varying impact. It is important to track these updates in a way that can be automated and managed by a wide array of systems and users. To that end, we must cover the concepts of "Document Series" and "Document Instances". - -A "Document Series" is defined as a document and all of its updates and versions. In more human terms if I have written "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". -A "Document Instance" is defined as a single document that is part of a "Document Series". Using the above example, "Document 1 version 2" is a "Document Instance" -In OSCAL we use `` to track "Document Series", and `uuid` to track "Document Instance". +In OSCAL we use `` to track "Document Series", and `@uuid` to track "Document Instance". -Back to our OSCAL Catalog example, we have already generated a uuid to identify the particular instance that we are publishing. Since we are publishing the first document in a series, we should also define a ``. The `scheme` attribute is a (URI)[/reference/datatypes/#uri] that identifies the naming scheme we are using for the ID. While there are no strict requirements around the scheme and the ID, it is recommended that an existing identification scheme is used. For our example we will use [DOI](https://www.doi.org/). +Continuing with our OSCAL Catalog example, we have already generated a uuid to identify the particular instance that we are publishing. Since we are publishing the first document in a series, we should also define a ``. The `@scheme` attribute is a [URI](/reference/datatypes/#uri) that identifies the naming scheme we are using for the ID. While there are no strict requirements around the scheme and the ID, it is recommended that an existing identification scheme is used. For our example we will use [DOI](https://www.doi.org/). {{< highlight xml "linenos=table" >}} -10.1000/182 +10.1000/182 {{< /highlight >}} -In the future, any updated versions of this document we publish will have the same `` value, but a different `uuid`. +In the future, any updated versions of this document we publish will have the same `` value, but a different `@uuid`. -In the case that a document does not explicitly provide a `` value, it is given one implicitly that is equal to it's `uuid`. 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. +In the case that a document does not explicitly provide a `` value, it is given one implicitly that is equal to it's `@uuid`. 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 `` elements denote that a document is a part of multiple Document Series. This is a rare but valid use case. {{% /tab %}} - {{% tab %}} -OSCAL documents, by their nature, will often receive updates of varying impact. It is important to track these updates in a way that can be automated and managed by a wide array of systems and users. To that end, we must cover the concepts of "Document Series" and "Document Instances". - -A "Document Series" is defined as a document and all of its updates and versions. In more human terms if I have written "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". -A "Document Instance" is defined as a single document that is part of a "Document Series". Using the above example, "Document 1 version 2" is a "Document Instance" -In OSCAL we use `"document-ids"` to track "Document Series", and `"uuid"` to track "Document Instance". +In OSCAL we use `document-ids` to track "Document Series", and `uuid` to track "Document Instance". -Back to our OSCAL Catalog example, we have already generated a uuid to identify the particular instance that we are publishing. Since we are publishing the first document in a series, we should also define a `"document-ids"`. The `"scheme"` field is a (URI)[/reference/datatypes/#uri] that identifies the naming scheme we are using for the ID. While there are no strict requirements around the scheme and the ID, it is recommended that an existing identification scheme is used. For our example we will use [DOI](https://www.doi.org/). +Continuing with our OSCAL Catalog example, we have already generated a uuid to identify the particular instance that we are publishing. Since we are publishing the first document in a series, we should also define a `document-ids`. The `scheme` field is a [URI](/reference/datatypes/#uri) that identifies the naming scheme we are using for the ID. While there are no strict requirements around the scheme and the ID, it is recommended that an existing identification scheme is used. For our example we will use [DOI](https://www.doi.org/). {{< highlight json "linenos=table" >}} { @@ -422,21 +408,16 @@ Back to our OSCAL Catalog example, we have already generated a uuid to identify } {{< /highlight >}} -In the future, any updated versions of this document we publish will have the same `"document-ids"` values, but a different `"uuid"`. +In the future, any updated versions of this document we publish will have the same `document-ids` values, but a different `uuid`. -In the case that a document does not explicitly provide at least one object inside `"document-ids"`, it is given a value implicitly that is equal to it's `"uuid"`. This means that if we publish a new document without a `"document-ids"`, then later need to publish an update to it, we can tie it back to the original document. +In the case that a document does not explicitly provide at least one object inside `document-ids`, it is given a value implicitly that is equal to it's `uuid`. This means that if we publish a new document without a `document-ids`, then later need to publish an update to it, we can tie it back to the original document. {{% /tab %}} - {{% tab %}} -OSCAL documents, by their nature, will often receive updates of varying impact. It is important to track these updates in a way that can be automated and managed by a wide array of systems and users. To that end, we must cover the concepts of "Document Series" and "Document Instances". - -A "Document Series" is defined as a document and all of its updates and versions. In more human terms if I have written "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". -A "Document Instance" is defined as a single document that is part of a "Document Series". Using the above example, "Document 1 version 2" is a "Document Instance" In OSCAL we use `document-id` to track "Document Series", and `uuid` to track "Document Instance". -Back to our OSCAL Catalog example, we have already generated a uuid to identify the particular instance that we are publishing. Since we are publishing the first document in a series, we should also define a `document-id`. The `scheme` field is a (URI)[/reference/datatypes/#uri] that identifies the naming scheme we are using for the ID. While there are no strict requirements around the scheme and the ID, it is recommended that an existing identification scheme is used. For our example we will use [DOI](https://www.doi.org/). +Continuing with our OSCAL Catalog example, we have already generated a uuid to identify the particular instance that we are publishing. Since we are publishing the first document in a series, we should also define a `document-id`. The `scheme` field is a [URI](/reference/datatypes/#uri) that identifies the naming scheme we are using for the ID. While there are no strict requirements around the scheme and the ID, it is recommended that an existing identification scheme is used. For our example we will use [DOI](https://www.doi.org/). {{< highlight yaml "linenos=table" >}} --- @@ -451,33 +432,33 @@ In the case that a document does not explicitly provide a `document-id` value, i {{% /tab %}} {{% /tabs %}} - - -## Using Props +### Using Props {{< tabs XML JSON YAML >}} {{% tab %}} -The `` element provides a key-value pairing to provide additional information alongside the well-defined elements of the Metadata Section. Some common use cases include labels, sorting tags, and classification. There are no restrictions on using custom `name` and `value` pairs making `` an excellent place to do extension of the OSCAL model to meet proprietary use cases. The Metadata Section may include any number of `` elements. +The Metadata Section may include any number of `` elements. The `` element provides a key-value pairing to provide additional information alongside the well-defined elements of the Metadata Section. Some common use cases include labels, sorting tags, and classification. There are no restrictions on using custom `@name` and `@value` pairs making `` an excellent place to do extension of the OSCAL model to meet proprietary use cases. The Metadata Section may include any number of `` elements. + +{{% callout note %}} +More information on the use of `` is provided in the [Props and Links tutorial](/learn/tutorials/extensions/#props). +{{% /callout %}} -For our example, we will create a `` to mark an OSCAL document with a [Traffic Light Protocol (TLP)](https://en.wikipedia.org/wiki/Traffic_Light_Protocol) classification. +For this example, we will create a `` to mark an OSCAL document with a [Traffic Light Protocol (TLP)](https://en.wikipedia.org/wiki/Traffic_Light_Protocol) classification. {{< highlight xml "linenos=table" >}} {{< /highlight >}} -The `name` attribute is the key, and the `value` attribute is the value. Together they form a key-value pair to facilitate automated data lookup. Here we use an optional `class` attribute to provide an additional layer of information, noting that the marking we are using is the TLP protocol. - -The optional attributes of `` are as follows: - -- class: A textual label that provides a sub-type or characterization of the property's name. This can be used to further distinguish or discriminate between the semantics of multiple properties of the same object with the same name and ns. -- uuid: A unique identifier that can be used to reference this property elsewhere in an OSCAL document. A UUID should be consistently used for a given location across revisions of the document. -- ns: A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name. - -Additionally, the content of the `` element is optionally Markup content that represents [Remarks](https://pages.nist.gov/OSCAL/documentation/schema/assessment-layer/assessment-plan/xml-schema/#global_remarks_h2). +The `@name` attribute is the key, and the `@value` attribute is the value. Together they form a key-value pair to facilitate automated data lookup. Here we use an optional `@class` attribute to provide an additional layer of information, noting that the marking we are using is the TLP protocol. +The [Props and Links tutorial](/learn/tutorials/extensions/#using-an-existing-prop) provides more details on these attributes. + {{% /tab %}} {{% tab %}} -The `"props"` array provides any number of key-value pairing to provide additional information alongside the well-defined fields of the Metadata Section. Some common use cases include labels, sorting tags, and classification. There are no restrictions on using custom `"name"` and `"value"` pairs making `"props"` an excellent place to do extension of the OSCAL model to meet proprietary use cases. +The `props` object array provides any number of key-value pairing to provide additional information alongside the well-defined fields of the Metadata Section. Some common use cases include labels, sorting tags, and classification. There are no restrictions on using custom `name` and `value` pairs making `props` an excellent place to do extension of the OSCAL model to meet proprietary use cases. + +{{% callout note %}} +More information on the use of `props` is provided in the [Props and Links tutorial](/learn/tutorials/extensions/#props). +{{% /callout %}} -For our example, we will create a `"props"` array to mark an OSCAL document with a [Traffic Light Protocol (TLP)](https://en.wikipedia.org/wiki/Traffic_Light_Protocol) classification. +For this example, we will create a `props` array to mark an OSCAL document with a [Traffic Light Protocol (TLP)](https://en.wikipedia.org/wiki/Traffic_Light_Protocol) classification. {{< highlight json "linenos=table" >}} { @@ -491,20 +472,17 @@ For our example, we will create a `"props"` array to mark an OSCAL document with } {{< /highlight >}} -The `"name"` field is the key, and the `"value"` field is the value. Together they form a key-value pair to facilitate automated data lookup. Here we use an optional `"class"` field to provide an additional layer of information, noting that the marking we are using is the TLP protocol. - -The optional fields of objects inside `"props"` are as follows: - -- `"class"`: A textual label that provides a sub-type or characterization of the property's name. This can be used to further distinguish or discriminate between the semantics of multiple properties of the same object with the same name and ns. -- `"uuid"`: A unique identifier that can be used to reference this property elsewhere in an OSCAL document. A UUID should be consistently used for a given location across revisions of the document. -- `"ns"`: A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name. -- `"remarks"`: Additional commentary on the containing object. See [Remarks](https://pages.nist.gov/OSCAL/documentation/schema/assessment-layer/assessment-plan/xml-schema/#global_remarks_h2). +The `name` field is the key, and the `value` field is the value. Together they form a key-value pair to facilitate automated data lookup. Here we use an optional `class` field to provide an additional layer of information, noting that the marking we are using is the TLP protocol. The [Props and Links tutorial](/learn/tutorials/extensions/#using-an-existing-prop) provides more details on these fields. {{% /tab %}} {{% tab %}} The `props` array provides any number of key-value pairings to provide additional information alongside the well-defined fields of the Metadata Section. Some common use cases include labels, sorting tags, and classification. There are no restrictions on using custom `name` and `value` pairs making `prop` an excellent place to do extension of the OSCAL model to meet proprietary use cases. -For our example, we will create a `props` to mark an OSCAL document with a [Traffic Light Protocol (TLP)](https://en.wikipedia.org/wiki/Traffic_Light_Protocol) classification. +{{% callout note %}} +More information on the use of `props` is provided in the [Props and Links tutorial](/learn/tutorials/extensions/#props). +{{% /callout %}} + +For this example, we will create a `props` to mark an OSCAL document with a [Traffic Light Protocol (TLP)](https://en.wikipedia.org/wiki/Traffic_Light_Protocol) classification. {{< highlight yaml "linenos=table" >}} --- @@ -514,50 +492,40 @@ For our example, we will create a `props` to mark an OSCAL document with a [Traf class: TLP {{< /highlight >}} -The `name` field is the key, and the `value` field is the value. Together they form a key-value pair to facilitate automated data lookup. Here we use an optional `class` field to provide an additional layer of information, noting that the marking we are using is the TLP protocol. - -The optional fields of the objects inside `props` are as follows: - -- `class`: A textual label that provides a sub-type or characterization of the property's name. This can be used to further distinguish or discriminate between the semantics of multiple properties of the same object with the same name and ns. -- `uuid`: A unique identifier that can be used to reference this property elsewhere in an OSCAL document. A UUID should be consistently used for a given location across revisions of the document. -- `ns`: A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name. -- `remarks`: Additional commentary on the containing object. See [Remarks](https://pages.nist.gov/OSCAL/documentation/schema/assessment-layer/assessment-plan/xml-schema/#global_remarks_h2). +The `name` field is the key, and the `value` field is the value. Together they form a key-value pair to facilitate automated data lookup. Here we use an optional `class` field to provide an additional layer of information, noting that the marking we are using is the TLP protocol. The [Props and Links tutorial](/learn/tutorials/extensions/#using-an-existing-prop) provides more details on these fields. {{% /tab %}} {{% /tabs %}} -## Using Link +### Using Link {{< tabs XML JSON YAML >}} {{% tab %}} -Alongside the `` element, `` is way of providing additional information in the Metadata section that is not covered by the other elements. Each `` must contain a single `href` attribute, which contains a resolvable URI. Each `` should also include a `rel` attribute, which describes the type of relationship provided by the `href`. Although any string can be used in the `rel` attribute, OSCAL identifies five common link relationships that are frequently useful: - - canonical: The link identifies the authoritative location for this file. - - alternate: The link identifies an alternative location or format for this file. - - latest-version: This link identifies a resource containing the latest version in the version history. Defined by RFC 5829. - - predecessor-version: This link identifies a resource containing the predecessor version in the version history. RFC 5829. - - successor-version: This link identifies a resource containing the predecessor version in the version history. RFC 5829. +Alongside the `` element, `` is way of providing additional information in the Metadata section that is not covered by the other elements. Each `` must contain a single `@href` attribute, which contains a resolvable URI. Each `` should also include a `@rel` attribute, which describes the type of relationship provided by the `@href`. + +{{% callout note %}} +The [Props and Links tutorial](/learn/tutorials/extensions/#links) provides comprehensive examples of how to implement a ``. +{{% /callout %}} For this example, we will create a "latest-version" link, which provides a static link to the latest version of this Document Series. By pointing to a static URL, but updating the contents of that URL as the document is updated, any user that has an old version of the document can quickly and easily update. {{< highlight xml "linenos=table" >}} - + {{< /highlight >}} The "predecessor-version" and "successor-version" links could be used in tandem with the above to create a navigable web of document versions. -By using other custom `rel` values, any relevant or related resource can be described and linked to in the OSCAL Document's Metadata Section. +By using other custom `@rel` values, any relevant or related resource can be described and linked to in the OSCAL Document's Metadata Section. -Use of the optional `media-type` attribute can provide consumers with processing instructions based on the media type of the resource found at the `href`. See [IANA Media Types](https://www.iana.org/assignments/media-types/media-types.xhtml). {{% /tab %}} - {{% tab %}} -Alongside the `"props"` array, the `"links"` array is a way of providing additional information in the Metadata section that is not covered by the other fields. Each object inside the `"links"` array must contain a single `"href"` field, which contains a resolvable URI. Each object should also include a `"rel"` field, which describes the type of relationship provided by the `"href"`. Although any string can be used in the `"rel"` field, OSCAL identifies five common link relationships that are frequently useful: - - canonical: The link identifies the authoritative location for this file. - - alternate: The link identifies an alternative location or format for this file. - - latest-version: This link identifies a resource containing the latest version in the version history. Defined by RFC 5829. - - predecessor-version: This link identifies a resource containing the predecessor version in the version history. RFC 5829. - - successor-version: This link identifies a resource containing the predecessor version in the version history. RFC 5829. +Alongside the `props` array, the `links` array is a way of providing additional information in the Metadata section that is not covered by the other fields. Each object inside the `links` array must contain a single `href` field, which contains a resolvable URI. Each object should also include a `rel` field, which describes the type of relationship provided by the `href`. + +{{% callout note %}} +The [Props and Links tutorial](/learn/tutorials/extensions/#links) provides comprehensive examples of how to implement a `link`. +{{% /callout %}} For this example, we will create a "latest-version" link, which provides a static link to the latest version of this Document Series. By pointing to a static URL, but updating the contents of that URL as the document is updated, any user that has an old version of the document can quickly and easily update. @@ -574,20 +542,16 @@ For this example, we will create a "latest-version" link, which provides a stati The "predecessor-version" and "successor-version" links could be used in tandem with the above to create a navigable web of document versions. -By using other custom `"rel"` values, any relevant or related resource can be described and linked to in the OSCAL Document's Metadata Section. +By using other custom `rel` values, any relevant or related resource can be described and linked to in the OSCAL Document's Metadata Section. -Use of the optional `"media-type"` field can provide consumers with processing instructions based on the media type of the resource found at the `"href"`. See [IANA Media Types](https://www.iana.org/assignments/media-types/media-types.xhtml). {{% /tab %}} - - {{% tab %}} -Alongside the `props` array, the `links` array is way of providing additional information in the Metadata section that is not covered by the other fields. Each object inside the `links` array must contain a single `href` field, which contains a resolvable URI. Each object should also include a `rel` field, which describes the type of relationship provided by the `href`. Although any string can be used in the `rel` field, OSCAL identifies five common link relationships that are frequently useful: - - canonical: The link identifies the authoritative location for this file. - - alternate: The link identifies an alternative location or format for this file. - - latest-version: This link identifies a resource containing the latest version in the version history. Defined by RFC 5829. - - predecessor-version: This link identifies a resource containing the predecessor version in the version history. RFC 5829. - - successor-version: This link identifies a resource containing the predecessor version in the version history. RFC 5829. +Alongside the `props` array, the `links` array is way of providing additional information in the Metadata section that is not covered by the other fields. Each object inside the `links` array must contain a single `href` field, which contains a resolvable URI. Each object should also include a `rel` field, which describes the type of relationship provided by the `href`. + +{{% callout note %}} +The [Props and Links tutorial](/learn/tutorials/extensions/#links) provides comprehensive examples of how to implement a `link`. +{{% /callout %}} For this example, we will create a "latest-version" link, which provides a static link to the latest version of this Document Series. By pointing to a static URL, but updating the contents of that URL as the document is updated, any user that has an old version of the document can quickly and easily update. @@ -602,87 +566,90 @@ The "predecessor-version" and "successor-version" links could be used in tandem By using other custom `rel` values, any relevant or related resource can be described and linked to in the OSCAL Document's Metadata Section. -Use of the optional `media-type` field can provide consumers with processing instructions based on the media type of the resource found at the `href`. See [IANA Media Types](https://www.iana.org/assignments/media-types/media-types.xhtml). {{% /tab %}} {{% /tabs %}} -## The Other Optional Elements + +### Using Other Optional Elements + {{< tabs XML JSON YAML >}} {{% tab %}} -The remainder of this tutorial will briefly cover the other optional elements inside the Metadata Section. While not required by the specification, these elements provide invaluable information, particularly for providence and authorship data. This information is declared in the Metadata Section, and is often passed by-reference to other parts of the OSCAL Document. Each element can be clicked to get additional information. +The remainder of this tutorial briefly covers the other optional elements inside the Metadata Section. While not required by the specification, these elements provide invaluable information, particularly for providence and authorship data. This information is declared in the Metadata Section, and is often passed by-reference to other parts of the OSCAL Document. Each element can be clicked to get additional information. [``](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/xml-schema/#global_role) - Roles define some function or purpose that is to be assigned to some entity later in the document. Role elements have a `id` attribute with a [NCName](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#ncname) that is used to reference the role elsewhere in the OSCAL document. A number of pre-defined roles exist in OSCAL, but differ depending on context. In the Metadata Section they are as follows: - - prepared-by: Indicates the organization that created this content. - - prepared-for: Indicates the organization for which this content was created. - - content-approver: Indicates the organization responsible for all content represented in the "document". + +- prepared-by: Indicates the organization that created this content. +- prepared-for: Indicates the organization for which this content was created. +- content-approver: Indicates the organization responsible for all content represented in the "document". Other roles can be locally defined by the content creator. -[``](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/xml-schema/#global_location) - Geographic data defined by a street address. Locations have a `uuid` attribute that allow them to be referenced elsewhere in the OSCAL Document. Includes elements to describe a variety of data describing the location in question. +[``](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/xml-schema/#global_location) - Geographic data defined by a street address. Locations have a `@uuid` attribute that allow them to be referenced elsewhere in the OSCAL Document. Includes elements to describe a variety of data describing the location in question. -[``](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/xml-schema/#global_party) - Defines some entity, either a person or an organization. Has a `uuid` attribute that allows for references this party elsewhere in the OSCAL Document. Includes elements to describe a variety of data describing the party in question, including a location uuid. +[``](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/xml-schema/#global_party) - Defines some entity, either a person or an organization. Has a `@uuid` attribute that allows for references this party elsewhere in the OSCAL Document. Includes elements to describe a variety of data describing the party in question, including a location uuid. -[``](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/xml-schema/#global_party) - Explicitly declares a party that is responsible for this OSCAL document. The `role-id` attribute references the role that the party is fulfilling, and is either a custom role locally defined or one of the pore-defined roles; see the `` section above for details. Uses a Party's uuid to link the given role to the given party. +[``](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/xml-schema/#global_party) - Explicitly declares a party that is responsible for this OSCAL document. The `@role-id` attribute references the role that the party is fulfilling, and is either a custom role locally defined or one of the pore-defined roles; see the `` section above for details. Uses a Party's uuid to link the given role to the given party. `` - [Markup](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#markup-multiline) formatted plaintext with notes and remarks regarding the Metadata Section of this document. {{% /tab %}} - {{% tab %}} The remainder of this tutorial will briefly cover the other optional objects inside the Metadata Section. While not required by the specification, these objects provide invaluable information, particularly for providence and authorship data. This information is declared in the Metadata Section, and is often passed by-reference to other parts of the OSCAL Document. Each object can be clicked to get additional information. -[`"roles"`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_role) - An array of Role objects. Roles define some function or purpose that is to be assigned to some entity later in the document. Role objects have a `"id"` field with a [NCName](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#ncname) that is used to reference the role elsewhere in the OSCAL document. A number of pre-defined roles exist in OSCAL, but differ depending on context. In the Metadata Section they are as follows: - - prepared-by: Indicates the organization that created this content. - - prepared-for: Indicates the organization for which this content was created. - - content-approver: Indicates the organization responsible for all content represented in the "document". +[`roles`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_role) - An array of Role objects. Roles define some function or purpose that is to be assigned to some entity later in the document. Role objects have a `id` field with a [NCName](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#ncname) that is used to reference the role elsewhere in the OSCAL document. A number of pre-defined roles exist in OSCAL, but differ depending on context. In the Metadata Section they are as follows: + +- prepared-by: Indicates the organization that created this content. +- prepared-for: Indicates the organization for which this content was created. +- content-approver: Indicates the organization responsible for all content represented in the "document". Other roles can be locally defined by the content creator. -[`"locations"`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_location) - An array of Location objects. Geographic data defined by a street address. Locations have a `"uuid"` field that allow them to be referenced elsewhere in the OSCAL Document. Includes fields to describe a variety of data describing the location in question. +[`locations`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_location) - An array of Location objects. Geographic data defined by a street address. Locations have a `uuid` field that allow them to be referenced elsewhere in the OSCAL Document. Includes fields to describe a variety of data describing the location in question. -[`"parties"`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_party) - An array of Party objects. Defines some entity, either a person or an organization. Has a `"uuid"` field that allows for references this party elsewhere in the OSCAL Document. Includes fields to describe a variety of data describing the party in question, including a location uuid. +[`parties`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_party) - An array of Party objects. Defines some entity, either a person or an organization. Has a `uuid` field that allows for references this party elsewhere in the OSCAL Document. Includes fields to describe a variety of data describing the party in question, including a location uuid. -[`"responsible-parties"`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_party) - An array of Responsible-Party objects. Explicitly declares a party that is responsible for this OSCAL document. The `"role-id"` field references the role that the party is fulfilling, and is either a custom role locally defined or one of the pore-defined roles; see the `"roles"` section above for details. Uses a Party's uuid to link the given role to the given party. +[`responsible-parties`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_party) - An array of Responsible-Party objects. Explicitly declares a party that is responsible for this OSCAL document. The `role-id` field references the role that the party is fulfilling, and is either a custom role locally defined or one of the pore-defined roles; see the `roles` section above for details. Uses a Party's uuid to link the given role to the given party. -`"remarks"` - [Markup](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#markup-multiline) formatted plaintext with notes and remarks regarding the Metadata Section of this document. +`remarks` - [Markup](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#markup-multiline) formatted plaintext with notes and remarks regarding the Metadata Section of this document. {{% /tab %}} - {{% tab %}} The remainder of this tutorial will briefly cover the other optional objects inside the Metadata Section. While not required by the specification, these objects provide invaluable information, particularly for providence and authorship data. This information is declared in the Metadata Section, and is often passed by-reference to other parts of the OSCAL Document. Each object can be clicked to get additional information. -[`role`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_role) - Roles define some function or purpose that is to be assigned to some entity later in the document. Role objects have a `id` field with a [NCName](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#ncname) that is used to reference the role elsewhere in the OSCAL document. A number of pre-defined roles exist in OSCAL, but differ depending on context. In the Metadata Section they are as follows: - - prepared-by: Indicates the organization that created this content. - - prepared-for: Indicates the organization for which this content was created. - - content-approver: Indicates the organization responsible for all content represented in the "document". +[`roles`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_role) - Roles define some function or purpose that is to be assigned to some entity later in the document. Role objects have a `id` field with a [NCName](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#ncname) that is used to reference the role elsewhere in the OSCAL document. A number of pre-defined roles exist in OSCAL, but differ depending on context. In the Metadata Section they are as follows: + +- prepared-by: Indicates the organization that created this content. +- prepared-for: Indicates the organization for which this content was created. +- content-approver: Indicates the organization responsible for all content represented in the "document". Other roles can be locally defined by the content creator. -[`location`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_location) - Geographic data defined by a street address. Locations have a `uuid` field that allow them to be referenced elsewhere in the OSCAL Document. Includes fields to describe a variety of data describing the location in question. +[`locations`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_location) - Geographic data defined by a street address. Locations have a `uuid` field that allow them to be referenced elsewhere in the OSCAL Document. Includes fields to describe a variety of data describing the location in question. -[`party`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_party) - Defines some entity, either a person or an organization. Has a `uuid` field that allows for references this party elsewhere in the OSCAL Document. Includes fields to describe a variety of data describing the party in question, including a location uuid. +[`parties`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_party) - Defines some entity, either a person or an organization. Has a `uuid` field that allows for references this party elsewhere in the OSCAL Document. Includes fields to describe a variety of data describing the party in question, including a location uuid. -[`responsible-party`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_party) - Explicitly declares a party that is responsible for this OSCAL document. The `role-id` field references the role that the party is fulfilling, and is either a custom role locally defined or one of the pore-defined roles; see the `role` section above for details. Uses a Party's uuid to link the given role to the given party. +[`responsible-parties`](https://pages.nist.gov/OSCAL/documentation/schema/catalog-layer/catalog/json-schema/#global_party) - Explicitly declares a party that is responsible for this OSCAL document. The `role-id` field references the role that the party is fulfilling, and is either a custom role locally defined or one of the pore-defined roles; see the `role` section above for details. Uses a Party's uuid to link the given role to the given party. `remarks` - [Markup](https://pages.nist.gov/OSCAL/documentation/schema/datatypes/#markup-multiline) formatted plaintext with notes and remarks regarding the Metadata Section of this document. {{% /tab %}} +{{% /tabs %}} +## Putting It All Together -{{% /tabs %}} -## Putting it all together {{< tabs XML JSON YAML >}} {{% tab %}} {{< highlight xml "linenos=table" >}} - + Example OSCAL Document 2021-01-01T00:00:00-5:00 2021-01-01T00:00:00-5:00 - 1.0.0 + 1.0.0 1.0.0 10.1000/182 - + Example Company @@ -736,7 +703,7 @@ Other roles can be locally defined by the content creator. "role-id":"prepared-by", "party-uuid":"15d2e37c-0452-4695-9c6a-ddc1ff15397b" } - ] + ] } } } @@ -753,17 +720,17 @@ Other roles can be locally defined by the content creator. last-modified: 2021-01-01T00:00:00-5:00, version: 1.0.0, oscal-version: 1.0.0, - document-ids: + document-ids: - scheme: https://www.doi.org/, value: 10.1000/182 - props: + props: - name: marking, value: red, class: TLP - links: + links: - rel: latest-version, href: https://www.examplecompany.com/catalog/exampleoscalcatalog/latest - parties: + parties: - uuid: 15d2e37c-0452-4695-9c6a-ddc1ff15397b, type: organization, name: Example Company @@ -781,4 +748,4 @@ 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 \ No newline at end of file +- How to use optional fields to express additional metadata and extend the Metadata Section