Skip to main content

OSCAL Component Definition Model JSON Format Reference

OSCAL model OSCAL Component Definition Model

Version 1.0.0-rc1

JSON Schema oscal_component_schema.json

XML to JSON converter oscal_component_xml-to-json-converter.xsl (How do I use the converter to convert OSCAL XML to JSON?)

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

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

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

addr-line

formal name Address line

A single line of an address.

A string conforming to the lexical and value-space requirements defined for string.

This object appears as a member of an array property defined for address.

address

formal name Address

A postal address for the location.

This object appears as a member of an array property defined for party.

Properties (6)

  • type

    NCName [0 or 1] Address Type

    Indicates the type of address.

  • addr-lines

    array [optional] array of strings
    (array member) string [0 to ∞] Address line

    A single line of an address.

  • city

    string [0 or 1] City

    City, town or geographical region for the mailing address.

  • state

    string [0 or 1] State

    State, province or analogous geographical region for mailing address

  • postal-code

    string [0 or 1] Postal Code

    Postal or ZIP code for mailing address

  • country

    string [0 or 1] Country Code

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

back-matter

formal name Back matter

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.

Property (1)

  • resources

    array [optional] array of objects
    (array member) object [1 to ∞] Resource

    A resource associated with content in the containing document. A resource may be directly included in the document base64 encoded or may point to one or more equivalent internet resources.

    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.

    Properties (9): uuid, title, description, prop, document-id, citation, rlink, base64, remarks
    • uuid

      uuid [1] Resource Universally Unique Identifier

      A globally unique identifier that can be used to reference this defined resource elsewhere in an OSCAL document. A UUID should be consistently used for a given resource across revisions of the document.

    • title

      markup-line [0 or 1] Resource Title

      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

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

    • props

      array [optional] array of objects
      (array member) object (globally defined) [0 to ∞] Property

      An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

      Remarks (general)

      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.

    • document-ids

      array [optional] array of objects
      (array member) object [0 to ∞] Document Identifier

      A document identifier qualified by an identifier scheme. A document identifier provides a globally unique identifier 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 (general)

      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.

    • citation

      object [0 or 1] Citation

      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, prop, biblio
      • text

        markup-line [1] Citation Text

        A line of citation text.

      • props

        array [optional] array of objects
        (array member) object (globally defined) [0 to ∞] Property

        An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

        Remarks (general)

        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.

      • biblio

        object [0 or 1] Bibliographic Definition

        A container for structured bibliographic information. The model of this information is undefined by OSCAL.

    • array [optional] array of objects
    • base64

      object [0 or 1] Base64

      The Base64 alphabet in RFC 2045 - aligned with XSD.

      Properties (2): filename, media-type
      • filename

        uri-reference [0 or 1] File Name

        Name of the file before it was encoded as Base64 to be embedded in a resource. This is the name that will be assigned to the file when the file is decoded.

      • media-type

        string [0 or 1] Media Type

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

    • remarks

      markup-multiline [0 or 1] Remarks

      Additional commentary on the containing object.

capability

formal name Capability

A grouping of other components and/or capabilities.

This object appears, with any others of its type, grouped as a property of component-definition.

Properties (8)

  • uuid

    uuid [1] Capability Identifier

    A unique identifier for a capability.

  • name

    string [1] Capability Name

    The capability's human-readable name.

  • description

    markup-multiline [1] Capability Description

    A summary of the capability.

  • props

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Property

    An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

    Remarks (general)

    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.

  • links

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Link

    A reference to a local or remote resource

    Remarks (general)

    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.

  • incorporates-components

    array [optional] array of objects
  • control-implementations

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Control Implementation Set

    Defines how the component or capability supports a set of controls.

    Remarks (general)

    Use of set-parameter in this context, sets the parameter for all related controls referenced in an implemented-requirement. If the same parameter is also set in a specific implemented-requirement, then the new value will override this value.

  • remarks

    markup-multiline [0 or 1] Remarks

    Additional commentary on the containing object.

component-definition

formal name Component Definition

A collection of component descriptions, which may optionally be grouped by capability.

component-definition is a root (containing) object for this schema.

Properties (6)

  • uuid

    uuid [1] Component Definition Universally Unique Identifier

    A globally unique identifier for this component definition instance. This UUID should be changed when this document is revised.

  • metadata

    object (globally defined) [1] Publication metadata

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

  • import-component-definitions

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Import Component Definition

    Loads a component definition from another resource.

  • components

    array [optional] array of objects
    {} object (globally defined) [0 to ∞] Component

    A defined component that can be part of an implemented system.

    Remarks (general)

    Components may be products, services, APIs, policies, processes, plans, guidance, standards, or other tangible items that enable security and/or privacy.

    The type indicates which of these component types is represented.

    A group of components may be aggregated into a capability. For example, an account management capability that consists of an account management process, and a Lightweight Directory Access Protocol (LDAP) software implementation.

    Capabilities are expressed by combining one or more components.

  • capabilities

    array [optional] array of objects
    {} object (globally defined) [0 to ∞] Capability

    A grouping of other components and/or capabilities.

  • back-matter

    object (globally defined) [0 or 1] Back matter

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

    Remarks (general)

    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.

control-implementation

formal name Control Implementation Set

Defines how the component or capability supports a set of controls.

This object appears as a member of an array property defined for defined-component and capability.

Remarks

Use of set-parameter in this context, sets the parameter for all related controls referenced in an implemented-requirement. If the same parameter is also set in a specific implemented-requirement, then the new value will override this value.

Properties (7)

  • uuid

    uuid [1] Control Implementation Set Identifier

    A unique identifier for the set of implemented controls.

  • source

    uri-reference [1] Source Resource Reference

    A reference to an OSCAL catalog or profile providing the referenced control or subcontrol definition.

    Remarks (local)

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

  • description

    markup-multiline [1] Control Implementation Description

    A description of how the specified set of controls are implemented for the containing component or capability.

  • props

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Property

    An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

    Remarks (general)

    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.

  • links

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Link

    A reference to a local or remote resource

    Remarks (general)

    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.

  • set-parameters

    array [optional] array of objects
    {} object (globally defined) [0 to ∞] Set Parameter Value

    Identifies the parameter that will be set by the enclosed value.

  • implemented-requirements

    array [required] array of objects
    (array member) object (globally defined) [1 to ∞] Control Implementation

    Describes how the containing component or capability implements an individual control.

defined-component

formal name Component

A defined component that can be part of an implemented system.

This object appears, with any others of its type, grouped as a property of component-definition.

Remarks

Components may be products, services, APIs, policies, processes, plans, guidance, standards, or other tangible items that enable security and/or privacy.

The type indicates which of these component types is represented.

A group of components may be aggregated into a capability. For example, an account management capability that consists of an account management process, and a Lightweight Directory Access Protocol (LDAP) software implementation.

Capabilities are expressed by combining one or more components.

Properties (11)

  • uuid

    uuid [1] Component Identifier

    The unique identifier for the component.

  • type

    string [1] Component Type

    A category describing the purpose of the component.

  • title

    markup-line [1] Component Title

    A human readable name for the component.

  • description

    markup-multiline [1] Component Description

    A description of the component, including information about its function.

  • purpose

    markup-line [0 or 1] Purpose

    A summary of the technological or business purpose of the component.

  • props

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Property

    An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

    Remarks (general)

    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.

  • links

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Link

    A reference to a local or remote resource

    Remarks (general)

    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.

  • responsible-roles

    array [optional] array of objects
    {} object (globally defined) [0 to ∞] Responsible Role

    A reference to one or more roles with responsibility for performing a function relative to the containing object.

  • protocols

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Service Protocol Information

    Information about the protocol used to provide a service.

    Remarks (local)

    Used for service components to define the protocols supported by the service.

  • control-implementations

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Control Implementation Set

    Defines how the component or capability supports a set of controls.

    Remarks (general)

    Use of set-parameter in this context, sets the parameter for all related controls referenced in an implemented-requirement. If the same parameter is also set in a specific implemented-requirement, then the new value will override this value.

  • remarks

    markup-multiline [0 or 1] Remarks

    Additional commentary on the containing object.

document-id

formal name Document Identifier

A document identifier qualified by an identifier scheme. A document identifier provides a globally unique identifier 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.

This object appears as a member of an array property defined for metadata and resource.

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

  • identifier

    string [1] Document Identifier Value

    This property provides the (nominal) value for this object as a whole.

  • scheme

    uri [1] Document Identification Scheme

    Qualifies the kind of document identifier using a URI. If the scheme is not provided the value of the element will be interpreted as a string of characters.

    allowed value for document-id/@scheme

    The value may be locally defined, or the following:

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

email-address

formal name Email Address

An email address as defined by RFC 5322 Section 3.4.1.

A string conforming to the lexical and value-space requirements defined for email.

This object appears as a member of an array property defined for location and party.

hash

formal name Hash

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

This object appears as a member of an array property defined for rlink.

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.

Properties

  • value

    string [1] Hash Value

    This property provides the (nominal) value for this object as a whole.

  • algorithm

    string [1] Hash algorithm

    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.

    allowed values for hash/@algorithm

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

implemented-requirement

formal name Control Implementation

Describes how the containing component or capability implements an individual control.

This object appears as a member of an array property defined for control-implementation.

Properties (9)

  • uuid

    uuid [1] Control Implementation Identifier

    A unique identifier for a specific control implementation.

  • control-id

    NCName [0 or 1] Control Identifier Reference

    A reference to a control identifier.

  • description

    markup-multiline [1] Control Implementation Description

    A description of how the specified control is implemented for the containing component or capability.

  • props

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Property

    An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

    Remarks (general)

    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.

  • links

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Link

    A reference to a local or remote resource

    Remarks (general)

    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.

  • responsible-roles

    array [optional] array of objects
    {} object (globally defined) [0 to ∞] Responsible Role

    A reference to one or more roles with responsibility for performing a function relative to the containing object.

  • set-parameters

    array [optional] array of objects
    {} object (globally defined) [0 to ∞] Set Parameter Value

    Identifies the parameter that will be set by the enclosed value.

  • statements

    array [optional] array of objects
    {} object (globally defined) [0 to ∞] Control Statement Implementation

    Identifies which statements within a control are addressed.

  • remarks

    markup-multiline [0 or 1] Remarks

    Additional commentary on the containing object.

import-component-definition

formal name Import Component Definition

Loads a component definition from another resource.

This object appears as a member of an array property defined for component-definition.

Property (1)

  • href

    uri-reference [1] Hyperlink Reference

    A link to a resource that defines a set of components and/or capabilities to import into this collection.

incorporates-component

formal name Incorporates Component

TBD

This object appears, with any others of its type, grouped as a property of capability.

Properties (2)

  • component-uuid

    uuid [1] Component Reference

    A reference to a component by its identifier

  • description

    markup-multiline [1] Component Description

    A description of the component, including information about its function.

last-modified

formal name Last Modified Timestamp

The date and time the document was last modified. The date-time value must be formatted according to RFC 3339 with full time and time zone included.

A string conforming to the lexical and value-space requirements defined for dateTime-with-timezone.

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.

location

formal name Location

A location, with associated metadata that can be referenced.

This object appears as a member of an array property defined for metadata.

Properties (9)

  • uuid

    uuid [1] Location Universally Unique Identifier

    A unique identifier that can be used to reference this defined location elsewhere in an OSCAL document. A UUID should be consistently used for a given location across revisions of the document.

  • title

    markup-line [0 or 1] Location Title

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

  • address

    object (globally defined) [1] Address

    A postal address for the location.

    Remarks (local)

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

  • email-addresses

    array [optional] array of strings
    (array member) email [0 to ∞] Email Address

    An email address as defined by RFC 5322 Section 3.4.1.

    Remarks (local)

    This is a contact email associated with the location.

  • telephone-numbers

    array [optional] array of objects
    (array member) object [0 to ∞] Telephone Number

    Contact number by telephone.

    Remarks (local)

    A phone number used to contact the location.

  • urls

    array [optional] array of strings
    (array member) uri [1 to ∞] Location URL

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

  • props

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Property

    An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

    Remarks (general)

    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.

  • links

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Link

    A reference to a local or remote resource

    Remarks (general)

    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.

  • remarks

    markup-multiline [0 or 1] Remarks

    Additional commentary on the containing object.

location-uuid

formal name Location Reference

References a location defined in metadata.

A string conforming to the lexical and value-space requirements defined for uuid.

This object appears as a member of an array property defined for party.

metadata

formal name Publication metadata

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

Properties (14)

  • title

    markup-line [1] Document Title

    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

    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 (general)

    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

    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 (general)

    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

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

    Remarks (general)

    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

    The OSCAL model version the document was authored against.

    Remarks (general)

    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 [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Revision History Entry

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

    Remarks (general)

    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.

  • document-ids

    array [optional] array of objects
    (array member) object [0 to ∞] Document Identifier

    A document identifier qualified by an identifier scheme. A document identifier provides a globally unique identifier 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 (general)

    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.

  • props

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Property

    An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

    Remarks (general)

    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.

  • links

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Link

    A reference to a local or remote resource

    Remarks (general)

    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.

  • roles

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Role

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

    Remarks (general)

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

  • locations

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Location

    A location, with associated metadata that can be referenced.

  • parties

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Party (organization or person)

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

  • responsible-parties

    array [optional] array of objects
    {} object (globally defined) [0 to ∞] Responsible Party

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

  • remarks

    markup-multiline [0 or 1] Remarks

    Additional commentary on the containing object.

oscal-version

formal name OSCAL version

The OSCAL model version the document was authored against.

A string conforming to the lexical and value-space requirements defined for string.

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.

party

formal name Party (organization or person)

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

This object appears as a member of an array property defined for metadata.

Properties (13)

  • uuid

    uuid [1] Party Universally Unique Identifier

    A unique identifier that can be used to reference this defined location elsewhere in an OSCAL document. A UUID should be consistently used for a given party across revisions of the document.

  • type

    string [1] Party Type

    A category describing the kind of party the object describes.

    allowed values for party/@type

    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

    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

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

  • external-ids

    array [optional] array of objects
    (array member) object [1 to ∞] Party External Identifier

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

    Property (1): scheme
    • scheme

      uri [1] External Identifier Schema

      Indicates the type of external identifier.

      allowed value for party/external-id/@scheme

      The value may be locally defined, or the following:

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

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Property

    An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

    Remarks (general)

    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.

  • links

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Link

    A reference to a local or remote resource

    Remarks (general)

    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.

  • email-addresses

    array [optional] array of strings
    (array member) email [0 to ∞] Email Address

    An email address as defined by RFC 5322 Section 3.4.1.

    Remarks (local)

    This is a contact email associated with the party.

  • telephone-numbers

    array [optional] array of objects
    (array member) object [0 to ∞] Telephone Number

    Contact number by telephone.

    Remarks (local)

    A phone number used to contact the party.

  • addresses

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Address

    A postal address for the location.

  • location-uuids

    array [optional] array of strings
    (array member) uuid [0 to ∞] Location Reference

    References a location defined in metadata.

  • member-of-organizations

    array [optional] array of strings
    (array member) uuid [1 to ∞] Organizational Affiliation

    Identifies that the party object is a member of the organization associated with the provided UUID.

    Remarks

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

  • remarks

    markup-multiline [0 or 1] Remarks

    Additional commentary on the containing object.

party-uuid

formal name Party Reference

References a party defined in metadata.

A string conforming to the lexical and value-space requirements defined for uuid.

This object appears as a member of an array property defined for responsible-party and responsible-role.

port-range

formal name Port Range

Where applicable this is the IPv4 port range on which the service operates.

This object appears as a member of an array property defined for protocol.

Remarks

To be validated as a natural number (integer >= 1). A single port uses the same value for start and end. Use multiple 'port-range' entries for non-contiguous ranges.

Properties (3)

  • start

    nonNegativeInteger [0 or 1] Start

    Indicates the starting port number in a port range

    Remarks

    Should be a number within a permitted range

  • end

    nonNegativeInteger [0 or 1] End

    Indicates the ending port number in a port range

    Remarks

    Should be a number within a permitted range

  • transport

    NCName [0 or 1] Transport

    Indicates the transport type.

    allowed values for port-range/@transport

    The value must be one of the following:

    • TCP: Transmission Control Protocol
    • UDP: User Datagram Protocol

prop

formal name Property

An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

This object appears as a member of an array property defined for metadata, revision, location, party, role, resource, citation, responsible-party, responsible-role, defined-component, capability, control-implementation, implemented-requirement, and statement.

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

    NCName [1] Property Name

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

    allowed value for location/prop/@name

    The value may be locally defined, or the following:

    • type: Characterizes the kind of location.

    allowed values for party/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.

    allowed values for back-matter/resource/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.

    allowed value for prop/@name

    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.

    allowed values for defined-component/prop/@name

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

    • version: The version of the component.
    • patch-level: The specific patch level of the component.
    • model: The model of the component.
    • release-date: The date the component was released, such as a software release date or policy publication date.
    • validation-type: Used with component-type='validation' to provide a well-known name for a kind of validation.
    • validation-reference: Used with component-type='validation' to indicate the validating body's assigned identifier for their validation of this component.
    • asset-type: Simple indication of the asset's function, such as Router, Storage Array, DNS Server.
    • asset-id: An organizationally specific identifier that is used to uniquely identify a logical or tangible item by the organization that owns the item.
    • asset-tag: An asset tag assigned by the organization responsible for maintaining the logical or tangible item.
    • public: Identifies whether the asset is publicly accessible (yes/no)
    • virtual: Identifies whether the asset is virtualized (yes/no)
    • vlan-id: Virtual LAN identifier of the asset.
    • network-id: The network identifier of the asset.
    • label: A human-readable label for the parent context.
    • sort-id: An alternative identifier, whose value is easily sortable among other such values in the document.
    • baseline-configuration-name: The name of the baseline configuration for the asset.
    • allows-authenticated-scan: Can the asset be check with an authenticated scan? (yes/no)
    • function: The function provided by the asset for the system.
  • uuid

    uuid [0 or 1] Property Universally Unique Identifier

    A unique identifier that can be used to reference this property elsewhere in an OSCAL document. A UUID should be consistently used for a given location across revisions of the document.

  • ns

    uri [0 or 1] Property Namespace

    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

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

    allowed value for location/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 a subclass of data-center.

    allowed values for back-matter/resource/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.

    allowed values for defined-component/prop[@name='asset-type']/@value

    The value must be one of the following:

    • operating-system: System software that manages computer hardware, software resources, and provides common services for computer programs.
    • database: An electronic collection of data, or information, that is specially organized for rapid search and retrieval.
    • web-server: A system that delivers content or services to end users over the Internet or an intranet.
    • dns-server: A system that resolves domain names to internet protocol (IP) addresses.
    • email-server: A computer system that sends and receives electronic mail messages.
    • directory-server: A system that stores, organizes and provides access to directory information in order to unify network resources.
    • pbx: A private branch exchange (PBX) provides a a private telephone switchboard.
    • firewall: A network security system that monitors and controls incoming and outgoing network traffic based on predetermined security rules.
    • router: A physical or virtual networking device that forwards data packets between computer networks.
    • switch: A physical or virtual networking device that connects devices within a computer network by using packet switching to receive and forward data to the destination device.
    • storage-array: A consolidated, block-level data storage capability.
    • appliance: A physical or virtual machine that centralizes hardware, software, or services for a specific purpose.

    allowed values for defined-component/prop[@name='virtual']/@value

    The value must be one of the following:

    • yes: The component is virtualized.
    • no: The component is not virtualized.

    allowed values for defined-component/prop[@name='public']/@value

    The value must be one of the following:

    • yes: The component is publicly accessible.
    • no: The component is not publicly accessible.

    allowed values for defined-component/prop[@name='implementation-point']/@value

    The value must be one of the following:

    • inteneral: The component is implemented within the system boundary.
    • external: The component is implemented outside the system boundary.
  • class

    NCName [0 or 1] Property Class

    A textual label that provides a sub-type or characterization of the property's name. This can be used to further distinguish or discriminate between the semantics of multiple properties of the same object with the same name and ns.

    Remarks

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

    allowed values for location/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.
  • remarks

    markup-multiline [0 or 1] Remarks

    Additional commentary on the containing object.

protocol

formal name Service Protocol Information

Information about the protocol used to provide a service.

This object appears as a member of an array property defined for defined-component.

Properties (4)

  • uuid

    uuid [0 or 1] Service Protocol Information Universally Unique Identifier

    A globally unique identifier that can be used to reference this service protocol entry elsewhere in an OSCAL document. A UUID should be consistently used for a given resource across revisions of the document.

  • name

    string [1] Protocol Name

    The common name of the protocol, which should be the appropriate "service name" from the IANA Service Name and Transport Protocol Port Number Registry.

    Remarks

    The short name of the protocol (e.g., https).

  • title

    markup-line [0 or 1] Protocol Title

    A human readable name for the protocol (e.g., Transport Layer Security).

  • port-ranges

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Port Range

    Where applicable this is the IPv4 port range on which the service operates.

    Remarks (general)

    To be validated as a natural number (integer >= 1). A single port uses the same value for start and end. Use multiple 'port-range' entries for non-contiguous ranges.

published

formal name Publication Timestamp

The date and time the document was published. The date-time value must be formatted according to RFC 3339 with full time and time zone included.

A string conforming to the lexical and value-space requirements defined for dateTime-with-timezone.

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.

remarks

formal name Remarks

Additional commentary on the containing object.

A string conforming to the lexical and value-space requirements defined for markup-multiline.

As such, this value permits expression of marked up text in Markdown format, according to the rules described for the (text-based) datatype. This datatype permits the expression of block-level constructs including paragraphs, lists and simple tables, potentially including simple formatting such as bold or typographic emphasis. This representation is designed for the relatively unconstrained capture of simple free text, i.e. without formatting or decoration that might serve as ad-hoc and uncontrolled semantic encoding not subject to detection, regularization or validation.

This data construct is designed to be minimalistic for purposes of ease of development and interchange. It will not fit all operational scenarios; when markup-multiline is not adequate for purposes of necessary (informational) fidelity to information encoded in source formats (and subsequently converted into OSCAL), alternative strategies are available for such data capture. Users and stakeholders who expose requirements in this area are encouraged to provide feedback and request guidance.

responsible-party

formal name Responsible Party

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

This object appears, with any others of its type, grouped as a property of metadata.

Properties (5)

  • role-id

    NCName [1] Responsible Role

    The role that the party is responsible for.

    allowed values for metadata/responsible-party/@role-id

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

    • prepared-by: Indicates the organization that created this content.
    • prepared-for: Indicates the organization for which this content was created.
    • content-approver: Indicates the organization responsible for all content represented in the "document".
  • party-uuids

    array [required] array of strings
    (array member) uuid [1 to ∞] Party Reference

    References a party defined in metadata.

    Remarks (local)

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

  • props

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Property

    An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

    Remarks (general)

    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.

  • links

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Link

    A reference to a local or remote resource

    Remarks (general)

    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.

  • remarks

    markup-multiline [0 or 1] Remarks

    Additional commentary on the containing object.

responsible-role

formal name Responsible Role

A reference to one or more roles with responsibility for performing a function relative to the containing object.

This object appears, with any others of its type, grouped as a property of defined-component, implemented-requirement, and statement.

Properties (5)

  • role-id

    NCName [1] Responsible Role ID

    The role that is responsible for the business function.

  • props

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Property

    An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

    Remarks (general)

    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.

  • links

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Link

    A reference to a local or remote resource

    Remarks (general)

    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.

  • party-uuids

    array [optional] array of strings
    (array member) uuid [0 to ∞] Party Reference

    References a party defined in metadata.

  • remarks

    markup-multiline [0 or 1] Remarks

    Additional commentary on the containing object.

revision

formal name Revision History Entry

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

This object appears as a member of an array property defined for metadata.

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.

Properties (8)

  • title

    markup-line [0 or 1] Document Title

    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

    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 (general)

    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

    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 (general)

    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 [0 or 1] Document Version

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

    Remarks (general)

    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

    The OSCAL model version the document was authored against.

    Remarks (general)

    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 [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Property

    An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

    Remarks (general)

    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.

  • links

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Link

    A reference to a local or remote resource

    Remarks (general)

    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.

  • remarks

    markup-multiline [0 or 1] Remarks

    Additional commentary on the containing object.

role

formal name Role

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

This object appears as a member of an array property defined for metadata.

Remarks

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

Properties (7)

  • id

    NCName [1] Role Identifier

    A unique identifier for a specific role instance. This identifier's uniqueness is document scoped and is intended to be consistent for the same role across minor revisions of the document.

    Remarks

    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.

  • title

    markup-line [1] Role Title

    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

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

  • description

    markup-multiline [0 or 1] Role Description

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

  • props

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Property

    An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

    Remarks (general)

    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.

  • links

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Link

    A reference to a local or remote resource

    Remarks (general)

    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.

  • remarks

    markup-multiline [0 or 1] Remarks

    Additional commentary on the containing object.

set-parameter

formal name Set Parameter Value

Identifies the parameter that will be set by the enclosed value.

This object appears, with any others of its type, grouped as a property of control-implementation and implemented-requirement.

Properties (3)

  • param-id

    NCName [1] Parameter ID

    A reference to a parameter within a control, who's catalog has been imported into the current implementation context.

  • values

    array [required] array of strings
    (array member) string [1 to ∞] Parameter Value

    A parameter value or set of values.

  • remarks

    markup-multiline [0 or 1] Remarks

    Additional commentary on the containing object.

statement

formal name Control Statement Implementation

Identifies which statements within a control are addressed.

This object appears, with any others of its type, grouped as a property of implemented-requirement.

Properties (7)

  • statement-id

    NCName [1] Control Statement Reference

    A reference to a control statement by its identifier

    Remarks (local)

    A reference to the specific implemented statement associated with a control.

  • uuid

    uuid [1] Control Statement Implementation Identifier

    A unique identifier for a specific control implementation.

  • description

    markup-multiline [1] Statement Implementation Description

    A summary of how the containing control statement is implemented by the component or capability.

  • props

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Property

    An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair. The value of a property is a simple scalar value, which may be expressed as a list of values.

    Remarks (general)

    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.

  • links

    array [optional] array of objects
    (array member) object (globally defined) [0 to ∞] Link

    A reference to a local or remote resource

    Remarks (general)

    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.

  • responsible-roles

    array [optional] array of objects
    {} object (globally defined) [0 to ∞] Responsible Role

    A reference to one or more roles with responsibility for performing a function relative to the containing object.

  • remarks

    markup-multiline [0 or 1] Remarks

    Additional commentary on the containing object.

telephone-number

formal name Telephone Number

Contact number by telephone.

This object appears as a member of an array property defined for location and party.

Properties

  • number

    string [1] Telephone Number Value

    This property provides the (nominal) value for this object as a whole.

  • type

    string [0 or 1] type flag

    Indicates the type of phone number.

    allowed values for telephone-number/@type

    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.

version

formal name Document Version

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

A string conforming to the lexical and value-space requirements defined for string.

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.

This page was last updated on April 22, 2021.