@mitre/hdf-schema 3.4.0 → 3.4.2

package/dist/ts/hdf.ts

@@ -66,9 +66,6 @@ export interface HDFResults {
 
 /**
  * Information on a baseline that was evaluated, including any findings.
- *
- * Shared metadata fields for baselines. Used in both standalone baseline documents and
- * evaluated baseline results.
  */
 export interface EvaluatedBaseline {
     /**
@@ -172,8 +169,7 @@ export interface EvaluatedBaseline {
 }
 
 /**
- * A dependency for a baseline. Can include relative paths or URLs for where to find the
- * dependency.
+ * A dependency for a baseline. Can include relative paths or URLs for where to find the dependency.
  */
 export interface Dependency {
     /**
@@ -237,9 +233,9 @@ export interface RequirementGroup {
 }
 
 /**
- * A typed input parameter that bridges governance requirements and scanner automation.
- * Inputs carry expected configuration values with type information, comparison operators,
- * and validation constraints, enabling traceability from policy through to scan results.
+ * A typed input parameter that bridges governance requirements and scanner automation. Inputs carry
+ * expected configuration values with type information, comparison operators, and validation
+ * constraints, enabling traceability from policy through to scan results.
  */
 export interface Input {
     /**
@@ -280,8 +276,6 @@ export interface Input {
 }
 
 /**
- * Validation constraints for the input value.
- *
  * Validation constraints for an input value.
  */
 export interface InputConstraints {
@@ -305,8 +299,6 @@ export interface InputConstraints {
 }
 
 /**
- * The comparison operator used when evaluating this input against observed values.
- *
  * Comparison operator for evaluating the input value against observed values. Numeric:
  * eq/ne/lt/le/gt/ge. String: eq/ne/contains/matches. Collection: in/notIn.
  */
@@ -324,8 +316,6 @@ export enum ComparisonOperator {
 }
 
 /**
- * The data type of this input.
- *
  * The data type of the input value. Aligns with InSpec input types.
  */
 export enum InputType {
@@ -338,27 +328,8 @@ export enum InputType {
 }
 
 /**
- * Cryptographic integrity information for verifying this baseline has not been tampered
- * with.
- *
- * Cryptographic integrity information for verifying the HDF file has not been tampered
- * with. If algorithm is provided, checksum must also be provided, and vice versa.
- *
- * Cryptographic integrity information for verifying this file.
- *
- * Cryptographic integrity information for verifying this comparison document.
- *
- * Cryptographic integrity information for verifying this system document has not been
- * tampered with.
- *
- * Cryptographic integrity information for verifying this plan document has not been
- * tampered with.
- *
- * Cryptographic integrity information for verifying this amendments document has not been
- * tampered with.
- *
- * Cryptographic integrity information for verifying this evidence package has not been
- * tampered with.
+ * Cryptographic integrity information for verifying the HDF file has not been tampered with. If
+ * algorithm is provided, checksum must also be provided, and vice versa.
  */
 export interface Integrity {
     /**
@@ -381,10 +352,8 @@ export interface Integrity {
 }
 
 /**
- * The hash algorithm used for the checksum.
- *
- * Supported cryptographic hash algorithms for checksums and integrity verification. blake3
- * covers container-image and other artifact digests that use it.
+ * Supported cryptographic hash algorithms for checksums and integrity verification. blake3 covers
+ * container-image and other artifact digests that use it.
  */
 export enum HashAlgorithm {
     Blake3 = "blake3",
@@ -394,32 +363,7 @@ export enum HashAlgorithm {
 }
 
 /**
- * SHA-256 checksum of the original baseline definition file (before execution). This is an
- * immutable reference to the baseline as defined, used to detect tampering with baseline
- * requirements or metadata.
- *
  * Cryptographic checksum for baseline integrity verification.
- *
- * SHA-256 checksum of the previous amendment in chronological order. Creates a
- * tamper-evident chain of amendments (similar to blockchain). Null for the first amendment
- * on a requirement.
- *
- * SHA-256 checksum of the raw results before any amendments (statusOverrides or POAMs).
- * Used to detect tampering with test results. Compare with currentChecksum to verify
- * amendment integrity.
- *
- * Optional cryptographic checksum for verifying the integrity of remediation resources
- * fetched from the URI. Recommended for security when referencing external automation
- * scripts.
- *
- * Cryptographic checksum of the source document for integrity verification.
- *
- * Checksum of the prior amendment in the chain. Creates a tamper-evident linked list. Null
- * for the first amendment.
- *
- * Cryptographic checksum for verifying the referenced document's integrity.
- *
- * Cryptographic checksum of the referenced artifact for integrity verification.
  */
 export interface Checksum {
     /**
@@ -435,9 +379,6 @@ export interface Checksum {
 
 /**
  * A requirement that has been evaluated, including any findings.
- *
- * Core requirement fields shared between baseline requirements and evaluated requirements.
- * Contains the fundamental requirement definition without assessment results.
  */
 export interface EvaluatedRequirement {
     /**
@@ -585,14 +526,13 @@ export interface EvaluatedRequirement {
 
 /**
  * Represents a package referenced by a vulnerability finding or by an amendment's scope. On
- * Evaluated_Requirement.affectedPackages it says 'this CVE affects these package versions'.
- * On Standalone_Override.affectedPackages it says 'this amendment is scoped to these
- * packages' (used by VEX, OSCAL POA&M, FedRAMP component-aware amendments). NOT a
- * system-level component identifier — see `components[]` on hdf-system for those. Validity
- * requires at least one of: (name + version + ecosystem), purl alone, or cpe alone. purl
- * and cpe are self-describing identifiers that encode name/version implicitly, so either
- * may stand on its own; the name+version+ecosystem combination is the explicit form for
- * sources without formal identifiers.
+ * Evaluated_Requirement.affectedPackages it says 'this CVE affects these package versions'. On
+ * Standalone_Override.affectedPackages it says 'this amendment is scoped to these packages' (used
+ * by VEX, OSCAL POA&M, FedRAMP component-aware amendments). NOT a system-level component identifier
+ * — see `components[]` on hdf-system for those. Validity requires at least one of: (name + version
+ * + ecosystem), purl alone, or cpe alone. purl and cpe are self-describing identifiers that encode
+ * name/version implicitly, so either may stand on its own; the name+version+ecosystem combination
+ * is the explicit form for sources without formal identifiers.
  */
 export interface AffectedPackage {
     /**
@@ -683,16 +623,12 @@ export enum ControlType {
 }
 
 /**
- * Structured CVSS scoring data backing this override. Captures the rubric (which
- * Environmental/Threat metrics the consumer modified, the recomputed score) used to justify
- * a riskAdjustment. For other override types this is optional context.
- *
- * A CVSS (Common Vulnerability Scoring System) score record for a vulnerability finding.
- * Captures the vendor-supplied Base metric group and optional consumer-supplied Threat,
- * Environmental, and Supplemental metric groups. Supports all four CVSS major versions
- * (2.0, 3.0, 3.1, 4.0). Vector strings are validated against a permissive umbrella grammar;
- * semantic validation (correct metrics per version, correct values per metric) is performed
- * by the hdf-utilities `validateCvssVector` helper rather than at the schema layer.
+ * A CVSS (Common Vulnerability Scoring System) score record for a vulnerability finding. Captures
+ * the vendor-supplied Base metric group and optional consumer-supplied Threat, Environmental, and
+ * Supplemental metric groups. Supports all four CVSS major versions (2.0, 3.0, 3.1, 4.0). Vector
+ * strings are validated against a permissive umbrella grammar; semantic validation (correct metrics
+ * per version, correct values per metric) is performed by the hdf-utilities `validateCvssVector`
+ * helper rather than at the schema layer.
  */
 export interface Cvss {
     /**
@@ -765,15 +701,9 @@ export interface Cvss {
 }
 
 /**
- * Qualitative severity band corresponding to baseScore. CVSS 2.0 does not natively use
- * 'none' or 'critical' bands; map accordingly when populating.
- *
  * Qualitative CVSS severity band. Aligns with FIRST/NVD bands: none=0.0, low=0.1-3.9,
- * medium=4.0-6.9, high=7.0-8.9, critical=9.0-10.0. Distinct from the broader Severity enum
- * used on Requirement_Core (which includes 'informational').
- *
- * Qualitative severity band corresponding to computedScore. Same band convention as
- * baseSeverity.
+ * medium=4.0-6.9, high=7.0-8.9, critical=9.0-10.0. Distinct from the broader Severity enum used on
+ * Requirement_Core (which includes 'informational').
  */
 export enum CVSSSeverity {
     Critical = "critical",
@@ -808,29 +738,19 @@ export interface Description {
 }
 
 /**
- * The type of the most recent non-expired override or POAM governing this requirement.
- * Indicates why the requirement is in its current state (e.g., waiver, falsePositive,
- * riskAdjustment) or what remediation is being tracked (poam). Absent when no overrides or
- * POAMs apply.
- *
- * The type of amendment, aligned with FedRAMP deviation request categories. 'waiver': risk
- * accepted by Authorizing Official. 'attestation': manually verified by assessor. 'poam':
- * remediation tracked (no status change). 'inherited': control provided by another
- * component or system. 'falsePositive': scanner incorrectly identified a finding — for
- * compliance scans (STIG, CIS), the check actually passes, so status is typically set to
- * 'passed'; for vulnerability scans (CVE, SCA), the flagged vulnerability does not apply to
- * this system, so status is typically set to 'notApplicable'. The disposition field on the
- * requirement distinguishes false positives from genuinely not-applicable findings.
- * 'riskAdjustment': impact score adjusted based on environmental context (FedRAMP Risk
- * Adjustment); does not change pass/fail status, only impact via the impact field.
- * 'operationalRequirement': deviation required by operational constraints (FedRAMP
- * Operational Requirement); the finding cannot be remediated because the system requires
- * the affected functionality. Remains an open risk. Migration note: 'exception' was removed
- * in v3.1.0 — use 'waiver' with status 'notApplicable' instead.
- *
- * The type of override applied to this requirement.
- *
- * The type of amendment.
+ * The type of amendment, aligned with FedRAMP deviation request categories. 'waiver': risk accepted
+ * by Authorizing Official. 'attestation': manually verified by assessor. 'poam': remediation
+ * tracked (no status change). 'inherited': control provided by another component or system.
+ * 'falsePositive': scanner incorrectly identified a finding — for compliance scans (STIG, CIS), the
+ * check actually passes, so status is typically set to 'passed'; for vulnerability scans (CVE,
+ * SCA), the flagged vulnerability does not apply to this system, so status is typically set to
+ * 'notApplicable'. The disposition field on the requirement distinguishes false positives from
+ * genuinely not-applicable findings. 'riskAdjustment': impact score adjusted based on environmental
+ * context (FedRAMP Risk Adjustment); does not change pass/fail status, only impact via the impact
+ * field. 'operationalRequirement': deviation required by operational constraints (FedRAMP
+ * Operational Requirement); the finding cannot be remediated because the system requires the
+ * affected functionality. Remains an open risk. Migration note: 'exception' was removed in v3.1.0 —
+ * use 'waiver' with status 'notApplicable' instead.
  */
 export enum OverrideType {
     Attestation = "attestation",
@@ -843,20 +763,9 @@ export enum OverrideType {
 }
 
 /**
- * The current effective compliance status of this requirement after applying the most
- * recent non-expired override with a status field, or computed from results (worst-wins) if
- * no status-bearing overrides exist.
- *
- * The status of an individual test result. 'notApplicable' indicates the requirement does
- * not apply to the target. 'notReviewed' indicates the requirement was not assessed (e.g.,
- * requires manual verification).
- *
- * The status of this test within the requirement. Example: 'failed'.
- *
- * The new status this override sets for the requirement. Optional when only impact is being
- * overridden.
- *
- * The new status this amendment sets. Optional when only impact is being overridden.
+ * The status of an individual test result. 'notApplicable' indicates the requirement does not apply
+ * to the target. 'notReviewed' indicates the requirement was not assessed (e.g., requires manual
+ * verification).
  */
 export enum ResultStatus {
     Error = "error",
@@ -867,13 +776,9 @@ export enum ResultStatus {
 }
 
 /**
- * FIRST.org EPSS (Exploit Prediction Scoring System) score for this CVE finding. Used
- * alongside CVSS for prioritization — captures the probability the vulnerability will be
- * exploited.
- *
- * FIRST.org Exploit Prediction Scoring System (EPSS) data for a single vulnerability. All
- * three fields are required when an Epss object is present; the date disambiguates which
- * day's score this is, since EPSS recomputes daily.
+ * FIRST.org Exploit Prediction Scoring System (EPSS) data for a single vulnerability. All three
+ * fields are required when an Epss object is present; the date disambiguates which day's score this
+ * is, since EPSS recomputes daily.
  */
 export interface Epss {
     /**
@@ -896,8 +801,8 @@ export interface Epss {
 }
 
 /**
- * Supporting evidence for a finding or override, such as screenshots, code samples, log
- * excerpts, or URLs.
+ * Supporting evidence for a finding or override, such as screenshots, code samples, log excerpts,
+ * or URLs.
  */
 export interface Evidence {
     /**
@@ -937,41 +842,8 @@ export interface Evidence {
 }
 
 /**
- * Identity of who or what captured this evidence.
- *
- * Represents an identity that performed an action, such as capturing evidence or applying
- * an override.
- *
- * Identity of who created this POA&M. For simple cases, use type 'simple' with just an
- * identifier.
- *
- * Identity of who completed this milestone.
- *
- * The identity that created this signature.
- *
- * Identity of who applied this override. For simple cases, use type 'simple' with just an
- * identifier.
- *
- * Identity of the person or system that approved this override.
- *
- * Team or individual responsible for this component. Enables per-component ownership when
- * different teams manage different parts of a system.
- *
- * The identity of the person or system responsible for executing the test. This could be a
- * human auditor manually completing a checklist, an automated CI/CD system, or a security
- * tool. Optional field to support both automated and manual HDF generation.
- *
- * Team or individual responsible for this system's authorization and compliance. Maps to
- * OSCAL responsible-party with role 'system-owner'.
- *
- * Default identity of who created this amendments document. Individual overrides may
- * specify their own appliedBy.
- *
- * Identity of the authorizing official who approved these amendments.
- *
- * Identity of who applied this amendment.
- *
- * Identity of who prepared this evidence package.
+ * Represents an identity that performed an action, such as capturing evidence or applying an
+ * override.
  */
 export interface Identity {
     /**
@@ -1055,9 +927,9 @@ export interface Kev {
 }
 
 /**
- * Plan of Action and Milestones for tracking remediation, mitigation, or risk acceptance.
- * POAMs do NOT change the effectiveStatus - the requirement remains in its current state
- * while the POA&M tracks remediation efforts.
+ * Plan of Action and Milestones for tracking remediation, mitigation, or risk acceptance. POAMs do
+ * NOT change the effectiveStatus - the requirement remains in its current state while the POA&M
+ * tracks remediation efforts.
  */
 export interface Poam {
     /**
@@ -1142,21 +1014,9 @@ export enum MilestoneStatus {
 }
 
 /**
- * Optional digital signature for enhanced trust and non-repudiation.
- *
- * A digital signature following W3C Data Integrity Proofs pattern. Supports hardware
- * security tokens (PKCS#11/PKCS#12), Yubikeys, GPG keys, passkeys, and other cryptographic
- * signing methods via JWK, PEM, or Base58 key formats.
- *
- * Optional digital signature for enhanced trust and non-repudiation. Supports hardware
- * security tokens (PKCS#11/PKCS#12), Yubikeys, GPG keys, passkeys, and other signing
- * methods.
- *
- * Digital signature for non-repudiation.
- *
- * Document-level digital signature covering all amendments.
- *
- * Digital signature covering the entire evidence package.
+ * A digital signature following W3C Data Integrity Proofs pattern. Supports hardware security
+ * tokens (PKCS#11/PKCS#12), Yubikeys, GPG keys, passkeys, and other cryptographic signing methods
+ * via JWK, PEM, or Base58 key formats.
  */
 export interface Signature {
     /**
@@ -1201,10 +1061,8 @@ export interface Signature {
 }
 
 /**
- * The verification method containing the public key for signature verification.
- *
- * Verification method containing the public key needed to verify a digital signature.
- * Supports multiple key formats including JWK (for RSA, EC), PEM, and Base58.
+ * Verification method containing the public key needed to verify a digital signature. Supports
+ * multiple key formats including JWK (for RSA, EC), PEM, and Base58.
  */
 export interface VerificationMethod {
     /**
@@ -1246,12 +1104,6 @@ export enum POAMType {
 
 /**
  * A reference to an external document.
- *
- * A reference using the 'ref' field.
- *
- * A URL pointing at the reference.
- *
- * A URI pointing at the reference.
  */
 export interface Reference {
     ref?: { [key: string]: any }[] | string;
@@ -1306,9 +1158,6 @@ export interface RequirementResult {
 }
 
 /**
- * Explicit severity rating. Typically derived from impact score but provided explicitly for
- * clarity.
- *
  * Severity rating for a requirement. Typically derived from the numeric impact score.
  */
 export enum Severity {
@@ -1320,8 +1169,6 @@ export enum Severity {
 }
 
 /**
- * The explicit location of the requirement within the source code.
- *
  * The explicit location of a requirement within source code.
  */
 export interface SourceLocation {
@@ -1337,9 +1184,9 @@ export interface SourceLocation {
 }
 
 /**
- * An intentional change to a requirement's compliance status and/or impact score. At least
- * one of status or impact must be set. Overrides change the effectiveStatus or impact of
- * the requirement. All overrides must have an expiration date to enforce periodic review.
+ * An intentional change to a requirement's compliance status and/or impact score. At least one of
+ * status or impact must be set. Overrides change the effectiveStatus or impact of the requirement.
+ * All overrides must have an expiration date to enforce periodic review.
  */
 export interface StatusOverride {
     /**
@@ -1408,11 +1255,8 @@ export interface StatusOverride {
 }
 
 /**
- * Override to the requirement's impact score. At least one of status or impact must be
- * set.
- *
- * An override to the requirement's impact score. The prior impact is the original result
- * value or the preceding override in the chain.
+ * An override to the requirement's impact score. The prior impact is the original result value or
+ * the preceding override in the chain.
  */
 export interface ImpactOverride {
     /**
@@ -1423,28 +1267,21 @@ export interface ImpactOverride {
 }
 
 /**
- * Structured controlled-vocabulary classification for why this override applies.
- * Complements (does not replace) the free-text 'reason' field. Most useful on falsePositive
- * and attestation overrides where the structured category enables filtering and lossless
- * round-trip with VEX / OSCAL / FedRAMP DR. See the Justification primitive for the
- * precedent vocabulary and rationale.
- *
- * Structured controlled-vocabulary reason for an override, complementing the free-text
- * 'reason' field. 'reason' carries the human-readable rationale an auditor reads;
- * 'justification' carries the machine-readable category enabling filtering, aggregation,
- * and lossless round-trip with structured ecosystems (VEX, OSCAL, FedRAMP DR). Both fields
- * may be present simultaneously and are NOT redundant: 'reason' explains the specific
- * circumstance; 'justification' classifies it. Authors SHOULD populate both when a
- * controlled-vocabulary value applies — the enum value alone is not self-explanatory to an
- * auditor. The vocabulary is drawn from the VEX ecosystem: the first five values are common
- * across OpenVEX, CSAF VEX, and CycloneDX VEX; the remaining six (requires_configuration /
- * requires_dependency / requires_environment / protected_by_compiler / protected_at_runtime
- * / protected_at_perimeter) are CycloneDX-specific and describe why the vulnerable code
- * path is unreachable in the deployed configuration. The enum is extended additively across
- * schema versions as other ecosystems' controlled vocabularies are integrated; documents
- * using values added in a newer schema version will fail validation against an older
- * schema. Consumers SHOULD validate against the schema version declared by the document
- * ($schema) rather than assume a fixed vocabulary.
+ * Structured controlled-vocabulary reason for an override, complementing the free-text 'reason'
+ * field. 'reason' carries the human-readable rationale an auditor reads; 'justification' carries
+ * the machine-readable category enabling filtering, aggregation, and lossless round-trip with
+ * structured ecosystems (VEX, OSCAL, FedRAMP DR). Both fields may be present simultaneously and are
+ * NOT redundant: 'reason' explains the specific circumstance; 'justification' classifies it.
+ * Authors SHOULD populate both when a controlled-vocabulary value applies — the enum value alone is
+ * not self-explanatory to an auditor. The vocabulary is drawn from the VEX ecosystem: the first
+ * five values are common across OpenVEX, CSAF VEX, and CycloneDX VEX; the remaining six
+ * (requires_configuration / requires_dependency / requires_environment / protected_by_compiler /
+ * protected_at_runtime / protected_at_perimeter) are CycloneDX-specific and describe why the
+ * vulnerable code path is unreachable in the deployed configuration. The enum is extended
+ * additively across schema versions as other ecosystems' controlled vocabularies are integrated;
+ * documents using values added in a newer schema version will fail validation against an older
+ * schema. Consumers SHOULD validate against the schema version declared by the document ($schema)
+ * rather than assume a fixed vocabulary.
  */
 export enum Justification {
     ComponentNotPresent = "component_not_present",
@@ -1461,19 +1298,12 @@ export enum Justification {
 }
 
 /**
- * How this requirement is intended to be verified. Disambiguates the two cases that null
- * 'code' overloads: 'manual-by-design' (the requirement is statement-form and not amenable
- * to automation, e.g. FedRAMP 20x KSIs); 'manual-pending-automation' (automation could
- * exist but does not yet, e.g. a STIG rule lacking a fix). 'automated' = a check exists and
- * runs without operator action; 'hybrid' = part automated, part manual. Optional: when
- * omitted, consumers should not infer a default.
- *
- * How a requirement is intended to be verified. Disambiguates the two cases that null
- * 'code' overloads: 'manual-by-design' (the requirement is statement-form and not amenable
- * to automation, e.g. FedRAMP 20x KSIs); 'manual-pending-automation' (automation could
- * exist but does not yet, e.g. a STIG rule lacking a fix). 'automated' = a check exists and
- * runs without operator action; 'hybrid' = part automated, part manual. Named '_Enum' to
- * disambiguate from the unrelated Verification_Method DID-context struct.
+ * How a requirement is intended to be verified. Disambiguates the two cases that null 'code'
+ * overloads: 'manual-by-design' (the requirement is statement-form and not amenable to automation,
+ * e.g. FedRAMP 20x KSIs); 'manual-pending-automation' (automation could exist but does not yet,
+ * e.g. a STIG rule lacking a fix). 'automated' = a check exists and runs without operator action;
+ * 'hybrid' = part automated, part manual. Named '_Enum' to disambiguate from the unrelated
+ * Verification_Method DID-context struct.
  */
 export enum VerificationMethodEnum {
     Automated = "automated",
@@ -1506,44 +1336,8 @@ export interface SupportedPlatform {
 }
 
 /**
- * A system component. Uses discriminated union pattern with 'type' field as discriminator.
- * Superset of Target with identity, external IDs, and SBOM support.
- *
- * A physical or virtual server, workstation, or network device.
- *
- * Base properties shared by all component types. Extends the Target concept with stable
- * identity, external references, generalized BOM attachment (boms[]), and unified artifact
- * integrity (integrity[]).
- *
- * A static container image (not running). Image integrity — formerly the 'digest' field —
- * is expressed via the shared Base_Component.integrity array.
- *
- * A running container instance.
- *
- * A container orchestration platform (Kubernetes, OpenShift, ECS, etc.).
- *
- * A cloud provider account (AWS account, Azure subscription, GCP project).
- *
- * A specific cloud resource (EC2 instance, S3 bucket, Azure VM, etc.).
- *
- * A code repository (for SAST tools).
- *
- * A running application or API (for DAST tools).
- *
- * A software artifact or dependency (for SCA tools). Package integrity — formerly the
- * 'checksum' field — is expressed via the shared Base_Component.integrity array.
- *
- * A network segment or network device.
- *
- * A database instance.
- *
- * A thin AI-model component: identity and correlation only (parallel to Host_Component's
- * fqdn/ip). All model detail — architecture, parameter count, serialization format, lineage
- * — lives in an attached ai-model BOM (boms[]), never on the component itself.
- *
- * A thin dataset component: identity and correlation only, symmetric with
- * AI_Model_Component. All dataset detail — record count, format, classification, lineage —
- * lives in an attached dataset BOM (boms[]), never on the component itself.
+ * A system component. Uses discriminated union pattern with 'type' field as discriminator. Superset
+ * of Target with identity, external IDs, and SBOM support.
  */
 export interface Component {
     /**
@@ -1846,12 +1640,10 @@ export interface BillOfMaterials {
 }
 
 /**
- * Normalized dataset extension. Permitted only when bomType is dataset.
- *
- * Normalized dataset fields (SPDX 3.0 Dataset profile / MLCommons Croissant aligned). All
- * optional; open for partial-fidelity passthrough of unmapped native fields. Symmetric with
- * AI_Model_Extension: carries the dataset's own lineage (baseDatasetRefs/derivation) just
- * as the model extension carries baseModelRef/adaptationType.
+ * Normalized dataset fields (SPDX 3.0 Dataset profile / MLCommons Croissant aligned). All optional;
+ * open for partial-fidelity passthrough of unmapped native fields. Symmetric with
+ * AI_Model_Extension: carries the dataset's own lineage (baseDatasetRefs/derivation) just as the
+ * model extension carries baseModelRef/adaptationType.
  */
 export interface DatasetBOMExtension {
     /**
@@ -1918,13 +1710,11 @@ export enum DatasetDerivationType {
 }
 
 /**
- * Normalized ai-model extension. Permitted only when bomType is ai-model.
- *
- * Normalized AI-model fields, aligned to the CISA/G7 'SBOM for AI' minimum elements. All
- * fields optional (standards-correct; only the EU AI Act makes a subset binding for
- * high-risk/GPAI). Left open (additionalProperties: true) so a converter can carry unmapped
- * native fields opaquely (partial-fidelity pattern). Subject name/version are inherited
- * from the host aiModel component, not repeated here.
+ * Normalized AI-model fields, aligned to the CISA/G7 'SBOM for AI' minimum elements. All fields
+ * optional (standards-correct; only the EU AI Act makes a subset binding for high-risk/GPAI). Left
+ * open (additionalProperties: true) so a converter can carry unmapped native fields opaquely
+ * (partial-fidelity pattern). Subject name/version are inherited from the host aiModel component,
+ * not repeated here.
  */
 export interface AIModelBOMExtension {
     /**
@@ -2064,9 +1854,8 @@ export interface PerformanceMetric {
 }
 
 /**
- * A single normalized software package entry within an sbom BOM. Minimal identity + version
- * for querying/diffing; the full native record remains available via passthrough
- * (document/ref).
+ * A single normalized software package entry within an sbom BOM. Minimal identity + version for
+ * querying/diffing; the full native record remains available via passthrough (document/ref).
  */
 export interface SBOMPackage {
     /**
@@ -2089,8 +1878,8 @@ export interface SBOMPackage {
 }
 
 /**
- * An override of a baseline input value for a specific component. Enables system-specific
- * tailoring of baseline parameters.
+ * An override of a baseline input value for a specific component. Enables system-specific tailoring
+ * of baseline parameters.
  */
 export interface InputOverride {
     /**
@@ -2146,19 +1935,7 @@ export enum TargetType {
 }
 
 /**
- * Information about the tool that generated this file.
- *
  * Information about the tool that generated this HDF file.
- *
- * The tool that generated this file.
- *
- * Information about the tool that generated this comparison.
- *
- * Information about the tool that generated this system document.
- *
- * Information about the tool that generated this plan.
- *
- * Information about the tool that generated this document.
  */
 export interface Generator {
     /**
@@ -2173,15 +1950,9 @@ export interface Generator {
 }
 
 /**
- * Optional reference to automated remediation resources (Ansible playbooks, Terraform
- * scripts, etc.) for fixing failing requirements found in this assessment.
- *
- * Reference to automated remediation resources for implementing security controls. Points
- * to external automation content like Ansible playbooks, Terraform scripts, or
- * vendor-provided remediation tools.
- *
- * Optional reference to automated remediation resources (Ansible playbooks, Terraform
- * scripts, etc.) for implementing the security controls defined in this baseline.
+ * Reference to automated remediation resources for implementing security controls. Points to
+ * external automation content like Ansible playbooks, Terraform scripts, or vendor-provided
+ * remediation tools.
  */
 export interface Remediation {
     /**
@@ -2200,12 +1971,8 @@ export interface Remediation {
 }
 
 /**
- * Information about the test execution environment where the security tool was run.
- * Distinct from targets (what is being tested).
- *
- * Information about the test execution environment. This is distinct from the target being
- * scanned - the runner is where the security tool executes, while targets are what is being
- * assessed.
+ * Information about the test execution environment. This is distinct from the target being scanned
+ * - the runner is where the security tool executes, while targets are what is being assessed.
  */
 export interface Runner {
     /**
@@ -2257,8 +2024,6 @@ export interface Runner {
 }
 
 /**
- * Statistics for the assessment run, including duration and result counts.
- *
  * Statistics for the assessment run(s) such as duration and result counts.
  */
 export interface Statistics {
@@ -2274,8 +2039,6 @@ export interface Statistics {
 }
 
 /**
- * Breakdowns of requirement statistics by result status.
- *
  * Statistics for requirement results, grouped by status.
  */
 export interface StatisticHash {
@@ -2303,17 +2066,7 @@ export interface StatisticHash {
 }
 
 /**
- * Statistics for requirements that encountered an error during assessment.
- *
  * Statistics for a given item, such as the total count.
- *
- * Statistics for requirements that failed.
- *
- * Statistics for requirements that are not applicable to the target.
- *
- * Statistics for requirements that were not reviewed (manual check required).
- *
- * Statistics for requirements that passed.
  */
 export interface StatisticBlock {
     /**
@@ -2324,12 +2077,8 @@ export interface StatisticBlock {
 }
 
 /**
- * The security tool that produced the assessment data in this file.
- *
- * The security tool that produced the assessment data represented in this HDF file. Aligns
- * with SARIF, OSCAL, and CycloneDX terminology.
- *
- * The security tool that produced the assessment data in this source.
+ * The security tool that produced the assessment data represented in this HDF file. Aligns with
+ * SARIF, OSCAL, and CycloneDX terminology.
  */
 export interface Tool {
     /**
@@ -2351,11 +2100,8 @@ export interface Tool {
 }
 
 /**
- * Information on the set of requirements that can be assessed, including baseline metadata
- * and requirement definitions.
- *
- * Shared metadata fields for baselines. Used in both standalone baseline documents and
- * evaluated baseline results.
+ * Information on the set of requirements that can be assessed, including baseline metadata and
+ * requirement definitions.
  */
 export interface HDFBaseline {
     /**
@@ -2438,9 +2184,6 @@ export interface HDFBaseline {
 
 /**
  * A requirement definition without assessment results.
- *
- * Core requirement fields shared between baseline requirements and evaluated requirements.
- * Contains the fundamental requirement definition without assessment results.
  */
 export interface BaselineRequirement {
     /**
@@ -2516,8 +2259,8 @@ export interface BaselineRequirement {
 }
 
 /**
- * Structured comparison between two or more HDF security assessment documents. Supports
- * temporal, baseline, fleet, and multi-source comparison modes.
+ * Structured comparison between two or more HDF security assessment documents. Supports temporal,
+ * baseline, fleet, and multi-source comparison modes.
  */
 export interface HDFComparison {
     /**
@@ -2617,8 +2360,6 @@ export interface Annotation {
 }
 
 /**
- * The category of this annotation.
- *
  * The category of an annotation attached to a comparison.
  */
 export enum AnnotationCategory {
@@ -2669,13 +2410,11 @@ export enum BaselineDiffState {
 }
 
 /**
- * The mode of comparison being performed.
- *
- * The mode of comparison. 'temporal' compares the same target over time. 'baseline'
- * compares against a golden reference. 'fleet' compares across multiple systems.
- * 'multiSource' compares outputs from different scanners. 'baselineEvolution' compares two
- * baseline documents to detect requirement changes between versions. 'systemDrift' compares
- * two system documents to detect component-level changes.
+ * The mode of comparison. 'temporal' compares the same target over time. 'baseline' compares
+ * against a golden reference. 'fleet' compares across multiple systems. 'multiSource' compares
+ * outputs from different scanners. 'baselineEvolution' compares two baseline documents to detect
+ * requirement changes between versions. 'systemDrift' compares two system documents to detect
+ * component-level changes.
  */
 export enum ComparisonMode {
     Baseline = "baseline",
@@ -2880,8 +2619,6 @@ export interface ScannerConflict {
 }
 
 /**
- * How the conflict was resolved.
- *
  * How a conflict between multiple scanner results was resolved.
  */
 export enum ConflictResolution {
@@ -2908,13 +2645,9 @@ export interface Value {
 }
 
 /**
- * The strategy that was used to match this requirement across sources.
- *
- * The strategy used to match requirements across sources. 'exactId' matches by identical
- * IDs. 'mappedId' uses an ID mapping table. 'cciMatch'/'nistMatch' match by framework
- * identifiers. 'fuzzyTitle'/'fuzzyContent' use text similarity.
- *
- * The primary strategy used to match requirements across sources.
+ * The strategy used to match requirements across sources. 'exactId' matches by identical IDs.
+ * 'mappedId' uses an ID mapping table. 'cciMatch'/'nistMatch' match by framework identifiers.
+ * 'fuzzyTitle'/'fuzzyContent' use text similarity.
  */
 export enum MatchStrategy {
     CciMatch = "cciMatch",
@@ -2926,12 +2659,10 @@ export enum MatchStrategy {
 }
 
 /**
- * The state of this requirement in the comparison.
- *
- * SARIF-compatible vocabulary extended for security. 'new' = present only in new source,
- * 'absent' = present only in old, 'unchanged' = same effective status, 'updated' = status
- * changed (generic), 'fixed' = was failing now passing, 'regressed' = was passing now
- * failing, 'moved' = reorganized same content, 'split'/'merged' = reserved for v1.1.
+ * SARIF-compatible vocabulary extended for security. 'new' = present only in new source, 'absent' =
+ * present only in old, 'unchanged' = same effective status, 'updated' = status changed (generic),
+ * 'fixed' = was failing now passing, 'regressed' = was passing now failing, 'moved' = reorganized
+ * same content, 'split'/'merged' = reserved for v1.1.
  */
 export enum RequirementState {
     Absent = "absent",
@@ -2950,8 +2681,6 @@ export enum FormatVersion {
 }
 
 /**
- * Configuration for how requirements were matched across sources.
- *
  * Configuration for how requirements are matched across sources.
  */
 export interface MatchingConfig {
@@ -3100,8 +2829,6 @@ export enum OriginalFormat {
 }
 
 /**
- * The role of this source in the comparison.
- *
  * The role of a source document in the comparison.
  */
 export enum SourceRole {
@@ -3188,8 +2915,6 @@ export interface ComparisonSummary {
 }
 
 /**
- * State counts broken down by severity level.
- *
  * Breakdown of state counts by severity level.
  */
 export interface SeverityBreakdown {
@@ -3213,15 +2938,7 @@ export interface SeverityBreakdown {
 }
 
 /**
- * State counts for critical severity requirements.
- *
  * Counts of requirements in each state.
- *
- * State counts for high severity requirements.
- *
- * State counts for low severity requirements.
- *
- * State counts for medium severity requirements.
  */
 export interface StateCounts {
     /**
@@ -3299,8 +3016,8 @@ export interface PerSourceSummary {
 }
 
 /**
- * Describes a system's authorization boundary, components, and interconnections. Maps to
- * OSCAL SSP system-characteristics and FedRAMP system inventory.
+ * Describes a system's authorization boundary, components, and interconnections. Maps to OSCAL SSP
+ * system-characteristics and FedRAMP system inventory.
  */
 export interface HDFSystem {
     /**
@@ -3393,8 +3110,6 @@ export interface HDFSystem {
 }
 
 /**
- * Current Authorization to Operate (ATO) status.
- *
  * Authorization to Operate (ATO) status for the system.
  */
 export enum AuthorizationStatus {
@@ -3407,8 +3122,6 @@ export enum AuthorizationStatus {
 }
 
 /**
- * FIPS 199 security categorization (impact level).
- *
  * FIPS 199 security categorization level (impact level).
  */
 export enum CategorizationLevel {
@@ -3418,10 +3131,10 @@ export enum CategorizationLevel {
 }
 
 /**
- * Declares a control's designation within a system — whether it is common (provided by
- * another component or system), system-specific (implemented locally), or hybrid (shared
- * responsibility). Maps to NIST SP 800-53 Appendix C control designations and OSCAL SSP
- * by-component provided/inherited semantics.
+ * Declares a control's designation within a system — whether it is common (provided by another
+ * component or system), system-specific (implemented locally), or hybrid (shared responsibility).
+ * Maps to NIST SP 800-53 Appendix C control designations and OSCAL SSP by-component
+ * provided/inherited semantics.
  */
 export interface ControlDesignation {
     /**
@@ -3470,9 +3183,9 @@ export enum Designation {
 }
 
 /**
- * A data flow between two endpoints. The 'from' endpoint is always a local component; the
- * 'to' endpoint can be local, cross-system, or external. Use 'direction' to indicate
- * whether data flows one-way or both ways.
+ * A data flow between two endpoints. The 'from' endpoint is always a local component; the 'to'
+ * endpoint can be local, cross-system, or external. Use 'direction' to indicate whether data flows
+ * one-way or both ways.
  */
 export interface DataFlow {
     /**
@@ -3521,8 +3234,8 @@ export enum Direction {
 }
 
 /**
- * Defines an assessment plan — what baselines to run against which targets, with resolved
- * inputs and scheduling. Maps to OSCAL Assessment Plan.
+ * Defines an assessment plan — what baselines to run against which targets, with resolved inputs
+ * and scheduling. Maps to OSCAL Assessment Plan.
  */
 export interface HDFPlan {
     /**
@@ -3576,8 +3289,8 @@ export interface HDFPlan {
 }
 
 /**
- * A single assessment within a plan — defines which baseline to run against which targets
- * with what configuration.
+ * A single assessment within a plan — defines which baseline to run against which targets with what
+ * configuration.
  */
 export interface Assessment {
     /**
@@ -3613,8 +3326,6 @@ export interface Assessment {
 }
 
 /**
- * Runner/scanner configuration for this assessment.
- *
  * Configuration for the assessment runner/scanner.
  */
 export interface RunnerConfig {
@@ -3630,8 +3341,6 @@ export interface RunnerConfig {
 }
 
 /**
- * Optional scheduling configuration for recurring assessments.
- *
  * Scheduling configuration for recurring assessments.
  */
 export interface Schedule {
@@ -3660,10 +3369,8 @@ export interface Schedule {
 }
 
 /**
- * The type of assessment plan.
- *
- * The type of assessment. 'automated' for scanner-driven, 'manual' for human-performed,
- * 'hybrid' for both.
+ * The type of assessment. 'automated' for scanner-driven, 'manual' for human-performed, 'hybrid'
+ * for both.
  */
 export enum PlanType {
     Automated = "automated",
@@ -3672,8 +3379,8 @@ export enum PlanType {
 }
 
 /**
- * Waivers, attestations, and POA&Ms that modify requirement compliance status or impact.
- * Amendments are standalone documents that can be applied to results via merge operations.
+ * Waivers, attestations, and POA&Ms that modify requirement compliance status or impact. Amendments
+ * are standalone documents that can be applied to results via merge operations.
  */
 export interface HDFAmendments {
     /**
@@ -3731,18 +3438,18 @@ export interface HDFAmendments {
 }
 
 /**
- * A standalone override to a requirement's compliance status or risk impact. Validation has
- * two branches gated on 'type': when type is 'operationalRequirement', neither 'status' nor
- * 'impact' may be set — the override records accepted risk without changing the finding
- * (documentation-only). For all other types, at least one of 'status' or 'impact' must be
- * set. This rule aligns with: (1) OSCAL Assessment Results — finding.target.status and
+ * A standalone override to a requirement's compliance status or risk impact. Validation has two
+ * branches gated on 'type': when type is 'operationalRequirement', neither 'status' nor 'impact'
+ * may be set — the override records accepted risk without changing the finding
+ * (documentation-only). For all other types, at least one of 'status' or 'impact' must be set. This
+ * rule aligns with: (1) OSCAL Assessment Results — finding.target.status and
  * finding.associated-risk[].facet[] are separate axes
- * (https://pages.nist.gov/OSCAL/learn/concepts/layer/assessment/assessment-results/); (2)
- * FedRAMP deviation request types — Risk Adjustment changes impact only, Operational
- * Requirement documents acceptance only, False Positive changes status
- * (https://www.ignyteplatform.com/blog/fedramp/fedramp-deviation-requests-submit/); (3)
- * NIST SP 800-37 RMF — risk response (accept/mitigate/transfer) is a separate step from
- * control assessment status (https://csrc.nist.gov/pubs/sp/800/37/r2/final).
+ * (https://pages.nist.gov/OSCAL/learn/concepts/layer/assessment/assessment-results/); (2) FedRAMP
+ * deviation request types — Risk Adjustment changes impact only, Operational Requirement documents
+ * acceptance only, False Positive changes status
+ * (https://www.ignyteplatform.com/blog/fedramp/fedramp-deviation-requests-submit/); (3) NIST SP
+ * 800-37 RMF — risk response (accept/mitigate/transfer) is a separate step from control assessment
+ * status (https://csrc.nist.gov/pubs/sp/800/37/r2/final).
  */
 export interface StandaloneOverride {
     /**
@@ -3840,9 +3547,8 @@ export interface StandaloneOverride {
 }
 
 /**
- * Bundles references to all HDF documents for audit, authorization, and compliance review.
- * Each content entry references a document by type, URI, and checksum for integrity
- * verification.
+ * Bundles references to all HDF documents for audit, authorization, and compliance review. Each
+ * content entry references a document by type, URI, and checksum for integrity verification.
  */
 export interface HDFEvidencePackage {
     /**
@@ -3917,10 +3623,8 @@ export interface HDFEvidencePackage {
 }
 
 /**
- * Summary of assessment completeness and compliance status.
- *
- * Informational summary of assessment completeness. Not authoritative — tools should
- * compute these from the referenced documents.
+ * Informational summary of assessment completeness. Not authoritative — tools should compute these
+ * from the referenced documents.
  */
 export interface CompletenessCheck {
     /**
@@ -3951,8 +3655,6 @@ export interface CompletenessCheck {
 }
 
 /**
- * SBOM coverage across system components.
- *
  * SBOM coverage statistics for the system.
  */
 export interface SBOMCoverage {
@@ -3996,12 +3698,10 @@ export interface ContentReference {
 }
 
 /**
- * The type of HDF document being referenced.
- *
  * The type of document referenced in the evidence package. 'bom' covers any
- * Bill-of-Materials/manifest document (SBOM, AI model/dataset, and reserved future kinds) —
- * its specific kind is carried by the referenced document's bomType, not by a per-kind
- * Content_Type value.
+ * Bill-of-Materials/manifest document (SBOM, AI model/dataset, and reserved future kinds) — its
+ * specific kind is carried by the referenced document's bomType, not by a per-kind Content_Type
+ * value.
  */
 export enum ContentType {
     BOM = "bom",
@@ -4014,10 +3714,10 @@ export enum ContentType {
 }
 
 /**
- * A reference to external native-format evidence (log/telemetry corpus or other artifact)
- * carried by URI + integrity hash + format discriminator. Reference-only: the artifact is
- * never embedded (corpora can be huge) or transcoded (that would be lossy) — it stays
- * canonical in its native format and HDF acts as the structured index.
+ * A reference to external native-format evidence (log/telemetry corpus or other artifact) carried
+ * by URI + integrity hash + format discriminator. Reference-only: the artifact is never embedded
+ * (corpora can be huge) or transcoded (that would be lossy) — it stays canonical in its native
+ * format and HDF acts as the structured index.
  */
 export interface ExternalEvidenceReference {
     /**
@@ -4057,10 +3757,7 @@ export interface ExternalEvidenceReference {
 }
 
 /**
- * Optional descriptive metadata about the referenced corpus. Does not affect integrity.
- *
- * Descriptive metadata about a referenced external evidence corpus. Does not affect
- * integrity.
+ * Descriptive metadata about a referenced external evidence corpus. Does not affect integrity.
  */
 export interface ExternalEvidenceMetadata {
     /**
@@ -4080,8 +3777,6 @@ export interface ExternalEvidenceMetadata {
 }
 
 /**
- * The time window the referenced evidence covers.
- *
  * The time window a referenced external evidence corpus covers.
  */
 export interface ExternalEvidenceTimeRange {