OSCAL Control Mapping Model

A mapping collection affirmatively declares the relationships that exist between sets of controls and/or control statements in a source and target. It is expected that inferences can be made based on what is mapped; however, no inferences should be made based on what is not mapped, since it is impossible to quantify how complete or granular a given mapping is.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

If with-child-controls is yes on the call to a control, no sibling callelements need to be used to call any controls appearing within it. Since generally, this is how control enhancements are represented (as controls within controls), this provides a way to include controls with all their dependent controls (enhancements) without having to call them individually.

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.

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.

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.

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.

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

This element provides an alternative to calling controls individually from a catalog.

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.

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

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.

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.

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.

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.

This field is scoped - that is, it can be used at the document-level, the mapping level, or the individual map item level. It only applies to targets and sources within it's scope.

Coverage is calculated by taking the full set of all targets in-scope and the full set of all sources in-scope, then applying the "generation-method" to the two sets. By default the method is an arbitrary estimation of coverage.

In a general sense "coverage" is defined as the percent of the set of targets that have mapped to by the set of sources, where each map is an "equivalent-to" or "equal-to" valued "relationship". Where relationship is "subset-of" or otherwise, it counts as an appropriate fraction of a full map.

Since coverage is derived from mapping relationships, it is defined in the context of the mapping's "matching-rationale" - that is, the method used to determine relationships.

The value of this field applies to the entire document if found in the top-level mapping provenance, otherwise it applies to the specific mapping in which it is found.

If this field appears in both locations, the lower-scoped value overrides while within it's scope.

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

Since the reference target of an organizational affiliation must be another party (whether further qualified as person or organization) as indicated 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.

For example, consider the CSF 1.1's PR.AC-1, "Identities and credentials are issued, managed, verified, revoked, and audited for authorized devices, users and processes", and the Privacy Framework's PR.AC-P1, "Identities and credentials are issued, managed, verified, and devices."

These two requirements have identical wording except for "users” versus “individuals” and the order of the last few words. With a `matching-rationale` of syntactic, the relationship type would beintersects with because the two overlap, but each includes content that the other does not. However, with a rationale of semantic, the relationship type would be equal if “users” and “individuals” have the same meaning in their respective sources, subset if “users” was a subset of “individuals,” and so on.

When establishing relationships, mapping SHOULD be done at the control statement level where possible. This approach allows for a more accurate relationship.

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.