From 6f775a4cb48296568b9d06078d8e45b5a0007331 Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Tue, 27 Sep 2022 09:19:59 -0400 Subject: [PATCH] Updates to OSCAL Metaschema documentation and constraints (#1263) * completed partial update of the Metadata object documentation. * adjustments to roles * adjusted the cardinality of location/address to make address optional. * Improved documentation and constraints related to location and parties * addressed the remainder of metadata and control feedback from @Rene2mt. * Improved the introductory remarks for a profile to better describe what a profile is and what it does. * Fixed a broken constraint that was not targeting the right node. * started refining descriptions and adding properties to describe identifier attributes. * Addressed feedback from AJ during 20220718-20220722. (#48) * Week 30 feedback on SSP model. (#49) * Proposed metaschema docs updates (#50) * Addressed feedback based on #1392 * Adjustments based on model review feedback on 8/12. * Removed outdated merge phase remarks. Created issue #53 to address this. * Addressed A.J. Stein's Week 32 Feedback for Model Review (#52) * Addressed AJ Stein's week 32 feedback for usnistgov/OSCAL#1331. * Addressed DRAFT: Update catalog & profile metaschema documentation (#51) * Update catalog & profile metaschema documentation * Add props to control identifier * Fixed broken syntax and addressed consistency in wording within the Profile 'merge' construct. * Adjustments to alter, moving to to an inline definition * cleaned up empty remark. * Removed redundant constraints * removed some redundant constraints * Preliminary work on URI documentation to address #1249. * More work on document URI use in OSCAL * Updating data types related to usnistgov/metaschema#224. * Improved consistency of how URI concepts are discussed. * Added note about party locations * Updated Metaschema instances of `uri` and `uri-reference` data types to indicate their URI semantics. Resolves #1249. * Added identifier props to control layer metaschemas (#55) * Responding to #1066: metaschema edits; CSS enhancement (#56) * Whitespace cleanup in metadata metaschema * Apply suggestions from code review Co-authored-by: Alexander Stein Co-authored-by: Wendell Piez Co-authored-by: Rene Tshiteya --- .../content/concepts/identifier-use/_index.md | 4 +- docs/content/concepts/uri-use.md | 171 ++++ .../learn/tutorials/general/extension.md | 84 +- docs/content/reference/datatypes.md | 8 +- src/metaschema/metaschema-author.css | 159 ++++ .../oscal_assessment-common_metaschema.xml | 44 +- .../oscal_assessment-results_metaschema.xml | 11 +- src/metaschema/oscal_catalog_metaschema.xml | 186 ++-- src/metaschema/oscal_component_metaschema.xml | 72 +- .../oscal_control-common_metaschema.xml | 116 +-- ...oscal_implementation-common_metaschema.xml | 15 +- .../oscal_mapping-common_metaschema.xml | 17 +- src/metaschema/oscal_metadata_metaschema.xml | 894 ++++++++++-------- src/metaschema/oscal_profile_metaschema.xml | 158 ++-- src/metaschema/oscal_ssp_metaschema.xml | 30 +- 15 files changed, 1311 insertions(+), 658 deletions(-) create mode 100644 docs/content/concepts/uri-use.md create mode 100644 src/metaschema/metaschema-author.css diff --git a/docs/content/concepts/identifier-use/_index.md b/docs/content/concepts/identifier-use/_index.md index 629eee5d43..4715209814 100644 --- a/docs/content/concepts/identifier-use/_index.md +++ b/docs/content/concepts/identifier-use/_index.md @@ -20,7 +20,7 @@ By design, OSCAL supports [*machine-oriented*](#machine-oriented) and [*human-or [*Machine-oriented*](#machine-oriented) identifiers provide a persistent identity for an entity within the OSCAL models, which can be used in other locations within related OSCAL models to reference the associated entity. -These identifiers are intended to be auto-generated by tools when the entity is initially created. In OSCAL, a machine-oriented identifier is implemented using a Universally Unique Identifier (UUID) as defined by [RFC 4122](https://tools.ietf.org/html/rfc4122). A UUID is represented in OSCAL using the [UUID datatype](/reference/datatypes/#uuid). +These identifiers are intended to be auto-generated by tools when the entity is initially created. In OSCAL, a machine-oriented identifier is implemented using a Universally Unique Identifier (UUID) as defined by [RFC 4122](https://tools.ietf.org/html/rfc4122). A UUID is represented in OSCAL using the [`uuid`](/reference/datatypes/#uuid) data type. UUIDs were chosen because: - Programming interfaces exist in most programming environments to generate a UUID - UUIDs can be issued without a central authority @@ -32,7 +32,7 @@ The [OSCAL XML Reference Index](/reference/latest/complete/xml-index/#/@uuid) an #### Human-Oriented -A [*human-oriented*](#human-oriented) identifier incorporates semantic that support readability and processing by humans. OSCAL implements [*human-oriented*](#human-oriented) identifiers as [token](/reference/datatypes/#token) data types, which are non-colonized names. For example, control identifiers in a catalog may use a nomenclature that is familiar to the intended audience, allowing them to quickly determine what security control is being referred to, simply by its identifier value. +A [*human-oriented*](#human-oriented) identifier supports readability and use by human consumers. OSCAL implements [*human-oriented*](#human-oriented) identifiers as [`token`](/reference/datatypes/#token) data types. For example, control identifiers in a catalog may use a nomenclature that is familiar to the intended audience, allowing them to quickly determine what security control is being referred to, simply by its identifier value. The [OSCAL XML Reference Index](/reference/latest/complete/xml-index/#/@id) and [OSCAL JSON Reference Index](/reference/latest/complete/json-index/#/id) provide a comprehensive listing of the [*human-oriented*](#human-oriented) IDs in the core OSCAL models. References to these IDs are typically named according to the referenced object type (e.g., control) followed by “-id”, as seen here in the [XML Reference Index](/reference/latest/complete/xml-index/#/@control-id) (and likewise [JSON Reference Index](/reference/latest/complete/json-index/#/control-id) in the JSON reference index). diff --git a/docs/content/concepts/uri-use.md b/docs/content/concepts/uri-use.md new file mode 100644 index 0000000000..35c45f06ab --- /dev/null +++ b/docs/content/concepts/uri-use.md @@ -0,0 +1,171 @@ +--- +title: URI Usage +description: Provides information on the use of URIs in OSCAL. +weight: 40 +--- + +According to [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) a Uniform Resource Identifier (URI) "is a compact sequence of characters that identifies an abstract or physical resource." URIs are an important concept, which are used extensively in OSCAL. + +## Uniform Resource Identifier Overview + +According to RFC 3986, a URI has the following syntax, which is represented in [Augmented Backus-Naur Form (ABNF)](https://www.rfc-editor.org/rfc/rfc5234.html) below. + +> ``` +> URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] +> hier-part = "//" authority path-abempty +> / path-absolute +> / path-rootless +> / path-empty +> ``` +> +> The scheme and path components are required, though the path may be empty (no characters). When authority is present, the path must either be empty or begin with a slash ("/") character. When authority is not present, the path cannot begin with two slash characters ("//"). These restrictions result in five different ABNF rules for a path ([Section 3.3](https://www.rfc-editor.org/rfc/rfc3986#section-3.3)), only one of which will match any given URI reference. +> +> The following are two example URIs and their component parts: +> +> ``` +> foo://example.com:8042/over/there?name=ferret#nose +> \_/ \______________/\_________/ \_________/ \__/ +> | | | | | +> scheme authority path query fragment +> | _____________________|__ +> / \ / \ +> urn:example:animal:ferret:nose +> ``` + +According to RFC 3986, a URI can be used in a few different ways. Recognizing these URI forms is important in understanding how URIs are used in OSCAL. + +### URI with a Required Scheme + +As indicated above with the required scheme and path components. + +### Relative Reference + +A URI that is a relative reference, references a resource relative to another *[base URI](https://www.rfc-editor.org/rfc/rfc3986#section-5.1)*. Such a URI is resolved using [reference resolution](https://www.rfc-editor.org/rfc/rfc3986#section-5). + +The [syntax of a relative reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.2) is: + +> ``` +> relative-ref = relative-part [ "?" query ] [ "#" fragment ] +> +> relative-part = "//" authority path-abempty +> / path-absolute +> / path-noscheme +> / path-empty +> ``` + +### URI Reference + +A typical use of a URI, allowing a [URI with a required scheme](#uri-with-a-required-scheme) or a [relative reference](#relative-reference) to be used. + +The [syntax of a URI reference](https://www.rfc-editor.org/rfc/rfc3986#section-4.1) is: + +> URI-reference = URI / relative-ref + +### Absolute URI + +According to RFC 3986, the [syntax of an absolute URI](https://www.rfc-editor.org/rfc/rfc3986#section-4.3) is: + +> ``` +> absolute-URI = scheme ":" hier-part [ "?" query ] +> ``` + +## URI vs URL vs URN + +According to RFC 3986 section [1.1.3](https://www.rfc-editor.org/rfc/rfc3986#section-1.1.3), "a URI can be further classified as a *locator*, a *name*, or *both*." A given URI scheme is not limited to being only a name or a locator; both characteristics can be associated. + +- To be a *locator*, the resource pointed to by a URI needs to have persistence. + +- To be a *name*, the URI needs to be used consistently to refer to the thing that is named. A URI used only as a name is not required to resolve to a location. URIs schemes requiring an [*authority*](https://www.rfc-editor.org/rfc/rfc3986#section-3.2) element provide a means to use a registered DNS name to assert organizational control over a naming value space or namespace. + +A *Uniform Resource Locator (URL)* "refers to the subset of URIs that, in addition to identifying a resource, provide a means of locating the resource by describing its primary access mechanism (e.g., its network "location")." + +A URL, when applied consistently, can be used as a *name*. Optionally in such cases, the resource it resolves to can provide information about how to use the URL as a name. + +A *Uniform Resource Name (URN)* "has been used historically to refer to both URIs under the `urn` scheme [RFC2141](https://www.rfc-editor.org/rfc/rfc2141), which are required to remain globally unique and persistent even when the resource ceases to exist or becomes unavailable, and to any other URI with the properties of a name. + +A URN is often not a good fit for use as a *locator*, since it requires a secondary resolution process that maps the URN's *name* to a specific *location*. + +Due to the specific characteristics of a URL or URN, the term URI is often used to refer more broadly to all types of resource identifiers. + +## URIs in OSCAL + +The following sections discuss how URIs are used in OSCAL. + +### OSCAL URI Data Types + +OSCAL uses two data types for representing URIs. + +1. [`uri`](/reference/datatypes/#uri) - A URI which must provide the required scheme and path components. This means the URI will point directly to a resolvable resource. + + The `uri` data type is used in cases where a [*URI with a required scheme*](#uri-with-a-required-scheme) or an *absolute URI* is required. As a result, a [*relative reference*](#relative-reference) or a [*URI reference*](#uri-reference) is not allowed for use with this data type. + +2. [`uri-reference`](/reference/datatypes/#uri-reference) - A [*URI reference*](#uri-reference), which may be a [*URI with a required scheme*](#uri-with-a-required-scheme) or a [*relative reference*](#relative-reference). This allows all forms of URIs. + +### Common OSCAL URI Use Cases + +URIs are used in OSCAL to provide pointers to resources in the following ways. + +#### Linking to a network resolvable resource + +URIs are used to point directly to a network resolvable resource. + +In such cases, the URI may be: + +- A [*URI with a required scheme*](#uri-with-a-required-scheme), where the scheme will likely be `https` indicating the resource can be accessed using the [Hypertext Transfer Protocol](https://www.rfc-editor.org/rfc/rfc2616.html) (HTTP) using [Transport Layer Security](https://www.rfc-editor.org/rfc/rfc8446) (TLS). Data fields supporting only this use case will have the `uri` data type. + + OSCAL examples include: + + - `threat-id` - ([JSON/YAML](/reference/latest/complete/json-index/#/threat-id)) ([XML](/reference/latest/complete/xml-index/#/@threat-id)) + - `url` - ([JSON/YAML](/reference/latest/complete/json-index/#/url)) ([XML](/reference/latest/complete/xml-index/#/urls)) + +- A [*relative reference*](#relative-reference), pointing to a resource that can resolved using the current document resource as the *base URI*. Data fields supporting this use case will have the `uri-reference` data type. + + OSCAL examples include: + + - `href` - ([JSON/YAML](/reference/latest/complete/json-index/#/href)) ([XML](/reference/latest/complete/xml-index/#/@href)) + - `source` - ([JSON/YAML](/reference/latest/complete/json-index/#/source)) ([XML](/reference/latest/complete/xml-index/#/@source)) + - `filename` - ([JSON/YAML](/reference/latest/complete/json-index/#/filename)) ([XML](/reference/latest/complete/xml-index/#/@filename)) + +URIs serving this purpose need to be used as a *locator*. URLs are typically used for this purpose since the URI must resolve to a specific location. + +#### Linking to another OSCAL object + +A pointer to an OSCAL object identified by the referenced identifier, may be a [human-oriented](/concepts/identifier-use/#human-oriented) [`token`](/reference/datatypes/#token) or a [machine-oriented](/concepts/identifier-use/#machine-oriented) [`uuid`](https://pages.nist.gov/OSCAL/reference/datatypes/#uuid). + +This approach uses a [*relative reference*](#relative-reference) consisting of only a URI *fragment* containing the identifier or UUID of the referenced object within the current documents effective data model. The effective data model of a document includes all objects identified with the document and any directly or transitively imported documents. Identifiers with a *cross-instance* [scope](/concepts/identifier-use/#scope) are available to importing documents. + +URIs serving this purpose need to be used as a *locator*. + +Any data fields supporting this use case will have the `uri-reference` data type. + +A typical use of OSCAL object identifier linking is referencing a `resource` in the document's `back-matter` or an imported document's `back-matter`. For example, the back-matter resource identified by the UUID `f5a2bdb3-55ad-431e-a7ea-c0fd28fc08a0` can be referenced as follows. + +``` + +``` + +More information about the use of links to reference back-matter resources can be found in the [*Referencing Back-Matter Resources*](/learn/tutorials/general/extension/#referencing-back-matter-resources) section of the [*Extending OSCAL Models with Props and Links*](/learn/tutorials/general/extension/) tutorial. + +#### Use as a naming system identifier + +An absolute URI that identifies the naming system. URIs serving this purpose are used as a *name*. Data fields supporting this use case will have the `uri` data type. + +OSCAL supports a number of name/value and other controlled value collections. To allow independent organization to organize these value collections, namespaces are used to partition the value spaces on an organization-by-organization basis. An [*absolute URI*](#absolute-uri) is used as the namespace identifier for these situations. + +When used in this way, the authority component of the URI must use a value that the organization has control over. Typically, a DNS domain name controlled by the organization is used for this purpose. + +OSCAL examples include: + +- `ns` - ([JSON/YAML](/reference/latest/complete/json-index/#/ns)) ([XML](/reference/latest/complete/xml-index/#/@ns)) +- `system` - ([JSON/YAML](/reference/latest/complete/json-index/#/system)) ([XML](/reference/latest/complete/xml-index/#/@system)) +- `scheme` - ([JSON/YAML](/reference/latest/complete/json-index/#/scheme)) ([XML](/reference/latest/complete/xml-index/#/@scheme)) + +A key example of this approach is how property names are partitioned using a `ns` data element. + +For example, the namespace `http://example.com/ns/oscal` is used in an OSCAL property as follows. + +``` + +``` + +To learn more about the use of namespaces in properties, refer to the [*Extending Existing Prop Values*](/learn/tutorials/general/extension/#extending-existing-prop-values) section of the [*Extending OSCAL Models with Props and Links*](/learn/tutorials/general/extension/) tutorial. diff --git a/docs/content/learn/tutorials/general/extension.md b/docs/content/learn/tutorials/general/extension.md index 94485c1905..877f1c7b97 100644 --- a/docs/content/learn/tutorials/general/extension.md +++ b/docs/content/learn/tutorials/general/extension.md @@ -15,6 +15,7 @@ This tutorial describes the mechanisms for extending basic OSCAL models. Before - Have some familiarity with the [XML](https://www.w3.org/standards/xml/core), [JSON](https://www.json.org/), or [YAML](https://yaml.org/spec/) formats. - Review the [OSCAL Layers and Models](/concepts/layer/) documentation. - Review the latest [OSCAL Reference](/reference/latest/complete/). +- Review [URI Usage](/concepts/uri-use/) to better understand how URIs are used in OSCAL. ## What are the OSCAL Extension Mechanisms? @@ -483,8 +484,8 @@ Links in OSCAL provide a means to reference an arbitrary resource, which allows A link can: -1. Reference (external) information that is not represented in OSCAL format. This could include references to (cybersecurity) laws and regulations, references to organizational standards and guides, references to a software bill of materials (SBOM), and more. -2. Reference objects within the current OSCAL document. +1. Reference (external) information that is not represented in OSCAL format. This could include references to (cybersecurity) laws and regulations, references to organizational standards and guides, references to a software bill of materials (SBOM), and more. See [*linking to a network resolvable resource*](/concepts/uri-use/#linking-to-a-network-resolvable-resource) for more information. +2. Reference objects within the current OSCAL document. See [*linking to another OSCAL object*](/concepts/uri-use/#linking-to-another-oscal-object) for more information. Organizations can limit duplication of content, reduce the size of their OSCAL files, and maintain important content relationships by using links. @@ -548,7 +549,7 @@ Below is description of `links` key-values: ### Link to Internet URL -Organizations may need their documentation (e.g., SSP) to reference external resources, such applicable laws and regulations (e.g., HSPD-12) and other organizational items (e.g., official agency logos). This first example illustrates how an OSCAL SSP might make use of a link to an internet URL to reference a government policy and an agency logo. +Organizations may need their documentation (e.g., SSP) to reference external resources, such applicable laws and regulations (e.g., HSPD-12) and other organizational items (e.g., official agency logos). This first example illustrates how an OSCAL SSP might make use of a link to a resource through the use of an [absolute](/concepts/uri-use/#absolute-uri) or [relative](/concepts/uri-use/#relative-reference) URL to reference a government policy and an agency logo. {{< tabs XML JSON YAML >}} {{% tab %}} @@ -574,9 +575,9 @@ Organizations may need their documentation (e.g., SSP) to reference external res {{< /highlight >}} -In this case, the `` element on line 8 provides a reference to Homeland Security Policy Directive (HSPD) 12 by specifying the URL in the `@href` attribute. The OSCAL pre-defined "reference" value is used for the `@rel` attribute, providing some context for the purpose of this specific ``. The `` sub-element provides an associated label for the `` which may be useful when rendering the SSP in other formats (e.g., HTML, PDF). +In this case, the `` element on line 8 provides a reference to Homeland Security Policy Directive (HSPD) 12 by specifying the URL in the `@href` attribute. The `@rel` attribute uses the OSCAL pre-defined "reference" value, indicating that this specific `` is a "reference" link. The `` sub-element provides an associated label for the `` which may be useful when rendering the SSP in other formats (e.g., HTML, PDF). -Line 11 demonstrates the use of `` to point to the organization's official logo. An absolute URL was used to point to the location of the referenced content, however, it should be noted that the `@href` attribute also permits the use of relative URL paths. If the referenced resource is located on the same host, then a relative URL path could be used. The `@rel` attribute was set to "logo" to indicate that the `` is to a logo image. The `@media-type` attribute was included to let any rendering tools know that the logo content is a Portable Network Graphics (PNG) image type. The optional `` sub-element was excluded for brevity of this example. +Line 11 demonstrates the use of `` to point to the organization's official logo. An absolute URL was used to point to the location of the referenced content, however, it should be noted that the `@href` attribute also permits the use of relative URL paths. If the referenced resource is located on the same host, then a relative URL path could be used instead. The `@rel` attribute is set to "logo" to indicate that the `` is to a logo image. The `@media-type` attribute was included to let any rendering tools know that the logo content is a Portable Network Graphics (PNG) image type. The optional `` sub-element is excluded in this example for brevity. {{% /tab %}} {{% tab %}} {{< highlight json "linenos=table" >}} @@ -608,9 +609,9 @@ Line 11 demonstrates the use of `` to point to the organization's official } {{< /highlight >}} -In this case, the `links` object array on line 9 provides a reference to Homeland Security Policy Directive (HSPD) 12 by specifying the URL in the `href` property. The OSCAL pre-defined "reference" value is used for the `rel`, providing context for the purpose of this specific `link`. The `text` property provides an associated label for the `link` which may be useful when rendering the SSP in other formats (e.g., HTML, PDF). +In this case, the `links` object array on line 9 provides an object (one lines 10-14) that references Homeland Security Policy Directive (HSPD) 12 by specifying the URL in its `href` property. The `rel` property uses the OSCAL pre-defined "reference" value, indicating that this specific link object is a "reference" link. The `text` property provides an associated label for the `link` which may be useful when rendering the SSP in other formats (e.g., HTML, PDF). -Lines 16-18 demonstrate the use of link to point to the organization's official logo. An absolute URL was used to point to the location of the referenced content, however, it should be noted that the `href` property also permits the use of relative URL paths. If the referenced resource is located is on the same host, then a relative URL path could be used. The `rel` property was set to "logo" to indicate the link is to a logo image. The `media-type` property was included to let any rendering tools know that the logo content is a Portable Network Graphics (PNG) image type. The optional `text` property was excluded for brevity of this example. +Lines 16-189 demonstrate the use of a link to point to the organization's official logo. An absolute URL is used to point to the location of the referenced content, however, it should be noted that the `href` property also permits the use of relative URL paths. If the referenced resource is located is on the same host, then a relative URL path could be used instead. The `rel` property is set to "logo" to indicate the link is to a logo image. The `media-type` property was included to let any rendering tools know that the logo content is a Portable Network Graphics (PNG) image type. The optional `text` property is excluded in this example for brevity. {{% /tab %}} {{% tab %}} {{< highlight yaml "linenos=table" >}} @@ -624,7 +625,7 @@ system-security-plan: links: - href: https://www.dhs.gov/homeland-security-presidential-directive-12 rel: reference - text: HSPD-12 + text: HSPD-12 - href: https://federal-agency.gov/img/official-agency-logo.png rel: logo media-type: image/png @@ -634,9 +635,9 @@ system-security-plan: {{< /highlight >}} -In this case, the `links` object array on line 9 provides a reference to Homeland Security Policy Directive (HSPD) 12 by specifying the URL in the `href` property. The OSCAL pre-defined "reference" value is used for the `rel`, providing context for the purpose of this specific link. The `text` property provides an associated label for the link which may be useful when rendering the SSP in other formats (e.g., HTML, PDF). +In this case, the `links` list on line 8 provides a reference to Homeland Security Policy Directive (HSPD) 12 by specifying the URL in the `href` key. The `rel` key uses the OSCAL pre-defined "reference" value, indicating that this specific link item is a "reference" link. The `text` key provides an associated label for the link which may be useful when rendering the SSP in other formats (e.g., HTML, PDF). -Lines 11-13 demonstrate the use of link to point to the organization's official logo. An absolute URL was used to point to the location of the referenced content, however, it should be noted that the `href` property also permits the use of relative URL paths. If the referenced resource is located is on the same host, then a relative URL path could be used. The `rel` property was set to "logo" to indicate the link is to a logo image. The `media-type` property was included to let any rendering tools know that the logo content is a Portable Network Graphics (PNG) image type. The optional `text` property was excluded for brevity of this example. +Lines 12-14 demonstrate the use of a link to point to the organization's official logo. An absolute URL is used to point to the location of the referenced content, however, it should be noted that the `href` key also permits the use of relative URL paths. If the referenced resource is located is on the same host, then a relative URL path could be used. The `rel` key is set to "logo" to indicate the link is to a logo image. The `media-type` key is included to let any rendering tools know that the logo content is a Portable Network Graphics (PNG) image type. The optional `text` key was excluded for brevity of this example. {{% /tab %}} {{% /tabs %}} @@ -646,7 +647,7 @@ As a final note, providing link text is not required. Link text should only be p This section demonstrates how to reference back matter resources with links. -In OSCAL specifying a URI fragment in a link's hypertext reference, represented as `#fragment-id`, indicates that the link is referencing an identified object in the OSCAL document's data model. This allows a resource to be referenced in the OSCAL document's back matter using the UUID of the back matter resource. +In OSCAL specifying a bare URI fragment in a link's hypertext reference, represented as `#fragment-id`, indicates that the link is [referencing an object identified](/concepts/uri-use/#linking-to-another-oscal-object) in the context of the OSCAL document's data model. This allows a resource to be referenced in the back matter or the current OSCAL document or an imported document using the UUID of a `back-matter` resource. {{< tabs XML JSON YAML >}} {{% tab %}} @@ -674,16 +675,18 @@ In OSCAL specifying a URI fragment in a link's hypertext reference, represented href="https://csrc.nist.gov/csrc/media/publications/fips/199/final/documents/fips-pub-199-final.pdf" media-type="application/pdf" /> {{< /highlight >}} -When using `` to reference a back-matter ``, the `` must use the resource's `@uuid` attribute as the pointer. The `` property may have an `` sub-element that points to the (external) content via the `@href` attribute. Optionally, the `` element can also include a hash (e.g., to ensure the integrity of the referenced content), however, that is an advanced concept that is not covered in this tutorial. +When using `` to reference a back-matter ``, the `` must use the resource's `@uuid` attribute as the pointer. The `` may have an `` sub-element that points to the (external) content via the `@href` attribute. -Notice that in this example, the `` element on line 8 provides a fragment rather than a URL. OSCAL interprets this as a pointer to a back matter resource `@uuid` (see line 17). Within this `` element, several items are referenced (via ``). The `` must have a URL reference (`@href`). The third `` in this example provides a relative path. All of the other `` attributes (e.g., `@media-type` and `@hash`) are optional. Unlike ``, `` do not have any `@rel` attributes to provide additional context, nor do they have `` sub-elements. OSCAL content authors should consider these subtle differences when deciding whether to use `` or ``. +Optionally, the `` element can also include a hash (e.g., to ensure the integrity of the referenced content), however, that is an advanced concept that is not covered in this tutorial. + +Notice that in this example, the `` element on line 8 provides a fragment rather than a more complete URI. OSCAL interprets this as a pointer to a back matter resource `@uuid` (see line 17). Within this `` element, several items are referenced (via ``). An ``must have an `@href` with an [absolute URI](/concepts/uri-use/#absolute-uri) or a [relative URI](/concepts/uri-use/#relative-reference) pointing directly to the resource. 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 to use a `` or an ``. {{% /tab %}} {{% tab %}} {{< highlight json "linenos=table" >}} @@ -695,11 +698,13 @@ Notice that in this example, the `` element on line 8 provides a fragment "last-modified": "2022-01-01T09:30:00-005", "version": 20220531, "oscal-version": "1.0.0", - "links": { - "href": "#a7584118-3d2d-46c8-b388-df747309c0fa", - "rel": "reference", - "text": "Applicable Laws and Regulations, Standards, and Guides" - } + "links": [ + { + "href": "#a7584118-3d2d-46c8-b388-df747309c0fa", + "rel": "reference", + "text": "Applicable Laws and Regulations, Standards, and Guides" + } + ] }, "import-profile": "...", "system-characteristics": "...", @@ -717,7 +722,7 @@ Notice that in this example, the `` element on line 8 provides a fragment "media-type": "application/pdf" }, { - "href": "/security/standards/IT-Rules-of-Behavior.docx", + "href": "security/standards/IT-Rules-of-Behavior.docx", "media-type": "application/msword" }] } @@ -725,9 +730,13 @@ Notice that in this example, the `` element on line 8 provides a fragment } } {{< /highlight >}} -When using `links` to reference a back-matter `resources`, the `link` must use the resource's `uuid` property as the pointer. The `resource` property may have an `rlinks` object array that points to the (external) content via the `href` property. Optionally, the `rlinks` property can also include a hash (e.g., to ensure the integrity of the referenced content), however, that is an advanced concept that is not covered in this tutorial. +When using a `links` array object (see lines 10-14 above) to reference a back-matter resource object (see lines 22-36), the link object must use the resource object's `uuid` property in a URI fragment as the pointer (i.e. `#a7584118-3d2d-46c8-b388-df747309c0fa`). Notice that in this example, the link object on line 11 provides a fragment rather than a more complete URI. OSCAL interprets this as a pointer to a back matter resource `uuid` (see line 23). + +The referenced resource object on lines 22-36 may have an `rlinks` object array with objects that point to the (externally) available content via an `href` property. In this example, several resources are referenced (via `rlinks`). Each rlink object must have an `href` with an [absolute URI](/concepts/uri-use/#absolute-uri) or a [relative URI](/concepts/uri-use/#relative-reference) pointing directly to the resource. The third `rlink` in this example provides a relative path. -Notice that in this example, the `links` object array on line 9 provides a fragment rather than a URL. OSCAL interprets this as a pointer to a back matter resource `uuid` (see line 21). Within `resources`, several items are referenced (via `rlinks`). Each `rlink` must have a URL reference (`href`). The third `rlink` in this example provides a relative path. All of the other `rlink` properties (e.g., `media-type` and `hash`) are optional. Unlike `links`, `rlinks` do not have any `rel` properties to provide additional context, nor do they have `text` properties. OSCAL content authors should consider these subtle differences when deciding whether to use `links` or `rlinks`. +All of the other `rlink` properties (e.g., `media-type` and `hash`) are optional. An rlink object can also include a hash (e.g., to ensure the integrity of the referenced content), however, that is an advanced concept that is not covered in this tutorial. + +Unlike `links`, `rlinks` do not have a `rel` property to provide additional context, nor do they have `text` properties. OSCAL content authors should consider these subtle differences when deciding to use `links` or `rlinks`. {{% /tab %}} {{% tab %}} @@ -740,25 +749,34 @@ system-security-plan: version: 20220531 oscal-version: 1.0.0 links: - - href: '#a7584118-3d2d-46c8-b388-df747309c0fa' - rel: reference - text: Applicable Laws and Regulations, Standards, and Guides + - 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 + - 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 + - href: https://www.dhs.gov/homeland-security-presidential-directive-12 + - href: https://csrc.nist.gov/csrc/media/publications/fips/199/final/documents/fips-pub-199-final.pdf + media-type: application/pdf + - href: security/standards/IT-Rules-of-Behavior.docx + media-type: application/msword {{< /highlight >}} -When using `links` to reference back-matter `resources`, the `link` must use the resource's `uuid` key-value as the pointer. The `resource` key-value must have an `rlinks` array item that points to the (external) content via the `href` key-value. Optionally, the `rlinks` can also include a hash (e.g., to ensure the integrity of the referenced content), however, that is an advanced concept that is not covered in this tutorial. -Notice that in this example, the `links` object array on line 8 only provides a fragment rather than a URL. OSCAL interprets this as a pointer to a back matter resource `uuid` (see line 17). Within `resources`, several items are referenced (via `rlinks`). Each `rlink` must have a URL reference (`href`). The third `rlink` in this example provides a relative path. All of the other `rlink` properties (e.g., `media-type` and `hash`) are optional. Unlike `links`, `rlinks` do not have any `rel` properties to provide additional context, nor do they have `text` properties. OSCAL content authors should consider these subtle differences when deciding whether to use `links` or `rlinks`. +All of the other `rlink` properties (e.g., `media-type` and `hash`) are optional. An rlink object can also include a hash (e.g., to ensure the integrity of the referenced content), however, that is an advanced concept that is not covered in this tutorial. + +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 to use `links` or `rlinks`. + +When using a `links` item list (see lines 8-12 above) to reference a back-matter resource item (see lines 16-23), the link item must use the resource object's `uuid` key in a URI fragment as the pointer (i.e. `#a7584118-3d2d-46c8-b388-df747309c0fa`). Notice that in this example, the link item on line 9 provides a fragment rather than a more complete URI. OSCAL interprets this as a pointer to a back matter resource `uuid` (see line 23). + +The referenced resource item on lines 17-23 may have an `rlinks` list with items that point to the (externally) available content via an `href` key. In this example, several resources are referenced (via `rlinks`). Each rlink item must have an `href` with an [absolute URI](/concepts/uri-use/#absolute-uri) or a [relative URI](/concepts/uri-use/#relative-reference) pointing directly to the resource. The third rlink item in this example provides a relative path. + +All of the other rlink item keys (e.g., `media-type` and `hash`) are optional. An rlink item can also include a hash (e.g., to ensure the integrity of the referenced content), however, that is an advanced concept that is not covered in this tutorial. + +Unlike `links`, `rlinks` items do not have a `rel` key to provide additional context, nor do they have a `text` key. OSCAL content authors should consider these subtle differences when deciding to use `links` or `rlinks`. {{% /tab %}} {{% /tabs %}} diff --git a/docs/content/reference/datatypes.md b/docs/content/reference/datatypes.md index a55314a6a6..598a7aeedc 100644 --- a/docs/content/reference/datatypes.md +++ b/docs/content/reference/datatypes.md @@ -273,7 +273,7 @@ In XML Schema this is represented as a restriction on the built-in type [dateTim @@ -284,7 +284,7 @@ In JSON Schema, this is represented as: ```JSON { "type": "string", - "pattern": "^(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})?$" + "pattern": "^(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]*[1-9])?(Z|(-((0[0-9]|1[0-2]):00|0[39]:30)|\\+((0[0-9]|1[0-4]):00|(0[34569]|10):30|(0[58]|12):45)))?$" } ``` @@ -306,7 +306,7 @@ In XML Schema this is represented as a restriction on the built in type [dateTim @@ -318,7 +318,7 @@ In JSON Schema, this is represented as: { "type": "string", "format": "date-time", - "pattern": "^(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})$" + "pattern": "^(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]*[1-9])?(Z|(-((0[0-9]|1[0-2]):00|0[39]:30)|\\+((0[0-9]|1[0-4]):00|(0[34569]|10):30|(0[58]|12):45)))$" } ``` diff --git a/src/metaschema/metaschema-author.css b/src/metaschema/metaschema-author.css new file mode 100644 index 0000000000..064a793e46 --- /dev/null +++ b/src/metaschema/metaschema-author.css @@ -0,0 +1,159 @@ +METASCHEMA { font-family: Calibri, Verdana, sans-serif } + +* { display: block } + +pre { color: darkgrey } + +tag { color: black; font-family: monospace; font-size: 80%; font-weight: bold } + +METASCHEMA { } + +title { } + +import:before + { content: 'import module ' oxy_urlChooser(edit, '@href', columns 60) } + + + +define-assembly, +define-field, +define-flag { margin-top: 1ex; margin-bottom: 1ex; border: thin inset black; padding: 0.5em } + + +define-assembly:before, +define-field:before, +define-flag:before + { content: + oxy_name() + oxy_textfield(edit, '@name', columns, 12) + } + +root-name:before { content: "Root name: " } + + +prop:before + { content: 'property ' + oxy_textfield(edit, '@name', columns, 25) + oxy_textfield(edit, '@value', columns, 30) + } + + +define-assembly[group-as]:before, +define-field[group-as]:before, +define-flag[group-as]:before + { content: + oxy_name() + oxy_textfield(edit, '@name', columns, 12) } +define-assembly *, +define-field *, +define-flag * { margin: 0em } + +define-assembly > * { margin-top: 1em } + +pre { padding: 0.5em; background-color: gainsboro } + +define-assembly { } + +define-field { } + +define-flag { } + +flag { } + +formal-name { font-size: 120%; font-weight: bold; margin: 0.5em 0em } + +description, remarks { max-width: 60em } + +remarks { border-left: thin solid black; padding-left: 1em; margin-left: 1em } +remarks p { margin-top: 1em } + + +example { } + +prose { } + + +p { } + +code { display: inline; font-family: monospace } +q { display: inline; background-color: lemonchiffon } +em, i { display: inline; font-style: italic } +strong, b { display: inline; font-weight: bold } + +example { background-color: lavender; white-space: pre; } + +example *:before { content: '<' oxy_name() '>'; font-family: monospace; font-size: 80% } +example *:after { content: ''; font-family: monospace; font-size: 80% } + +model { padding-left: 0.5em; border-left: medium solid blue; font-size: 80%; padding-right: 2em } + +model model { font-size: 100%; } + +flag:before { content: + oxy_name() + ' ref: ' oxy_textfield(edit, '@ref', columns, 12) + } + +assembly:before, field:before { + content: + oxy_name() ' named ' + oxy_textfield(edit, '@ref', columns, 12) } + +group-as { margin-left: 2em } + +group-as:before { content: 'group as ' + oxy_textfield(edit, '@name', columns, 12) } + + +choice:before { content: + 'a choice between' + } + +prose:before { font-weight: bold; content: + 'prose' + } + +choice > * { margin-left: 2em } + +a { display: inline; color: blue } +a:before { content: oxy_urlChooser( + edit, "@href", + columns 42); } + + +/* CONSTRAINTS */ + +constraint > * { border: thin solid black; padding: 0.6em } + +allowed-values:before { content: "Allowed values" + ' level: ' oxy_combobox(edit, '@level', editable, false, values, "ERROR, WARNING" ) } + +enum { margin-left: 2em; display: list-item; + font-size: 90%; padding-left: 1em } +enum:before { content: oxy_textfield(edit, '@value', columns, 24); } + +index { } +index:before { content: "Index: " + ' name: ' oxy_textfield(edit, '@name', columns, 24) + ' target: ' oxy_textfield(edit, '@target', columns, 52) + ' level: ' oxy_combobox(edit, '@level', editable, false, values, "ERROR, WARNING" ); } + +key-field { margin-left: 2em } +key-field:before { content: "Key field " + ' target: ' oxy_textfield(edit, '@target', columns, 52) + ' level: ' oxy_combobox(edit, '@level', editable, false, values, "ERROR, WARNING" ); } + +expect { } +expect:before { content: "Expect " + ' target: ' oxy_textfield(edit, '@target', columns, 52) + ' test: ' oxy_textfield(edit, '@test', columns, 36) + ' level: ' oxy_combobox(edit, '@level', editable, false, values, "ERROR, WARNING" ); } + +index-has-key { } + +index-has-key:before { content: "Index has key: " + ' name: ' oxy_textfield(edit, '@name', columns, 24) + ' target: ' oxy_textfield(edit, '@target', columns, 52) + ' level: ' oxy_combobox(edit, '@level', editable, false, values, "ERROR, WARNING" ); } + + diff --git a/src/metaschema/oscal_assessment-common_metaschema.xml b/src/metaschema/oscal_assessment-common_metaschema.xml index bda02df397..ef7d702212 100644 --- a/src/metaschema/oscal_assessment-common_metaschema.xml +++ b/src/metaschema/oscal_assessment-common_metaschema.xml @@ -19,13 +19,16 @@ Import System Security Plan Used by the assessment plan and POA&M to import information about the system. - + System Security Plan Reference A resolvable URL reference to the system security plan for the system being assessed. -

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

-

If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

-

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

+

This value may be one of:

+
    +
  1. an absolute URI that points to a network resolvable resource,
    2. +
  2. a relative reference pointing to a network resolvable resource whose base URI is the URI of the containing document, or
    3. +
  3. a bare URI fragment (i.e., `#uuid`) pointing to a back-matter resource in this or an imported document (see linking to another OSCAL object).
    4. +
@@ -59,7 +62,7 @@ - + **(deprecated)** Use 'assessment-objective' instead. **(deprecated)** Use 'assessment-method' instead. The part defines an assessment objective. @@ -853,13 +856,16 @@ Relevant Evidence Links this observation to relevant evidence. - + Relevant Evidence Reference A resolvable URL reference to relevant evidence. -

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter resource in the same document.

-

If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

-

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

+

This value may be one of:

+
    +
  1. an absolute URI that points to a network resolvable resource,
    2. +
  2. a relative reference pointing to a network resolvable resource whose base URI is the URI of the containing document, or
    3. +
  3. a bare URI fragment (i.e., `#uuid`) pointing to a back-matter resource in this or an imported document (see linking to another OSCAL object).
    4. +
@@ -1019,10 +1025,22 @@ The value conforms to FedRAMP definitions. + +

This value must be an absolute URI that serves as a naming system identifier.

+ + Threat Information Resource Reference An optional location for the threat data, from which this ID originates. + +

This value may be one of:

+
    +
  1. an absolute URI that points to a network resolvable resource,
    2. +
  2. a relative reference pointing to a network resolvable resource whose base URI is the URI of the containing document, or
    3. +
  3. a bare URI fragment (i.e., `#uuid`) pointing to a back-matter resource in this or an imported document (see linking to another OSCAL object).
    4. +
+ @@ -1299,6 +1317,9 @@ + +

This value must be an absolute URI that serves as a naming system identifier.

+ Facet Value @@ -1640,13 +1661,12 @@ - + Part Namespace A namespace qualifying the part's name. This allows different organizations to associate distinct semantics with the same name. -

Provides a means to segment the value space for the name, so that different organizations and individuals can assert control over the allowed names and associated text used in a part. This allows the semantics associated with a given name to be defined on an organization-by-organization basis.

-

An organization MUST use a URI that they have control over. e.g., a domain registered to the organization in a URI, a registered uniform resource names (URN) namespace.

+

This value must be an absolute URI that serves as a naming system identifier.

When a ns is not provided, its value should be assumed to be http://csrc.nist.gov/ns/oscal and the name should be a name defined by the associated OSCAL model.

 diff --git a/src/metaschema/oscal_assessment-results_metaschema.xml b/src/metaschema/oscal_assessment-results_metaschema.xml index 93433080c3..5637803d17 100644 --- a/src/metaschema/oscal_assessment-results_metaschema.xml +++ b/src/metaschema/oscal_assessment-results_metaschema.xml @@ -322,11 +322,12 @@ Assessment Plan Reference A resolvable URL reference to the assessment plan governing the assessment activities. -

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter - resource in the same document.

- -

If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

-

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

+

This value may be one of:

+
    +
  1. an absolute URI that points to a network resolvable resource,
    2. +
  2. a relative reference pointing to a network resolvable resource whose base URI is the URI of the containing document, or
    3. +
  3. a bare URI fragment (i.e., `#uuid`) pointing to a back-matter resource in this or an imported document (see linking to another OSCAL object).
    4. +
diff --git a/src/metaschema/oscal_catalog_metaschema.xml b/src/metaschema/oscal_catalog_metaschema.xml index f036a5beac..ef63cef286 100644 --- a/src/metaschema/oscal_catalog_metaschema.xml +++ b/src/metaschema/oscal_catalog_metaschema.xml @@ -5,34 +5,36 @@ ]> - + + OSCAL Control Catalog Model 1.0.4 oscal-catalog http://csrc.nist.gov/ns/oscal/1.0 http://csrc.nist.gov/ns/oscal -

The OSCAL Control Catalog format can be used to describe a collection of security controls and related control enhancements, along with contextualizing documentation and metadata. The root of the Control Catalog format is catalog. -

+

The OSCAL Control Catalog format can be used to describe a collection of security controls and related control enhancements, along with contextualizing documentation and metadata. The root of the Control Catalog format is catalog.

 Catalog - A collection of controls. + A structured, organized collection of control information. catalog Catalog Universally Unique Identifier - A globally unique identifier with cross-instance scope for this catalog instance. This UUID should be changed when this document is revised. + Provides a globally unique means to identify a given catalog instance. + + + + + - @@ -50,21 +52,38 @@ The tool used to produce a resolved profile. + The document-level uuid of the source profile from which the catalog was produced by profile resolution. - The tool used to produce a resolved profile. + The profile from which the catalog was produced by profile resolution. + The document-level uuid of the profile from which the catalog was produced by profile resolution. + + + + + + + + + + + + + + +

Catalogs may use one or more group objects to subdivide the control contents of a catalog.

-

An OSCAL catalog model provides a structured representation of control information.

 - A small catalog with a single control - + A small catalog with a single control. + A Miniature Catalog A Single Control + @@ -73,10 +92,15 @@ Control Group A group of controls, or of groups of controls. - + Group Identifier - A human-oriented, locally unique identifier with cross-instance scope that can be used to reference this defined group elsewhere in in this and other OSCAL instances (e.g., profiles). This id should be assigned per-subject, which means it should be consistently used to identify the same group across revisions of the document. + Identifies the group for the purpose of cross-linking within the defining instance or from other instances that reference the catalog. + + + + + Group Class @@ -92,7 +116,6 @@ A name given to the group, which may be used by a tool for display and navigation. - @@ -116,7 +139,6 @@ - &allowed-values-control-group-property-name; @@ -125,11 +147,11 @@ -

Catalogs can use a group to collect related controls into a single grouping. That can be useful to group controls into a family or other logical grouping.

-

A group may have its own properties, statements, parameters, and references, which are inherited by all members of that group.

+

Catalogs can use the catalog group construct to organize related controls into a single grouping, such as a family of controls or other logical organizational structure.

+

A group may have its own properties, statements, parameters, and references, which are inherited by all controls of that are a member of the group.

 - + My Group @@ -140,28 +162,41 @@ Control - A structured information object representing a security or privacy control. Each security or privacy control within the Catalog is defined by a distinct control instance. + A structured object representing a requirement or guideline, which when + implemented will reduce an aspect of risk related to an information system and its + information. Control Identifier - A human-oriented, locally unique identifier with instance scope that can be used to reference this control elsewhere in this and other OSCAL instances (e.g., profiles). This id should be assigned per-subject, which means it should be consistently used to identify the same control across revisions of the document. + Identifies a control such that it can be referenced in the defining + catalog and other OSCAL instances (e.g., profiles). + + + + + Control Class - A textual label that provides a sub-type or characterization of the control. + A textual label that provides a sub-type or characterization of the + control. -

A class can be used in validation rules to express extra constraints over named items of a specific class value.

-

A class can also be used in an OSCAL profile as a means to target an alteration to control content.

+

A class can be used in validation rules to express extra + constraints over named items of a specific class + value.

+

A class can also be used in an OSCAL profile as a means to + target an alteration to control content.

 Control Title - A name given to the control, which may be used by a tool for display and navigation. + A name given to the control, which may be used by a tool for + display and navigation. - @@ -176,7 +211,8 @@ Mapping - A mapping between the containing control and another resource. + A mapping between the containing control and another + resource. Mapping Identifier The unique identifier for the mapping. @@ -197,70 +233,100 @@ - - - &allowed-values-control-group-property-name; - The status of a control. For example, a value of 'withdrawn' can indicate that the control has been withdrawn and should no longer be used. + + + &allowed-values-control-group-property-name; + The status of a control. For example, a + value of 'withdrawn' can indicate that the control has + been withdrawn and should no longer be used. - + The control is no longer used. - **(deprecated)*** Use 'withdrawn' instead. + **(deprecated)*** Use 'withdrawn' + instead. - The link cites an external resource related to this control. - The link identifies another control with bearing to this control. - The link identifies another control that must be present if this control is present. - The link identifies other control content where this control content is now addressed. - The containing control definition was moved to the referenced control. + The link cites an external resource related to this + control. + The link identifies another control with bearing to + this control. + The link identifies another control that must be + present if this control is present. + The link identifies other control content + where this control content is now addressed. + The containing control definition was moved to the + referenced control. - - - An introduction to a control or a group of controls. + + + + + + An introduction to a control or a group of + controls. A set of control implementation requirements. - Additional information to consider when selecting, implementing, assessing, and monitoring a control. - **(deprecated)** Use 'assessment-method' instead. - The part describes a method-based assessment over a set of assessment objects. + Additional information to consider when selecting, + implementing, assessing, and monitoring a control. + **(deprecated)** Use + 'assessment-method' instead. + The part describes a method-based assessment + over a set of assessment objects. - + An individual item within a control statement.

Nested statement parts are "item" parts.

 - - **(deprecated)** Use 'assessment-objective' instead. - The part describes a set of assessment objectives. + + **(deprecated)** Use + 'assessment-objective' instead. + The part describes a set of assessment + objectives.

Objectives can be nested.

 - - **(deprecated)** Use 'assessment-objects' instead. - Provides a listing of assessment objects. + + **(deprecated)** Use + 'assessment-objects' instead. + Provides a listing of assessment + objects.

Assessment objects appear on assessment methods.

 - - - **(deprecated)** Use 'method' in the 'http://csrc.nist.gov/ns/rmf' namespace. The assessment method to use. This typically appears on parts with the name "assessment". + + **(deprecated)** Use 'method' in the 'http://csrc.nist.gov/ns/rmf' namespace. The assessment method to use. This typically appears on parts with the name "assessment-method". - - The assessment method to use. This typically appears on parts with the name "assessment". + + The assessment method to use. This typically appears on + parts with the name "assessment-method". - + The process of holding discussions with individuals or groups of individuals within an organization to once again, facilitate assessor understanding, achieve clarification, or obtain evidence. The process of reviewing, inspecting, observing, studying, or analyzing one or more assessment objects (i.e., specifications, mechanisms, or activities). The process of exercising one or more assessment objects (i.e., activities or mechanisms) under specified conditions to compare actual with expected behavior. -

Controls may be grouped using group, and controls may be partitioned using part or further enhanced (extended) using control.

-

A control must have a part with the name "statement", which represents the textual narrative of the control. This "statement" part must occur only once, but may have nested parts to allow for multiple paragraphs or sections of text.

+

Each security or privacy control within the catalog is defined by a distinct control instance. Controls may be as complex or as simple as a catalog defines them. They may be decomposed or further specified into child control objects, for example to represent control enhancements or specific breakouts of control functionality, to be maintained as discrete requirements. Controls may also contain structured parts (using part) and they may be grouped together in families or classes with group.

+

Control structures in OSCAL will also exhibit regularities and rules that are not codified in OSCAL but in its applications or domains of application. For example, for catalogs describing controls as defined by NIST SP 800-53, a control must have a part with the name "statement", which represents the textual narrative of the control. This "statement" part must occur only once, but may have nested parts to allow for multiple paragraphs or sections of text. This organization supports addressability of this data content as long as, and only insofar as, it is consistently implemented across the control set. As given with these model definitions, constraints defined and assigned here can aid in ensuring this regularity; but other such constraints and other useful patterns of use remain to be discovered and described.

 - + Control 1 diff --git a/src/metaschema/oscal_component_metaschema.xml b/src/metaschema/oscal_component_metaschema.xml index c757be4c80..8146d96d3e 100644 --- a/src/metaschema/oscal_component_metaschema.xml +++ b/src/metaschema/oscal_component_metaschema.xml @@ -19,10 +19,11 @@ http://csrc.nist.gov/ns/oscal/1.0 http://csrc.nist.gov/ns/oscal -

The OSCAL Component Definition Model can be used to describe the implementation of controls in a component or a set of components grouped as a capability. A component can be either a technical component, or a documentary component. A technical component is a component that is implemented in hardware (physical or virtual) or software. A documentary component is a component implemented in a document, such as a process, procedure, or policy.

-

The root of the OSCAL Implementation Component format is component-definition. -

-

NOTE: This documentation is a work in progress. As a result, documentation for many of the information elements is missing or incomplete.

+

The OSCAL Component Definition Model can be used to describe the implementation of controls in a component or a set of components grouped as a capability. A component can be either a technical component, or a documentary component.

+

A technical component is a component that is implemented in hardware (physical or virtual) or software. Suppliers may document components in an OSCAL component definition that describes the implementation of controls in their hardware and software.

+

A documentary component is a component implemented for a documented process, procedure, or policy. Suppliers may document components in an OSCAL component definition that describes the implementation of controls in their process, procedure, or policy.

+

The information provided by a technical or documentary component can be used by component consumers to provide starting narratives for documenting control implementations in an OSCAL SSP.

+

The root of the OSCAL Implementation Layer Component Definition model is component-definition.

 @@ -34,7 +35,12 @@ Component Definition Universally Unique Identifier - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference this component definition elsewhere in this or other OSCAL instances. The locally defined UUID of the component definition can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + Provides a globally unique means to identify a given component definition instance. + + + + + @@ -72,6 +78,14 @@ Hyperlink Reference A link to a resource that defines a set of components and/or capabilities to import into this collection. + +

This value may be one of:

+
    +
  1. an absolute URI that points to a network resolvable resource,
    2. +
  2. a relative reference pointing to a network resolvable resource whose base URI is the URI of the containing document, or
    3. +
  3. a bare URI fragment (i.e., `#uuid`) pointing to a back-matter resource in this or an imported document (see linking to another OSCAL object).
    4. +
+ @@ -81,7 +95,12 @@ Component Identifier - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference this component elsewhere in this or other OSCAL instances. The locally defined UUID of the component can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + Provides a globally unique means to identify a given component. + + + + + type @@ -252,7 +271,12 @@ Capability Identifier - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference this capability elsewhere in this or other OSCAL instances. The locally defined UUID of the capability can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance).This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + Provides a globally unique means to identify a given capability. + + + + + Capability Name @@ -284,12 +308,13 @@

A given component must not be referenced more than once within the same capability.

+ Incorporates Component - TBD + The collection of components comprising this capability. Component Reference @@ -309,13 +334,25 @@ Control Implementation Set Identifier - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference a set of implemented controls elsewhere in this or other OSCAL instances. The locally defined UUID of the control implementation set can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + Provides a means to identify a set of control implementations that are supported by a given component or capability. + + + + + - + + Source Resource Reference + A reference to an OSCAL catalog or profile providing the referenced control or subcontrol definition. -

A URL reference to the source catalog or profile for which this component is implementing controls for.

+

This value may be one of:

+
    +
  1. an absolute URI that points to a network resolvable resource,
    2. +
  2. a relative reference pointing to a network resolvable resource whose base URI is the URI of the containing document, or
    3. +
  3. a bare URI fragment (i.e., `#uuid`) pointing to a back-matter resource in this or an imported document (see linking to another OSCAL object).
    4. +
- + Control Implementation Description @@ -352,13 +389,18 @@ Control Implementation Identifier - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference a specific control implementation elsewhere in this or other OSCAL instances. The locally defined UUID of the control implementation can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance).This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + Provides a globally unique means to identify a given control implementation by a component. + + + + + Control Implementation Description - A suggestion for how the specified control may be implemented if the containing component or capability is instantiated in a system security plan. + A suggestion from the supplier (e.g., component vendor or author) for how the specified control may be implemented if the containing component or capability is instantiated in a system security plan. @@ -398,7 +440,7 @@ -

Implemented requirements within a component or capability in a component definition provide a means to suggest possible control implementation details, which may be used by a different party when authoring a system security plan. Thus, these requirements defined in a component definition are only a suggestion of how to implement, which may be adopted wholesale, changed, or ignored by a person defining an information system implementation.

+

Implemented requirements within a component or capability in a component definition provide a means for component suppliers to suggest possible control implementation details, which may be used by a different party (e.g., component consumers) when authoring a system security plan. Thus, these requirements defined in a component definition are only a suggestion of how to implement, which may be adopted wholesale, changed, or ignored by a person defining an information system implementation.

Use of set-parameter in this context, sets the parameter for the referenced control and any associated statements.

 diff --git a/src/metaschema/oscal_control-common_metaschema.xml b/src/metaschema/oscal_control-common_metaschema.xml index 09d9a7cac3..de51c93368 100644 --- a/src/metaschema/oscal_control-common_metaschema.xml +++ b/src/metaschema/oscal_control-common_metaschema.xml @@ -5,11 +5,12 @@ ]> + + xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0" abstract="yes"> OSCAL Control Catalog Format -- Common Models 1.0.4 - oscal-catalog-common + oscal-control-common http://csrc.nist.gov/ns/oscal/1.0 http://csrc.nist.gov/ns/oscal @@ -18,32 +19,38 @@ Part - A partition of a control's definition or a child of another part. + An annotated, markup-based textual element of a control's or catalog group's definition, or a child of another part. Part Identifier - A human-oriented, locally unique identifier with cross-instance scope that can be used to reference this defined part elsewhere in this or other OSCAL instances. When referenced from another OSCAL instance, this identifier must be referenced in the context of the containing resource (e.g., import-profile). This id should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + A unique identifier for the part. + + + + + + +

While a part is not required to have an id, it is often desirable for an identifier to be provided, which allows the part to be referenced elsewhere in OSCAL document instances. For this reason, it is RECOMMENDED to provide a part identifier.

+ Part Name - A textual label that uniquely identifies the part's semantic type. + A textual label that uniquely identifies the part's semantic type, which exists in a value space qualified by the ns. - - + Part Namespace - A namespace qualifying the part's name. This allows different organizations to associate distinct semantics with the same name. + An optional namespace qualifying the part's name. This allows different organizations to associate distinct semantics with the same name. -

Provides a means to segment the value space for the name, so that different organizations and individuals can assert control over the allowed names and associated text used in a part. This allows the semantics associated with a given name to be defined on an organization-by-organization basis.

-

An organization MUST use a URI that they have control over. e.g., a domain registered to the organization in a URI, a registered uniform resource names (URN) namespace.

+

This value must be an absolute URI that serves as a naming system identifier.

When a ns is not provided, its value should be assumed to be http://csrc.nist.gov/ns/oscal and the name should be a name defined by the associated OSCAL model.

 Part Class - A textual label that provides a sub-type or characterization of the part's name. This can be used to further distinguish or discriminate between the semantics of multiple parts of the same control with the same name and ns. - + An optional textual providing a sub-type or characterization of the part's name, or a category to which the part belongs. +

One use of this flag is to distinguish or discriminate between the semantics of multiple parts of the same control with the same name and ns (since even within a given namespace it can be useful to overload a name).

A class can be used in validation rules to express extra constraints over named items of a specific class value.

A class can also be used in an OSCAL profile as a means to target an alteration to control content.

 @@ -51,7 +58,7 @@ Part Title - A name given to the part, which may be used by a tool for display and navigation. + An optional name given to the part, which may be used by a tool for display and navigation. @@ -69,61 +76,60 @@ - &allowed-values-control-group-property-name; - +

A part provides for logical partitioning of prose, and can be thought of as a grouping structure (e.g., section). A part can have child parts allowing for arbitrary nesting of prose content (e.g., statement hierarchy). A part can contain prop objects that allow for enriching prose text with structured name/value information.

-

A part can be assigned an optional id, which allows for internal and external references to the textual concept contained within a part. A id provides a means for an OSCAL profile, or a higher layer OSCAL model to reference a specific part within a catalog. For example, an id can be used to reference or to make modifications to a control statement in a profile.

+

A part can be assigned an optional id, which allows references to this part from within a catalog, or within an instance of another OSCAL model that has a need to reference the part. Examples of where part referencing is used in OSCAL include:

+
    +
  • Referencing a part by id to tailor (make modifications to) a control statement in a profile.
    • +
  • Referencing a control statement represented by a part in a system security plan implemented-requirement where a statement-level response is desired.
    • +

Use of part and prop provides for a wide degree of extensibility within the OSCAL catalog model. The optional ns provides a means to qualify a part's name, allowing for organization-specific vocabularies to be defined with clear semantics. Any organization that extends OSCAL in this way should consistently assign a ns value that represents the organization, making a given namespace qualified name unique to that organization. This allows the combination of ns and name to always be unique and unambiguous, even when mixed with extensions from other organizations. Each organization is responsible for governance of their own extensions, and is strongly encouraged to publish their extensions as standards to their user community. If no ns is provided, the name is expected to be in the "OSCAL" namespace.

To ensure a ns is unique to an organization and naming conflicts are avoided, a URI containing a DNS or other globally defined organization name should be used. For example, if FedRAMP and DoD both extend OSCAL, FedRAMP will use the ns http://fedramp.gov/ns/oscal, while DoD might use the ns https://defense.gov for any organization specific name.

Tools that process OSCAL content are not required to interpret unrecognized OSCAL extensions; however, OSCAL compliant tools should not modify or remove unrecognized extensions, unless there is a compelling reason to do so, such as data sensitivity.

 - Multiple Parts with Different Organization-Specific Names - - Something FedRAMP Cares About - Something DoD Cares About - + Multiple Parts with Different Organization-Specific Names. + + A requirement specific to FedRAMP stakeholders. + A requirement specific to the Department of Defense stakeholders. + + Parameter Parameters provide a mechanism for the dynamic assignment of value(s) in a control. - param Parameter Identifier - - A human-oriented, locally unique identifier with cross-instance scope that can be used to reference this defined parameter elsewhere in this or other OSCAL instances. When referenced from another OSCAL instance, this identifier must be referenced in the context of the containing resource (e.g., import-profile). This id should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + A unique identifier for the parameter. + + + + + Parameter Class - A textual label that provides a characterization of the parameter. + A textual label that provides a characterization of the type, + purpose, use or scope of the parameter.

A class can be used in validation rules to express extra constraints over named items of a specific class value.

 Depends on - **(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used. + (deprecated) Another parameter invoking this one. This construct has been deprecated and should not be used. @@ -137,12 +143,13 @@ Parameter Label A short, placeholder name for the parameter, which can be used as a substitute for a value if no value is assigned. -

The label value should be suitable for inline display in a rendered catalog.

+

The label value is intended use when rendering a parameter in generated documentation or a user interface when a parameter is referenced. Note that labels are not required to be distinctive, which means that parameters within the same control may have the same label.

 Parameter Usage Description - Describes the purpose and use of a parameter + Describes the purpose and use of a + parameter. constraint @@ -150,27 +157,26 @@ guideline - - value -

A set of values provided in a catalog can be redefined at any higher layer of OSCAL (e.g., Profile).

+

A set of values provided in a catalog can be redefined in OSCAL's profile or system-security-plan models.

 select -

A set of parameter value choices, that may be picked from to set the parameter value.

+

The OSCAL parameter value construct can be used to prescribe a specific parameter value in a catalog or profile. In cases where a prescriptive value is not possible in a catalog or profile, it may be possible to constrain the set of possible values to a few options. Use of select in a parameter instead of value is a way of defining value options that may be set.

+

A set of allowed parameter values expressed as a set of options which may be selected. These options constrain the permissible values that may be selected for the containing parameter. When the value assignment is made, such as in an OSCAL profile or system security plan, the actual selected value can be examined to determine if it matches one of the permissible choices for the parameter value.

+

When the value of how-many is set to "one-or-more", multiple values may be assigned reflecting more than one choice.

 - @@ -178,7 +184,9 @@ An alternate to the value provided by the parameter's label. This will typically be qualified by a class. - The parent parameter provides an aggregation of 2 or more other parameters, each described by this property. + The parent parameter provides an + aggregation of two or more other parameters, each described + by this property. depends-on is deprecated @@ -191,16 +199,13 @@ - Constraint - A formal or informal expression of a constraint or test + A formal or informal expression of a constraint or test. - Constraint Description A textual summary of the constraint to be applied. - Constraint Test A test expression which is expected to be evaluated by a tool. @@ -208,7 +213,8 @@ Constraint test - A formal (executable) expression of a constraint + A formal (executable) expression of a + constraint. @@ -223,19 +229,17 @@ Guideline Text Prose permits multiple paragraphs, lists, tables etc. - - Parameter Value A parameter value or set of values. Selection - Presenting a choice among alternatives + Presenting a choice among alternatives. Parameter Cardinality Describes the number of selections that must occur. Without this setting, only one value should be assumed to be permitted. @@ -249,13 +253,12 @@ Choice - A value selection among several such options + A value selection among several such + options. choice value - -

A set of parameter value choices, that may be picked from to set the parameter value.

@@ -267,7 +270,10 @@ Control Identifier Reference - A human-oriented identifier reference to a control with a corresponding id value. When referencing an externally defined control, the Control Identifier Reference must be used in the context of the external / imported OSCAL instance (e.g., uri-reference). + A reference to a control with a corresponding id value. When referencing an externally defined control, the Control Identifier Reference must be used in the context of the external / imported OSCAL instance (e.g., uri-reference). + + + Include All diff --git a/src/metaschema/oscal_implementation-common_metaschema.xml b/src/metaschema/oscal_implementation-common_metaschema.xml index 68097e6bae..695ac69450 100644 --- a/src/metaschema/oscal_implementation-common_metaschema.xml +++ b/src/metaschema/oscal_implementation-common_metaschema.xml @@ -604,10 +604,7 @@ - - Source Resource Reference - A reference to an OSCAL catalog or profile providing the referenced control or subcontrol definition. - + System Identification + A human-oriented, globally unique identifier with cross-instance scope that can be used to reference this system identification property elsewhere in this or other OSCAL instances. When referencing an externally defined system identification, the system identification must be used in the context of the external / imported OSCAL instance (e.g., uri-reference). This string should be assigned per-subject, which means it should be consistently used to identify the same system across revisions of the document. id @@ -679,6 +683,9 @@ A Universally Unique Identifier (UUID) as defined by RFC4122. + +

This value must be an absolute URI that serves as a naming system identifier.

+ diff --git a/src/metaschema/oscal_mapping-common_metaschema.xml b/src/metaschema/oscal_mapping-common_metaschema.xml index a7c5f63582..d0be2ab220 100644 --- a/src/metaschema/oscal_mapping-common_metaschema.xml +++ b/src/metaschema/oscal_mapping-common_metaschema.xml @@ -28,11 +28,11 @@ Mapping Entry Relationship The relationship type for the mapping entry, which describes the relationship between the effective requirements of the specified source and target sets. type - + Relationship Value Namespace A namespace qualifying the relationship's value. This allows different organizations to associate distinct semantics for relationships with the same name. -

An organization MUST use a URI that they have control over. e.g., a domain registered to the organization in a URI, a registered uniform resource names (URN) namespace.

+

This value must be an absolute URI that serves as a naming system identifier.

When a ns is not provided, its value should be assumed to be http://csrc.nist.gov/ns/oscal and the name should be a name defined by the associated OSCAL model.

 @@ -90,7 +90,7 @@ Mapped Resource Reference - A reference to a back-matter resource that is either the source or target of a mapping. + A reference to a resource that is either the source or target of a mapping. Resource Type The semantic type of the resource. @@ -104,11 +104,12 @@ Catalog or Profile Reference A resolvable URL reference to the base catalog or profile that this profile is tailoring. -

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter - resource in the same document.

- -

If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

-

If an internet resource is used, the href value will be an absolute or relative URL pointing to the location of the referenced resource. A relative URL will be resolved relative to the location of the document containing the link.

+

This value may be one of:

+
    +
  1. an absolute URI that points to a network resolvable resource,
    2. +
  2. a relative reference pointing to a network resolvable resource whose base URI is the URI of the containing document, or
    3. +
  3. a bare URI fragment (i.e., `#uuid`) pointing to a back-matter resource in this or an imported document (see linking to another OSCAL object).
    4. +
diff --git a/src/metaschema/oscal_metadata_metaschema.xml b/src/metaschema/oscal_metadata_metaschema.xml index 848123ac94..dced70a942 100644 --- a/src/metaschema/oscal_metadata_metaschema.xml +++ b/src/metaschema/oscal_metadata_metaschema.xml @@ -2,8 +2,9 @@ + + xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0" abstract="yes"> OSCAL Document Metadata Description 1.0.4 oscal-metadata @@ -14,8 +15,8 @@ - Publication metadata - Provides information about the publication and availability of the containing document. + Document Metadata + Provides information about the containing document, and defines concepts that are shared across the document. Document Title @@ -25,12 +26,43 @@ - - - - - - + + Revision History Entry + An entry in a sequential list of revisions to the containing document, expected to be in reverse chronological order (i.e. latest first). + + + Document Title + A name given to the document revision, which may be used by a tool for display and navigation. + + + + + + + + + + + + + + + + + The link identifies the authoritative location for this resource. Defined by RFC 6596. + The link identifies an alternative location or format for this resource. Defined by the HTML Living Standard + This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829. + This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829. + This link identifies a resource containing the version history of this document. Defined by RFC 5829. + + + + +

While published, last-modified, and oscal-version are not required, values for these entries should be provided if the information is known. A link with a rel of source should be provided if the information is known.

+ + @@ -40,15 +72,270 @@ - + + Role + Defines a function, which might be assigned to a party in a specific situation. - - + + + Role Identifier + A unique identifier for the role. + + + + + + + + + + Role Title + A name given to the role, which may be used by a tool for display and navigation. + + + Role Short Name + A short common name, abbreviation, or acronym for the role. + + + + Role Description + A summary of the role's purpose and associated responsibilities. + + + + + + + + + + + + + + +

Permissible values to be determined closer to the application (e.g. by a receiving authority).

+

OSCAL has defined a set of standardized roles for consistent use in OSCAL documents. This allows tools consuming OSCAL content to infer specific semantics when these roles are used. These roles are documented in the specific contexts of their use (e.g., responsible-party, responsible-role). When using such a role, it is necessary to define these roles in this list, which will then allow such a role to be referenced.

+ + + + Location + A physical point of presence, which may be associated with people, organizations, or other concepts within the current or linked OSCAL document. - - + + Location Universally Unique Identifier + A unique ID for the location, for reference. + + + + Location Title + A name given to the location, which may be used by a tool for display and navigation. + + + +

The physical address of the location, which will provided for physical locations. Virtual locations can omit this data item.

+ + + + + +

A contact email associated with the location.

+ + + + + +

A phone number used to contact the location.

+ + + + Location URL + The uniform resource locator (URL) for a web site or other resource associated with the location. + + +

This data field is deprecated in favor of using a link with an appropriate relationship.

+ + + + + + + + + + + + + Characterizes the kind of location. + + + A location that contains computing assets. A class can be used to indicate the sub-type of data-center as primary or alternate. + + + The location is a data-center used for normal operations. + The location is a data-center used for fail-over or backup operations. + + + In most cases, it is useful to define a location. In some cases, defining an explicit location may represent a security risk. + + + A location must have at least a title, address, email-address, or telephone number. + + + +

An address might be sensitive in nature. In such cases a title, mailing address, email-address, and/or phone number may be used instead.

+ + + + Party + An organization or person, which may be associated with roles or other concepts within the current or linked OSCAL document. - + + Party Universally Unique Identifier + + A unique identifier for the party. + + + + + + + + Party Type + A category describing the kind of party the object describes. + + + A human being regarded as an individual. + An organized group of one or more person individuals with a specific purpose. + + + + + + Party Name + The full name of the party. This is typically the legal name associated with the party. + + + Party Short Name + A short common name, abbreviation, or acronym for the party. + + + + Party External Identifier + An identifier for a person or organization using a designated + scheme. e.g. an Open Researcher and Contributor ID + (ORCID). + id + + + External Identifier Schema + Indicates the type of external identifier. + + + The identifier is Open Researcher and Contributor ID (ORCID). + + + +

This value must be an absolute URI that serves as a naming system identifier.

+ + + + + + + + + + + + +

This is a contact email associated with the party.

+ + + + + +

A phone number used to contact the party.

+ + + + + + + + + + + + Organizational Affiliation + + A reference to another party by UUID, typically an organization, that this subject is associated with. + + + + + + + + + + + +

Since the reference target of an organizational affiliation must be another party (whether further qualified as person or organization) as inidcated by its uuid. As a machine-oriented identifier with uniqueness across document and trans-document scope, this uuid value is sufficient to reference the data item locally or globally across related documents, e.g., in an imported OSCAL instance.

+

Parties of both the person or organization type can be associated with an organization using the member-of-organization.

+ + + + + + + A mail stop associated with the party. + The name or number of the party's office. + The formal job title of a person. + + + +

A party can be optionally associated with either an address or a location. While providing a meaningful location for a party is desired, there are some cases where it might not be possible to provide an exact location or even any location.

+ + @@ -59,6 +346,7 @@ + @@ -74,6 +362,7 @@ + @@ -82,6 +371,7 @@ + + + + @@ -105,126 +398,45 @@ - Indicates the organization that created this content. - Indicates the organization that prepared this content. - Indicates the organization for which this content was created. - Indicates the organization responsible for all content represented in the "document". - Indicates the organization to contact for questions or support related to this content. + Indicates the person or organization that created this content. + Indicates the person or organization that prepared this content. + Indicates the person or organization for which this content was created. + Indicates the person or organization responsible for all content represented in the "document". + Indicates the person or organization to contact for questions or support related to this content. The value identifies a comma-seperated listing of keywords associated with this content. These keywords may be used as search terms for indexing and other applications. - The link identifies the authoritative location for this file. Defined by RFC 6596. - The link identifies an alternative location or format for this file. Defined by the HTML Living Standard + The link identifies the authoritative location for this resource. Defined by RFC 6596. + The link identifies an alternative location or format for this resource. Defined by the HTML Living Standard This link identifies a resource containing the latest version in the version history. Defined by RFC 5829. This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829. This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829. - - - - - Revision History Entry - An entry in a sequential list of revisions to the containing document in reverse chronological order (i.e., most recent previous revision first). - - - Document Title - A name given to the document revision, which may be used by a tool for display and navigation. - - - - - - - - - - - - - - - - - The link identifies the authoritative location for this file. Defined by RFC 6596. - The link identifies an alternative location or format for this file. Defined by the HTML Living Standard - This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829. - This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829. - - - -

While published, last-modified, oscal-version, and version are not required, values for these entries should be provided if the information is known. For a revision entry to be considered valid, at least one of the following items must be provided: published, last-modified, version, or a link with a rel of source.

- - - - - Location - A location, with associated metadata that can be referenced. - - Location Universally Unique Identifier - - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference this defined location elsewhere in this or other OSCAL instances. The locally defined UUID of the location can be used to reference the data item locally or globally (e.g., from an importing OSCAL instance). This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. - - - - Location Title - A name given to the location, which may be used by a tool for display and navigation. - - - -

Typically, the physical address of the location will be used here. If this information is sensitive, then a mailing address can be used instead.

- - - - - - -

This is a contact email associated with the location.

- - - - - + + + -

A phone number used to contact the location.

+

The combination of scheme and the field value must be unique.

 - - - Location URL - The uniform resource locator (URL) for a web site or Internet presence associated with the location. - - - - - - - - - - - - - - Characterizes the kind of location. - - - A location that contains computing assets. A class can be used to indicate the sub-type of data-center as primary or alternate. - - - The location is a data-center used for normal operations. - The location is a data-center used for fail-over or backup operations. - + + +

All OSCAL documents use the same metadata structure, that provides a consistent way of expressing OSCAL document metadata across all OSCAL models. The metadata section also includes declarations of individual objects (i.e., roles, location, parties) that may be referenced within and across linked OSCAL documents.

+

The metadata in an OSCAL document has few required fields, representing only the bare minimum data needed to differentiate one instance from another. Tools and users creating OSCAL documents may choose to use any of the optional fields, as well as extension mechanisms (e.g., properties, links) to go beyond this minimum to suit their use cases.

+

A publisher of OSCAL content can use the published, last-modified, and version fields to establish information about an individual in a sequence of successive revisions of a given OSCAL-based publication. The metadata for a previous revision can be represented as a revision within this object. Links may also be provided using the predecessor-version and successor-version link relations to provide for direct access to the related resource. These relations can be provided as a link child of this object or as link within a given revision.

+

A responsible-party entry in this context refers to roles and parties that have responsibility relative to the production, review, publication, and use of the containing document.

+ - Location Reference - - A machine-oriented identifier reference to a location defined in the metadata section of this or another OSCAL instance. The UUID of the location in the source OSCAL instance is sufficient to reference the data item locally or globally (e.g., in an imported OSCAL instance). - + Location Universally Unique Identifier Reference + + Reference to a location by UUID. + + + @@ -235,178 +447,42 @@ - Location Reference - - A machine-oriented identifier reference to a location defined in the metadata section of this or another OSCAL instance. The UUID of the location in the source OSCAL instance is sufficient to reference the data item locally or globally (e.g., in an imported OSCAL instance). - + Location Universally Unique Identifier Reference + + Reference to a location by UUID. + + + - -

See the Concepts - Identifier Use page for additional information about the referenced identifier's scope.

- - - Party (organization or person) - A responsible entity which is either a person or an organization. - - Party Universally Unique Identifier - - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference this defined party elsewhere in this or other OSCAL instances. The locally defined UUID of the party can be used to reference the data item locally or globally (e.g., from an importing OSCAL instance). This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. - - - Party Type - A category describing the kind of party the object describes. - - - An individual. - A group of individuals formed for a specific purpose. - - - - - - - Party Name - The full name of the party. This is typically the legal name associated with the party. - - - Party Short Name - A short common name, abbreviation, or acronym for the party. - - - - Party External Identifier - An identifier for a person or organization using a designated scheme. e.g. an Open Researcher and Contributor ID (ORCID) - id - - - - External Identifier Schema - Indicates the type of external identifier. - - - The identifier is Open Researcher and Contributor ID (ORCID). - - - - - - - - - - - - - - -

This is a contact email associated with the party.

- - - - - - -

A phone number used to contact the party.

- - - - - - - - - - - - - Organizational Affiliation - - A machine-oriented identifier reference to another party (person or organization) that this subject is associated with. The UUID of the party in the source OSCAL instance is sufficient to reference the data item locally or globally (e.g., in an imported OSCAL instance). - - - - - - - - -

Parties of both the person or organization type can be associated with an organization using the member-of-organization.

- - - - - - - A mail stop associated with the party. - The name or number of the party's office. - The formal job title of a person. - - - - - Party Reference - - A machine-oriented identifier reference to another party defined in metadata. The UUID of the party in the source OSCAL instance is sufficient to reference the data item locally or globally (e.g., in an imported OSCAL instance). - + Party Universally Unique Identifier Reference + + Reference to a party by UUID. + + + - -

See the Concepts - Identifier Use page for additional information about the referenced identifier's scope.

- - - Role - Defines a function assumed or expected to be assumed by a party in a specific situation. - - - - Role Identifier - A human-oriented, locally unique identifier with cross-instance scope that can be used to reference this defined role elsewhere in this or other OSCAL instances. When referenced from another OSCAL instance, the locally defined ID of the Role from the imported OSCAL instance must be referenced in the context of the containing resource (e.g., import, import-component-definition, import-profile, import-ssp or import-ap). This ID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. - - - - Role Title - A name given to the role, which may be used by a tool for display and navigation. - - - Role Short Name - A short common name, abbreviation, or acronym for the role. - - - - Role Description - A summary of the role's purpose and associated responsibilities. - - - - - - - - - - -

Permissible values to be determined closer to the application (e.g. by a receiving authority).

-

OSCAL has defined a set of standardized roles for consistent use in OSCAL documents. This allows tools consuming OSCAL content to infer specific semantics when these roles are used. These roles are documented in the specific contexts of their use (e.g., responsible-party, responsible-role). When using such a role, it is necessary to define these roles in this list, which will then allow such a role to be referenced.

- - - Role Identifier Reference - - A human-oriented identifier reference to roles served by the user. + + Reference to a role by UUID. + + + @@ -420,37 +496,35 @@ Back matter - A collection of resources, which may be included directly or by reference. + A collection of resources that may be referenced from within the OSCAL document instance. Resource - A resource associated with content in the containing document. A resource may be directly included in the document base64 encoded or may point to one or more equivalent internet resources. + A resource associated with content in the containing document instance. A resource may be directly included in the document using base64 encoding or may point to one or more equivalent internet resources. Resource Universally Unique Identifier + A unique identifier for a resource. - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference this defined resource elsewhere in this or other OSCAL instances. This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. Resource Title - A name given to the resource, which may be used by a tool for display and navigation. + An optional name given to the resource, which may be used by a tool for display and navigation. - Resource Description - A short summary of the resource used to indicate the purpose of the resource. + An optional short summary of the resource used to indicate the purpose of the resource. - Citation - A citation consisting of end note text and optional structured bibliographic data. + An optional citation consisting of end note text using structured markup. Citation Text @@ -463,49 +537,60 @@ - +--> + + Resource link - A pointer to an external resource with an optional hash for verification and change detection. + A URL-based pointer to an external resource with an optional hash for verification and change detection. Hypertext Reference - A resolvable URI reference to a resource. + A resolvable URL pointing to the referenced resource. + +

This value may be either:

+
    +
  1. an absolute URI that points to a network resolvable resource,
    2. +
  2. a relative reference pointing to a network resolvable resource whose base URI is the URI of the containing document, or
    3. +
+ + A hash of the resource identified by href, which can be used to verify the resource was not changed since it was hashed. -

When appearing as part of a resource/rlink, the hash applies to the resource referenced by the href. -

+

The hash value can be used to confirm that the resource referenced by the href is the same resources that was hashed by retrieving the resource, calculating a hash, and comparing the result to this value.

 -

This construct is different from link, which makes no provision for a hash or formal title.

-

Multiple rlink can be included for a resource. In such a case, all provided rlink items are intended to be equivalent in content, but may differ in structure. A media-type is used to identify the format of a given rlink, and can be used to differentiate a items in a collection of rlinks. The media-type also provides a hint to the OSCAL document consumer about the structure of the resource referenced by the rlink. +

Multiple rlink objects can be included for a resource. In such a case, all provided rlink items are intended to be equivalent in content, but may differ in structure or format.

+

A media-type is used to identify the format of a given rlink, and can be used to differentiate items in a collection of rlinks. The media-type provides a hint to the OSCAL document consumer about the structure of the resource referenced by the rlink.

Base64 - The Base64 alphabet in RFC 2045 - aligned with XSD. + A resource encoded using the Base64 alphabet defined by RFC 2045. value - + File Name Name of the file before it was encoded as Base64 to be embedded in a resource. This is the name that will be assigned to the file when the file is decoded. @@ -516,13 +601,12 @@ - Identifies the type of resource represented. + Identifies the type of resource represented. The most specific appropriate type value SHOULD be used. For resources representing a published document, this represents the version number of that document. For resources representing a published document, this represents the publication date of that document. - - - + + Indicates the resource is an organization's logo. Indicates the resource represents an image. @@ -543,7 +627,7 @@ Indicates the resource represents a plan. Indicates the resource represents an artifact, such as may be reviewed by an assessor. - Indicates the resource represents evidence, such as to support an assessment findiing. + Indicates the resource represents evidence, such as to support an assessment finding. Indicates the resource represents output from a tool. Indicates the resource represents machine data, which may require a tool or analysis for interpretation or presentation. Indicates the resource represents notes from an interview, such as may be collected during an assessment. @@ -551,28 +635,26 @@ Indicates the resource is a report. Indicates the resource is a formal agreement between two or more parties. - + + A resource should provide at least an rlink or base64 object. + + Ensure that each rlink item references a unique resource. - -

Ensures that each rlink item references a unique resource.

- + + Ensure that all base64 resources have a unique filename. - -

Ensures that all base64 resources have a unique filename. -

- - -

A title is required when a citation is provided.

- + A title is required when a citation is provided. -

A resource can be used in two ways. 1) it may point to an specific retrievable network resource using a rlink, or 2) it may be included as an attachment using a base64. A resource may contain multiple rlink and base64 entries that represent alternative download locations (rlink) and attachments (base64) for the same resource. Both rlink and base64 allow for a media-type to be specified, which is used to distinguish between different representations of the same resource (e.g., Microsoft Word, PDF). When multiple rlink and base64 items are included for a given resource, all items must contain equivalent information. This allows the document consumer to choose a preferred item to process based on a the selected item's media-type. This is extremely important when the items represent OSCAL content that is represented in alternate formats (i.e., XML, JSON, YAML), allowing the same OSCAL data to be processed from any of the available formats indicated by the items.

+ +

A resource can be used in two ways. 1) it may point to an specific retrievable network resource using a rlink, or 2) it may be included as an attachment using a base64. A resource may contain multiple rlink and base64 entries that represent alternative download locations (rlink) and attachments (base64) for the same resource.

+

Both rlink and base64 allow for a media-type to be specified, which is used to distinguish between different representations of the same resource (e.g., Microsoft Word, PDF). When multiple rlink and base64 items are included for a given resource, all items must contain equivalent information. This allows the document consumer to choose a preferred item to process based on a the selected item's media-type. This is extremely important when the items represent OSCAL content that is represented in alternate formats (i.e., XML, JSON, YAML), allowing the same OSCAL data to be processed from any of the available formats indicated by the items.

When a resource includes a citation, then the title and citation properties must both be included.

 @@ -583,7 +665,7 @@ -

Provides a collection of identified resource objects that can be referenced by a link with a rel value of "reference" and an href value that is a fragment "#" followed by a reference to a reference identifier. Other specialized link "rel" values also use this pattern when indicated in that context of use.

+

Provides a collection of identified resource objects that can be referenced by a link with a rel value of "reference" and an href value that is a fragment "#" followed by a reference to a reference's uuid. Other specialized link "rel" values also use this pattern when indicated in that context of use.

 @@ -593,10 +675,10 @@ - My citation + My citation - + @@ -609,13 +691,15 @@ Property - An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values. + An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. prop Property Name - A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object. + A textual label, within a namespace, that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object. - + + + A label or descriptor that is tied to a sensitivity or classification marking system. An optional class can be used to define the specific marking system used for the associated value. @@ -623,16 +707,13 @@ Property Universally Unique Identifier - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference this defined property elsewhere in this or other OSCAL instances. This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + A unique identifier for a property. - - - + Property Namespace A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name. -

Provides a means to segment the value space for the name, so that different organizations and individuals can assert control over the allowed names and associated values used in a property. This allows the semantics associated with a given name/value pair to be defined on an organization-by-organization basis.

-

An organization MUST use a URI that they have control over. e.g., a domain registered to the organization in a URI, a registered uniform resource names (URN) namespace.

+

This value must be an absolute URI that serves as a naming system identifier.

When a ns is not provided, its value should be assumed to be http://csrc.nist.gov/ns/oscal and the name should be a name defined by the associated OSCAL model.

 @@ -642,10 +723,11 @@ Property 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. - + A textual label that provides a sub-type or characterization of the + property's name. -

A class can be used in validation rules to express extra constraints over named items of a specific class value.

+

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, or to group properties into categories.

+

A class can be used in validation rules to express extra constraints over named items of a specific class value. It is available for grouping, but unlike group is not expected specifically to designate any group membership as such.

 @@ -666,28 +748,30 @@ Link - A reference to a local or remote resource + A reference to a local or remote resource, that has a specific relation to the containing object. Hypertext Reference A resolvable URL reference to a resource. -

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter - resource in the same document.

- -

If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document.

-

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the referenced resource. A relative URI will be resolved relative to the location of the document containing the link.

+

This value may be one of:

+
    +
  1. an absolute URI that points to a network resolvable resource,
    2. +
  2. a relative reference pointing to a network resolvable resource whose base URI is the URI of the containing document, or
    3. +
  3. a bare URI fragment (i.e., `#uuid`) pointing to an OSCAL object by the objects identifier (e.g., id, uuid) in this or an imported document (see linking to another OSCAL object). The specific object type will differ based on the link relationship type.
    4. +
- Relation - Describes the type of relationship provided by the link. This can be an indicator of the link's purpose. + Link Relation Type + Describes the type of relationship provided by the link's hypertext reference. This can be an indicator of the link's purpose. - Reference + A generalized reference to a network resource (relative or absolute) or to a back-matter resource by UUID expressed as a bare URI fragment. + Link Media Type

The media-type provides a hint about the content model of the referenced resource. A valid entry from the IANA Media Types registry SHOULD be used.

 @@ -699,6 +783,12 @@ + + A local reference SHOULD NOT have a media-type. + +

Since both link and back-matter/resource both allow specification of a media-type, the media-type on link may conflict with the any media-type entries on a resource's rlink or base64 objects. This constraint prevents this from occurring.

+ + @@ -731,19 +821,19 @@ Responsible Party - A reference to a set of organizations or persons that have responsibility for performing a referenced role in the context of the containing object. + A reference to a set of persons and/or organizations that have responsibility for performing the referenced role in the context of the containing object. Responsible Role - - A human-oriented identifier reference to roles served by the user. + + A reference to a role performed by a party. + + + + Specifies one or more parties responsible for performing the associated role. - -

Specifies one or more parties that are responsible for performing the associated role. -

- @@ -757,10 +847,11 @@ - - - + +

A responsible-party requires one or more party-uuid references creating a strong relationship arc between the referenced role-id and the reference parties. This differs in semantics from responsible-role which doesn't require that a party-uuid is referenced.

+

The scope of use of this object determines if the responsibility has been performed or will be performed in the future. The containing object will describe the intent.

+ @@ -817,11 +908,10 @@ Responsible Role - A reference to one or more roles with responsibility for performing a function relative to the containing object. + A reference to a role with responsibility for performing a function relative to the containing object, optionally associated with a set of persons and/or organizations that perform that role. Responsible Role ID - - A human-oriented identifier reference to roles responsible for the business function. + A human-oriented identifier reference to a role performed. @@ -831,20 +921,25 @@ + Specifies zero or more parties responsible for performing the associated role. + +

A responsible-role allows zero or more party-uuid references, each of which creates a relationship arc between the referenced role-id and the referenced party. This differs in semantics from responsible-party, which requires that at least one party-uuid is referenced.

+

The scope of use of this object determines if the responsibility has been performed or will be performed in the future. The containing object will describe the intent.

+ - + Hash A representation of a cryptographic digest generated over a resource using a specified hash algorithm. value Hash algorithm - Method by which a hash is derived + The digest method by which a hash is derived. The SHA-224 algorithm as defined by NIST FIPS 180-4. @@ -866,26 +961,38 @@ -

Any other value used MUST be a value defined in the W3C XML Security Algorithm Cross-Reference Digest Methods (W3C, April 2013) or RFC 6931 Section 2.1.5 New SHA Functions.

+

Any other value used MUST be a value defined in the W3C XML Security Algorithm Cross-Reference Digest Methods (W3C, April 2013) or RFC 6931 Section 2.1.5 New SHA Functions.

 - -

A hash value can be used to authenticate that a referenced resource is the same resources as was pointed to by the author of the reference.

- + + + + + + Media Type - Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry. - + A label that indicates the nature of a resource, as a data serialization or + format. -

The IANA Media Types Registry should be used, but currently there is no official media type for YAML. OSCAL documents should specify application/yaml for general YAML content, or application/oscal+yaml for YAML-based OSCAL content. This approach aligns with use of a structured name suffix, per RFC 6838 Section 4.2.8.

+

The Internet Assigned Numbers Authority (IANA) Media + Types Registry defines a standardized set of media types, which may be used + here.

+

The application/oscal+xml, application/oscal+json or application/oscal+yaml media types SHOULD be used when referencing OSCAL XML, JSON, or YAML resources respectively.

+

**Note: There is no official media type for YAML at this time.** OSCAL documents should specify application/yaml for general YAML content, or application/oscal+yaml for YAML-based OSCAL content. This approach aligns with use of a structured name suffix, per RFC 6838 Section 4.2.8.

+

Some earlier OSCAL content incorporated the model into the media type. For example: application/oscal.catalog+xml. This practice SHOULD be avoided, since the OSCAL model can be detected by parsing the initial content of the referenced resource.

 Remarks - Additional commentary on the containing object. + Additional commentary about the containing object. + +

The remarks field SHOULD not be used to store arbitrary data. Instead, a prop or link should be used to annotate or reference any additional data not formally supported by OSCAL.

+ @@ -893,49 +1000,51 @@ Publication Timestamp - The date and time the document was published. The date-time value must be formatted according to RFC 3339 with full time and time zone included. + The date and time the document was last made available. -

This value represents the point in time when the OSCAL document was published. Typically, this date value will be machine generated at the time the containing document is published.

-

In some cases, an OSCAL document may be derived from some source material in a different format. In such a case, the published value should indicate when the OSCAL document was published, not the source material. Where necessary, the publication date of the original source material can be captured as a named property or custom metadata construct.

-

A publisher of OSCAL content can use this data point along with its siblings last-modified and version to establish a sequence of successive revisions of a given OSCAL-based publication. The metadata for previous revisions can be represented as a revision in this object.

+

Typically, this date value will be machine-generated at the time the containing document is published.

+

In some cases, an OSCAL document may be derived from some source material provided in a different format. In such a case, the published value should indicate when the OSCAL document instance was last published, not the source material.

+ Last Modified Timestamp - The date and time the document was last modified. The date-time value must be formatted according to RFC 3339 with full time and time zone included. + The date and time the document was last stored for later retrieval. -

This value represents the point in time when the OSCAL document was last updated, or at the point of creation the creation date. Typically, this date value will be machine generated at time of creation or modification.

-

In some cases, an OSCAL document may be derived from some source material in a different format. In such a case, the last-modified value should indicate the modification time of the OSCAL document, not the source material.

-

A publisher of OSCAL content can use this data point along with its siblings published and version to establish a sequence of successive revisions of a given OSCAL-based publication. The metadata for previous revisions can be represented as a revision in this object.

+

This value represents the point in time when the OSCAL document was last updated, or at the point of creation the creation date. Typically, this date value will be machine generated at time of creation or modification. Ideally, this field will be managed by the editing tool or service used to make modifications when storing the modified document.

+

The intent of the last modified timestamp is to distinguish between significant change milestones when the document may be accessed by multiple entities. This allows a given entity to differentiate between mutiple document states at specific points in time. It is possible to make multiple modifications to the document without storing these changes. In such a case, the last modified timestamp might not be updated until the document is finally stored.

+

In some cases, an OSCAL document may be derived from some source material in a different format. In such a case, the last-modified value should indicate the last modification time of the OSCAL document instance, not the source material.

 Document Version - A string used to distinguish the current version of the document from other previous (and future) versions. + Used to distinguish a specific revision of an OSCAL document from other previous and future versions. -

A version string may be a release number, sequence number, date, or other identifier suffcient to distinguish between different document versions. This version is typically set by the document owner or by the tool used to maintain the content.

-

While not required, it is recommended that OSCAL content authors use Semantic Versioning as a format for version strings. This allows for the easy identification of a version tree consisting of major, minor, and patch numbers.

-

A publisher of OSCAL content can use this data point along with its siblings published and last-modified to establish a sequence of successive revisions of a given OSCAL-based publication. The metadata for previous revisions can be represented as a revision in this object.

+

A version may be a release number, sequence number, date, or other identifier sufficient to distinguish between different document revisions.

+

While not required, it is recommended that OSCAL content authors use Semantic Versioning as the version format. This allows for the easy identification of a version tree consisting of major, minor, and patch numbers.

+

A version is typically set by the document owner or by the tool used to maintain the content.

 - OSCAL version - The OSCAL model version the document was authored against. + OSCAL Version + The OSCAL model version the document was authored against and will conform to as valid. -

Indicates the version of the OSCAL model to which this data set conforms, for example 1.1.0 or 1.0.0-M1. That can be used as a hint by a tool to indicate which version of the OSCAL XML or JSON schema to use for validation.

+

Indicates the version of the OSCAL model to which the document conforms, for example 1.1.0 or 1.0.0-milestone1. That can be used as a hint for a tool indicating which version of the OSCAL XML or JSON schema to use for validation.

+

The OSCAL version serves a different purpose from the document version and is used to represent a different concept. If both have the same value, this is coincidental.

 Email Address - An email address as defined by RFC 5322 Section 3.4.1. - + An email address as defined by RFC 5322 Section + 3.4.1. Telephone Number - Contact number by telephone. + A telephone service number as defined by ITU-T E.164. number type flag @@ -948,6 +1057,13 @@ + + + +

Providing a country code provides an international means to interpret the phone number.

+ + + @@ -967,11 +1083,12 @@ State - State, province or analogous geographical region for mailing address + State, province or analogous geographical region for a mailing + address. Postal Code - Postal or ZIP code for mailing address + Postal or ZIP code for mailing address. Country Code @@ -1000,31 +1117,30 @@ - Document Identifier - A document identifier qualified by an identifier scheme. A document identifier provides a globally unique identifier with a cross-instance scope that is used for a group of documents that are to be treated as different versions of the same document. If this element does not appear, or if the value of this element is empty, the value of "document-id" is equal to the value of the "uuid" flag of the top-level root element. + A document identifier qualified by an identifier + scheme. identifier - - - + Document Identification Scheme - Qualifies the kind of document identifier using a URI. If the scheme is not provided the value of the element will be interpreted as a string of characters. + Qualifies the kind of document identifier using a URI. If the scheme is not + provided the value of the element will be interpreted as a string of + characters. A Digital Object Identifier (DOI); use is preferred, since this allows for retrieval of a full bibliographic record. + +

This value must be an absolute URI that serves as a naming system identifier.

+ -

This element is optional, but it will always have a valid value, as if it is missing the value of "document-id" is assumed to be equal to the UUID of the root. This requirement allows for document creators to retroactively link an update to the original version, by providing a document-id on the new document that is equal to the uuid of the original document.

+

A document identifier provides a globally unique identifier with a cross-instance scope that is used for a group of documents that are to be treated as different versions, representations or digital surrogates of the same document.

+

A document identifier provides an additional data point for identifying a document that can be assigned by a publisher or organization for purposes in a wider system, such as a digital object identifier (DOI) or a local content management system identifier.

+

Use of a document identifier allows for document creators to associate sets of documents that are related in some way by the same document-id.

+

An OSCAL document always has an implicit document identifier provided by the document's UUID, defined by the uuid on the top-level object. Having a default UUID-based identifier ensures all documents can be minimally identified when other document identifiers are not provided.

 - - - diff --git a/src/metaschema/oscal_profile_metaschema.xml b/src/metaschema/oscal_profile_metaschema.xml index b801621f4d..5d3ea80e06 100644 --- a/src/metaschema/oscal_profile_metaschema.xml +++ b/src/metaschema/oscal_profile_metaschema.xml @@ -3,15 +3,29 @@ ]> + + xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0"> OSCAL Profile Model 1.0.4 oscal-profile http://csrc.nist.gov/ns/oscal/1.0 http://csrc.nist.gov/ns/oscal -

A profile designates a selection and configuration of controls from one or more catalogs, along with a series of operations over them. The topmost element in the OSCAL profile XML schema is profile.

+

In OSCAL a profile represents a set of selected controls from one or more control catalogs. Such a set of controls can + be referenced by an OSCAL system security plan (SSP) to establish a control baseline. This effective set of controls is produced from an OSCAL + profile using a deterministic, predictable process called profile resolution.

+

A profile references one or more OSCAL catalogs or profiles to import controls for control selection and tailoring. A profile can also describe how a resulting catalog is structured. When the profile is resolved, these selections and modifications are processed to produce a resulting OSCAL catalog.

+

OSCAL profiles have uses beyond establishing control baselines, such as documentation + generation or as reference tables for validations.

 @@ -19,12 +33,18 @@ Profile - Each OSCAL profile is defined by a Profile element + Each OSCAL profile is defined by a profile + element. profile Profile Universally Unique Identifier - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference this profile elsewhere in this or other OSCAL instances. The locally defined UUID of the profile can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance).This identifier should be assigned per-subject, which means it should be consistently used to identify the same profile across revisions of the document. + Provides a globally unique means to identify a given profile instance. + + + + + @@ -37,21 +57,21 @@

An OSCAL document that describes a tailoring of controls from one or more catalogs, with possible modification of multiple controls. It provides mechanisms by which controls may be selected (import), merged or (re)structured (merge), and amended (modify). OSCAL profiles may select subsets of controls, set parameter values for them in application, and even adjust the representation of controls as given in and by a catalog. They may also serve as sources for further modification in and by other profiles, that import them.

-

See the Concepts - Identifier Use page for additional information regarding this identifier's uniqueness and scope.

 - Import resource - The import designates a catalog or profile to be included (referenced and potentially modified) by this profile. The import also identifies which controls to select using the include-all, include-controls, and exclude-controls directives. + Import Resource + Designates a referenced source catalog or profile that provides a source of control information for use in creating a new overlay or baseline. Catalog or Profile Reference A resolvable URL reference to the base catalog or profile that this profile is tailoring. -

The value of the href can be an internet resource, or an internal reference using a fragment e.g. #fragment that points to a back-matter - resource in the same document.

- -

If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references the uuid value of a resource in the document's back-matter.

-

If an internet resource is used, the href value will be an absolute or relative URL pointing to the location of the referenced resource. A relative URL will be resolved relative to the location of the document containing the link.

+

This value may be one of:

+
    +
  1. an absolute URI that points to a network resolvable resource,
    2. +
  2. a relative reference pointing to a network resolvable resource whose base URI is the URI of the containing document, or
    3. +
  3. a bare URI fragment (i.e., `#uuid`) pointing to a back-matter resource in this or an imported document (see linking to another OSCAL object).
    4. +
@@ -78,7 +98,6 @@ -

A profile must be based on an existing OSCAL catalog or another OSCAL profile. An import indicates such a source whose controls are to be included (referenced and modified) in a profile. This source will either be a catalog whose controls are given (by value), or a profile with its own control imports.

The contents of the import element indicate which controls from the source will be included. Controls from the source catalog or profile may be either selected, using the include-all or include-controls directives, or de-selected (using an exclude-controls directive).

 @@ -88,44 +107,43 @@ - Merge controls - A Merge element provides structuring directives that drive how controls are organized after resolution. + Merge Controls + Provides structuring directives that instruct how controls are organized after profile resolution. - Combination rule - A Combine element defines how to combine multiple (competing) versions of the same control. + Combination Rule + A Combine element defines how to resolve duplicate instances of the same control (e.g., controls with the same ID). - Combination method - How clashing controls should be handled + Combination Method + Declare how clashing controls should be + handled. Use the first definition - the first control with a given ID is used; subsequent ones are discarded - **(deprecated)** **(unspecified)** Merge - controls with the same ID are combined + **(deprecated)** **(unspecified)** + Merge - controls with the same ID are + combined Keep - controls with the same ID are kept, retaining the clash - + - -

Whenever combining controls from multiple (import) pathways, an issue arises of what to do with clashing invocations (multiple competing versions of a control).

-

This setting permits a profile designer to apply a rule for the resolution of such cases. In a well-designed profile (e.g. one that uses mapping), such collisions would ordinarily be avoided, but this setting can be useful for defining what to do when it occurs.

-

If no combine element appears, it is considered equivalent to providing a combine element with a method of value keep.

- - Flat - Use the flat structuring method. + Flat Without Grouping + Directs that controls appear without any grouping structure. - As-Is Structuring Directive - An As-is element indicates that the controls should be structured in resolution as they are structured in their source catalogs. It does not contain any elements or attributes. + Group As-Is + Indicates that the controls selected should retain their original grouping as defined in the import source. - Custom grouping - A Custom element frames a structure for embedding represented controls in resolution. + Custom Grouping + Provides an alternate grouping structure that selected controls will be placed in. @@ -135,25 +153,28 @@ -

The custom element represents a custom arrangement or organization of controls in the resolution of a catalog.

-

While the as-is element provides for a restitution of a control set's organization (in one or more source catalogs), this element permits the definition of an entirely different structure.

+

The custom element represents a custom arrangement or organization of controls in the resolution of a catalog. This structuring directive gives the profile author the ability to define an entirely different organization of controls as compared to their source catalog(s).

 - -

The contents of the merge element may be used to reorder or restructure controls by indicating an order and/or structure in resolution.

-

Implicitly, a merge element is also a filter: controls that are included in a profile, but not included (implicitly or explicitly) in the scope of a merge element, will not be merged into (will be dropped) in the resulting resolution.

- - Control group - A group of (selected) controls or of groups of controls + Control Group + A group of (selected) controls or of groups of controls. - + Group Identifier - A human-oriented, locally unique identifier with cross-instance scope that can be used to reference this defined group elsewhere in this or other OSCAL instances. When referenced from another OSCAL instance, this identifier must be referenced in the context of the containing resource (e.g., import-profile). This id should be assigned per-subject, which means it should be consistently used to identify the same group across revisions of the document. + Identifies the group. + + + + + + +

This optional data element is available to support hyperlinking to formal groups or families as defined in control catalogs, among other operations.

+ Group Class @@ -166,7 +187,7 @@ Group Title - A name given to the group, which may be used by a tool for display and navigation. + A name to be given to the group for use in display. @@ -194,18 +215,24 @@ - Modify controls - Set parameters or amend controls in resolution + Modify Controls + Set parameters or amend controls in resolution. Parameter Setting - A parameter setting, to be propagated to points of insertion + A parameter setting, to be propagated to points of + insertion. Parameter ID - A human-oriented, locally unique identifier with cross-instance scope that can be used to reference this defined parameter elsewhere in this or other OSCAL instances. When referenced from another OSCAL instance, this identifier must be referenced in the context of the containing resource (e.g., import-profile). This id should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + An identifier for the parameter. + + + + + Parameter Class @@ -215,7 +242,7 @@ - Depends on + Depends On **(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used. @@ -234,7 +261,8 @@ Parameter Usage Description - Describes the purpose and use of a parameter + Describes the purpose and use of a + parameter. constraint @@ -260,7 +288,7 @@ Alteration - An Alter element specifies changes to be made to an included control when a profile is resolved. + Specifies changes to be made to an included control when a profile is resolved. @@ -270,7 +298,8 @@ Reference by (assigned) name - Identify items to remove by matching their assigned name + Identify items remove by matching their + assigned name. Reference by class @@ -282,7 +311,10 @@ Item Name Reference - Identify items to remove by the name of the item's information element name, e.g. title or prop + Identify items to remove by the name of the + item's information object name, e.g. + title or + prop. A descendant parameter and all of its descendants. @@ -305,11 +337,14 @@ Addition - Specifies contents to be added into controls, in resolution + Specifies contents to be added into controls, in + resolution. Position - Where to add the new content with respect to the targeted element (beside it or inside it) + Where to add the new content with respect to + the targeted element (beside it or inside + it). Preceding the by-id target @@ -329,7 +364,6 @@ A name given to the control, which may be used by a tool for display and navigation. - @@ -343,7 +377,6 @@ - &allowed-values-control-group-property-name; @@ -372,7 +405,7 @@ - Select controls + Select Controls Specifies which controls to use in the containing context. Order @@ -407,18 +440,19 @@ - Call - Call a control by its ID + Select Control + Select a control or controls from an imported control set. Match Controls by Identifier - + Selecting a control by its ID given as a literal. Match Controls by Pattern - Select controls by (regular expression) match on ID + Selecting a set of controls by matching their IDs with a + wildcard pattern. @@ -428,7 +462,7 @@ - Include contained controls with control + Include Contained Controls with Control When a control is included, whether its child (dependent) controls are also included. diff --git a/src/metaschema/oscal_ssp_metaschema.xml b/src/metaschema/oscal_ssp_metaschema.xml index 216190339e..6c51f093dd 100644 --- a/src/metaschema/oscal_ssp_metaschema.xml +++ b/src/metaschema/oscal_ssp_metaschema.xml @@ -57,12 +57,13 @@ Profile Reference A resolvable URL reference to the profile or catalog to use as the system's control baseline. -

The value of the href can be an internet resource, or a local reference using a fragment e.g. #fragment that points to a back-matter - resource in the same document.

- -

If a local reference using a fragment is used, this will be indicated by a fragment "#" followed by an identifier which references an identified resource in the document's back-matter or another object that is within the scope of the containing OSCAL document. The identified resource will be used instead as the target resource.

-

If an internet resource is used, the href value will be an absolute or relative URI pointing to the location of the target resource. A relative URI will be resolved relative to the location of the document containing the link.

-

If the resource is an OSCAL profile, it is expected that a tool will resolve the profile according to the OSCAL [profile resolution specification](https://pages.nist.gov/OSCAL/concepts/processing/profile-resolution/) to produce a resolved profile for use when processing the containing system security plan. This allows a system security plan processor to use the baseline as a catalog of controls.

+

This value may be one of:

+
    +
  1. an absolute URI that points to a network resolvable resource,
    2. +
  2. a relative reference pointing to a network resolvable resource whose base URI is the URI of the containing document, or
    3. +
  3. a bare URI fragment (i.e., `#uuid`) pointing to a back-matter resource in this or an imported document (see linking to another OSCAL object).
    4. +
+

If the resource is an OSCAL profile, it is expected that a tool will resolve the profile according to the OSCAL profile resolution specification to produce a resolved profile for use when processing the containing system security plan. This allows a system security plan processor to use the baseline as a catalog of controls.

While it is possible to reference a previously resolved OSCAL profile as a catalog, this practice is discouraged since the unresolved form of the profile communicates more information about selections and changes to the underlying catalog. Furthermore, the underlying catalog can be maintained separately from the profile, which also has maintenance advantages for distinct maintainers, ensuring that the best available information is produced through profile resolution.

 @@ -88,6 +89,9 @@ System Name - Short A short name for the system, such as an acronym, that is suitable for display in a data table or summary list. + +

Since system-name-short is optional, if the system-name-short is not provided, the system-name can be used as a substitute.

+ System Description @@ -218,6 +222,9 @@ Based on the section identifiers in NIST Special Publication 800-60 Volume II Revision 1. + +

This value must be an absolute URI that serves as a naming system identifier.

+ @@ -274,6 +281,10 @@ + A 'low' sensitivity level as defined in FIPS-199. @@ -319,18 +330,19 @@ Security Impact Level The overall level of expected impact resulting from unauthorized disclosure, modification, or loss of access to information. + - Security Objective: Confidentiality A target-level of confidentiality for the system, based on the sensitivity of information within the system. - Security Objective: Integrity A target-level of integrity for the system, based on the sensitivity of information within the system. - Security Objective: Availability A target-level of availability for the system, based on the sensitivity of information within the system.