Skip to main content

Complete v1.0.4 JSON Format Reference

The following is the JSON format reference for the combination of all OSCAL models, which is organized hierarchically. Each entry represents the corresponding JSON property in the model's JSON format, and provides details about the semantics and use of the property. The JSON Format Outline provides a streamlined, hierarchical representation of this model's JSON format which can be used along with this reference to better understand the JSON representation of this model.

JSON Base URI http://csrc.nist.gov/ns/oscal/1.0

This format represents a combination of all of the OSCAL models.

Description A collection of controls.

Remarks

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.

Constraints (2)

allowed value for metadata/prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • resolution-tool: The tool used to produce a resolved profile.

allowed value for metadata/link/@rel

The value must be one of the following:

  • source-profile: The tool used to produce a resolved profile.
Properties (6)

uuid

uuid

[1]

Catalog Universally Unique Identifier

Description A globally unique identifier with cross-instance scope for this catalog instance. This UUID should be changed when this document is revised.

metadata

object
(global definition)

[1]

Publication metadata

Description Provides information about the publication and availability of the containing document.

Constraints (13)

index for role an index index-metadata-role-ids shall list values returned by targets role using keys constructed of key field(s) @id

is unique for document-id: any target value must be unique (i.e., occur only once)

is unique for prop: any target value must be unique (i.e., occur only once)

index for .//prop an index index-metadata-property-uuid shall list values returned by targets .//prop using keys constructed of key field(s) @uuid

is unique for link: any target value must be unique (i.e., occur only once)

index for role an index index-metadata-role-id shall list values returned by targets role using keys constructed of key field(s) @id

index for location an index index-metadata-location-uuid shall list values returned by targets location using keys constructed of key field(s) @uuid

index for party an index index-metadata-party-uuid shall list values returned by targets party using keys constructed of key field(s) @uuid

index for party[@type='organization'] an index index-metadata-party-organizations-uuid shall list values returned by targets party[@type='organization'] using keys constructed of key field(s) @uuid

is unique for responsible-party: any target value must be unique (i.e., occur only once)

allowed values for responsible-party/@role-id

The value may be locally defined, or one of the following:

  • creator: Indicates the organization that created this content.
  • prepared-by: Indicates the organization that prepared this content.
  • prepared-for: Indicates the organization for which this content was created.
  • content-approver: Indicates the organization responsible for all content represented in the "document".
  • contact: Indicates the organization to contact for questions or support related to this content.

allowed value for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • keywords: 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.

allowed values for link/@rel

The value may be locally defined, or one of the following:

  • canonical: The link identifies the authoritative location for this file. Defined by RFC 6596.
  • alternate: The link identifies an alternative location or format for this file. Defined by the HTML Living Standard
  • latest-version: This link identifies a resource containing the latest version in the version history. Defined by RFC 5829.
  • predecessor-version: This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829.
  • successor-version: This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829.
Properties (14)

title

markup-line

[1]

Document Title

Description A name given to the document, which may be used by a tool for display and navigation.

published

dateTime-with-timezone

[0 or 1]

Publication Timestamp

Description 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.

Remarks

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.

last-modified

dateTime-with-timezone

[1]

Last Modified Timestamp

Description 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.

Remarks

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.

version

string

[1]

Document Version

Description A string used to distinguish the current version of the document from other previous (and future) versions.

Remarks

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.

oscal-version

string

[1]

OSCAL version

Description The OSCAL model version the document was authored against.

Remarks

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.

revisions

array

[0 or 1]

(array member)

object

[1 to ∞]

Revision History Entry

Description An entry in a sequential list of revisions to the containing document in reverse chronological order (i.e., most recent previous revision first).

Remarks

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.

Constraint (1)

allowed values for link/@rel

The value may be locally defined, or one of the following:

  • canonical: The link identifies the authoritative location for this file. Defined by RFC 6596.
  • alternate: The link identifies an alternative location or format for this file. Defined by the HTML Living Standard
  • predecessor-version: This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829.
  • successor-version: This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829.
Properties (8)

title

markup-line

[0 or 1]

Document Title

Description A name given to the document revision, which may be used by a tool for display and navigation.

published

dateTime-with-timezone

[0 or 1]

Publication Timestamp

Description 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.

Remarks

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.

last-modified

dateTime-with-timezone

[0 or 1]

Last Modified Timestamp

Description 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.

Remarks

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.

version

string

[1]

Document Version

Description A string used to distinguish the current version of the document from other previous (and future) versions.

Remarks

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.

oscal-version

string

[0 or 1]

OSCAL version

Description The OSCAL model version the document was authored against.

Remarks

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.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

document-ids

array

[0 or 1]

(array member)

string

[0 to ∞]

Document Identifier

Description 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.

Remarks

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.

Properties (2)

scheme

uri

[0 or 1]

Document Identification Scheme

Description 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.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • http://www.doi.org/: A Digital Object Identifier (DOI); use is preferred, since this allows for retrieval of a full bibliographic record.

identifier

string

[0 or 1]

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)

name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.

uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)

href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

roles

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Role

Description Defines a function assumed or expected to be assumed by a party in a specific situation.

Remarks

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.

Properties (7)

id

token

[1]

Role Identifier

Description 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.

title

markup-line

[1]

Role Title

Description A name given to the role, which may be used by a tool for display and navigation.

short-name

string

[0 or 1]

Role Short Name

Description A short common name, abbreviation, or acronym for the role.

description

markup-multiline

[0 or 1]

Role Description

Description A summary of the role's purpose and associated responsibilities.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

locations

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Location

Description A location, with associated metadata that can be referenced.

Constraints (3)

allowed value for prop/@name

The value may be locally defined, or the following:

  • type: Characterizes the kind of location.

allowed value for prop[@name='type']/@value

The value may be locally defined, or the following:

  • data-center: A location that contains computing assets. A class can be used to indicate the sub-type of data-center as primary or alternate.

allowed values for prop[@name='type' and @value='data-center']/@class

The value may be locally defined, or one of the following:

  • primary: The location is a data-center used for normal operations.
  • alternate: The location is a data-center used for fail-over or backup operations.
Properties (9)

uuid

uuid

[1]

Location Universally Unique Identifier

Description 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.

title

markup-line

[0 or 1]

Location Title

Description A name given to the location, which may be used by a tool for display and navigation.

address

object

[1]

Address

Description A postal address for the location.

Remarks

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

Properties (6)
type

token

[0 or 1]

Address Type

Description Indicates the type of address.

Constraint (1)

allowed values

The value may be locally defined, or one of the following:

  • home: A home address.
  • work: A work address.
addr-lines

array

[0 or 1]

(array member)

string

[0 to ∞]

Address line

Description A single line of an address.

city

string

[0 or 1]

City

Description City, town or geographical region for the mailing address.

state

string

[0 or 1]

State

Description State, province or analogous geographical region for mailing address

postal-code

string

[0 or 1]

Postal Code

Description Postal or ZIP code for mailing address

country

string

[0 or 1]

Country Code

Description The ISO 3166-1 alpha-2 country code for the mailing address.

Constraint (1)

matches: a target (value) must match the regular expression '[A-Z]{2}'.

email-addresses

array

[0 or 1]

(array member)

email

[0 to ∞]

Email Address

Description An email address as defined by RFC 5322 Section 3.4.1.

Remarks

This is a contact email associated with the location.

telephone-numbers

array

[0 or 1]

(array member)

string

[0 to ∞]

Telephone Number

Description Contact number by telephone.

Remarks

A phone number used to contact the location.

Properties (2)
type

string

[0 or 1]

type flag

Description Indicates the type of phone number.

Constraint (1)

allowed values

The value may be locally defined, or one of the following:

  • home: A home phone number.
  • office: An office phone number.
  • mobile: A mobile phone number.
number

string

[0 or 1]

urls

array

[0 or 1]

(array member)

uri

[0 to ∞]

Location URL

Description The uniform resource locator (URL) for a web site or Internet presence associated with the location.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

parties

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Party (organization or person)

Description A responsible entity which is either a person or an organization.

Constraint (1)

allowed values for prop/@name

The value must be one of the following:

  • mail-stop: A mail stop associated with the party.
  • office: The name or number of the party's office.
  • job-title: The formal job title of a person.
Properties (12)

uuid

uuid

[1]

Party Universally Unique Identifier

Description 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.

type

string

[1]

Party Type

Description A category describing the kind of party the object describes.

Constraint (1)

allowed values

The value must be one of the following:

  • person: An individual.
  • organization: A group of individuals formed for a specific purpose.

name

string

[0 or 1]

Party Name

Description The full name of the party. This is typically the legal name associated with the party.

short-name

string

[0 or 1]

Party Short Name

Description A short common name, abbreviation, or acronym for the party.

external-ids

array

[0 or 1]

(array member)

string

[0 to ∞]

Party External Identifier

Description An identifier for a person or organization using a designated scheme. e.g. an Open Researcher and Contributor ID (ORCID)

Properties (2)
scheme

uri

[1]

External Identifier Schema

Description Indicates the type of external identifier.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • http://orcid.org/: The identifier is Open Researcher and Contributor ID (ORCID).

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

email-addresses

array

[0 or 1]

(array member)

email

[0 to ∞]

Email Address

Description An email address as defined by RFC 5322 Section 3.4.1.

Remarks

This is a contact email associated with the party.

telephone-numbers

array

[0 or 1]

(array member)

string

[0 to ∞]

Telephone Number

Description Contact number by telephone.

Remarks

A phone number used to contact the party.

Properties (2)
type

string

[0 or 1]

type flag

Description Indicates the type of phone number.

Constraint (1)

allowed values

The value may be locally defined, or one of the following:

  • home: A home phone number.
  • office: An office phone number.
  • mobile: A mobile phone number.
number

string

[0 or 1]

A choice:

addresses

array

[0 or 1]

(array member)

object

[1 to ∞]

Address

Description A postal address for the location.

Properties (6)
type

token

[0 or 1]

Address Type

Description Indicates the type of address.

Constraint (1)

allowed values

The value may be locally defined, or one of the following:

  • home: A home address.
  • work: A work address.
addr-lines

array

[0 or 1]

(array member)

string

[0 to ∞]

Address line

Description A single line of an address.

city

string

[0 or 1]

City

Description City, town or geographical region for the mailing address.

state

string

[0 or 1]

State

Description State, province or analogous geographical region for mailing address

postal-code

string

[0 or 1]

Postal Code

Description Postal or ZIP code for mailing address

country

string

[0 or 1]

Country Code

Description The ISO 3166-1 alpha-2 country code for the mailing address.

Constraint (1)

matches: a target (value) must match the regular expression '[A-Z]{2}'.

location-uuids

array

[0 or 1]

(array member)

uuid

[0 to ∞]

Location Reference

Description 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).

Remarks

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

Constraint (1)

index has keythis value must correspond to a listing in the index index-metadata-location-uuid using a key constructed of key field(s) .

member-of-organizations

array

[0 or 1]

(array member)

uuid

[0 to ∞]

Organizational Affiliation

Description 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).

Remarks

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

Constraint (1)

index has keythis value must correspond to a listing in the index index-metadata-party-organizations-uuid using a key constructed of key field(s) .

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

responsible-parties

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Responsible Party

Description A reference to a set of organizations or persons that have responsibility for performing a referenced role in the context of the containing object.

Constraints (2)

index has keythis value must correspond to a listing in the index index-metadata-role-id using a key constructed of key field(s) @role-id

index has key for party-uuidthis value must correspond to a listing in the index index-metadata-party-uuid using a key constructed of key field(s) .

Properties (5)

role-id

token

[1]

Responsible Role

Description A human-oriented identifier reference to roles served by the user.

party-uuids

array

[1]

(array member)

uuid

[1 to ∞]

Party Reference

Description 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).

Remarks

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

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

Constraint (1)

index has keythis value must correspond to a listing in the index index-metadata-party-uuid using a key constructed of key field(s) .

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

params

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Parameter

Description Parameters provide a mechanism for the dynamic assignment of value(s) in a control.

Remarks

In a catalog, a parameter is typically used as a placeholder for the future assignment of a parameter value, although the OSCAL model allows for the direct assignment of a value if desired by the control author. The value may be optionally used to specify one or more values. If no value is provided, then it is expected that the value will be provided at the Profile or Implementation layer.

A parameter can include a variety of metadata options that support the future solicitation of one or more values. A label provides a textual placeholder that can be used in a tool to solicit parameter value input, or to display in catalog documentation. The desc provides a short description of what the parameter is used for, which can be used in tooling to help a user understand how to use the parameter. A constraint can be used to provide criteria for the allowed values. A guideline provides a recommendation for the use of a parameter.

Constraints (2)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
  • alt-label: An alternate to the value provided by the parameter's label. This will typically be qualified by a class.

allowed value for prop[has-oscal-namespace('http://csrc.nist.gov/ns/rmf')]/@name

The value must be one of the following:

  • aggregates: The parent parameter provides an aggregation of 2 or more other parameters, each described by this property.
Properties (11)

id

token

[1]

Parameter Identifier

Description 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.

class

token

[0 or 1]

Parameter Class

Description A textual label that provides a characterization of the parameter.

Remarks

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

depends-on

token

[0 or 1]

Depends on

Description **(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)

name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.

uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)

href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

label

markup-line

[0 or 1]

Parameter Label

Description A short, placeholder name for the parameter, which can be used as a substitute for a value if no value is assigned.

Remarks

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

usage

markup-multiline

[0 or 1]

Parameter Usage Description

Description Describes the purpose and use of a parameter

constraints

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Constraint

Description A formal or informal expression of a constraint or test

Properties (2)

description

markup-multiline

[0 or 1]

Constraint Description

Description A textual summary of the constraint to be applied.

tests

array

[0 or 1]

(array member)

object

[1 to ∞]

Constraint Test

Description A test expression which is expected to be evaluated by a tool.

Properties (2)
expression

string

[1]

Constraint test

Description A formal (executable) expression of a constraint

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

guidelines

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Guideline

Description A prose statement that provides a recommendation for the use of a parameter.

Property (1)

prose

markup-multiline

[1]

Guideline Text

Description Prose permits multiple paragraphs, lists, tables etc.

A choice:

values

array

[0 or 1]

(array member)

string

[0 to ∞]

Parameter Value

Description A parameter value or set of values.

Remarks

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

select

object
(global definition)

[0 or 1]

Selection

Description Presenting a choice among alternatives

Remarks

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

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

Properties (2)

how-many

token

[0 or 1]

Parameter Cardinality

Description Describes the number of selections that must occur. Without this setting, only one value should be assumed to be permitted.

Constraint (1)

allowed values

The value must be one of the following:

  • one: Only one value is permitted.
  • one-or-more: One or more values are permitted.

choice

array

[0 or 1]

(array member)

markup-line

[0 to ∞]

Choice

Description A value selection among several such options

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

controls

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Control

Description 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.

Remarks

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.

Constraints (10)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
  • status: 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 value for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name='status']/@value

The value must be one of the following:

  • withdrawn: The control is no longer used.

allowed values for link/@rel

The value may be locally defined, or one of the following:

  • reference: The link cites an external resource related to this control.
  • related: The link identifies another control with bearing to this control.
  • required: The link identifies another control that must be present if this control is present.
  • incorporated-into: The link identifies other control content where this control content is now addressed.
  • moved-to: The containing control definition was moved to the referenced control.

allowed values for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • overview: An introduction to a control or a group of controls.
  • statement: A set of control implementation requirements.
  • guidance: Additional information to consider when selecting, implementing, assessing, and monitoring a control.
  • assessment: **(deprecated)** Use 'assessment-method' instead.
  • assessment-method: The part describes a method-based assessment over a set of assessment objects.

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name='statement']//part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • item: An individual item within a control statement.
  • Nested statement parts are "item" parts.

allowed values for .//part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • objective: **(deprecated)** Use 'assessment-objective' instead.
  • assessment-objective: The part describes a set of assessment objectives.
  • Objectives can be nested.

allowed values for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • objects: **(deprecated)** Use 'assessment-objects' instead.
  • assessment-objects: Provides a listing of assessment objects.
  • Assessment objects appear on assessment methods.

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • method: **(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".

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/prop[has-oscal-namespace('http://csrc.nist.gov/ns/rmf')]/@name

The value must be one of the following:

  • method: The assessment method to use. This typically appears on parts with the name "assessment".

allowed values for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/prop[has-oscal-namespace(('http://csrc.nist.gov/ns/oscal','http://csrc.nist.gov/ns/rmf')) and @name='method']/@value

The value must be one of the following:

  • INTERVIEW: 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.
  • EXAMINE: The process of reviewing, inspecting, observing, studying, or analyzing one or more assessment objects (i.e., specifications, mechanisms, or activities).
  • TEST: The process of exercising one or more assessment objects (i.e., activities or mechanisms) under specified conditions to compare actual with expected behavior.
Properties (8)

id

token

[1]

Control Identifier

Description 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.

class

token

[0 or 1]

Control Class

Description A textual label that provides a sub-type or characterization of the control.

Remarks

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.

title

markup-line

[1]

Control Title

Description A name given to the control, which may be used by a tool for display and navigation.

params

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Parameter

Description Parameters provide a mechanism for the dynamic assignment of value(s) in a control.

Remarks

In a catalog, a parameter is typically used as a placeholder for the future assignment of a parameter value, although the OSCAL model allows for the direct assignment of a value if desired by the control author. The value may be optionally used to specify one or more values. If no value is provided, then it is expected that the value will be provided at the Profile or Implementation layer.

A parameter can include a variety of metadata options that support the future solicitation of one or more values. A label provides a textual placeholder that can be used in a tool to solicit parameter value input, or to display in catalog documentation. The desc provides a short description of what the parameter is used for, which can be used in tooling to help a user understand how to use the parameter. A constraint can be used to provide criteria for the allowed values. A guideline provides a recommendation for the use of a parameter.

Constraints (2)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
  • alt-label: An alternate to the value provided by the parameter's label. This will typically be qualified by a class.

allowed value for prop[has-oscal-namespace('http://csrc.nist.gov/ns/rmf')]/@name

The value must be one of the following:

  • aggregates: The parent parameter provides an aggregation of 2 or more other parameters, each described by this property.
Properties (11)

id

token

[1]

Parameter Identifier

Description 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.

class

token

[0 or 1]

Parameter Class

Description A textual label that provides a characterization of the parameter.

Remarks

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

depends-on

token

[0 or 1]

Depends on

Description **(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

label

markup-line

[0 or 1]

Parameter Label

Description A short, placeholder name for the parameter, which can be used as a substitute for a value if no value is assigned.

Remarks

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

usage

markup-multiline

[0 or 1]

Parameter Usage Description

Description Describes the purpose and use of a parameter

constraints

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Constraint

Description A formal or informal expression of a constraint or test

Properties (2)
description

markup-multiline

[0 or 1]

Constraint Description

Description A textual summary of the constraint to be applied.

tests

array

[0 or 1]

(array member)

object

[1 to ∞]

Constraint Test

Description A test expression which is expected to be evaluated by a tool.

Properties (2)
expression

string

[1]

Constraint test

Description A formal (executable) expression of a constraint

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

guidelines

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Guideline

Description A prose statement that provides a recommendation for the use of a parameter.

Property (1)
prose

markup-multiline

[1]

Guideline Text

Description Prose permits multiple paragraphs, lists, tables etc.

A choice:

values

array

[0 or 1]

(array member)

string

[0 to ∞]

Parameter Value

Description A parameter value or set of values.

Remarks

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

select

object
(global definition)

[0 or 1]

Selection

Description Presenting a choice among alternatives

Remarks

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

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

Properties (2)
how-many

token

[0 or 1]

Parameter Cardinality

Description Describes the number of selections that must occur. Without this setting, only one value should be assumed to be permitted.

Constraint (1)

allowed values

The value must be one of the following:

  • one: Only one value is permitted.
  • one-or-more: One or more values are permitted.
choice

array

[0 or 1]

(array member)

markup-line

[0 to ∞]

Choice

Description A value selection among several such options

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)

name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.

uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)

href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

parts

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Part

Description A partition of a control's definition or a child of another part.

Remarks

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.

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.

Constraint (1)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
Properties (9)

id

token

[0 or 1]

Part Identifier

Description 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.

name

token

[1]

Part Name

Description A textual label that uniquely identifies the part's semantic type.

ns

uri

[0 or 1]

Part Namespace

Description A namespace qualifying the part's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

class

token

[0 or 1]

Part Class

Description 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.

Remarks

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.

title

markup-line

[0 or 1]

Part Title

Description A name given to the part, which may be used by a tool for display and navigation.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

prose

markup-multiline

[0 or 1]

Part Text

Description Permits multiple paragraphs, lists, tables etc.

parts

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Part

Description A partition of a control's definition or a child of another part.

Remarks

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.

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.

Constraint (1)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

controls

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Control

Description 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.

Remarks

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.

Constraints (10)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
  • status: 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 value for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name='status']/@value

The value must be one of the following:

  • withdrawn: The control is no longer used.

allowed values for link/@rel

The value may be locally defined, or one of the following:

  • reference: The link cites an external resource related to this control.
  • related: The link identifies another control with bearing to this control.
  • required: The link identifies another control that must be present if this control is present.
  • incorporated-into: The link identifies other control content where this control content is now addressed.
  • moved-to: The containing control definition was moved to the referenced control.

allowed values for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • overview: An introduction to a control or a group of controls.
  • statement: A set of control implementation requirements.
  • guidance: Additional information to consider when selecting, implementing, assessing, and monitoring a control.
  • assessment: **(deprecated)** Use 'assessment-method' instead.
  • assessment-method: The part describes a method-based assessment over a set of assessment objects.

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name='statement']//part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • item: An individual item within a control statement.
  • Nested statement parts are "item" parts.

allowed values for .//part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • objective: **(deprecated)** Use 'assessment-objective' instead.
  • assessment-objective: The part describes a set of assessment objectives.
  • Objectives can be nested.

allowed values for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • objects: **(deprecated)** Use 'assessment-objects' instead.
  • assessment-objects: Provides a listing of assessment objects.
  • Assessment objects appear on assessment methods.

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • method: **(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".

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/prop[has-oscal-namespace('http://csrc.nist.gov/ns/rmf')]/@name

The value must be one of the following:

  • method: The assessment method to use. This typically appears on parts with the name "assessment".

allowed values for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/prop[has-oscal-namespace(('http://csrc.nist.gov/ns/oscal','http://csrc.nist.gov/ns/rmf')) and @name='method']/@value

The value must be one of the following:

  • INTERVIEW: 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.
  • EXAMINE: The process of reviewing, inspecting, observing, studying, or analyzing one or more assessment objects (i.e., specifications, mechanisms, or activities).
  • TEST: The process of exercising one or more assessment objects (i.e., activities or mechanisms) under specified conditions to compare actual with expected behavior.

groups

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Control Group

Description A group of controls, or of groups of controls.

Remarks

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.

Constraints (2)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • overview: An introduction to a control or a group of controls.
Properties (8)

id

token

[0 or 1]

Group Identifier

Description 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.

class

token

[0 or 1]

Group Class

Description A textual label that provides a sub-type or characterization of the group.

Remarks

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.

title

markup-line

[1]

Group Title

Description A name given to the group, which may be used by a tool for display and navigation.

params

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Parameter

Description Parameters provide a mechanism for the dynamic assignment of value(s) in a control.

Remarks

In a catalog, a parameter is typically used as a placeholder for the future assignment of a parameter value, although the OSCAL model allows for the direct assignment of a value if desired by the control author. The value may be optionally used to specify one or more values. If no value is provided, then it is expected that the value will be provided at the Profile or Implementation layer.

A parameter can include a variety of metadata options that support the future solicitation of one or more values. A label provides a textual placeholder that can be used in a tool to solicit parameter value input, or to display in catalog documentation. The desc provides a short description of what the parameter is used for, which can be used in tooling to help a user understand how to use the parameter. A constraint can be used to provide criteria for the allowed values. A guideline provides a recommendation for the use of a parameter.

Constraints (2)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
  • alt-label: An alternate to the value provided by the parameter's label. This will typically be qualified by a class.

allowed value for prop[has-oscal-namespace('http://csrc.nist.gov/ns/rmf')]/@name

The value must be one of the following:

  • aggregates: The parent parameter provides an aggregation of 2 or more other parameters, each described by this property.
Properties (11)

id

token

[1]

Parameter Identifier

Description 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.

class

token

[0 or 1]

Parameter Class

Description A textual label that provides a characterization of the parameter.

Remarks

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

depends-on

token

[0 or 1]

Depends on

Description **(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

label

markup-line

[0 or 1]

Parameter Label

Description A short, placeholder name for the parameter, which can be used as a substitute for a value if no value is assigned.

Remarks

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

usage

markup-multiline

[0 or 1]

Parameter Usage Description

Description Describes the purpose and use of a parameter

constraints

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Constraint

Description A formal or informal expression of a constraint or test

Properties (2)
description

markup-multiline

[0 or 1]

Constraint Description

Description A textual summary of the constraint to be applied.

tests

array

[0 or 1]

(array member)

object

[1 to ∞]

Constraint Test

Description A test expression which is expected to be evaluated by a tool.

Properties (2)
expression

string

[1]

Constraint test

Description A formal (executable) expression of a constraint

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

guidelines

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Guideline

Description A prose statement that provides a recommendation for the use of a parameter.

Property (1)
prose

markup-multiline

[1]

Guideline Text

Description Prose permits multiple paragraphs, lists, tables etc.

A choice:

values

array

[0 or 1]

(array member)

string

[0 to ∞]

Parameter Value

Description A parameter value or set of values.

Remarks

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

select

object
(global definition)

[0 or 1]

Selection

Description Presenting a choice among alternatives

Remarks

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

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

Properties (2)
how-many

token

[0 or 1]

Parameter Cardinality

Description Describes the number of selections that must occur. Without this setting, only one value should be assumed to be permitted.

Constraint (1)

allowed values

The value must be one of the following:

  • one: Only one value is permitted.
  • one-or-more: One or more values are permitted.
choice

array

[0 or 1]

(array member)

markup-line

[0 to ∞]

Choice

Description A value selection among several such options

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)

name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.

uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)

href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

parts

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Part

Description A partition of a control's definition or a child of another part.

Remarks

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.

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.

Constraint (1)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
Properties (9)

id

token

[0 or 1]

Part Identifier

Description 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.

name

token

[1]

Part Name

Description A textual label that uniquely identifies the part's semantic type.

ns

uri

[0 or 1]

Part Namespace

Description A namespace qualifying the part's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

class

token

[0 or 1]

Part Class

Description 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.

Remarks

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.

title

markup-line

[0 or 1]

Part Title

Description A name given to the part, which may be used by a tool for display and navigation.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

prose

markup-multiline

[0 or 1]

Part Text

Description Permits multiple paragraphs, lists, tables etc.

parts

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Part

Description A partition of a control's definition or a child of another part.

Remarks

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.

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.

Constraint (1)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

A choice:

groups

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Control Group

Description A group of controls, or of groups of controls.

Remarks

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.

Constraints (2)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • overview: An introduction to a control or a group of controls.

controls

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Control

Description 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.

Remarks

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.

Constraints (10)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
  • status: 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 value for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name='status']/@value

The value must be one of the following:

  • withdrawn: The control is no longer used.

allowed values for link/@rel

The value may be locally defined, or one of the following:

  • reference: The link cites an external resource related to this control.
  • related: The link identifies another control with bearing to this control.
  • required: The link identifies another control that must be present if this control is present.
  • incorporated-into: The link identifies other control content where this control content is now addressed.
  • moved-to: The containing control definition was moved to the referenced control.

allowed values for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • overview: An introduction to a control or a group of controls.
  • statement: A set of control implementation requirements.
  • guidance: Additional information to consider when selecting, implementing, assessing, and monitoring a control.
  • assessment: **(deprecated)** Use 'assessment-method' instead.
  • assessment-method: The part describes a method-based assessment over a set of assessment objects.

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name='statement']//part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • item: An individual item within a control statement.
  • Nested statement parts are "item" parts.

allowed values for .//part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • objective: **(deprecated)** Use 'assessment-objective' instead.
  • assessment-objective: The part describes a set of assessment objectives.
  • Objectives can be nested.

allowed values for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • objects: **(deprecated)** Use 'assessment-objects' instead.
  • assessment-objects: Provides a listing of assessment objects.
  • Assessment objects appear on assessment methods.

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • method: **(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".

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/prop[has-oscal-namespace('http://csrc.nist.gov/ns/rmf')]/@name

The value must be one of the following:

  • method: The assessment method to use. This typically appears on parts with the name "assessment".

allowed values for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/prop[has-oscal-namespace(('http://csrc.nist.gov/ns/oscal','http://csrc.nist.gov/ns/rmf')) and @name='method']/@value

The value must be one of the following:

  • INTERVIEW: 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.
  • EXAMINE: The process of reviewing, inspecting, observing, studying, or analyzing one or more assessment objects (i.e., specifications, mechanisms, or activities).
  • TEST: The process of exercising one or more assessment objects (i.e., activities or mechanisms) under specified conditions to compare actual with expected behavior.
Properties (8)

id

token

[1]

Control Identifier

Description 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.

class

token

[0 or 1]

Control Class

Description A textual label that provides a sub-type or characterization of the control.

Remarks

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.

title

markup-line

[1]

Control Title

Description A name given to the control, which may be used by a tool for display and navigation.

params

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Parameter

Description Parameters provide a mechanism for the dynamic assignment of value(s) in a control.

Remarks

In a catalog, a parameter is typically used as a placeholder for the future assignment of a parameter value, although the OSCAL model allows for the direct assignment of a value if desired by the control author. The value may be optionally used to specify one or more values. If no value is provided, then it is expected that the value will be provided at the Profile or Implementation layer.

A parameter can include a variety of metadata options that support the future solicitation of one or more values. A label provides a textual placeholder that can be used in a tool to solicit parameter value input, or to display in catalog documentation. The desc provides a short description of what the parameter is used for, which can be used in tooling to help a user understand how to use the parameter. A constraint can be used to provide criteria for the allowed values. A guideline provides a recommendation for the use of a parameter.

Constraints (2)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
  • alt-label: An alternate to the value provided by the parameter's label. This will typically be qualified by a class.

allowed value for prop[has-oscal-namespace('http://csrc.nist.gov/ns/rmf')]/@name

The value must be one of the following:

  • aggregates: The parent parameter provides an aggregation of 2 or more other parameters, each described by this property.
Properties (11)
id

token

[1]

Parameter Identifier

Description 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.

class

token

[0 or 1]

Parameter Class

Description A textual label that provides a characterization of the parameter.

Remarks

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

depends-on

token

[0 or 1]

Depends on

Description **(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

label

markup-line

[0 or 1]

Parameter Label

Description A short, placeholder name for the parameter, which can be used as a substitute for a value if no value is assigned.

Remarks

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

usage

markup-multiline

[0 or 1]

Parameter Usage Description

Description Describes the purpose and use of a parameter

constraints

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Constraint

Description A formal or informal expression of a constraint or test

Properties (2)
description

markup-multiline

[0 or 1]

Constraint Description

Description A textual summary of the constraint to be applied.

tests

array

[0 or 1]

(array member)

object

[1 to ∞]

Constraint Test

Description A test expression which is expected to be evaluated by a tool.

Properties (2)

expression

string

[1]

Constraint test

Description A formal (executable) expression of a constraint

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

guidelines

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Guideline

Description A prose statement that provides a recommendation for the use of a parameter.

Property (1)
prose

markup-multiline

[1]

Guideline Text

Description Prose permits multiple paragraphs, lists, tables etc.

A choice:

values

array

[0 or 1]

(array member)

string

[0 to ∞]

Parameter Value

Description A parameter value or set of values.

Remarks

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

select

object
(global definition)

[0 or 1]

Selection

Description Presenting a choice among alternatives

Remarks

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

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

Properties (2)
how-many

token

[0 or 1]

Parameter Cardinality

Description Describes the number of selections that must occur. Without this setting, only one value should be assumed to be permitted.

Constraint (1)

allowed values

The value must be one of the following:

  • one: Only one value is permitted.
  • one-or-more: One or more values are permitted.
choice

array

[0 or 1]

(array member)

markup-line

[0 to ∞]

Choice

Description A value selection among several such options

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

parts

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Part

Description A partition of a control's definition or a child of another part.

Remarks

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.

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.

Constraint (1)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
Properties (9)
id

token

[0 or 1]

Part Identifier

Description 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.

name

token

[1]

Part Name

Description A textual label that uniquely identifies the part's semantic type.

ns

uri

[0 or 1]

Part Namespace

Description A namespace qualifying the part's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

class

token

[0 or 1]

Part Class

Description 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.

Remarks

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.

title

markup-line

[0 or 1]

Part Title

Description A name given to the part, which may be used by a tool for display and navigation.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

prose

markup-multiline

[0 or 1]

Part Text

Description Permits multiple paragraphs, lists, tables etc.

parts

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Part

Description A partition of a control's definition or a child of another part.

Remarks

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.

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.

Constraint (1)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

controls

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Control

Description 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.

Remarks

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.

Constraints (10)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
  • status: 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 value for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name='status']/@value

The value must be one of the following:

  • withdrawn: The control is no longer used.

allowed values for link/@rel

The value may be locally defined, or one of the following:

  • reference: The link cites an external resource related to this control.
  • related: The link identifies another control with bearing to this control.
  • required: The link identifies another control that must be present if this control is present.
  • incorporated-into: The link identifies other control content where this control content is now addressed.
  • moved-to: The containing control definition was moved to the referenced control.

allowed values for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • overview: An introduction to a control or a group of controls.
  • statement: A set of control implementation requirements.
  • guidance: Additional information to consider when selecting, implementing, assessing, and monitoring a control.
  • assessment: **(deprecated)** Use 'assessment-method' instead.
  • assessment-method: The part describes a method-based assessment over a set of assessment objects.

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name='statement']//part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • item: An individual item within a control statement.
  • Nested statement parts are "item" parts.

allowed values for .//part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • objective: **(deprecated)** Use 'assessment-objective' instead.
  • assessment-objective: The part describes a set of assessment objectives.
  • Objectives can be nested.

allowed values for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • objects: **(deprecated)** Use 'assessment-objects' instead.
  • assessment-objects: Provides a listing of assessment objects.
  • Assessment objects appear on assessment methods.

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • method: **(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".

allowed value for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/prop[has-oscal-namespace('http://csrc.nist.gov/ns/rmf')]/@name

The value must be one of the following:

  • method: The assessment method to use. This typically appears on parts with the name "assessment".

allowed values for part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name=('assessment','assessment-method')]/prop[has-oscal-namespace(('http://csrc.nist.gov/ns/oscal','http://csrc.nist.gov/ns/rmf')) and @name='method']/@value

The value must be one of the following:

  • INTERVIEW: 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.
  • EXAMINE: The process of reviewing, inspecting, observing, studying, or analyzing one or more assessment objects (i.e., specifications, mechanisms, or activities).
  • TEST: The process of exercising one or more assessment objects (i.e., activities or mechanisms) under specified conditions to compare actual with expected behavior.

back-matter

object
(global definition)

[0 or 1]

Back matter

Description A collection of resources, which may be included directly or by reference.

Remarks

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.

Back matter including references and resources.

Constraint (1)

index for resource an index index-back-matter-resource shall list values returned by targets resource using keys constructed of key field(s) @uuid

Property (1)

resources

array

[0 or 1]

(array member)

object

[1 to ∞]

Resource

Description 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.

Remarks

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.

Constraints (6)

allowed values for prop/@name

The value must be one of the following:

  • type: Identifies the type of resource represented.
  • version: For resources representing a published document, this represents the version number of that document.
  • published: For resources representing a published document, this represents the publication date of that document.

matches for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name='published']/@value: the target value must match the lexical form of the 'dateTime' data type.

allowed values for prop[@name='type']/@value

The value may be locally defined, or one of the following:

  • logo: Indicates the resource is an organization's logo.
  • image: Indicates the resource represents an image.
  • screen-shot: Indicates the resource represents an image of screen content.
  • law: Indicates the resource represents an applicable law.
  • regulation: Indicates the resource represents an applicable regulation.
  • standard: Indicates the resource represents an applicable standard.
  • external-guidance: Indicates the resource represents applicable guidance.
  • acronyms: Indicates the resource provides a list of relevant acronyms.
  • citation: Indicates the resource cites relevant information.
  • policy: Indicates the resource is a policy.
  • procedure: Indicates the resource is a procedure.
  • system-guide: Indicates the resource is guidance document related to the subject system of an SSP.
  • users-guide: Indicates the resource is guidance document a user's guide or administrator's guide.
  • administrators-guide: Indicates the resource is guidance document a administrator's guide.
  • rules-of-behavior: Indicates the resource represents rules of behavior content.
  • plan: Indicates the resource represents a plan.
  • artifact: Indicates the resource represents an artifact, such as may be reviewed by an assessor.
  • evidence: Indicates the resource represents evidence, such as to support an assessment findiing.
  • tool-output: Indicates the resource represents output from a tool.
  • raw-data: Indicates the resource represents machine data, which may require a tool or analysis for interpretation or presentation.
  • interview-notes: Indicates the resource represents notes from an interview, such as may be collected during an assessment.
  • questionnaire: Indicates the resource is a set of questions, possibly with responses.
  • report: Indicates the resource is a report.
  • agreement: Indicates the resource is a formal agreement between two or more parties.

has cardinality for rlink|base64 the cardinality of rlink|base64 is constrained: 1; maximum unbounded.

is unique for rlink: any target value must be unique (i.e., occur only once)

is unique for base64: any target value must be unique (i.e., occur only once)

Properties (9)

uuid

uuid

[1]

Resource Universally Unique Identifier

Description 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.

title

markup-line

[0 or 1]

Resource Title

Description A name given to the resource, which may be used by a tool for display and navigation.

description

markup-multiline

[0 or 1]

Resource Description

Description A short summary of the resource used to indicate the purpose of the resource.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

document-ids

array

[0 or 1]

(array member)

string

[0 to ∞]

Document Identifier

Description 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.

Remarks

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.

Properties (2)
scheme

uri

[0 or 1]

Document Identification Scheme

Description 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.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • http://www.doi.org/: A Digital Object Identifier (DOI); use is preferred, since this allows for retrieval of a full bibliographic record.
identifier

string

[0 or 1]

citation

object

[0 or 1]

Citation

Description A citation consisting of end note text and optional structured bibliographic data.

Remarks

The text is used to define the endnote text, without any required bibliographic structure. If structured bibliographic data is needed, then the biblio can be used for this purpose.

A biblio can be used to capture a structured bibliographical citation in an appropriate format.

Properties (3)
text

markup-line

[1]

Citation Text

Description A line of citation text.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

array

[0 or 1]

(array member)

object

[1 to ∞]

Resource link

Description A pointer to an external resource with an optional hash for verification and change detection.

Remarks

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.

Properties (3)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URI reference to a resource.

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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.

hashes

array

[0 or 1]

(array member)

string

[0 to ∞]

Hash

Description A representation of a cryptographic digest generated over a resource using a specified hash algorithm.

Remarks

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.

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

Properties (2)
algorithm

string

[1]

Hash algorithm

Description Method by which a hash is derived

Remarks

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.

Constraint (1)

allowed values

The value may be locally defined, or one of the following:

  • SHA-224: The SHA-224 algorithm as defined by NIST FIPS 180-4.
  • SHA-256: The SHA-256 algorithm as defined by NIST FIPS 180-4.
  • SHA-384: The SHA-384 algorithm as defined by NIST FIPS 180-4.
  • SHA-512: The SHA-512 algorithm as defined by NIST FIPS 180-4.
  • SHA3-224: The SHA3-224 algorithm as defined by NIST FIPS 202.
  • SHA3-256: The SHA3-256 algorithm as defined by NIST FIPS 202.
  • SHA3-384: The SHA3-384 algorithm as defined by NIST FIPS 202.
  • SHA3-512: The SHA3-512 algorithm as defined by NIST FIPS 202.
value

string

[0 or 1]

base64

base64Binary

[0 or 1]

Base64

Description The Base64 alphabet in RFC 2045 - aligned with XSD.

Properties (3)
filename

uri-reference

[0 or 1]

File Name

Description 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.

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

Description Each OSCAL profile is defined by a Profile element

Remarks

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.

Properties (6)

uuid

uuid

[1]

Profile Universally Unique Identifier

Description 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.

metadata

object
(global definition)

[1]

Publication metadata

Description Provides information about the publication and availability of the containing document.

Constraints (13)

index for role an index index-metadata-role-ids shall list values returned by targets role using keys constructed of key field(s) @id

is unique for document-id: any target value must be unique (i.e., occur only once)

is unique for prop: any target value must be unique (i.e., occur only once)

index for .//prop an index index-metadata-property-uuid shall list values returned by targets .//prop using keys constructed of key field(s) @uuid

is unique for link: any target value must be unique (i.e., occur only once)

index for role an index index-metadata-role-id shall list values returned by targets role using keys constructed of key field(s) @id

index for location an index index-metadata-location-uuid shall list values returned by targets location using keys constructed of key field(s) @uuid

index for party an index index-metadata-party-uuid shall list values returned by targets party using keys constructed of key field(s) @uuid

index for party[@type='organization'] an index index-metadata-party-organizations-uuid shall list values returned by targets party[@type='organization'] using keys constructed of key field(s) @uuid

is unique for responsible-party: any target value must be unique (i.e., occur only once)

allowed values for responsible-party/@role-id

The value may be locally defined, or one of the following:

  • creator: Indicates the organization that created this content.
  • prepared-by: Indicates the organization that prepared this content.
  • prepared-for: Indicates the organization for which this content was created.
  • content-approver: Indicates the organization responsible for all content represented in the "document".
  • contact: Indicates the organization to contact for questions or support related to this content.

allowed value for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • keywords: 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.

allowed values for link/@rel

The value may be locally defined, or one of the following:

  • canonical: The link identifies the authoritative location for this file. Defined by RFC 6596.
  • alternate: The link identifies an alternative location or format for this file. Defined by the HTML Living Standard
  • latest-version: This link identifies a resource containing the latest version in the version history. Defined by RFC 5829.
  • predecessor-version: This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829.
  • successor-version: This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829.
Properties (14)

title

markup-line

[1]

Document Title

Description A name given to the document, which may be used by a tool for display and navigation.

published

dateTime-with-timezone

[0 or 1]

Publication Timestamp

Description 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.

Remarks

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.

last-modified

dateTime-with-timezone

[1]

Last Modified Timestamp

Description 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.

Remarks

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.

version

string

[1]

Document Version

Description A string used to distinguish the current version of the document from other previous (and future) versions.

Remarks

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.

oscal-version

string

[1]

OSCAL version

Description The OSCAL model version the document was authored against.

Remarks

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.

revisions

array

[0 or 1]

(array member)

object

[1 to ∞]

Revision History Entry

Description An entry in a sequential list of revisions to the containing document in reverse chronological order (i.e., most recent previous revision first).

Remarks

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.

Constraint (1)

allowed values for link/@rel

The value may be locally defined, or one of the following:

  • canonical: The link identifies the authoritative location for this file. Defined by RFC 6596.
  • alternate: The link identifies an alternative location or format for this file. Defined by the HTML Living Standard
  • predecessor-version: This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829.
  • successor-version: This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829.
Properties (8)

title

markup-line

[0 or 1]

Document Title

Description A name given to the document revision, which may be used by a tool for display and navigation.

published

dateTime-with-timezone

[0 or 1]

Publication Timestamp

Description 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.

Remarks

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.

last-modified

dateTime-with-timezone

[0 or 1]

Last Modified Timestamp

Description 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.

Remarks

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.

version

string

[1]

Document Version

Description A string used to distinguish the current version of the document from other previous (and future) versions.

Remarks

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.

oscal-version

string

[0 or 1]

OSCAL version

Description The OSCAL model version the document was authored against.

Remarks

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.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

document-ids

array

[0 or 1]

(array member)

string

[0 to ∞]

Document Identifier

Description 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.

Remarks

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.

Properties (2)

scheme

uri

[0 or 1]

Document Identification Scheme

Description 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.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • http://www.doi.org/: A Digital Object Identifier (DOI); use is preferred, since this allows for retrieval of a full bibliographic record.

identifier

string

[0 or 1]

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)

name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.

uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)

href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

roles

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Role

Description Defines a function assumed or expected to be assumed by a party in a specific situation.

Remarks

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.

Properties (7)

id

token

[1]

Role Identifier

Description 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.

title

markup-line

[1]

Role Title

Description A name given to the role, which may be used by a tool for display and navigation.

short-name

string

[0 or 1]

Role Short Name

Description A short common name, abbreviation, or acronym for the role.

description

markup-multiline

[0 or 1]

Role Description

Description A summary of the role's purpose and associated responsibilities.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

locations

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Location

Description A location, with associated metadata that can be referenced.

Constraints (3)

allowed value for prop/@name

The value may be locally defined, or the following:

  • type: Characterizes the kind of location.

allowed value for prop[@name='type']/@value

The value may be locally defined, or the following:

  • data-center: A location that contains computing assets. A class can be used to indicate the sub-type of data-center as primary or alternate.

allowed values for prop[@name='type' and @value='data-center']/@class

The value may be locally defined, or one of the following:

  • primary: The location is a data-center used for normal operations.
  • alternate: The location is a data-center used for fail-over or backup operations.
Properties (9)

uuid

uuid

[1]

Location Universally Unique Identifier

Description 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.

title

markup-line

[0 or 1]

Location Title

Description A name given to the location, which may be used by a tool for display and navigation.

address

object

[1]

Address

Description A postal address for the location.

Remarks

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

Properties (6)
type

token

[0 or 1]

Address Type

Description Indicates the type of address.

Constraint (1)

allowed values

The value may be locally defined, or one of the following:

  • home: A home address.
  • work: A work address.
addr-lines

array

[0 or 1]

(array member)

string

[0 to ∞]

Address line

Description A single line of an address.

city

string

[0 or 1]

City

Description City, town or geographical region for the mailing address.

state

string

[0 or 1]

State

Description State, province or analogous geographical region for mailing address

postal-code

string

[0 or 1]

Postal Code

Description Postal or ZIP code for mailing address

country

string

[0 or 1]

Country Code

Description The ISO 3166-1 alpha-2 country code for the mailing address.

Constraint (1)

matches: a target (value) must match the regular expression '[A-Z]{2}'.

email-addresses

array

[0 or 1]

(array member)

email

[0 to ∞]

Email Address

Description An email address as defined by RFC 5322 Section 3.4.1.

Remarks

This is a contact email associated with the location.

telephone-numbers

array

[0 or 1]

(array member)

string

[0 to ∞]

Telephone Number

Description Contact number by telephone.

Remarks

A phone number used to contact the location.

Properties (2)
type

string

[0 or 1]

type flag

Description Indicates the type of phone number.

Constraint (1)

allowed values

The value may be locally defined, or one of the following:

  • home: A home phone number.
  • office: An office phone number.
  • mobile: A mobile phone number.
number

string

[0 or 1]

urls

array

[0 or 1]

(array member)

uri

[0 to ∞]

Location URL

Description The uniform resource locator (URL) for a web site or Internet presence associated with the location.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

parties

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Party (organization or person)

Description A responsible entity which is either a person or an organization.

Constraint (1)

allowed values for prop/@name

The value must be one of the following:

  • mail-stop: A mail stop associated with the party.
  • office: The name or number of the party's office.
  • job-title: The formal job title of a person.
Properties (12)

uuid

uuid

[1]

Party Universally Unique Identifier

Description 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.

type

string

[1]

Party Type

Description A category describing the kind of party the object describes.

Constraint (1)

allowed values

The value must be one of the following:

  • person: An individual.
  • organization: A group of individuals formed for a specific purpose.

name

string

[0 or 1]

Party Name

Description The full name of the party. This is typically the legal name associated with the party.

short-name

string

[0 or 1]

Party Short Name

Description A short common name, abbreviation, or acronym for the party.

external-ids

array

[0 or 1]

(array member)

string

[0 to ∞]

Party External Identifier

Description An identifier for a person or organization using a designated scheme. e.g. an Open Researcher and Contributor ID (ORCID)

Properties (2)
scheme

uri

[1]

External Identifier Schema

Description Indicates the type of external identifier.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • http://orcid.org/: The identifier is Open Researcher and Contributor ID (ORCID).

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

email-addresses

array

[0 or 1]

(array member)

email

[0 to ∞]

Email Address

Description An email address as defined by RFC 5322 Section 3.4.1.

Remarks

This is a contact email associated with the party.

telephone-numbers

array

[0 or 1]

(array member)

string

[0 to ∞]

Telephone Number

Description Contact number by telephone.

Remarks

A phone number used to contact the party.

Properties (2)
type

string

[0 or 1]

type flag

Description Indicates the type of phone number.

Constraint (1)

allowed values

The value may be locally defined, or one of the following:

  • home: A home phone number.
  • office: An office phone number.
  • mobile: A mobile phone number.
number

string

[0 or 1]

A choice:

addresses

array

[0 or 1]

(array member)

object

[1 to ∞]

Address

Description A postal address for the location.

Properties (6)
type

token

[0 or 1]

Address Type

Description Indicates the type of address.

Constraint (1)

allowed values

The value may be locally defined, or one of the following:

  • home: A home address.
  • work: A work address.
addr-lines

array

[0 or 1]

(array member)

string

[0 to ∞]

Address line

Description A single line of an address.

city

string

[0 or 1]

City

Description City, town or geographical region for the mailing address.

state

string

[0 or 1]

State

Description State, province or analogous geographical region for mailing address

postal-code

string

[0 or 1]

Postal Code

Description Postal or ZIP code for mailing address

country

string

[0 or 1]

Country Code

Description The ISO 3166-1 alpha-2 country code for the mailing address.

Constraint (1)

matches: a target (value) must match the regular expression '[A-Z]{2}'.

location-uuids

array

[0 or 1]

(array member)

uuid

[0 to ∞]

Location Reference

Description 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).

Remarks

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

Constraint (1)

index has keythis value must correspond to a listing in the index index-metadata-location-uuid using a key constructed of key field(s) .

member-of-organizations

array

[0 or 1]

(array member)

uuid

[0 to ∞]

Organizational Affiliation

Description 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).

Remarks

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

Constraint (1)

index has keythis value must correspond to a listing in the index index-metadata-party-organizations-uuid using a key constructed of key field(s) .

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

responsible-parties

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Responsible Party

Description A reference to a set of organizations or persons that have responsibility for performing a referenced role in the context of the containing object.

Constraints (2)

index has keythis value must correspond to a listing in the index index-metadata-role-id using a key constructed of key field(s) @role-id

index has key for party-uuidthis value must correspond to a listing in the index index-metadata-party-uuid using a key constructed of key field(s) .

Properties (5)

role-id

token

[1]

Responsible Role

Description A human-oriented identifier reference to roles served by the user.

party-uuids

array

[1]

(array member)

uuid

[1 to ∞]

Party Reference

Description 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).

Remarks

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

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

Constraint (1)

index has keythis value must correspond to a listing in the index index-metadata-party-uuid using a key constructed of key field(s) .

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

imports

array

[1]

(array member)

object
(global definition)

[1 to ∞]

Import resource

Description 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.

Remarks

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).

Properties (3)

href

uri-reference

[1]

Catalog or Profile Reference

Description A resolvable URL reference to the base catalog or profile that this profile is tailoring.

Remarks

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.

A choice:

include-all

empty

[1]

Include All

Description Include all controls from the imported catalog or profile resources.

Remarks

This element provides an alternative to calling controls individually from a catalog.

Identifies that all controls are to be included from the imported catalog or profile.

include-controls

array

[1]

(array member)

object

[1 to ∞]

Call

Description Call a control by its ID

Remarks

If with-child-controls is yes on the call to a control, no sibling callelements need to be used to call any controls appearing within it. Since generally, this is how control enhancements are represented (as controls within controls), this provides a way to include controls with all their dependent controls (enhancements) without having to call them individually.

Identifies a subset of controls to import from the referenced catalog or profile by control identifier or match pattern.

Properties (3)

with-child-controls

token

[0 or 1]

Include contained controls with control

Description When a control is included, whether its child (dependent) controls are also included.

Constraint (1)

allowed values

The value must be one of the following:

  • yes: Include child controls with an included control.
  • no: When importing a control, only include child controls that are also explicitly called.

with-ids

array

[0 or 1]

(array member)

token

[0 to ∞]

Match Controls by Identifier

Description

matching

array

[0 or 1]

(array member)

empty

[1 to ∞]

Match Controls by Pattern

Description Select controls by (regular expression) match on ID

Property (1)
pattern

string

[0 or 1]

Pattern

Description A glob expression matching the IDs of one or more controls to be selected.

exclude-controls

array

[0 or 1]

(array member)

object

[1 to ∞]

Call

Description Call a control by its ID

Remarks

If with-child-controls is yes on the call to a control, no sibling callelements need to be used to call any controls appearing within it. Since generally, this is how control enhancements are represented (as controls within controls), this provides a way to include controls with all their dependent controls (enhancements) without having to call them individually.

Identifies which controls to exclude, or eliminate, from the set of included controls by control identifier or match pattern.

Properties (3)

with-child-controls

token

[0 or 1]

Include contained controls with control

Description When a control is included, whether its child (dependent) controls are also included.

Constraint (1)

allowed values

The value must be one of the following:

  • yes: Include child controls with an included control.
  • no: When importing a control, only include child controls that are also explicitly called.

with-ids

array

[0 or 1]

(array member)

token

[0 to ∞]

Match Controls by Identifier

Description

matching

array

[0 or 1]

(array member)

empty

[1 to ∞]

Match Controls by Pattern

Description Select controls by (regular expression) match on ID

Property (1)
pattern

string

[0 or 1]

Pattern

Description A glob expression matching the IDs of one or more controls to be selected.

merge

object
(global definition)

[0 or 1]

Merge controls

Description A Merge element provides structuring directives that drive how controls are organized after resolution.

Remarks

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.

Properties (2)

combine

empty

[0 or 1]

Combination rule

Description A Combine element defines how to combine multiple (competing) versions of the same control.

Remarks

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.

Property (1)

method

string

[0 or 1]

Combination method

Description How clashing controls should be handled

Constraint (1)

allowed values

The value must be one of the following:

  • use-first: Use the first definition - the first control with a given ID is used; subsequent ones are discarded
  • merge: **(deprecated)** **(unspecified)** Merge - controls with the same ID are combined
  • keep: Keep - controls with the same ID are kept, retaining the clash

A choice:

Description Use the flat structuring method.

as-is

boolean

[1]

As-Is Structuring Directive

Description 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.

custom

object

[0 or 1]

Custom grouping

Description A Custom element frames a structure for embedding represented controls in resolution.

Remarks

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.

Properties (2)

groups

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Control group

Description A group of (selected) controls or of groups of controls

Remarks

This construct mirrors the same construct that exists in an OSCAL catalog.

Properties (8)
id

token

[0 or 1]

Group Identifier

Description 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.

class

token

[0 or 1]

Group Class

Description A textual label that provides a sub-type or characterization of the group.

Remarks

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.

title

markup-line

[1]

Group Title

Description A name given to the group, which may be used by a tool for display and navigation.

params

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Parameter

Description Parameters provide a mechanism for the dynamic assignment of value(s) in a control.

Remarks

In a catalog, a parameter is typically used as a placeholder for the future assignment of a parameter value, although the OSCAL model allows for the direct assignment of a value if desired by the control author. The value may be optionally used to specify one or more values. If no value is provided, then it is expected that the value will be provided at the Profile or Implementation layer.

A parameter can include a variety of metadata options that support the future solicitation of one or more values. A label provides a textual placeholder that can be used in a tool to solicit parameter value input, or to display in catalog documentation. The desc provides a short description of what the parameter is used for, which can be used in tooling to help a user understand how to use the parameter. A constraint can be used to provide criteria for the allowed values. A guideline provides a recommendation for the use of a parameter.

Constraints (2)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
  • alt-label: An alternate to the value provided by the parameter's label. This will typically be qualified by a class.

allowed value for prop[has-oscal-namespace('http://csrc.nist.gov/ns/rmf')]/@name

The value must be one of the following:

  • aggregates: The parent parameter provides an aggregation of 2 or more other parameters, each described by this property.
Properties (11)
id

token

[1]

Parameter Identifier

Description 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.

class

token

[0 or 1]

Parameter Class

Description A textual label that provides a characterization of the parameter.

Remarks

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

depends-on

token

[0 or 1]

Depends on

Description **(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)

name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.

uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)

href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

label

markup-line

[0 or 1]

Parameter Label

Description A short, placeholder name for the parameter, which can be used as a substitute for a value if no value is assigned.

Remarks

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

usage

markup-multiline

[0 or 1]

Parameter Usage Description

Description Describes the purpose and use of a parameter

constraints

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Constraint

Description A formal or informal expression of a constraint or test

Properties (2)

description

markup-multiline

[0 or 1]

Constraint Description

Description A textual summary of the constraint to be applied.

tests

array

[0 or 1]

(array member)

object

[1 to ∞]

Constraint Test

Description A test expression which is expected to be evaluated by a tool.

Properties (2)

expression

string

[1]

Constraint test

Description A formal (executable) expression of a constraint

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

guidelines

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Guideline

Description A prose statement that provides a recommendation for the use of a parameter.

Property (1)

prose

markup-multiline

[1]

Guideline Text

Description Prose permits multiple paragraphs, lists, tables etc.

A choice:

values

array

[0 or 1]

(array member)

string

[0 to ∞]

Parameter Value

Description A parameter value or set of values.

Remarks

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

select

object
(global definition)

[0 or 1]

Selection

Description Presenting a choice among alternatives

Remarks

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

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

Properties (2)

how-many

token

[0 or 1]

Parameter Cardinality

Description Describes the number of selections that must occur. Without this setting, only one value should be assumed to be permitted.

Constraint (1)

allowed values

The value must be one of the following:

  • one: Only one value is permitted.
  • one-or-more: One or more values are permitted.

choice

array

[0 or 1]

(array member)

markup-line

[0 to ∞]

Choice

Description A value selection among several such options

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

parts

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Part

Description A partition of a control's definition or a child of another part.

Remarks

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.

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.

Constraint (1)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
Properties (9)
id

token

[0 or 1]

Part Identifier

Description 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.

name

token

[1]

Part Name

Description A textual label that uniquely identifies the part's semantic type.

ns

uri

[0 or 1]

Part Namespace

Description A namespace qualifying the part's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

class

token

[0 or 1]

Part Class

Description 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.

Remarks

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.

title

markup-line

[0 or 1]

Part Title

Description A name given to the part, which may be used by a tool for display and navigation.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)

name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.

uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

prose

markup-multiline

[0 or 1]

Part Text

Description Permits multiple paragraphs, lists, tables etc.

parts

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Part

Description A partition of a control's definition or a child of another part.

Remarks

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.

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.

Constraint (1)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)

href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

A choice:

groups

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Control group

Description A group of (selected) controls or of groups of controls

Remarks

This construct mirrors the same construct that exists in an OSCAL catalog.

insert-controls

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Select controls

Description Specifies which controls to use in the containing context.

Remarks

To be schema-valid, this element must contain either (but not both) a single include-all directive, or a sequence of include-controls directives.

If this directive is not provided, then no controls are to be inserted; i.e., all controls are included explicitly.

Properties (3)
order

token

[0 or 1]

Order

Description A designation of how a selection of controls in a profile is to be ordered.

Constraint (1)

allowed values

The value must be one of the following:

  • keep
  • ascending
  • descending

A choice:

include-all

empty

[1]

Include All

Description Include all controls from the imported catalog or profile resources.

Remarks

This element provides an alternative to calling controls individually from a catalog.

include-controls

array

[1]

(array member)

object

[1 to ∞]

Call

Description Call a control by its ID

Remarks

If with-child-controls is yes on the call to a control, no sibling callelements need to be used to call any controls appearing within it. Since generally, this is how control enhancements are represented (as controls within controls), this provides a way to include controls with all their dependent controls (enhancements) without having to call them individually.

Properties (3)

with-child-controls

token

[0 or 1]

Include contained controls with control

Description When a control is included, whether its child (dependent) controls are also included.

Constraint (1)

allowed values

The value must be one of the following:

  • yes: Include child controls with an included control.
  • no: When importing a control, only include child controls that are also explicitly called.

with-ids

array

[0 or 1]

(array member)

token

[0 to ∞]

Match Controls by Identifier

Description

matching

array

[0 or 1]

(array member)

empty

[1 to ∞]

Match Controls by Pattern

Description Select controls by (regular expression) match on ID

Property (1)

pattern

string

[0 or 1]

Pattern

Description A glob expression matching the IDs of one or more controls to be selected.

exclude-controls

array

[0 or 1]

(array member)

object

[1 to ∞]

Call

Description Call a control by its ID

Remarks

If with-child-controls is yes on the call to a control, no sibling callelements need to be used to call any controls appearing within it. Since generally, this is how control enhancements are represented (as controls within controls), this provides a way to include controls with all their dependent controls (enhancements) without having to call them individually.

Identifies which controls to exclude, or eliminate, from the set of matching includes.

Properties (3)

with-child-controls

token

[0 or 1]

Include contained controls with control

Description When a control is included, whether its child (dependent) controls are also included.

Constraint (1)

allowed values

The value must be one of the following:

  • yes: Include child controls with an included control.
  • no: When importing a control, only include child controls that are also explicitly called.

with-ids

array

[0 or 1]

(array member)

token

[0 to ∞]

Match Controls by Identifier

Description

matching

array

[0 or 1]

(array member)

empty

[1 to ∞]

Match Controls by Pattern

Description Select controls by (regular expression) match on ID

Property (1)

pattern

string

[0 or 1]

Pattern

Description A glob expression matching the IDs of one or more controls to be selected.

insert-controls

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Select controls

Description Specifies which controls to use in the containing context.

Remarks

To be schema-valid, this element must contain either (but not both) a single include-all directive, or a sequence of include-controls directives.

If this directive is not provided, then no controls are to be inserted; i.e., all controls are included explicitly.

Properties (3)
order

token

[0 or 1]

Order

Description A designation of how a selection of controls in a profile is to be ordered.

Constraint (1)

allowed values

The value must be one of the following:

  • keep
  • ascending
  • descending

A choice:

include-all

empty

[1]

Include All

Description Include all controls from the imported catalog or profile resources.

Remarks

This element provides an alternative to calling controls individually from a catalog.

include-controls

array

[1]

(array member)

object

[1 to ∞]

Call

Description Call a control by its ID

Remarks

If with-child-controls is yes on the call to a control, no sibling callelements need to be used to call any controls appearing within it. Since generally, this is how control enhancements are represented (as controls within controls), this provides a way to include controls with all their dependent controls (enhancements) without having to call them individually.

Properties (3)
with-child-controls

token

[0 or 1]

Include contained controls with control

Description When a control is included, whether its child (dependent) controls are also included.

Constraint (1)

allowed values

The value must be one of the following:

  • yes: Include child controls with an included control.
  • no: When importing a control, only include child controls that are also explicitly called.
with-ids

array

[0 or 1]

(array member)

token

[0 to ∞]

Match Controls by Identifier

Description

matching

array

[0 or 1]

(array member)

empty

[1 to ∞]

Match Controls by Pattern

Description Select controls by (regular expression) match on ID

Property (1)

pattern

string

[0 or 1]

Pattern

Description A glob expression matching the IDs of one or more controls to be selected.

exclude-controls

array

[0 or 1]

(array member)

object

[1 to ∞]

Call

Description Call a control by its ID

Remarks

If with-child-controls is yes on the call to a control, no sibling callelements need to be used to call any controls appearing within it. Since generally, this is how control enhancements are represented (as controls within controls), this provides a way to include controls with all their dependent controls (enhancements) without having to call them individually.

Identifies which controls to exclude, or eliminate, from the set of matching includes.

Properties (3)
with-child-controls

token

[0 or 1]

Include contained controls with control

Description When a control is included, whether its child (dependent) controls are also included.

Constraint (1)

allowed values

The value must be one of the following:

  • yes: Include child controls with an included control.
  • no: When importing a control, only include child controls that are also explicitly called.
with-ids

array

[0 or 1]

(array member)

token

[0 to ∞]

Match Controls by Identifier

Description

matching

array

[0 or 1]

(array member)

empty

[1 to ∞]

Match Controls by Pattern

Description Select controls by (regular expression) match on ID

Property (1)

pattern

string

[0 or 1]

Pattern

Description A glob expression matching the IDs of one or more controls to be selected.

modify

object
(global definition)

[0 or 1]

Modify controls

Description Set parameters or amend controls in resolution

Constraint (1)

is unique for set-parameter: any target value must be unique (i.e., occur only once)

Properties (2)

set-parameters

array

[0 or 1]

(array member)

object

[1 to ∞]

Parameter Setting

Description A parameter setting, to be propagated to points of insertion

Properties (10)

param-id

token

[1]

Parameter ID

Description 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.

class

token

[0 or 1]

Parameter Class

Description A textual label that provides a characterization of the parameter.

Remarks

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

depends-on

token

[0 or 1]

Depends on

Description **(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

label

markup-line

[0 or 1]

Parameter Label

Description A short, placeholder name for the parameter, which can be used as a substitute for a value if no value is assigned.

Remarks

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

usage

markup-multiline

[0 or 1]

Parameter Usage Description

Description Describes the purpose and use of a parameter

constraints

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Constraint

Description A formal or informal expression of a constraint or test

Properties (2)
description

markup-multiline

[0 or 1]

Constraint Description

Description A textual summary of the constraint to be applied.

tests

array

[0 or 1]

(array member)

object

[1 to ∞]

Constraint Test

Description A test expression which is expected to be evaluated by a tool.

Properties (2)
expression

string

[1]

Constraint test

Description A formal (executable) expression of a constraint

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

guidelines

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Guideline

Description A prose statement that provides a recommendation for the use of a parameter.

Property (1)
prose

markup-multiline

[1]

Guideline Text

Description Prose permits multiple paragraphs, lists, tables etc.

A choice:

values

array

[0 or 1]

(array member)

string

[0 to ∞]

Parameter Value

Description A parameter value or set of values.

Remarks

Used to (re)define a parameter value.

select

object
(global definition)

[0 or 1]

Selection

Description Presenting a choice among alternatives

Remarks

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

Properties (2)
how-many

token

[0 or 1]

Parameter Cardinality

Description Describes the number of selections that must occur. Without this setting, only one value should be assumed to be permitted.

Constraint (1)

allowed values

The value must be one of the following:

  • one: Only one value is permitted.
  • one-or-more: One or more values are permitted.
choice

array

[0 or 1]

(array member)

markup-line

[0 to ∞]

Choice

Description A value selection among several such options

alters

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Alteration

Description An Alter element specifies changes to be made to an included control when a profile is resolved.

Remarks

Use @control-id to indicate the scope of alteration.

It is an error for two alter elements to apply to the same control. In practice, multiple alterations can be applied (together), but it creates confusion.

At present, no provision is made for altering many controls at once (for example, to systematically remove properties or add global properties); extending this element to match multiple control IDs could provide for this.

Properties (3)

control-id

token

[1]

Control Identifier Reference

Description 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).

removes

array

[0 or 1]

(array member)

empty

[1 to ∞]

Removal

Description Specifies objects to be removed from a control based on specific aspects of the object that must all match.

Remarks

Use name-ref, class-ref, id-ref or generic-identifier to indicate class tokens or ID reference, or the formal name, of the component to be removed or erased from a control, when a catalog is resolved. The control affected is indicated by the pointer on the removal's parent (containing) alter element.

To change an element, use remove to remove the element, then add to add it back again with changes.

Properties (5)
by-name

token

[0 or 1]

Reference by (assigned) name

Description Identify items to remove by matching their assigned name

by-class

token

[0 or 1]

Reference by class

Description Identify items to remove by matching their class.

by-id

token

[0 or 1]

Reference by ID

Description Identify items to remove indicated by their id.

by-item-name

token

[0 or 1]

Item Name Reference

Description Identify items to remove by the name of the item's information element name, e.g. title or prop

by-ns

token

[0 or 1]

Item Namespace Reference

Description Identify items to remove by the item's ns, which is the namespace associated with a part, or prop.

adds

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Addition

Description Specifies contents to be added into controls, in resolution

Remarks

When no id-ref is given, the addition is inserted into the control targeted by the alteration at the start or end as indicated by position. Only position values of "starting" or "ending" are permitted when there is no id-ref.

id-ref, when given, should indicate, by its ID, an element inside the control to serve as the anchor point for the addition. In this case, position value may be any of the permitted values.

Constraint (1)

allowed values for prop/@name

The value may be locally defined, or one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
Properties (7)
position

token

[0 or 1]

Position

Description Where to add the new content with respect to the targeted element (beside it or inside it)

Constraint (1)

allowed values

The value must be one of the following:

  • before: Preceding the id-ref target
  • after: Following the id-ref target
  • starting: Inside the control or id-ref target, at the start
  • ending: Inside the control or id-ref target, at the end
by-id

token

[0 or 1]

Reference by ID

Description Target location of the addition.

title

markup-line

[0 or 1]

Title Change

Description A name given to the control, which may be used by a tool for display and navigation.

params

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Parameter

Description Parameters provide a mechanism for the dynamic assignment of value(s) in a control.

Remarks

In a catalog, a parameter is typically used as a placeholder for the future assignment of a parameter value, although the OSCAL model allows for the direct assignment of a value if desired by the control author. The value may be optionally used to specify one or more values. If no value is provided, then it is expected that the value will be provided at the Profile or Implementation layer.

A parameter can include a variety of metadata options that support the future solicitation of one or more values. A label provides a textual placeholder that can be used in a tool to solicit parameter value input, or to display in catalog documentation. The desc provides a short description of what the parameter is used for, which can be used in tooling to help a user understand how to use the parameter. A constraint can be used to provide criteria for the allowed values. A guideline provides a recommendation for the use of a parameter.

Constraints (2)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
  • alt-label: An alternate to the value provided by the parameter's label. This will typically be qualified by a class.

allowed value for prop[has-oscal-namespace('http://csrc.nist.gov/ns/rmf')]/@name

The value must be one of the following:

  • aggregates: The parent parameter provides an aggregation of 2 or more other parameters, each described by this property.
Properties (11)
id

token

[1]

Parameter Identifier

Description 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.

class

token

[0 or 1]

Parameter Class

Description A textual label that provides a characterization of the parameter.

Remarks

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

depends-on

token

[0 or 1]

Depends on

Description **(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)

name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.

uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)

href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

label

markup-line

[0 or 1]

Parameter Label

Description A short, placeholder name for the parameter, which can be used as a substitute for a value if no value is assigned.

Remarks

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

usage

markup-multiline

[0 or 1]

Parameter Usage Description

Description Describes the purpose and use of a parameter

constraints

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Constraint

Description A formal or informal expression of a constraint or test

Properties (2)

description

markup-multiline

[0 or 1]

Constraint Description

Description A textual summary of the constraint to be applied.

tests

array

[0 or 1]

(array member)

object

[1 to ∞]

Constraint Test

Description A test expression which is expected to be evaluated by a tool.

Properties (2)

expression

string

[1]

Constraint test

Description A formal (executable) expression of a constraint

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

guidelines

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Guideline

Description A prose statement that provides a recommendation for the use of a parameter.

Property (1)

prose

markup-multiline

[1]

Guideline Text

Description Prose permits multiple paragraphs, lists, tables etc.

A choice:

values

array

[0 or 1]

(array member)

string

[0 to ∞]

Parameter Value

Description A parameter value or set of values.

Remarks

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

select

object
(global definition)

[0 or 1]

Selection

Description Presenting a choice among alternatives

Remarks

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

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

Properties (2)

how-many

token

[0 or 1]

Parameter Cardinality

Description Describes the number of selections that must occur. Without this setting, only one value should be assumed to be permitted.

Constraint (1)

allowed values

The value must be one of the following:

  • one: Only one value is permitted.
  • one-or-more: One or more values are permitted.

choice

array

[0 or 1]

(array member)

markup-line

[0 to ∞]

Choice

Description A value selection among several such options

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

parts

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Part

Description A partition of a control's definition or a child of another part.

Remarks

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.

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.

Constraint (1)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.
Properties (9)
id

token

[0 or 1]

Part Identifier

Description 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.

name

token

[1]

Part Name

Description A textual label that uniquely identifies the part's semantic type.

ns

uri

[0 or 1]

Part Namespace

Description A namespace qualifying the part's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

class

token

[0 or 1]

Part Class

Description 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.

Remarks

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.

title

markup-line

[0 or 1]

Part Title

Description A name given to the part, which may be used by a tool for display and navigation.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)

name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.

uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

prose

markup-multiline

[0 or 1]

Part Text

Description Permits multiple paragraphs, lists, tables etc.

parts

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Part

Description A partition of a control's definition or a child of another part.

Remarks

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.

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.

Constraint (1)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • label: A human-readable label for the parent context, which may be rendered in place of the actual identifier for some use cases.
  • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
  • alt-identifier: An alternate or aliased identifier for the parent context.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)

href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

back-matter

object
(global definition)

[0 or 1]

Back matter

Description A collection of resources, which may be included directly or by reference.

Remarks

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.

Constraint (1)

index for resource an index index-back-matter-resource shall list values returned by targets resource using keys constructed of key field(s) @uuid

Property (1)

resources

array

[0 or 1]

(array member)

object

[1 to ∞]

Resource

Description 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.

Remarks

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.

Constraints (6)

allowed values for prop/@name

The value must be one of the following:

  • type: Identifies the type of resource represented.
  • version: For resources representing a published document, this represents the version number of that document.
  • published: For resources representing a published document, this represents the publication date of that document.

matches for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name='published']/@value: the target value must match the lexical form of the 'dateTime' data type.

allowed values for prop[@name='type']/@value

The value may be locally defined, or one of the following:

  • logo: Indicates the resource is an organization's logo.
  • image: Indicates the resource represents an image.
  • screen-shot: Indicates the resource represents an image of screen content.
  • law: Indicates the resource represents an applicable law.
  • regulation: Indicates the resource represents an applicable regulation.
  • standard: Indicates the resource represents an applicable standard.
  • external-guidance: Indicates the resource represents applicable guidance.
  • acronyms: Indicates the resource provides a list of relevant acronyms.
  • citation: Indicates the resource cites relevant information.
  • policy: Indicates the resource is a policy.
  • procedure: Indicates the resource is a procedure.
  • system-guide: Indicates the resource is guidance document related to the subject system of an SSP.
  • users-guide: Indicates the resource is guidance document a user's guide or administrator's guide.
  • administrators-guide: Indicates the resource is guidance document a administrator's guide.
  • rules-of-behavior: Indicates the resource represents rules of behavior content.
  • plan: Indicates the resource represents a plan.
  • artifact: Indicates the resource represents an artifact, such as may be reviewed by an assessor.
  • evidence: Indicates the resource represents evidence, such as to support an assessment findiing.
  • tool-output: Indicates the resource represents output from a tool.
  • raw-data: Indicates the resource represents machine data, which may require a tool or analysis for interpretation or presentation.
  • interview-notes: Indicates the resource represents notes from an interview, such as may be collected during an assessment.
  • questionnaire: Indicates the resource is a set of questions, possibly with responses.
  • report: Indicates the resource is a report.
  • agreement: Indicates the resource is a formal agreement between two or more parties.

has cardinality for rlink|base64 the cardinality of rlink|base64 is constrained: 1; maximum unbounded.

is unique for rlink: any target value must be unique (i.e., occur only once)

is unique for base64: any target value must be unique (i.e., occur only once)

Properties (9)

uuid

uuid

[1]

Resource Universally Unique Identifier

Description 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.

title

markup-line

[0 or 1]

Resource Title

Description A name given to the resource, which may be used by a tool for display and navigation.

description

markup-multiline

[0 or 1]

Resource Description

Description A short summary of the resource used to indicate the purpose of the resource.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

document-ids

array

[0 or 1]

(array member)

string

[0 to ∞]

Document Identifier

Description 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.

Remarks

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.

Properties (2)
scheme

uri

[0 or 1]

Document Identification Scheme

Description 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.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • http://www.doi.org/: A Digital Object Identifier (DOI); use is preferred, since this allows for retrieval of a full bibliographic record.
identifier

string

[0 or 1]

citation

object

[0 or 1]

Citation

Description A citation consisting of end note text and optional structured bibliographic data.

Remarks

The text is used to define the endnote text, without any required bibliographic structure. If structured bibliographic data is needed, then the biblio can be used for this purpose.

A biblio can be used to capture a structured bibliographical citation in an appropriate format.

Properties (3)
text

markup-line

[1]

Citation Text

Description A line of citation text.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

array

[0 or 1]

(array member)

object

[1 to ∞]

Resource link

Description A pointer to an external resource with an optional hash for verification and change detection.

Remarks

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.

Properties (3)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URI reference to a resource.

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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.

hashes

array

[0 or 1]

(array member)

string

[0 to ∞]

Hash

Description A representation of a cryptographic digest generated over a resource using a specified hash algorithm.

Remarks

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.

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

Properties (2)
algorithm

string

[1]

Hash algorithm

Description Method by which a hash is derived

Remarks

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.

Constraint (1)

allowed values

The value may be locally defined, or one of the following:

  • SHA-224: The SHA-224 algorithm as defined by NIST FIPS 180-4.
  • SHA-256: The SHA-256 algorithm as defined by NIST FIPS 180-4.
  • SHA-384: The SHA-384 algorithm as defined by NIST FIPS 180-4.
  • SHA-512: The SHA-512 algorithm as defined by NIST FIPS 180-4.
  • SHA3-224: The SHA3-224 algorithm as defined by NIST FIPS 202.
  • SHA3-256: The SHA3-256 algorithm as defined by NIST FIPS 202.
  • SHA3-384: The SHA3-384 algorithm as defined by NIST FIPS 202.
  • SHA3-512: The SHA3-512 algorithm as defined by NIST FIPS 202.
value

string

[0 or 1]

base64

base64Binary

[0 or 1]

Base64

Description The Base64 alphabet in RFC 2045 - aligned with XSD.

Properties (3)
filename

uri-reference

[0 or 1]

File Name

Description 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.

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

component-definition

object
(global definition)

Component Definition

Description A collection of component descriptions, which may optionally be grouped by capability.

Constraints (2)

index for component an index index-system-component-uuid shall list values returned by targets component using keys constructed of key field(s) @uuid

is unique for capability: any target value must be unique (i.e., occur only once)

Properties (6)

uuid

uuid

[1]

Component Definition Universally Unique Identifier

Description 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.

metadata

object
(global definition)

[1]

Publication metadata

Description Provides information about the publication and availability of the containing document.

Constraints (13)

index for role an index index-metadata-role-ids shall list values returned by targets role using keys constructed of key field(s) @id

is unique for document-id: any target value must be unique (i.e., occur only once)

is unique for prop: any target value must be unique (i.e., occur only once)

index for .//prop an index index-metadata-property-uuid shall list values returned by targets .//prop using keys constructed of key field(s) @uuid

is unique for link: any target value must be unique (i.e., occur only once)

index for role an index index-metadata-role-id shall list values returned by targets role using keys constructed of key field(s) @id

index for location an index index-metadata-location-uuid shall list values returned by targets location using keys constructed of key field(s) @uuid

index for party an index index-metadata-party-uuid shall list values returned by targets party using keys constructed of key field(s) @uuid

index for party[@type='organization'] an index index-metadata-party-organizations-uuid shall list values returned by targets party[@type='organization'] using keys constructed of key field(s) @uuid

is unique for responsible-party: any target value must be unique (i.e., occur only once)

allowed values for responsible-party/@role-id

The value may be locally defined, or one of the following:

  • creator: Indicates the organization that created this content.
  • prepared-by: Indicates the organization that prepared this content.
  • prepared-for: Indicates the organization for which this content was created.
  • content-approver: Indicates the organization responsible for all content represented in the "document".
  • contact: Indicates the organization to contact for questions or support related to this content.

allowed value for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • keywords: 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.

allowed values for link/@rel

The value may be locally defined, or one of the following:

  • canonical: The link identifies the authoritative location for this file. Defined by RFC 6596.
  • alternate: The link identifies an alternative location or format for this file. Defined by the HTML Living Standard
  • latest-version: This link identifies a resource containing the latest version in the version history. Defined by RFC 5829.
  • predecessor-version: This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829.
  • successor-version: This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829.
Properties (14)

title

markup-line

[1]

Document Title

Description A name given to the document, which may be used by a tool for display and navigation.

published

dateTime-with-timezone

[0 or 1]

Publication Timestamp

Description 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.

Remarks

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.

last-modified

dateTime-with-timezone

[1]

Last Modified Timestamp

Description 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.

Remarks

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.

version

string

[1]

Document Version

Description A string used to distinguish the current version of the document from other previous (and future) versions.

Remarks

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.

oscal-version

string

[1]

OSCAL version

Description The OSCAL model version the document was authored against.

Remarks

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.

revisions

array

[0 or 1]

(array member)

object

[1 to ∞]

Revision History Entry

Description An entry in a sequential list of revisions to the containing document in reverse chronological order (i.e., most recent previous revision first).

Remarks

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.

Constraint (1)

allowed values for link/@rel

The value may be locally defined, or one of the following:

  • canonical: The link identifies the authoritative location for this file. Defined by RFC 6596.
  • alternate: The link identifies an alternative location or format for this file. Defined by the HTML Living Standard
  • predecessor-version: This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829.
  • successor-version: This link identifies a resource containing the predecessor version in the version history. Defined by RFC 5829.
Properties (8)

title

markup-line

[0 or 1]

Document Title

Description A name given to the document revision, which may be used by a tool for display and navigation.

published

dateTime-with-timezone

[0 or 1]

Publication Timestamp

Description 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.

Remarks

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.

last-modified

dateTime-with-timezone

[0 or 1]

Last Modified Timestamp

Description 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.

Remarks

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.

version

string

[1]

Document Version

Description A string used to distinguish the current version of the document from other previous (and future) versions.

Remarks

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.

oscal-version

string

[0 or 1]

OSCAL version

Description The OSCAL model version the document was authored against.

Remarks

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.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

document-ids

array

[0 or 1]

(array member)

string

[0 to ∞]

Document Identifier

Description 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.

Remarks

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.

Properties (2)

scheme

uri

[0 or 1]

Document Identification Scheme

Description 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.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • http://www.doi.org/: A Digital Object Identifier (DOI); use is preferred, since this allows for retrieval of a full bibliographic record.

identifier

string

[0 or 1]

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)

name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.

uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)

href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference

media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

roles

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Role

Description Defines a function assumed or expected to be assumed by a party in a specific situation.

Remarks

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.

Properties (7)

id

token

[1]

Role Identifier

Description 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.

title

markup-line

[1]

Role Title

Description A name given to the role, which may be used by a tool for display and navigation.

short-name

string

[0 or 1]

Role Short Name

Description A short common name, abbreviation, or acronym for the role.

description

markup-multiline

[0 or 1]

Role Description

Description A summary of the role's purpose and associated responsibilities.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type

Description Specifies a media type as defined by the Internet Assigned Numbers Authority (IANA) Media Types Registry.

Remarks

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 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.

text

markup-line

[0 or 1]

Link Text

Description A textual label to associate with the link, which may be used for presentation in a tool.

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

locations

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Location

Description A location, with associated metadata that can be referenced.

Constraints (3)

allowed value for prop/@name

The value may be locally defined, or the following:

  • type: Characterizes the kind of location.

allowed value for prop[@name='type']/@value

The value may be locally defined, or the following:

  • data-center: A location that contains computing assets. A class can be used to indicate the sub-type of data-center as primary or alternate.

allowed values for prop[@name='type' and @value='data-center']/@class

The value may be locally defined, or one of the following:

  • primary: The location is a data-center used for normal operations.
  • alternate: The location is a data-center used for fail-over or backup operations.
Properties (9)

uuid

uuid

[1]

Location Universally Unique Identifier

Description 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.

title

markup-line

[0 or 1]

Location Title

Description A name given to the location, which may be used by a tool for display and navigation.

address

object

[1]

Address

Description A postal address for the location.

Remarks

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

Properties (6)
type

token

[0 or 1]

Address Type

Description Indicates the type of address.

Constraint (1)

allowed values

The value may be locally defined, or one of the following:

  • home: A home address.
  • work: A work address.
addr-lines

array

[0 or 1]

(array member)

string

[0 to ∞]

Address line

Description A single line of an address.

city

string

[0 or 1]

City

Description City, town or geographical region for the mailing address.

state

string

[0 or 1]

State

Description State, province or analogous geographical region for mailing address

postal-code

string

[0 or 1]

Postal Code

Description Postal or ZIP code for mailing address

country

string

[0 or 1]

Country Code

Description The ISO 3166-1 alpha-2 country code for the mailing address.

Constraint (1)

matches: a target (value) must match the regular expression '[A-Z]{2}'.

email-addresses

array

[0 or 1]

(array member)

email

[0 to ∞]

Email Address

Description An email address as defined by RFC 5322 Section 3.4.1.

Remarks

This is a contact email associated with the location.

telephone-numbers

array

[0 or 1]

(array member)

string

[0 to ∞]

Telephone Number

Description Contact number by telephone.

Remarks

A phone number used to contact the location.

Properties (2)
type

string

[0 or 1]

type flag

Description Indicates the type of phone number.

Constraint (1)

allowed values

The value may be locally defined, or one of the following:

  • home: A home phone number.
  • office: An office phone number.
  • mobile: A mobile phone number.
number

string

[0 or 1]

urls

array

[0 or 1]

(array member)

uri

[0 to ∞]

Location URL

Description The uniform resource locator (URL) for a web site or Internet presence associated with the location.

props

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Property

Description 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.

Remarks

Properties permit the deployment and management of arbitrary controlled values, within OSCAL objects. A property can be included for any purpose useful to an application or implementation. Typically, properties will be used to sort, filter, select, order, and arrange OSCAL content objects, to relate OSCAL objects to one another, or to associate an OSCAL object to class hierarchies, taxonomies, or external authorities. Thus, the lexical composition of properties may be constrained by external processes to ensure consistency.

Property allows for associated remarks that describe why the specific property value was applied to the containing object, or the significance of the value in the context of the containing object.

Properties (6)
name

token

[1]

Property Name

Description A textual label that uniquely identifies a specific attribute, characteristic, or quality of the property's containing object.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • marking: 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.
uuid

uuid

[0 or 1]

Property Universally Unique Identifier

Description 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.

ns

uri

[0 or 1]

Property Namespace

Description A namespace qualifying the property's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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.

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.

value

string

[1]

Property Value

Description Indicates the value of the attribute, characteristic, or quality.

class

token

[0 or 1]

Property Class

Description 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.

Remarks

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

remarks

markup-multiline

[0 or 1]

Remarks

Description Additional commentary on the containing object.

array

[0 or 1]

(array member)

object
(global definition)

[1 to ∞]

Link

Description A reference to a local or remote resource

Remarks

To provide a cryptographic hash for a remote target resource, a local reference to a back matter resource is needed. The resource allows one or more hash values to be provided using the rlink/hash object.

The OSCAL link is a roughly based on the HTML link element.

Constraints (3)

matches for .[@rel=('reference') and starts-with(@href,'#')]/@href: the target value must match the lexical form of the 'uri-reference' data type.

index has key for .[@rel=('reference') and starts-with(@href,'#')]this value must correspond to a listing in the index index-back-matter-resource using a key constructed of key field(s) @href

matches for .[@rel=('reference') and not(starts-with(@href,'#'))]/@href: the target value must match the lexical form of the 'uri' data type.

Properties (4)
href

uri-reference

[1]

Hypertext Reference

Description A resolvable URL reference to a resource.

Remarks

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.

rel

token

[0 or 1]

Relation

Description Describes the type of relationship provided by the link. This can be an indicator of the link's purpose.

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: Reference
media-type

string

[0 or 1]

Media Type