Skip to main content

Identifier Use

This page reviews important concepts to be aware of when declaring or referencing identifiers in OSCAL models, with in-depth explanations of identifier uniqueness and scope.

Identifier Type

By design, OSCAL supports machine-oriented and human-oriented identifiers. The OSCAL models dictate which are used for different data items.

Machine-Oriented

Machine-oriented identifiers provide a persistent identity for an entity within the OSCAL models, which can be used in other locations within related OSCAL models to reference the associated entity.

These identifiers are intended to be auto-generated by tools when the entity is initially created. In OSCAL, a machine-oriented identifier is implemented using a Universally Unique Identifier (UUID) as defined by RFC 4122. A UUID is represented in OSCAL using the UUID datatype. UUIDs were chosen because:

  • Programming interfaces exist in most programming environments to generate a UUID
  • UUIDs can be issued without a central authority
  • UUIDs are represented in 128 bits, providing for a large address space with low risk of identifier collisions for randomly generated values
The opaque nature of UUIDs, which consist of a series of hexadecimal characters, makes them less than ideal for wildcard matching scenarios. Thus, their use in OSCAL is intended for identification only where an exact match is required. Where wildcard matching is needed, the other data elements associated with the entity should be evaluated for a match instead.

The OSCAL XML Reference Index and OSCAL JSON Reference Index provide a listing of UUIDs in the core OSCAL models. References to these identifiers typically follow a naming convention of the object type followed by “-uuid”. For example, see the XML reference index for location-uuid (or location-uuids in the JSON reference index).

Human-Oriented

A human-oriented identifier incorporates semantic that support readability and processing by humans. OSCAL implements human-oriented identifiers as token data types, which are non-colonized names. For example, control identifiers in a catalog may use a nomenclature that is familiar to the intended audience, allowing them to quickly determine what security control is being referred to, simply by its identifier value.

The OSCAL XML Reference Index and OSCAL JSON Reference Index provide a comprehensive listing of the human-oriented IDs in the core OSCAL models. References to these IDs are typically named according to the referenced object type (e.g., control) followed by “-id”, as seen here in the XML Reference Index (and likewise JSON Reference Index in the JSON reference index).

Uniqueness

OSCAL identifier uniqueness is categorized as locally-unique or globally-unique. As implied by the category name, locally-unique identifiers must be unique within the current document, whereas globally-unique identifiers are guaranteed to be unique across all other identifiers. OSCAL’s machine-oriented UUID identifiers are always globally-unique. Human-oriented identifiers must be defined and managed organizationally and are more susceptible to identifier duplication or collisions. Thus, human-oriented identifiers are less likely or cannot be guaranteed to be globally-unique.

Scope

Identifiers that are only intended for use within the same OSCAL instance are categorized as instance scope. However, since OSCAL supports composition relationships, there are many cases where identifiers in a source OSCAL instance need to be referenced from other OSCAL instances. These are considered cross-instance scoped identifier references. The figure below illustrates how the core OSCAL models relationships are established through import and link mechanisms, enabling cross-instance references.

A diagram depicting the relationships between OSCAL models. The solid black arrows depict relationships implemented via the import mechanism (e.g., import, import-profile, import-component-definition, import-ssp, and import-ap), whereas the dashed red line arrows illustrate relationships established through links.

The following import types are supported:

When implementing cross-instance references, identifier must be referenced in the context of the containing resource. The appropriate import attribute should be used (similar to a namespacing) to deconflict identifiers with the same values in the associated OSCAL instances. This is particularly important for human-oriented identifiers that may not be globally unique but still require cross-instance scoping. For example, this technique allows for the same control IDs to be used and referenced in a profile and its imported catalog(s) without conflict.

The next section describes the identifier scoping per defining model.

Catalog Identifiers

Identifiers defined in a catalog may be referenced locally or from an importing profile (see the diagram in the Scope section). Additionally, identifiers defined in a catalog may be referenced in other upstream OSCAL instances in a hierarchical set of associated OSCAL documents (e.g., SSPs, assessment plans, assessment results, and POA&Ms). The table below provides a listing of the core OSCAL catalog model identifiers.

Defining ModelIdentifier TypeIdentifiers
CatalogMachine-OrientedXML Index | JSON Index
CatalogHuman-OrientedXML Index | JSON Index

Profile Identifiers

Identifiers defined in a profile may be referenced locally or from an importing profile or SSP (see the diagram in the Scope section). Component definitions can reference these identifiers through its control-implementation - source reference to the profile. Other upstream OSCAL models, including assessment plans, assessment results, and POA&Ms can also reference these profile identifiers via the hierarchical set of associated OSCAL documents. The table below provides a listing of the core OSCAL profile model identifiers.

Defining ModelIdentifier TypeIdentifiers
ProfileMachine-OrientedXML Index | JSON Index
ProfileHuman-OrientedXML Index | JSON Index

Component Definition Identifiers

Identifiers defined in a component definition may be referenced locally or from an importing component definition instance (see the diagram in the Scope section). SSPs may also reference identifiers from a component definitions through its implementation of links for a given component.Other upstream OSCAL models, including assessment plans, assessment results, and POA&Ms can also reference these component definition indirectly (e.g., via reference to an SSP component that has a a link to a component definition). The table below provides a listing of the core OSCAL component definition model identifiers.

Defining ModelIdentifier TypeIdentifiers
Component DefinitionMachine-OrientedXML Index | JSON Index
Component DefinitionHuman-OrientedXML Index | JSON Index

SSP Identifiers

Identifiers defined in an SSP may be referenced locally or from an importing AP or POA&M (see the diagram in the Scope section). SSP identifiers can also be referenced from the AR through its hierarchical relationship with AP. The table below provides a listing of the core OSCAL SSP model identifiers.

Defining ModelIdentifier TypeIdentifiers
SSPMachine-OrientedXML Index | JSON Index
SSPHuman-OrientedXML Index | JSON Index

AP Identifiers

Identifiers defined in an AP may be referenced locally or from an importing AR (see the diagram in the Scope section). The table below provides a listing of the core OSCAL AP model identifiers.

Defining ModelIdentifier TypeIdentifiers
APMachine-OrientedXML Index | JSON Index
APHuman-OrientedXML Index | JSON Index

AR Identifiers

Identifiers defined in an AR may be referenced locally (see the diagram in the Scope section). However, observations, risks, and findings may also be referenced implicitly in the POA&M. The table below provides a listing of the core OSCAL AR model identifiers.

Defining ModelIdentifier TypeIdentifiers
ARMachine-OrientedXML Index | JSON Index
ARHuman-OrientedXML Index | JSON Index

POA&M Identifiers

Identifiers defined in a POA&M are only referenced locally (see the diagram in the Scope section). The table below provides a listing of the core OSCAL POA&M model identifiers.

Defining ModelIdentifier TypeIdentifiers
POA&MMachine-OrientedXML Index | JSON Index
POA&MHuman-OrientedXML Index | JSON Index

Consistency

Identifier (value) must be managed across revisions of the same document. In general, OSCAL identifiers have per-subject consistency. They should only be changed if the underlying identified subject has changed in a significant way that no longer represents the same identified subject.

This page was last updated on June 24, 2022.