Skip to main content

Catalog Model v1.1.3 XML Format Index

The following is a reference for the XML element and attribute types derived from the metaschema for this model.

Short name oscal-catalog

XML namespace http://csrc.nist.gov/ns/oscal/1.0

Remarks

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

action

assembly

Action

description An action applied by a role within a given party to the content.

Constraints (4)

index has key for responsible-partythis 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 responsible-partythis value must correspond to a listing in the index index-metadata-party-uuid using a key constructed of key field(s) party-uuid

allowed value for ./system/@value

The value may be locally defined, or the following:

  • http://csrc.nist.gov/ns/oscal: This value identifies action types defined in the NIST OSCAL namespace.

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

The value must be one of the following:

  • approval: An approval of a document instance's content.
  • request-changes: A request from the responisble party or parties to change the content.
Attributes (4):

uuid

uuid

[0 or 1]

Action Universally Unique Identifier

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

date

date-time-with-timezone

[0 or 1]

Action Occurrence Date

description The date and time when the action occurred.

type

token

[0 or 1]

Action Type

description The type of action documented by the assembly, such as an approval.

system

uri

[0 or 1]

Action Type System

description Specifies the action type system used.

Remarks

Provides a means to segment the value space for the type, so that different organizations and individuals can assert control over the allowed action's type. This allows the semantics associated with a given type 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.

Elements (4):

property

assembly

[0 to ∞]

Property

use name prop

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.

assembly

[0 to ∞]

Link

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.

responsible-party

assembly

[0 to ∞]

Responsible Party

Remarks

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

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

remarks

markup-multiline

[0 or 1]

Remarks

Remarks

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

addr-line

string

Address line

description A single line of an address.

address

assembly

Address

description A postal address for the location.

Attribute (1):

type

token

[0 or 1]

Address Type

use name type

Elements (5):

addr-line

string

[0 to ∞]

Address line

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 a 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}'.

back-matter

assembly

Back matter

description A collection of resources that may be referenced from within the OSCAL document instance.

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's uuid. 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

Elements (1):

resource

assembly

[0 to ∞]

Resource

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

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[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name

The value must be one of the following:

  • type: Identifies the type of resource represented. The most specific appropriate type value SHOULD be used.
  • 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 'date-time-with-timezone' data type.

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

The value must be 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 finding.
  • 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)

A title is required when a citation is provided.
Attribute (1):

uuid

uuid

[0 or 1]

Resource Universally Unique Identifier

description A unique identifier for a resource.

Elements (8):

title

markup-line

[0 or 1]

Resource Title

description An optional 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 An optional short summary of the resource used to indicate the purpose of the resource.

property

assembly

[0 to ∞]

Property

use name prop

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.

document-id

string

[0 to ∞]

Document Identifier

Remarks

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

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

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

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

citation

assembly

[0 or 1]

Citation

description An optional citation consisting of end note text using structured markup.

Elements (3):

text

markup-line

[1]

Citation Text

description A line of citation text.

property

assembly

[0 to ∞]

Property

use name prop

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.

assembly

[0 to ∞]

Link

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.

assembly

[0 to ∞]

Resource link

description A URL-based pointer to an external resource with an optional hash for verification and change detection.

Remarks

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

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

Attributes (2):

href

uri-reference

[0 or 1]

Hypertext Reference

description A resolvable URL pointing to the referenced resource.

Remarks

This value may be either:

  1. an absolute URI that points to a network resolvable resource,
  2. a relative reference pointing to a network resolvable resource whose base URI is the URI of the containing document, or

media-type

string

[0 or 1]

Media Type

Remarks

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

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

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

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

Elements (1):

hash

string

[0 to ∞]

Hash

description A hash of the resource identified by href, which can be used to verify the resource was not changed since it was hashed.

Remarks

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

base64

base64

[0 or 1]

Base64

description A resource encoded using the Base64 alphabet defined by RFC 2045.

Attributes (2):

filename

token

[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

Remarks

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

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

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

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

remarks

markup-multiline

[0 or 1]

Remarks

Remarks

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

catalog

assembly

Catalog

description A structured, organized collection of control information.

root name catalog

Remarks

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

Constraints (8)

allowed values 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.
  • source-profile-uuid: The document-level uuid of the source profile from which the catalog was produced by profile resolution.

allowed values for metadata/link/@rel

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

  • source-profile: The profile from which the catalog was produced by profile resolution.
  • source-profile-uuid: The document-level uuid of the profile from which the catalog was produced by profile resolution.

index for //part an index catalog-parts shall list values returned by targets //part using keys constructed of key field(s) @id

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

index for //(control|group|part) an index catalog-groups-controls-parts shall list values returned by targets //(control|group|part) using keys constructed of key field(s) @id

index for //control an index catalog-controls shall list values returned by targets //control using keys constructed of key field(s) @id

index for //param an index catalog-params shall list values returned by targets //param using keys constructed of key field(s) @id

index for //group an index catalog-groups shall list values returned by targets //group using keys constructed of key field(s) @id

Attribute (1):

uuid

uuid

[0 or 1]

Catalog Universally Unique Identifier

description Provides a globally unique means to identify a given catalog instance.

Elements (5):

metadata

assembly

[1]

Document Metadata

Remarks

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

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

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

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

parameter

assembly

[0 to ∞]

Parameter

use name param

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.

control

assembly

[0 to ∞]

Control

Remarks

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

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

group

assembly

[0 to ∞]

Control Group

Remarks

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

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

back-matter

assembly

[0 or 1]

Back matter

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's uuid. Other specialized link "rel" values also use this pattern when indicated in that context of use.

Back matter including references and resources.

control

assembly

Control

description A structured object representing a requirement or guideline, which when implemented will reduce an aspect of risk related to an information system and its information.

Remarks

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

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

Constraints (11)

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 values 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.
  • Withdrawn: **(deprecated)*** Use 'withdrawn' instead.

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.

index has key for link[@rel=('related','required','incorporated-into','moved-to') and starts-with(@href,'#')]this value must correspond to a listing in the index catalog-groups-controls-parts using a key constructed of key field(s) @href

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 implementation requirements or recommendations.
  • guidance: Additional information to consider when selecting, implementing, assessing, and monitoring a control.
  • example: An example of an implemented requirement or control statement.
  • 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-method".

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

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.
Attributes (2):

id

token

[0 or 1]

Control Identifier

description Identifies a control such that it can be referenced in the defining catalog and other OSCAL instances (e.g., profiles).

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.

Elements (6):

title

markup-line

[1]

Control Title

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

parameter

assembly

[0 to ∞]

Parameter

use name param

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.

property

assembly

[0 to ∞]

Property

use name prop

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.

assembly

[0 to ∞]

Link

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.

part

assembly

[0 to ∞]

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 references to this part from within a catalog, or within an instance of another OSCAL model that has a need to reference the part. Examples of where part referencing is used in OSCAL include:

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

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

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

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

control

assembly

[0 to ∞]

Control

Remarks

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

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

control-id

token

Control Identifier Reference

description A reference to a control with a corresponding id value. When referencing an externally defined control, the Control Identifier Reference must be used in the context of the external / imported OSCAL instance (e.g., uri-reference).

document-id

string

Document Identifier

description A document identifier qualified by an identifier scheme.

Remarks

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

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

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

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

Attribute (1):

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.

Remarks

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

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.

email-address

email-address

Email Address

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

group

assembly

Control Group

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

Remarks

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

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

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 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.
  • instruction: Information providing directions for a control or a group of controls.
Attributes (2):

id

token

[0 or 1]

Group Identifier

description Identifies the group for the purpose of cross-linking within the defining instance or from other instances that reference the catalog.

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.

Elements (6):

title

markup-line

[1]

Group Title

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

parameter

assembly

[0 to ∞]

Parameter

use name param

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.

property

assembly

[0 to ∞]

Property

use name prop

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.

assembly

[0 to ∞]

Link

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.

part

assembly

[0 to ∞]

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 references to this part from within a catalog, or within an instance of another OSCAL model that has a need to reference the part. Examples of where part referencing is used in OSCAL include:

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

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

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

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

group

assembly

[0 to ∞]

Control Group

Remarks

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

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

control

assembly

[0 to ∞]

Control

Remarks

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

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

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

Constraints (4)

matches for .[@algorithm=('SHA-224','SHA3-224')]: a target (value) must match the regular expression '^[0-9a-fA-F]{56}$'.

matches for .[@algorithm=('SHA-256','SHA3-256')]: a target (value) must match the regular expression '^[0-9a-fA-F]{64}$'.

matches for .[@algorithm=('SHA-384','SHA3-384')]: a target (value) must match the regular expression '^[0-9a-fA-F]{96}$'.

matches for .[@algorithm=('SHA-512','SHA3-512')]: a target (value) must match the regular expression '^[0-9a-fA-F]{128}$'.

Attribute (1):

algorithm

string

[0 or 1]

Hash algorithm

description The digest 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.

include-all

assembly

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.

last-modified

date-time-with-timezone

Last Modified Timestamp

description The date and time the document was last stored for later retrieval.

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. Ideally, this field will be managed by the editing tool or service used to make modifications when storing the modified document.

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

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

link

assembly

Link

description A reference to a local or remote resource, that has a specific relation to the containing object.

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 (4) A local reference SHOULD NOT have a media-type. Since both link and back-matter/resource both allow specification of a media-type, the media-type on link may conflict with the any media-type entries on a resource's rlink or base64 objects. This constraint prevents this from occurring.

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.

matches for @resource-fragment: a target (value) must match the regular expression '(?:[0-9a-zA-Z-._~/?!$&'()*+,;=:@]|%[0-9A-F][0-9A-F])+'.

Attributes (4):

href

uri-reference

[0 or 1]

Hypertext Reference

description A resolvable URL reference to a resource.

Remarks

This value may be one of:

  1. an absolute URI that points to a network resolvable resource,
  2. a relative reference pointing to a network resolvable resource whose base URI is the URI of the containing document, or
  3. a bare URI fragment (i.e., `#uuid`) pointing to an OSCAL object by the objects identifier (e.g., id, uuid) in this or an imported document (see linking to another OSCAL object). The specific object type will differ based on the link relationship type.

rel

token

[0 or 1]

Link Relation Type

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

Constraint (1)

allowed value

The value may be locally defined, or the following:

  • reference: A generalized reference to a network resource (relative or absolute) or to a back-matter resource by UUID expressed as a bare URI fragment.

media-type

string

[0 or 1]

Media Type

Remarks

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

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

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

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

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.

resource-fragment

string

[0 or 1]

Resource Fragment

description In case where the href points to a back-matter/resource, this value will indicate the URI fragment to append to any rlink associated with the resource. This value MUST be URI encoded.

Elements (1):

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.

location-type

token

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.

location-uuid

uuid

Location Universally Unique Identifier Reference

description Reference to a location by UUID.

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

media-type

string

Media Type

description A label that indicates the nature of a resource, as a data serialization or format.

Remarks

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

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

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

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

metadata

assembly

Document Metadata

description Provides information about the containing document, and defines concepts that are shared across the document.

Remarks

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

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

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

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

Constraints (14)

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 person or organization that created this content.
  • prepared-by: Indicates the person or organization that prepared this content.
  • prepared-for: Indicates the person or organization for which this content was created.
  • content-approver: Indicates the person or organization responsible for all content represented in the "document".
  • contact: Indicates the person or 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 resource. Defined by RFC 6596.
  • alternate: The link identifies an alternative location or format for this resource. 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.

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

Elements (15):

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

date-time-with-timezone

[0 or 1]

Publication Timestamp

Remarks

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

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

last-modified

date-time-with-timezone

[1]

Last Modified Timestamp

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. Ideally, this field will be managed by the editing tool or service used to make modifications when storing the modified document.

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

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

version

string

[1]

Document Version

Remarks

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

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

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

oscal-version

string

[1]

OSCAL Version

Remarks

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

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

revision

assembly

[0 to ∞]

Revision History Entry

description An entry in a sequential list of revisions to the containing document, expected to be in reverse chronological order (i.e. latest first).

wrapper element revisions

Remarks

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

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 resource. Defined by RFC 6596.
  • alternate: The link identifies an alternative location or format for this resource. 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.
  • version-history: This link identifies a resource containing the version history of this document. Defined by RFC 5829.
Elements (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

date-time-with-timezone

[0 or 1]

Publication Timestamp

Remarks

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

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

last-modified

date-time-with-timezone

[0 or 1]

Last Modified Timestamp

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. Ideally, this field will be managed by the editing tool or service used to make modifications when storing the modified document.

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

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

version

string

[1]

Document Version

Remarks

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

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

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

oscal-version

string

[0 or 1]

OSCAL Version

Remarks

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

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

property

assembly

[0 to ∞]

Property

use name prop

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.

assembly

[0 to ∞]

Link

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.

remarks

markup-multiline

[0 or 1]

Remarks

Remarks

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

document-id

string

[0 to ∞]

Document Identifier

Remarks

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

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

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

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

property

assembly

[0 to ∞]

Property

use name prop

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.

assembly

[0 to ∞]

Link

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.

role

assembly

[0 to ∞]

Role

description Defines a function, which might be assigned to 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.

Attribute (1):

id

token

[0 or 1]

Role Identifier

description A unique identifier for the role.

Elements (6):

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.

property

assembly

[0 to ∞]

Property

use name prop

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.

assembly

[0 to ∞]

Link

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.

remarks

markup-multiline

[0 or 1]

Remarks

Remarks

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

location

assembly

[0 to ∞]

Location

description A physical point of presence, which may be associated with people, organizations, or other concepts within the current or linked OSCAL document.

Remarks

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

Constraints (5)

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

The value must be one of the following:

  • type: Characterizes the kind of location.

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

The value must be one of 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[has-oscal-namespace('http://csrc.nist.gov/ns/oscal') and @name='type' and @value='data-center']/@class

The value must be 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.

has cardinality for address the cardinality of address is constrained: 1; maximum unbounded.

has cardinality for title|address|email-address|telephone-number the cardinality of title|address|email-address|telephone-number is constrained: 1; maximum unbounded.

Attribute (1):

uuid

uuid

[0 or 1]

Location Universally Unique Identifier

description A unique ID for the location, for reference.

Elements (8):

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

assembly

[0 or 1]

Address

Remarks

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

email-address

email-address

[0 to ∞]

Email Address

Remarks

A contact email associated with the location.

telephone-number

string

[0 to ∞]

Telephone Number

Remarks

A phone number used to contact the location.

url

uri

[0 to ∞]

Location URL

deprecated as of 1.1.0

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

Remarks

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

property

assembly

[0 to ∞]

Property

use name prop

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.

assembly

[0 to ∞]

Link

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.

remarks

markup-multiline

[0 or 1]

Remarks

Remarks

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

party

assembly

[0 to ∞]

Party

description An organization or person, which may be associated with roles or other concepts within the current or linked OSCAL document.

Remarks

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

Constraint (1)

allowed values for prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@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.
Attributes (2):

uuid

uuid

[0 or 1]

Party Universally Unique Identifier

description A unique identifier for the party.

type

string

[0 or 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: A human being regarded as an individual.
  • organization: An organized group of one or more person individuals with a specific purpose.
Elements (10):

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

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

Attribute (1):

scheme

uri

[0 or 1]

External Identifier Schema

description Indicates the type of external identifier.

Remarks

This value must be an absolute URI that serves as a naming system 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).

property

assembly

[0 to ∞]

Property

use name prop

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.

assembly

[0 to ∞]

Link

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.

email-address

email-address

[0 to ∞]

Email Address

Remarks

This is a contact email associated with the party.

telephone-number

string

[0 to ∞]

Telephone Number

Remarks

A phone number used to contact the party.

address

assembly

[0 to ∞]

Address

location-uuid

uuid

[0 to ∞]

Location Universally Unique Identifier Reference

member-of-organization

uuid

[0 to ∞]

Organizational Affiliation

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

Remarks

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

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

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

Remarks

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

responsible-party

assembly

[0 to ∞]

Responsible Party

Remarks

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

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

action

assembly

[0 to ∞]

Action

remarks

markup-multiline

[0 or 1]

Remarks

Remarks

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

oscal-version

string

OSCAL Version

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

Remarks

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

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

param

assembly

Parameter

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

use name param

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 two or more other parameters, each described by this property.
depends-on is deprecated
Attributes (3):

id

token

[0 or 1]

Parameter Identifier

description A unique identifier for the parameter.

class

token

[0 or 1]

Parameter Class

description A textual label that provides a characterization of the type, purpose, use or scope 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

deprecated as of 1.0.1

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

Elements (8):

property

assembly

[0 to ∞]

Property

use name prop

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.

assembly

[0 to ∞]

Link

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.

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 is intended use when rendering a parameter in generated documentation or a user interface when a parameter is referenced. Note that labels are not required to be distinctive, which means that parameters within the same control may have the same label.

usage

markup-multiline

[0 or 1]

Parameter Usage Description

description Describes the purpose and use of a parameter.

constraint

assembly

[0 to ∞]

Constraint

use name constraint

guideline

assembly

[0 to ∞]

Guideline

use name guideline

value

string

[0 to ∞]

Parameter Value

use name value

Remarks

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

select

assembly

[0 or 1]

Selection

use name select

Remarks

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

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

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

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

remarks

markup-multiline

[0 or 1]

Remarks

Remarks

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

parameter-constraint

assembly

Constraint

description A formal or informal expression of a constraint or test.

Elements (2):

description

markup-multiline

[0 or 1]

Constraint Description

description A textual summary of the constraint to be applied.

test

assembly

[0 to ∞]

Constraint Test

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

Elements (2):

expression

string

[1]

Constraint test

description A formal (executable) expression of a constraint.

remarks

markup-multiline

[0 or 1]

Remarks

Remarks

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

parameter-guideline

assembly

Guideline

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

Elements (1):

(unwrapped)

markup-multiline

[1]

Guideline Text

description Prose permits multiple paragraphs, lists, tables etc.

parameter-selection

assembly

Selection

description Presenting a choice among alternatives.

Remarks

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

Attribute (1):

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.
Elements (1):

choice

markup-line

[0 to ∞]

Choice

description A value selection among several such options.

parameter-value

string

Parameter Value

description A parameter value or set of values.

part

assembly

Part

description An annotated, markup-based textual element of a control's or catalog group'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 references to this part from within a catalog, or within an instance of another OSCAL model that has a need to reference the part. Examples of where part referencing is used in OSCAL include:

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

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

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

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

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.
Attributes (4):

id

token

[0 or 1]

Part Identifier

description A unique identifier for the part.

Remarks

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

name

token

[0 or 1]

Part Name

description A textual label that uniquely identifies the part's semantic type, which exists in a value space qualified by the ns.

ns

uri

[0 or 1]

Part Namespace

description An optional namespace qualifying the part's name. This allows different organizations to associate distinct semantics with the same name.

Remarks

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

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

class

token

[0 or 1]

Part Class

description An optional textual providing a sub-type or characterization of the part's name, or a category to which the part belongs.

Remarks

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

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

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

Elements (5):

title

markup-line

[0 or 1]

Part Title

description An optional name given to the part, which may be used by a tool for display and navigation.

property

assembly

[0 to ∞]

Property

use name prop

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.

(unwrapped)

markup-multiline

[0 or 1]

Part Text

description Permits multiple paragraphs, lists, tables etc.

part

assembly

[0 to ∞]

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 references to this part from within a catalog, or within an instance of another OSCAL model that has a need to reference the part. Examples of where part referencing is used in OSCAL include:

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

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

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

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

assembly

[0 to ∞]

Link

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.

party-uuid

uuid

Party Universally Unique Identifier Reference

description Reference to a party by UUID.

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

prop

assembly

Property

description An attribute, characteristic, or quality of the containing object expressed as a namespace qualified name/value pair.

use name prop

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.

Constraint (1)

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

The value must be one of 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.
Attributes (6):

name

token

[0 or 1]

Property Name

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

uuid

uuid

[0 or 1]

Property Universally Unique Identifier

description A unique identifier for a property.

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

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

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

value

string

[0 or 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.

Remarks

This can be used to further distinguish or discriminate between the semantics of multiple properties of the same object with the same name and ns, or to group properties into categories.

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

group

token

[0 or 1]

Property Group

description An identifier for relating distinct sets of properties.

Remarks

Different sets of properties may relate to separate contexts. Declare a group on a property to associate it with one or more other properties in a given context.

Elements (1):

remarks

markup-multiline

[0 or 1]

Remarks

Remarks

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

published

date-time-with-timezone

Publication Timestamp

description The date and time the document was last made available.

Remarks

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

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

description Additional commentary about the containing object.

Remarks

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

responsible-party

assembly

Responsible Party

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

Remarks

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

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

Constraint (1)

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

Attribute (1):

role-id

token

[0 or 1]

Responsible Role

description A reference to a role performed by a party.

Elements (4):

party-uuid

uuid

[1 to ∞]

Party Universally Unique Identifier Reference

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

property

assembly

[0 to ∞]

Property

use name prop

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.

assembly

[0 to ∞]

Link

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.

remarks

markup-multiline

[0 or 1]

Remarks

Remarks

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

responsible-role

assembly

Responsible Role

description A reference to a role with responsibility for performing a function relative to the containing object, optionally associated with a set of persons and/or organizations that perform that role.

Remarks

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

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

Attribute (1):

role-id

token

[0 or 1]

Responsible Role ID

description A human-oriented identifier reference to a role performed.

Elements (4):

property

assembly

[0 to ∞]

Property

use name prop

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.

assembly

[0 to ∞]

Link

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.

party-uuid

uuid

[0 to ∞]

Party Universally Unique Identifier Reference

description Specifies zero or more parties responsible for performing the associated role.

remarks

markup-multiline

[0 or 1]

Remarks

Remarks

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

role-id

token

Role Identifier Reference

description Reference to a role by UUID.

Constraint (1)

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

telephone-number

string

Telephone Number

description A telephone service number as defined by ITU-T E.164.

Constraint (1)

matches: a target (value) must match the regular expression '^[0-9]{3}[0-9]{1,12}$'.

Attribute (1):

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.

version

string

Document Version

description Used to distinguish a specific revision of an OSCAL document from other previous and future versions.

Remarks

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

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

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

This page was last updated on January 1, 0001.