HDF OSCAL Extension Vocabulary
When hdf-libs writes OSCAL (an Assessment Results / SAR or a Plan of Action and Milestones), it stamps every property it invents with a namespace, as NIST's OSCAL extension guidance directs. This page defines every such property so a consumer who meets one can look up what it means.
The HDF extension namespace is https://mitre.github.io/hdf-libs/ns/oscal. It is an identifier and will not change, even if the site that publishes this page moves.
This page is generated from the vocabulary table that the exporters and importers themselves read, so it cannot describe a property they do not emit, or omit one they do.
HDF properties
Every property below carries the namespace https://mitre.github.io/hdf-libs/ns/oscal.
| Name | OSCAL object(s) | Meaning | Value format | HDF field |
|---|---|---|---|---|
hdf-requirement-id | assessment-results.results[].findings[]; plan-of-action-and-milestones.risks[] | The HDF requirement id the finding assesses, or the requirement id of the override the POA&M risk represents, exactly as the source recorded it; omitted when the id is empty. The finding target-id carries an OSCAL token encoding of it, which is not injective, and the POA&M item and risk titles are display text. | String (§1.7) | baselines[].requirements[].id, overrides[].requirementId |
requirement-title | assessment-results.results[].findings[] | The exact HDF requirement title the finding reports. Requirement_Core.title is prose that may carry line breaks (§2); the finding title is display text OSCAL types single-line, so the exact title is preserved here while the display title is normalized (§4.3). | String (§1.7) | baselines[].requirements[].title |
baseline-version | assessment-results.results[] | The version of the HDF baseline the result reports. | String (§1.7) | baselines[].version |
baseline-name | assessment-results.results[] | The exact HDF baseline name the result reports, so an HDF-produced SAR round-trips the name that hdf-diff and baseline references key on. The result title is display text and is not injective, so two baselines sharing a title would otherwise collide (§4.3, §4.5). | String (§1.7) | baselines[].name |
baseline-title | assessment-results.results[] | The exact HDF baseline title the result reports, distinct from the baseline name (baseline-name). The result title is display text OSCAL types single-line, so a title carrying a line terminator is preserved here while the display title is normalized (§4.3). | String (§1.7) | baselines[].title |
nist | assessment-results.results[].findings[] | A NIST SP 800-53 control the requirement maps to, one prop per mapping, in source order. | String (§1.7), NIST control notation as the source spelled it | baselines[].requirements[].tags.nist[] |
cci | assessment-results.results[].findings[] | A DISA Control Correlation Identifier the requirement maps to, one prop per mapping, in source order. | String (§1.7) | baselines[].requirements[].tags.cci[] |
control-type | assessment-results.results[].findings[] | The requirement's control type. | One of policy, procedure, technical, management, operational | baselines[].requirements[].controlType |
verification-method | assessment-results.results[].findings[] | How the requirement is verified. | One of automated, manual-by-design, manual-pending-automation, hybrid | baselines[].requirements[].verificationMethod |
applicability | assessment-results.results[].findings[] | Whether the requirement is required, optional or advisory. | One of required, optional, advisory | baselines[].requirements[].applicability |
cwe | assessment-results.results[].findings[] | A CWE identifier associated with the requirement, one prop per identifier, in source order. | String (§1.7) | baselines[].requirements[].cwe[] |
epss-score | assessment-results.results[].findings[] | The EPSS exploitation probability score. | Decimal number from 0 to 1 | baselines[].requirements[].epss.score |
epss-percentile | assessment-results.results[].findings[] | The EPSS percentile of the score. | Decimal number from 0 to 1 | baselines[].requirements[].epss.percentile |
kev | assessment-results.results[].findings[] | The vulnerability is in the CISA Known Exploited Vulnerabilities catalog; emitted only when it is. | The literal true | baselines[].requirements[].kev.inKev |
kev-due-date | assessment-results.results[].findings[] | The remediation due date the KEV catalog sets for the vulnerability. | String (§1.7), a date as the source recorded it | baselines[].requirements[].kev.dueDate |
cvss-base-score | assessment-results.results[].findings[] | A CVSS base score, one prop per CVSS record that carries one, in source order. | Decimal number from 0 to 10 | baselines[].requirements[].cvss[].baseScore |
cvss-base-vector | assessment-results.results[].findings[] | A CVSS base vector, one prop per CVSS record that carries one, in source order. | String (§1.7), a CVSS vector string | baselines[].requirements[].cvss[].baseVector |
reference | assessment-results.results[].findings[] | A requirement reference that is plain text rather than a URL or URI (those become finding links). | String (§1.7) | baselines[].requirements[].refs[].ref |
check | assessment-results.results[].findings[] | Pre-ADR only: a one-line preview of the requirement's check text, with the full text in remarks. No longer emitted; the check text is carried in observation relevant-evidence marked with description-label. | String (§1.7) | baselines[].requirements[].descriptions[label=check].data |
fix | assessment-results.results[].findings[] | Pre-ADR only: a one-line preview of the requirement's fix text when no risk was emitted, with the full text in remarks. No longer emitted; the fix text is carried in a risk remediation or observation relevant-evidence marked with description-label. | String (§1.7) | baselines[].requirements[].descriptions[label=fix].data |
rationale | assessment-results.results[].findings[] | Pre-ADR only: a one-line preview of the requirement's rationale text, with the full text in remarks. No longer emitted; the rationale is carried in the finding target description. | String (§1.7) | baselines[].requirements[].descriptions[label=rationale].data |
description-label | assessment-results.results[].observations[].relevant-evidence[]; assessment-results.results[].risks[].remediations[] | Marks the object as carrying the text of the HDF description with this label; evidence entries hold the full text in remarks, remediations in description. | One of check, fix | baselines[].requirements[].descriptions[].label |
empty-field | Any object that carries HDF props | An optional HDF string field that is present but empty; the importer returns it present and empty (§1.7.3). | The HDF JSON property name, dot-separated relative to the OSCAL object that carries the marker (e.g. systemRef, checksum.value); for props that share a group, the field within that group (e.g. key, fixedInVersion) (§1.7.5) | (none) |
absent-field | Any object that carries HDF props | OSCAL requires a value the HDF field does not have, so the object holds display fallback text; the importer leaves the field absent and never reads the fallback as HDF data (§1.7.4). | The HDF JSON property name, dot-separated relative to the OSCAL object that carries the marker (e.g. systemRef, checksum.value); for props that share a group, the field within that group (e.g. key, fixedInVersion) (§1.7.5) | (none) |
component-name | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | The exact HDF component name the assessment subject reconstitutes. The subject title is display text OSCAL types single-line, so a name carrying a line terminator is preserved here while the display title is normalized (§4.3). | String (§1.7) | components[].name |
component-description | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | The description of the component the assessment subject reconstitutes. | String (§1.7) | components[].description |
component-hostname | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A host component's short OS-reported hostname. | String (§1.7) | components[].hostname |
component-fqdn | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A host component's fully qualified domain name. | String (§1.7) | components[].fqdn |
component-domain | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A host component's directory domain. | String (§1.7) | components[].domain |
component-ip-address | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A host component's IP address. | String (§1.7) | components[].ipAddress |
component-mac-address | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A host component's MAC address. | String (§1.7) | components[].macAddress |
component-os-name | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A host component's operating system name. | String (§1.7) | components[].osName |
component-os-version | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A host component's operating system version. | String (§1.7) | components[].osVersion |
component-image-id | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A container image component's image id. | String (§1.7) | components[].imageId |
component-registry | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A container image component's registry. | String (§1.7) | components[].registry |
component-repository | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A container image component's repository. | String (§1.7) | components[].repository |
component-tag | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A container image component's tag. | String (§1.7) | components[].tag |
component-container-id | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A container instance component's running container id. | String (§1.7) | components[].containerId |
component-image | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A container instance component's source image. | String (§1.7) | components[].image |
component-runtime | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A container instance component's runtime. | String (§1.7) | components[].runtime |
component-platform-type | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A container platform component's platform type. | String (§1.7) | components[].platformType |
component-cluster-name | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A container platform component's cluster name. | String (§1.7) | components[].clusterName |
component-namespace | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A container platform component's namespace. | String (§1.7) | components[].namespace |
component-version | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A component's version (container platform, application, artifact, database, aiModel or dataset). | String (§1.7) | components[].version |
component-provider | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A cloud account or cloud resource component's cloud provider. | An HDF cloud provider value (aws, azure, gcp, oci, other) | components[].provider |
component-account-id | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A cloud account component's account identifier. | String (§1.7) | components[].accountId |
component-region | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A cloud account or cloud resource component's region. | String (§1.7) | components[].region |
component-resource-type | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A cloud resource component's resource type. | String (§1.7) | components[].resourceType |
component-resource-id | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A cloud resource component's provider-specific resource id. | String (§1.7) | components[].resourceId |
component-arn | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A cloud resource component's Amazon Resource Name. | String (§1.7) | components[].arn |
component-url | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A repository or application component's URL. | String (§1.7), a URL | components[].url |
component-branch | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A repository component's scanned branch. | String (§1.7) | components[].branch |
component-commit | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A repository component's scanned commit SHA. | String (§1.7) | components[].commit |
component-environment | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | An application component's environment. | String (§1.7) | components[].environment |
component-package-manager | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | An artifact component's package manager. | String (§1.7) | components[].packageManager |
component-package-name | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | An artifact component's package name. | String (§1.7) | components[].packageName |
component-cidr | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A network component's CIDR block. | String (§1.7) | components[].cidr |
component-gateway | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A network component's gateway address. | String (§1.7) | components[].gateway |
component-engine | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A database component's engine. | String (§1.7) | components[].engine |
component-host | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A database component's host. | String (§1.7) | components[].host |
component-port | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A database component's port. | Decimal number, a TCP port | components[].port |
component-model-id | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | An aiModel component's provider/registry model id. | String (§1.7) | components[].modelId |
component-dataset-id | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | A dataset component's provider/registry dataset id. | String (§1.7) | components[].datasetId |
component-label-key | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | The key of a component label, grouped component-label-<n>, n the label's 1-based position in sorted key order. | String (§1.7) | components[].labels (key) |
component-label-value | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | The value of the component label its group names. | String (§1.7) | components[].labels (value) |
component-external-id-key | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | The scheme of a component external id, grouped component-external-id-<n>, n its 1-based position in sorted key order. | String (§1.7) | components[].externalIds (key) |
component-external-id-value | assessment-results.results[].observations[].subjects[]; assessment-results.results[].local-definitions.components[] | The value of the component external id its group names. | String (§1.7) | components[].externalIds (value) |
amendment-id | plan-of-action-and-milestones.metadata | The identifier of the HDF amendments document. | String (§1.7), a UUID | amendmentId |
override-type | plan-of-action-and-milestones.risks[] | The type of the HDF override the risk represents. A risk carrying it in the HDF namespace is HDF-produced (ADR-0014 §4.3), so the importer reads every §4.6 field from its HDF props; a risk carrying it without ns is a pre-ADR export, which imports through the pre-ADR mapping. | An HDF override type, such as waiver, poam or falsePositive | overrides[].type |
impact-override | plan-of-action-and-milestones.risks[] | The impact the override assigns to the requirement. | Decimal number from 0 to 1 | overrides[].impact.value |
justification | plan-of-action-and-milestones.risks[] | The controlled-vocabulary justification for the override. | An HDF override justification value | overrides[].justification |
baseline-ref | plan-of-action-and-milestones.risks[] | The baseline the override is scoped to. | String (§1.7) | overrides[].baselineRef |
component-ref | plan-of-action-and-milestones.risks[] | The component the override is scoped to. | String (§1.7), a UUID | overrides[].componentRef |
milestone-status | plan-of-action-and-milestones.risks[].remediations[].tasks[] | The status of the milestone the remediation task represents. Documents exported before ADR-0014 carry it on the remediation, and import through the pre-ADR mapping (§4.3), which does not read it. | An HDF milestone status | overrides[].milestones[].status |
completed-at | plan-of-action-and-milestones.risks[].remediations[].tasks[] | When the milestone was completed. | RFC 3339 date-time in UTC | overrides[].milestones[].completedAt |
completed-by | plan-of-action-and-milestones.risks[].remediations[].tasks[] | Pre-ADR only: the identifier of whoever completed the milestone. No longer emitted; the task's responsible-roles entry with role-id completed-by names the party. | String (§1.7) | overrides[].milestones[].completedBy.identifier |
mime-type | plan-of-action-and-milestones.observations[] | The media type of the evidence the observation carries. | String (§1.7), a media type | overrides[].evidence[].mimeType |
captured-by | plan-of-action-and-milestones.observations[] | Pre-ADR only: the identifier of whoever captured the evidence. No longer emitted; the observation's origins actor names the party. | String (§1.7) | overrides[].evidence[].capturedBy.identifier |
source-name | plan-of-action-and-milestones.back-matter.resources[] | The name of the source of the external reference the resource carries. | String (§1.7) | overrides[].externalReferences[].sourceName |
external-id | plan-of-action-and-milestones.back-matter.resources[] | The identifier the source assigns to the external reference the resource carries. | String (§1.7) | overrides[].externalReferences[].externalId |
override-status | plan-of-action-and-milestones.risks[] | The status the override sets, emitted only when the override sets one; the risk status is closed for passed and notApplicable and open otherwise. | An HDF result status: passed, failed, notApplicable, notReviewed or error | overrides[].status |
inherited-from | plan-of-action-and-milestones.risks[] | The componentId of the local component that provides the control the override inherits. | String (§1.7), a UUID | overrides[].inheritedFrom |
affected-package-name | plan-of-action-and-milestones.risks[] | The name of a package the override is scoped to; every prop of one package shares the group package-<n>, n its 1-based position in source order. | String (§1.7) | overrides[].affectedPackages[].name |
affected-package-version | plan-of-action-and-milestones.risks[] | The version of a package the override is scoped to, grouped as affected-package-name. | String (§1.7) | overrides[].affectedPackages[].version |
affected-package-ecosystem | plan-of-action-and-milestones.risks[] | The ecosystem of a package the override is scoped to, grouped as affected-package-name. | An HDF package ecosystem, such as npm, rpm or generic | overrides[].affectedPackages[].ecosystem |
affected-package-cpe | plan-of-action-and-milestones.risks[] | The CPE 2.3 name of a package the override is scoped to, grouped as affected-package-name. | String (§1.7), a CPE 2.3 name | overrides[].affectedPackages[].cpe |
affected-package-purl | plan-of-action-and-milestones.risks[] | The package URL of a package the override is scoped to, grouped as affected-package-name. | String (§1.7), a package URL | overrides[].affectedPackages[].purl |
affected-package-fixed-in-version | plan-of-action-and-milestones.risks[] | The first version of a package the override is scoped to that contains the fix, grouped as affected-package-name. | String (§1.7) | overrides[].affectedPackages[].fixedInVersion |
evidence-encoding | plan-of-action-and-milestones.observations[] | The encoding the evidence data declares; data whose encoding is exactly base64 is carried in the linked resource as-is. | String (§1.7) | overrides[].evidence[].encoding |
evidence-size | plan-of-action-and-milestones.observations[] | The size of the evidence data in bytes. | Decimal number | overrides[].evidence[].size |
reference-rel | plan-of-action-and-milestones.back-matter.resources[] | The relationship of the external reference the resource carries to the override. | String (§1.7) | overrides[].externalReferences[].rel |
reference-media-type | plan-of-action-and-milestones.back-matter.resources[] | The media type of the artifact the external reference points at. | String (§1.7), a media type | overrides[].externalReferences[].mediaType |
checksum-algorithm | plan-of-action-and-milestones.back-matter.resources[] | The hash algorithm of the checksum of the artifact the external reference points at. | One of sha256, sha384, sha512, blake3 | overrides[].externalReferences[].checksum.algorithm |
checksum-value | plan-of-action-and-milestones.back-matter.resources[] | The checksum of the artifact the external reference points at. | String (§1.7), a hex digest | overrides[].externalReferences[].checksum.value |
added-by | plan-of-action-and-milestones.back-matter.resources[] | Who attached the external reference: the uuid of the metadata party carrying the identity. | A party UUID | overrides[].externalReferences[].addedBy |
added-at | plan-of-action-and-milestones.back-matter.resources[] | When the external reference was attached. | RFC 3339 date-time in UTC | overrides[].externalReferences[].addedAt |
reference-kind | plan-of-action-and-milestones.back-matter.resources[] | The kind of payload the external reference classifies, such as threat-intel or advisory. | String (§1.7) | overrides[].externalReferences[].kind |
identity-identifier | plan-of-action-and-milestones.metadata.parties[] | The identifier of the HDF identity the party carries; omitted when the identifier is empty. The party name is display text. | String (§1.7) | Identity.identifier |
identity-type | plan-of-action-and-milestones.metadata.parties[] | The type of the HDF identity the party carries; the party type is display text. The party remarks hold the identity description. | One of email, username, system, agent, simple, other | Identity.type |
amendments-name | plan-of-action-and-milestones.metadata | The name of the HDF amendments document; omitted when the name is empty. The metadata title is display text. | String (§1.7) | name |
label-key | plan-of-action-and-milestones.metadata | The key of an amendments label, with class amendment-label and group label-<n>, n the label's 1-based position in sorted key order. | String (§1.7) | labels (key) |
label-value | plan-of-action-and-milestones.metadata | The value of the amendments label its group names, with class amendment-label. | String (§1.7) | labels (value) |
Third-party properties
These properties are defined by other organizations. hdf-libs emits or reads them under their owner's namespace, not the HDF namespace, and reproduces them on re-export exactly as received.
NIST — http://csrc.nist.gov/ns/oscal
| Name | OSCAL object(s) | Meaning | Value format | HDF field |
|---|---|---|---|---|
label | catalog.controls[]; catalog.groups[].controls[] | NIST vocabulary: a human-readable label for the control, which may be rendered in place of its identifier. | String | requirements[].tags.label |
sort-id | catalog.controls[]; catalog.groups[].controls[] | NIST vocabulary: an alternative identifier that sorts easily among the other controls in the document. | String | requirements[].tags.sort-id |
version | assessment-plan.assessment-assets.components[] | NIST vocabulary: the version of the component. The importer reads it from the first assessment-asset component as the runner version. | String | assessments[].runner.version |
type | assessment-results.back-matter.resources[] | NIST vocabulary: the kind of resource. HDF emits the value evidence on the resource holding a requirement's source code. | A NIST resource type; HDF emits evidence | (none) |
FedRAMP — https://fedramp.gov/ns/oscal
| Name | OSCAL object(s) | Meaning | Value format | HDF field |
|---|---|---|---|---|
impacted-control-id | plan-of-action-and-milestones.risks[] | FedRAMP vocabulary: a control impacted by the POA&M item. The POA&M exporter emits it and the importer reads it as the override requirement id. | OSCAL control id token | overrides[].requirementId |
POAM-ID | plan-of-action-and-milestones.poam-items[] | FedRAMP vocabulary: the CSP-assigned POA&M tracking identifier. The importer reads it as the override requirement id when no related risk carries impacted-control-id. | String, a CSP tracking number | overrides[].requirementId |
CORE | catalog.controls[]; catalog.groups[].controls[]; profile.modify.alters[].adds[] | FedRAMP vocabulary: the control must be included in every FedRAMP assessment. The importer maps the value true to applicability required. | The literal true | requirements[].applicability |
assessment-type | assessment-plan.metadata | FedRAMP vocabulary: the type of assessment. The importer maps automated and manual to the plan type. | String | type |