@mitre/hdf-schema 3.6.0-rc.5 → 3.7.0-rc.1

package/dist/schemas/hdf-comparison.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://mitre.github.io/hdf-libs/schemas/hdf-comparison/v3.5.0",
+  "$id": "https://mitre.github.io/hdf-libs/schemas/hdf-comparison/v3.7.0",
   "type": "object",
   "unevaluatedProperties": false,
   "required": [
@@ -14,7 +14,7 @@
     "externalReferences": {
       "type": "array",
       "items": {
-        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/External_Reference"
+        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/External_Reference"
       },
       "description": "Optional references to external artifacts relevant to this comparison (CTI/STIX, advisories, or any URI-addressable artifact). Inert context; see External_Reference."
     },
@@ -24,7 +24,7 @@
       "description": "Schema version for this comparison format."
     },
     "comparisonMode": {
-      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.5.0#/$defs/Comparison_Mode",
+      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.7.0#/$defs/Comparison_Mode",
       "description": "The mode of comparison being performed."
     },
     "timestamp": {
@@ -33,50 +33,50 @@
       "description": "When this comparison was performed."
     },
     "generator": {
-      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/Generator",
+      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/Generator",
       "description": "Information about the tool that generated this comparison."
     },
     "sources": {
       "type": "array",
       "minItems": 2,
       "items": {
-        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.5.0#/$defs/Source"
+        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.7.0#/$defs/Source"
       },
       "description": "The source documents being compared. At least two sources are required."
     },
     "matching": {
-      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.5.0#/$defs/Matching_Config",
+      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.7.0#/$defs/Matching_Config",
       "description": "Configuration for how requirements were matched across sources."
     },
     "summary": {
-      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.5.0#/$defs/Comparison_Summary",
+      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.7.0#/$defs/Comparison_Summary",
       "description": "Summary statistics for the overall comparison."
     },
     "baselineDiffs": {
       "type": "array",
       "items": {
-        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.5.0#/$defs/Baseline_Diff"
+        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.7.0#/$defs/Baseline_Diff"
       },
       "description": "Comparison of baselines between sources."
     },
     "requirementDiffs": {
       "type": "array",
       "items": {
-        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.5.0#/$defs/Requirement_Diff"
+        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.7.0#/$defs/Requirement_Diff"
       },
       "description": "Detailed comparison of individual requirements between sources."
     },
     "componentDiffs": {
       "type": "array",
       "items": {
-        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.5.0#/$defs/Component_Diff"
+        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.7.0#/$defs/Component_Diff"
       },
       "description": "Comparison of components between two system documents. Used in systemDrift mode. A component's BOM changes surface as a field change on its boms[] here."
     },
     "packageDiffs": {
       "type": "array",
       "items": {
-        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.5.0#/$defs/Package_Diff"
+        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.7.0#/$defs/Package_Diff"
       },
       "description": "RESERVED — not emitted by the current systemDrift comparison. systemDrift now reports a component's BOM changes as a field change on its boms[] (see componentDiffs), and standalone SBOM package diffing is a separate `hdf diff <sbom> <sbom>` output shape. This field is retained for a future normalized package-level diff; consumers must not expect it from today's systemDrift output."
     },
@@ -88,19 +88,19 @@
     "drift": {
       "type": "array",
       "items": {
-        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.5.0#/$defs/Requirement_Diff"
+        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.7.0#/$defs/Requirement_Diff"
       },
       "description": "External/metadata changes separate from status changes (Terraform pattern)."
     },
     "annotations": {
       "type": "object",
       "additionalProperties": {
-        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.5.0#/$defs/Annotation"
+        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.7.0#/$defs/Annotation"
       },
       "description": "Map of annotation IDs to annotation objects, providing context or action items for requirement diffs."
     },
     "integrity": {
-      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/Integrity",
+      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/Integrity",
       "description": "Cryptographic integrity information for verifying this comparison document."
     },
     "extensions": {
@@ -112,9 +112,9 @@
   "description": "Structured comparison between two or more HDF security assessment documents. Supports temporal, baseline, fleet, and multi-source comparison modes.",
   "title": "HDF Comparison",
   "$defs": {
-    "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0",
       "title": "HDF Common Primitives",
       "description": "Shared building blocks used by hdf-results and hdf-baseline schemas.",
       "$defs": {
@@ -194,22 +194,20 @@
             }
           },
           "unevaluatedProperties": false,
+          "$comment": "Examples, in order: 1) By-identity: cite a CVE by its id in the 'cve' system without a URL — equivalently urn:cve:CVE-2021-44228; 2) By-identity AND by-locator together (anyOf, not oneOf) — an ATT&CK technique cited by id with its canonical URL; 3) By-locator to a retrievable STIX bundle, with integrity hash, media type, and attribution; 4) Enrichment envelope: a STIX threat-intel object embedded losslessly in `document` and classified via `kind`, cited by id and pointed at by href — the pointer and the embedded copy compose. The payload rides verbatim; HDF does not normalize STIX fields.",
           "examples": [
             {
-              "$comment": "By-identity: cite a CVE by its id in the 'cve' system without a URL — equivalently urn:cve:CVE-2021-44228.",
               "sourceName": "cve",
               "externalId": "CVE-2021-44228",
               "rel": "definition"
             },
             {
-              "$comment": "By-identity AND by-locator together (anyOf, not oneOf) — an ATT&CK technique cited by id with its canonical URL.",
               "sourceName": "mitre-att&ck",
               "externalId": "T1059",
               "href": "https://attack.mitre.org/techniques/T1059/",
               "rel": "canonical"
             },
             {
-              "$comment": "By-locator to a retrievable STIX bundle, with integrity hash, media type, and attribution.",
               "sourceName": "stix",
               "href": "https://cti.example.org/bundles/log4shell.json",
               "rel": "investigate",
@@ -225,7 +223,6 @@
               "addedAt": "2026-07-26T00:00:00Z"
             },
             {
-              "$comment": "Enrichment envelope: a STIX threat-intel object embedded losslessly in `document` and classified via `kind`, cited by id and pointed at by href — the pointer and the embedded copy compose. The payload rides verbatim; HDF does not normalize STIX fields.",
               "sourceName": "stix",
               "externalId": "vulnerability--f7c1b8e0-1234-4a2b-9c3d-000000000001",
               "href": "https://cti.example.org/bundles/log4shell.json#vulnerability--f7c1b8e0-1234-4a2b-9c3d-000000000001",
@@ -557,6 +554,24 @@
             "type",
             "data"
           ],
+          "if": {
+            "properties": {
+              "encoding": {
+                "const": "base64"
+              }
+            },
+            "required": [
+              "encoding"
+            ]
+          },
+          "then": {
+            "properties": {
+              "data": {
+                "pattern": "^[0-9A-Za-z+/]+={0,2}$",
+                "contentEncoding": "base64"
+              }
+            }
+          },
           "properties": {
             "type": {
               "type": "string",
@@ -573,7 +588,8 @@
             },
             "data": {
               "type": "string",
-              "description": "The evidence content. For screenshots/files: base64-encoded data or URL. For code/logs: the raw text. For URLs: the URL string."
+              "minLength": 1,
+              "description": "The evidence content. For screenshots/files: base64-encoded data or URL. For code/logs: the raw text. For URLs: the URL string. Must not be empty. When encoding is 'base64', data must be bare base64 matching ^[0-9A-Za-z+/]+={0,2}$ (OSCAL's Base64Datatype): no data: URI prefix, URL, or line breaks."
             },
             "description": {
               "type": "string",
@@ -585,7 +601,7 @@
             },
             "encoding": {
               "type": "string",
-              "description": "Encoding used for the data. Example: 'base64', 'utf-8'."
+              "description": "Encoding used for the data. Example: 'base64', 'utf-8'. The value 'base64' (exactly, lowercase) requires data to be bare base64."
             },
             "size": {
               "type": "number",
@@ -649,6 +665,7 @@
               }
             }
           ],
+          "$comment": "Examples, in order: 1) base64-encoded PNG screenshot with full capture provenance; 2) raw configuration text; 3) log excerpt; 4) URL to an external ticket; 5) base64-encoded file captured by an automated system.",
           "description": "Supporting evidence for a finding or override, such as screenshots, code samples, log excerpts, or URLs.",
           "title": "Evidence"
         },
@@ -726,6 +743,13 @@
             "status"
           ],
           "properties": {
+            "title": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^[^ \\t\\n\\r]([^\\n\\r]*[^ \\t\\n\\r])?$",
+              "$comment": "The pattern is OSCAL's StringDatatype (\\S(.*\\S)?) as its XSD defines \\S and '.', spelled with explicit classes so ECMA-262 and Go regexp engines agree: \\S and '.' differ between them on CR and non-ASCII whitespace.",
+              "description": "Short single-line label for this milestone, suitable where a consumer needs a title (for example an OSCAL POA&M remediation or task). No line breaks, and no leading or trailing whitespace. The description remains the full text of the milestone; the title does not replace it."
+            },
             "description": {
               "type": "string",
               "description": "Description of this milestone or task."
@@ -755,6 +779,25 @@
               "description": "Identity of who completed this milestone."
             }
           },
+          "examples": [
+            {
+              "title": "Deploy OpenSSH 9.8p1",
+              "description": "Upgrade OpenSSH to 9.8p1 on every RHEL 9 host in the web tier to remediate CVE-2024-6387, then restart sshd during the Saturday maintenance window.",
+              "estimatedCompletion": "2026-10-31T00:00:00Z",
+              "status": "inProgress"
+            },
+            {
+              "description": "Isolate the affected host on a restricted VLAN until the vendor patch is available.",
+              "estimatedCompletion": "2026-09-05T00:00:00Z",
+              "status": "completed",
+              "completedAt": "2026-09-04T14:30:00Z",
+              "completedBy": {
+                "identifier": "network-admin@example.com",
+                "type": "email"
+              }
+            }
+          ],
+          "$comment": "Examples, in order: 1) titled milestone in progress — the title is the short label, the description the full remediation text; 2) untitled completed milestone with completion provenance — title is optional, and a consumer needing one derives it.",
           "description": "A milestone or task within a POA&M remediation plan.",
           "title": "Milestone"
         },
@@ -1044,9 +1087,9 @@
               "description": "Whether the requirement is mandatory within its baseline.\n\nDistinct from severity (risk weight) and status (lifecycle state).\n\nMaps cleanly onto: FedRAMP rev5 OSCAL 'CORE' prop, FedRAMP 20x inline 'Optional:' markers, CMMC sublevel rows, and CIS Implementation Group memberships (IG1/IG2/IG3 may carry richer semantics; layer those onto props[]/tags{}).\n\nOptional: when omitted, consumers should treat the requirement as 'required' by convention."
             }
           },
+          "$comment": "Examples, in order: 1) v3.1.x-style requirement: classification fields omitted. Consumers must continue to handle this shape for backward compatibility; 2) v3.2 example populating all three classification fields. controlType=technical because AC-3 is enforced via configuration, not policy text. verificationMethod=automated because a check exists. applicability=required because this is a CORE control in the source baseline; 3) v3.2 example for a manual-by-design requirement. FedRAMP 20x KSIs are statement-form: code is omitted (not null) and verificationMethod=manual-by-design distinguishes this from 'automation could exist but doesn't yet'. controlType=policy because this is an authored governance statement; 4) v3.2 example for a STIG rule lacking a <fix>. Differs from manual-by-design: automation should exist, just not yet. applicability=advisory used here because the source format flagged it as recommended-but-not-mandatory; CIS-style IG memberships and FedRAMP 'Optional:' markers map onto applicability=optional or advisory similarly.",
           "examples": [
             {
-              "$comment": "v3.1.x-style requirement: classification fields omitted. Consumers must continue to handle this shape under v3.5.0 (backward compatibility).",
               "id": "SV-238196",
               "title": "The Ubuntu operating system must enforce password complexity",
               "impact": 0.5,
@@ -1076,7 +1119,6 @@
               ]
             },
             {
-              "$comment": "v3.2 example populating all three classification fields. controlType=technical because AC-3 is enforced via configuration, not policy text. verificationMethod=automated because a check exists. applicability=required because this is a CORE control in the source baseline.",
               "id": "AC-3",
               "title": "Access Enforcement",
               "impact": 0.7,
@@ -1098,7 +1140,6 @@
               "applicability": "required"
             },
             {
-              "$comment": "v3.2 example for a manual-by-design requirement. FedRAMP 20x KSIs are statement-form: code is omitted (not null) and verificationMethod=manual-by-design distinguishes this from 'automation could exist but doesn't yet'. controlType=policy because this is an authored governance statement.",
               "id": "KSI-CNA-01",
               "title": "Cyber Security Plan documents the system",
               "impact": 0.5,
@@ -1118,7 +1159,6 @@
               "applicability": "required"
             },
             {
-              "$comment": "v3.2 example for a STIG rule lacking a <fix>. Differs from manual-by-design: automation should exist, just not yet. applicability=advisory used here because the source format flagged it as recommended-but-not-mandatory; CIS-style IG memberships and FedRAMP 'Optional:' markers map onto applicability=optional or advisory similarly.",
               "id": "SV-999999",
               "title": "Example STIG rule pending automation",
               "impact": 0.3,
@@ -1183,9 +1223,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/comparison/v3.7.0",
       "title": "HDF Comparison Primitives",
       "description": "Types for representing structured comparisons between HDF security assessment documents.",
       "$defs": {
@@ -1357,7 +1397,7 @@
               "description": "The original format of the source document before conversion to HDF."
             },
             "checksum": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
               "description": "Cryptographic checksum of the source document for integrity verification."
             },
             "assessmentTimestamp": {
@@ -1366,13 +1406,13 @@
               "description": "When the source assessment was performed. ISO 8601 format."
             },
             "tool": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/Tool",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/Tool",
               "description": "The security tool that produced the assessment data in this source."
             },
             "components": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.5.0#/$defs/Component"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.7.0#/$defs/Component"
               },
               "description": "The components assessed in this source."
             },
@@ -1724,7 +1764,7 @@
             "before": {
               "oneOf": [
                 {
-                  "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.5.0#/$defs/Component"
+                  "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.7.0#/$defs/Component"
                 },
                 {
                   "type": "null"
@@ -1735,7 +1775,7 @@
             "after": {
               "oneOf": [
                 {
-                  "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.5.0#/$defs/Component"
+                  "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.7.0#/$defs/Component"
                 },
                 {
                   "type": "null"
@@ -1812,9 +1852,9 @@
               "description": "License identifiers for this package."
             }
           },
+          "$comment": "Examples, in order: 1) Software package diff keyed by purl (the SBOM case); 2) AI-model node diff keyed by identifier when no purl applies.",
           "examples": [
             {
-              "$comment": "Software package diff keyed by purl (the SBOM case).",
               "purl": "pkg:npm/express@4.18.2",
               "name": "express",
               "state": "updated",
@@ -1822,7 +1862,6 @@
               "newVersion": "4.18.2"
             },
             {
-              "$comment": "AI-model node diff keyed by identifier when no purl applies.",
               "identifier": "acme/llama-2-7b-chat-support",
               "name": "Llama-2-7b-chat (finetuned)",
               "state": "added",
@@ -1941,7 +1980,7 @@
             "before": {
               "oneOf": [
                 {
-                  "$ref": "https://mitre.github.io/hdf-libs/schemas/hdf-results/v3.5.0#/$defs/Evaluated_Requirement"
+                  "$ref": "https://mitre.github.io/hdf-libs/schemas/hdf-results/v3.7.0#/$defs/Evaluated_Requirement"
                 },
                 {
                   "type": "null"
@@ -1952,7 +1991,7 @@
             "after": {
               "oneOf": [
                 {
-                  "$ref": "https://mitre.github.io/hdf-libs/schemas/hdf-results/v3.5.0#/$defs/Evaluated_Requirement"
+                  "$ref": "https://mitre.github.io/hdf-libs/schemas/hdf-results/v3.7.0#/$defs/Evaluated_Requirement"
                 },
                 {
                   "type": "null"
@@ -2048,9 +2087,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0",
       "title": "HDF Extension Primitives",
       "description": "Extension types for waivers, attestations, generators, and integrity.",
       "$defs": {
@@ -2080,20 +2119,20 @@
             "externalReferences": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/External_Reference"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/External_Reference"
               },
               "description": "Optional references to the external artifacts behind this override (e.g. the STIX bundle/object or CTI feed motivating an E:A riskAdjustment). Inert context distinct from `evidence`; see External_Reference. Symmetric with Standalone_Override.externalReferences for the inline (results-embedded) override carrier."
             },
             "type": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.5.0#/$defs/Override_Type",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.7.0#/$defs/Override_Type",
               "description": "The type of override applied to this requirement."
             },
             "status": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0#/$defs/Result_Status",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0#/$defs/Result_Status",
               "description": "The new status this override sets for the requirement. Optional when only impact is being overridden."
             },
             "impact": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.5.0#/$defs/Impact_Override",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.7.0#/$defs/Impact_Override",
               "description": "Override to the requirement's impact score. At least one of status or impact must be set."
             },
             "reason": {
@@ -2101,7 +2140,7 @@
               "description": "Explanation for why this override was applied."
             },
             "appliedBy": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Identity",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Identity",
               "description": "Identity of who applied this override. For simple cases, use type 'simple' with just an identifier."
             },
             "appliedAt": {
@@ -2115,30 +2154,31 @@
               "description": "Timestamp when this override expires and must be reviewed/renewed. REQUIRED - no permanent overrides allowed. ISO 8601 format."
             },
             "signature": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Signature",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Signature",
               "description": "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."
             },
             "evidence": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Evidence"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Evidence"
               },
               "description": "Supporting evidence for this override, such as screenshots demonstrating manual verification for attestations."
             },
             "previousChecksum": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
               "description": "SHA-256 checksum of the previous amendment in chronological order. Each amendment's checksum is recorded by the NEXT one, so editing an amendment in place is detectable — provided a later amendment is chained to it. It is NOT tamper-proof: the final amendment, the document envelope, deleted trailing amendments, and a chain that has been stripped or recomputed wholesale are all outside what it can detect. Use signature for non-repudiation. Omitted on the first amendment on a requirement."
             },
             "cvss": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.5.0#/$defs/Cvss",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.7.0#/$defs/Cvss",
               "$comment": "When present alongside impact.value on a riskAdjustment override, impact.value should be approximately cvss.computedScore / 10.0. Soft consistency rule — validators may warn but should not error. The cvss block makes Environmental/Threat enrichment auditable.",
               "description": "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."
             },
             "justification": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.5.0#/$defs/Justification",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.7.0#/$defs/Justification",
               "description": "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."
             }
           },
+          "$comment": "Example 3: Inline riskAdjustment carrying the STIX source that motivated it via externalReferences (the enrichment envelope, with the raw sighting embedded losslessly in document). This is the shape the enrich pass writes onto Evaluated_Requirement.overrides[] for the E:A recompute.",
           "examples": [
             {
               "type": "waiver",
@@ -2165,7 +2205,6 @@
               "expiresAt": "2026-10-14T00:00:00Z"
             },
             {
-              "$comment": "Inline riskAdjustment carrying the STIX source that motivated it via externalReferences (the enrichment envelope, with the raw sighting embedded losslessly in document). This is the shape the enrich pass writes onto Evaluated_Requirement.overrides[] for the E:A recompute.",
               "type": "riskAdjustment",
               "impact": {
                 "value": 0.9
@@ -2228,7 +2267,7 @@
               "evidence": [
                 {
                   "type": "screenshot",
-                  "data": "base64-encoded-screenshot-data-here",
+                  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
                   "description": "Screenshot showing firewall configuration",
                   "mimeType": "image/png",
                   "encoding": "base64",
@@ -2271,7 +2310,7 @@
               "description": "Detailed explanation of the plan, including what actions will be taken."
             },
             "appliedBy": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Identity",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Identity",
               "description": "Identity of who created this POA&M. For simple cases, use type 'simple' with just an identifier."
             },
             "appliedAt": {
@@ -2287,23 +2326,23 @@
             "milestones": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Milestone"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Milestone"
               },
               "description": "Optional array of milestones tracking progress toward completion."
             },
             "signature": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Signature",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Signature",
               "description": "Optional digital signature for enhanced trust and non-repudiation."
             },
             "evidence": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Evidence"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Evidence"
               },
               "description": "Supporting evidence for this POA&M, such as documentation of compensating controls or mitigation implementation."
             },
             "previousChecksum": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
               "description": "SHA-256 checksum of the previous amendment in chronological order. Each amendment's checksum is recorded by the NEXT one, so editing an amendment in place is detectable — provided a later amendment is chained to it. It is NOT tamper-proof: the final amendment, the document envelope, deleted trailing amendments, and a chain that has been stripped or recomputed wholesale are all outside what it can detect. Use signature for non-repudiation. Omitted on the first amendment on a requirement."
             }
           },
@@ -2456,7 +2495,7 @@
           },
           "properties": {
             "algorithm": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Hash_Algorithm",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Hash_Algorithm",
               "description": "The hash algorithm used for the checksum."
             },
             "checksum": {
@@ -2489,9 +2528,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.7.0",
       "title": "HDF Amendment Primitives",
       "description": "Types for waivers, attestations, and POA&Ms that modify requirement compliance status.",
       "$defs": {
@@ -2602,7 +2641,7 @@
             "externalReferences": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/External_Reference"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/External_Reference"
               },
               "description": "Optional references to the external artifacts behind this override (e.g. the STIX bundle/object, advisory, or CTI feed that motivated it). Inert context distinct from `evidence`; see External_Reference."
             },
@@ -2612,6 +2651,7 @@
             },
             "requirementId": {
               "type": "string",
+              "minLength": 1,
               "description": "The ID of the requirement being amended. Must match a requirement ID in the referenced baseline."
             },
             "baselineRef": {
@@ -2619,7 +2659,7 @@
               "description": "Name of the baseline containing the requirement. Required when the system has multiple baselines with potentially overlapping requirement IDs."
             },
             "status": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0#/$defs/Result_Status",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0#/$defs/Result_Status",
               "description": "The new status this amendment sets. Optional when only impact is being overridden."
             },
             "impact": {
@@ -2631,7 +2671,7 @@
               "description": "Justification for this amendment."
             },
             "appliedBy": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Identity",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Identity",
               "description": "Identity of who applied this amendment."
             },
             "appliedAt": {
@@ -2647,20 +2687,20 @@
             "evidence": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Evidence"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Evidence"
               },
               "description": "Supporting evidence (screenshots, logs, URLs, documents)."
             },
             "signature": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Signature",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Signature",
               "description": "Digital signature for non-repudiation."
             },
             "previousChecksum": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
               "description": "SHA-256 checksum of the prior amendment in chronological order. Each amendment's checksum is recorded by the NEXT one, so editing an amendment in place is detectable — provided a later amendment is chained to it. It is NOT tamper-proof: the final amendment, the document envelope, deleted trailing amendments, and a chain that has been stripped or recomputed wholesale are all outside what it can detect. Use signature for non-repudiation. Omitted on the first amendment."
             },
             "cvss": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.5.0#/$defs/Cvss",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.7.0#/$defs/Cvss",
               "$comment": "When present alongside impact.value on a riskAdjustment override, impact.value should be approximately cvss.computedScore / 10.0. Soft consistency rule — validators may warn but should not error. The cvss block makes Environmental/Threat enrichment auditable.",
               "description": "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."
             },
@@ -2671,7 +2711,7 @@
             "milestones": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Milestone"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Milestone"
               },
               "description": "Remediation milestones (primarily for POA&M type amendments)."
             },
@@ -2688,11 +2728,12 @@
             "affectedPackages": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.5.0#/$defs/Affected_Package"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.7.0#/$defs/Affected_Package"
               },
               "description": "Software packages this amendment is scoped to, distinct from componentRef (which scopes to an HDF-internal Component by UUID).\n\nUse when the source amendment format references packages by purl/cpe/name+version — e.g., VEX `affects[]` / `products[]`, OSCAL POA&M `subjects[]`, FedRAMP component-aware amendments.\n\nSymmetric with Evaluated_Requirement.affectedPackages, which scopes findings to the same package vocabulary.\n\nWhen omitted, the amendment applies system-wide (or only to componentRef when that is set)."
             }
           },
+          "$comment": "Example 7: VEX-style import — falsePositive scoped to specific packages by purl. The affectedPackages array carries structured product identity instead of squeezing 'Products: …' into the reason free-text field.",
           "examples": [
             {
               "type": "waiver",
@@ -2794,7 +2835,6 @@
               "expiresAt": "2026-09-26T00:00:00Z"
             },
             {
-              "$comment": "VEX-style import — falsePositive scoped to specific packages by purl. The affectedPackages array carries structured product identity instead of squeezing 'Products: …' into the reason free-text field.",
               "type": "falsePositive",
               "requirementId": "CVE-2026-12345",
               "status": "notApplicable",
@@ -2821,9 +2861,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0",
       "title": "HDF Result Primitives",
       "description": "Types for representing assessment results and statuses.",
       "$defs": {
@@ -2954,9 +2994,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.7.0",
       "title": "HDF CVSS Primitives",
       "description": "Types for representing CVSS (Common Vulnerability Scoring System) data attached to assessment findings. Supports CVSS v2.0, v3.0, v3.1, and v4.0 metric groups (Base, Threat, Environmental, Supplemental).",
       "$defs": {
@@ -3020,7 +3060,7 @@
               ]
             }
           ],
-          "$comment": "Only `version` is required; every metric/score field is optional because a single Cvss instance may represent vendor-supplied Base data (on a finding's cvss[]), consumer-supplied enrichment (on a riskAdjustment override — Environmental/Threat/Supplemental deltas with NO base, since base is the finding's scan-specific vendor data), or a fully-resolved effectiveCvss. The Base/Threat/Environmental/Supplemental groups do not partition cleanly into vendor-vs-consumer (Threat straddles: vendor temporal data and consumer exploit-maturity both live here), so a single permissive type is more honest than separate vendor/consumer types. The anyOf guardrail rejects a content-free object (e.g. {version} alone) by requiring at least one substantive metric or score. baseVector remains optional even when baseScore is present: some vendor tools (Twistlock/Prisma Cloud) emit a final score without the vector that derived it — that score is captured structurally rather than lost.",
+          "$comment": "Only `version` is required; every metric/score field is optional because a single Cvss instance may represent vendor-supplied Base data (on a finding's cvss[]), consumer-supplied enrichment (on a riskAdjustment override — Environmental/Threat/Supplemental deltas with NO base, since base is the finding's scan-specific vendor data), or a fully-resolved effectiveCvss. The Base/Threat/Environmental/Supplemental groups do not partition cleanly into vendor-vs-consumer (Threat straddles: vendor temporal data and consumer exploit-maturity both live here), so a single permissive type is more honest than separate vendor/consumer types. The anyOf guardrail rejects a content-free object (e.g. {version} alone) by requiring at least one substantive metric or score. baseVector remains optional even when baseScore is present: some vendor tools (Twistlock/Prisma Cloud) emit a final score without the vector that derived it — that score is captured structurally rather than lost. Examples, in order: 1) Base-only: vendor-supplied CVSS 3.1 data exactly as a scanner (e.g., Nessus, Grype) would emit it. No consumer enrichment yet; 2) Base + Threat: consumer added Exploit Maturity ('E:U' = Unproven) and Remediation Level ('RL:O' = Official Fix) to a HTTP/2 'Rapid Reset' DoS finding. Threat score drops from base 7.5 to 5.5; 3) Base + Environmental: consumer asserts the affected system is high-criticality (CR:H, IR:H, AR:H) AND network-reachable in their environment (MAV:N). Environmental score reflects deployment risk for the xz-utils backdoor; 4) Full CVSS 4.0: vendor base + consumer threat (E:A = Attacked, exploits seen in the wild) + environmental (high CIA requirements) + supplemental context (S:P = present safety impact, AU:N = no autonomous spread, RE:M = moderate response effort) for the Fortinet FortiOS pre-auth RCE. computedScore reflects post-mitigation final risk; 5) CVSS 2.0 legacy: Heartbleed (CVE-2014-0160) as still reported by older scanner output and legacy NVD data. CVSS 2.0 vectors have no 'CVSS:2.0/' prefix.",
           "properties": {
             "version": {
               "type": "string",
@@ -3100,7 +3140,6 @@
           },
           "examples": [
             {
-              "$comment": "Base-only: vendor-supplied CVSS 3.1 data exactly as a scanner (e.g., Nessus, Grype) would emit it. No consumer enrichment yet.",
               "version": "3.1",
               "source": "CVE-2024-12345",
               "baseVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
@@ -3108,7 +3147,6 @@
               "baseSeverity": "critical"
             },
             {
-              "$comment": "Base + Threat: consumer added Exploit Maturity ('E:U' = Unproven) and Remediation Level ('RL:O' = Official Fix) to a HTTP/2 'Rapid Reset' DoS finding. Threat score drops from base 7.5 to 5.5.",
               "version": "3.1",
               "source": "CVE-2023-44487",
               "baseVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H",
@@ -3118,7 +3156,6 @@
               "threatScore": 5.5
             },
             {
-              "$comment": "Base + Environmental: consumer asserts the affected system is high-criticality (CR:H, IR:H, AR:H) AND network-reachable in their environment (MAV:N). Environmental score reflects deployment risk for the xz-utils backdoor.",
               "version": "3.1",
               "source": "CVE-2024-3094",
               "baseVector": "CVSS:3.1/AV:L/AC:H/PR:H/UI:N/S:U/C:H/I:H/A:H",
@@ -3130,7 +3167,6 @@
               "computedSeverity": "critical"
             },
             {
-              "$comment": "Full CVSS 4.0: vendor base + consumer threat (E:A = Attacked, exploits seen in the wild) + environmental (high CIA requirements) + supplemental context (S:P = present safety impact, AU:N = no autonomous spread, RE:M = moderate response effort) for the Fortinet FortiOS pre-auth RCE. computedScore reflects post-mitigation final risk.",
               "version": "4.0",
               "source": "CVE-2024-21762",
               "baseVector": "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N",
@@ -3145,7 +3181,6 @@
               "computedSeverity": "medium"
             },
             {
-              "$comment": "CVSS 2.0 legacy: Heartbleed (CVE-2014-0160) as still reported by older scanner output and legacy NVD data. CVSS 2.0 vectors have no 'CVSS:2.0/' prefix.",
               "version": "2.0",
               "source": "CVE-2014-0160",
               "baseVector": "AV:N/AC:L/Au:N/C:P/I:N/A:N",
@@ -3158,9 +3193,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.7.0",
       "title": "HDF Affected Package Primitives",
       "description": "Types for representing the software package(s) affected by a vulnerability finding.",
       "$defs": {
@@ -3226,9 +3261,9 @@
               "description": "Optional version string identifying the first release that contains the fix for the vulnerability. Use the same version syntax as `version`. Example: '1.1.1l' fixes 'openssl@1.1.1k'."
             }
           },
+          "$comment": "Examples, in order: 1) RPM ecosystem with full CPE + PURL — typical Grype/Trivy output for a RHEL host scan; 2) NPM ecosystem with PURL only — the JavaScript world rarely emits CPEs; PURL is the canonical identifier; 3) Minimal valid AffectedPackage — only the three required fields. Use when the scanner reports a package by name+version without emitting CPE or PURL strings; 4) Maven ecosystem with full identifiers + fixedInVersion — log4j Log4Shell-style finding showing the patch path from vulnerable to fixed; 5) purl-only — VEX import path where the source format gives a purl and we choose not to decompose it. Valid because purl encodes name/version/ecosystem implicitly; 6) cpe-only — NIST-flavored scopes where the consumer carries a CPE 2.3 string and no purl. Valid because cpe encodes vendor/product/version.",
           "examples": [
             {
-              "$comment": "RPM ecosystem with full CPE + PURL — typical Grype/Trivy output for a RHEL host scan.",
               "name": "openssl",
               "version": "1.1.1k-7.el8_4",
               "ecosystem": "rpm",
@@ -3237,7 +3272,6 @@
               "fixedInVersion": "1.1.1l"
             },
             {
-              "$comment": "NPM ecosystem with PURL only — the JavaScript world rarely emits CPEs; PURL is the canonical identifier.",
               "name": "lodash",
               "version": "4.17.20",
               "ecosystem": "npm",
@@ -3245,13 +3279,11 @@
               "fixedInVersion": "4.17.21"
             },
             {
-              "$comment": "Minimal valid AffectedPackage — only the three required fields. Use when the scanner reports a package by name+version without emitting CPE or PURL strings.",
               "name": "requests",
               "version": "2.28.1",
               "ecosystem": "pypi"
             },
             {
-              "$comment": "Maven ecosystem with full identifiers + fixedInVersion — log4j Log4Shell-style finding showing the patch path from vulnerable to fixed.",
               "name": "org.apache.logging.log4j:log4j-core",
               "version": "2.14.1",
               "ecosystem": "maven",
@@ -3260,11 +3292,9 @@
               "fixedInVersion": "2.17.1"
             },
             {
-              "$comment": "purl-only — VEX import path where the source format gives a purl and we choose not to decompose it. Valid because purl encodes name/version/ecosystem implicitly.",
               "purl": "pkg:npm/lodash@4.17.20"
             },
             {
-              "$comment": "cpe-only — NIST-flavored scopes where the consumer carries a CPE 2.3 string and no purl. Valid because cpe encodes vendor/product/version.",
               "cpe": "cpe:2.3:a:openssl:openssl:1.1.1k:*:*:*:*:*:*:*"
             }
           ],
@@ -3273,9 +3303,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.7.0",
       "title": "HDF Component Primitives",
       "description": "First-class system component with identity, polymorphic type, generalized BOM attachment (boms[]), and system-binding properties. Components are the successor to Targets, adding stable identity (componentId), external system cross-references, and manifest inventory (SBOM, AI model/dataset, and reserved future BOM kinds).",
       "$defs": {
@@ -3321,7 +3351,7 @@
               "description": "Description of this component's role or purpose."
             },
             "owner": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Identity",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Identity",
               "description": "Team or individual responsible for this component. Enables per-component ownership when different teams manage different parts of a system."
             },
             "externalIds": {
@@ -3341,14 +3371,14 @@
             "boms": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/bom/v3.5.0#/$defs/Bom"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/bom/v3.7.0#/$defs/Bom"
               },
               "description": "Component-scoped Bills of Materials (SBOM, ai-model, dataset, or any reserved bomType), each carried by passthrough (ref/document) or normalized. Replaces the former sbom/sbomRef/sbomFormat trio; a component may carry several BOMs (e.g. an SBOM plus an ai-model BOM). See primitives/bom.schema.json."
             },
             "integrity": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum"
               },
               "description": "Cryptographic integrity of this component's underlying artifact — model weights or shards, dataset archive, container image, or package bytes.\n\nAn array supports multi-file/sharded artifacts.\n\nThis is the single, generic home for artifact/subject integrity across all component types (it replaced the former per-type Container_Image digest and Artifact checksum fields).\n\nDistinct from BOM-document integrity (Bom.hashes[]) and from the document tamper-evidence Integrity type."
             },
@@ -3362,12 +3392,12 @@
             "inputOverrides": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.5.0#/$defs/Input_Override"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.7.0#/$defs/Input_Override"
               },
               "description": "System-specific overrides for baseline input values."
             },
             "targetSelector": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.5.0#/$defs/Target_Selector",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.7.0#/$defs/Target_Selector",
               "description": "Label selector to match targets belonging to this component during migration. Targets with matching labels are automatically included."
             }
           },
@@ -3498,9 +3528,9 @@
               }
             }
           ],
+          "$comment": "Examples, in order: 1) Domain-joined host carrying all three identity fields separately: short hostname, FQDN, and the (distinct) directory domain. HOST_NAME and HOST_FQDN from a STIG checklist map here; note the AD domain differs from the FQDN's DNS suffix; 2) Standalone/workgroup host: has a short hostname but no directory domain — 'domain' is omitted rather than fabricated from the FQDN suffix.",
           "examples": [
             {
-              "$comment": "Domain-joined host carrying all three identity fields separately: short hostname, FQDN, and the (distinct) directory domain. HOST_NAME and HOST_FQDN from a STIG checklist map here; note the AD domain differs from the FQDN's DNS suffix.",
               "type": "host",
               "name": "web-server-prod-01",
               "componentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
@@ -3516,7 +3546,6 @@
               }
             },
             {
-              "$comment": "Standalone/workgroup host: has a short hostname but no directory domain — 'domain' is omitted rather than fabricated from the FQDN suffix.",
               "type": "host",
               "name": "kiosk-lab-07",
               "hostname": "kiosk-lab-07",
@@ -3651,7 +3680,7 @@
                   "const": "cloudAccount"
                 },
                 "provider": {
-                  "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Cloud_Provider",
+                  "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Cloud_Provider",
                   "description": "Cloud provider."
                 },
                 "accountId": {
@@ -3690,7 +3719,7 @@
                   "const": "cloudResource"
                 },
                 "provider": {
-                  "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Cloud_Provider",
+                  "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Cloud_Provider",
                   "description": "Cloud provider."
                 },
                 "resourceType": {
@@ -3989,9 +4018,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/bom/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/bom/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/bom/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/bom/v3.7.0",
       "title": "HDF BOM Primitives",
       "description": "Generalized Bill-of-Materials / manifest representation.\n\nOne extensible Bom shape, discriminated by bomType, carries any manifest kind (SBOM, AI model/dataset, and reserved future kinds) either by passthrough (opaque ref/embed of the native document) or normalized (converted into HDF's queryable shape).\n\nSubject identity (name, version, componentId) is inherited from the host component or system — the BOM never re-owns it.\n\nSee ADR-0001.",
       "$defs": {
@@ -4047,7 +4076,7 @@
             "hashes": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum"
               },
               "description": "Integrity of the carried BOM *document* itself (the referenced/embedded manifest file), NOT the integrity of the BOM's subject artifact. Subject/artifact integrity (model weights, dataset archive) is a component-level concern, not carried here. Subject identity is inherited from the host component/system; per-node identity lives in the type-extension."
             },
@@ -4164,9 +4193,9 @@
               ]
             }
           ],
+          "$comment": "Examples, in order: 1) Passthrough SBOM by external reference — the universal escape hatch, available to every bomType; 2) Passthrough for a reserved-but-not-yet-normalized type (cbom) — carried opaquely until a normalized extension ships; 3) Normalized ai-model BOM: CISA/G7-aligned fields live in the model extension, never at the component root or shared base; 4) Normalized dataset BOM with lineage — a filtered derivative of a base dataset, referenced by an ai-model via datasetRefs.",
           "examples": [
             {
-              "$comment": "Passthrough SBOM by external reference — the universal escape hatch, available to every bomType.",
               "bomType": "sbom",
               "format": "cyclonedx",
               "ref": "https://artifacts.agency.gov/sbom/webtier.cdx.json",
@@ -4178,7 +4207,6 @@
               ]
             },
             {
-              "$comment": "Passthrough for a reserved-but-not-yet-normalized type (cbom) — carried opaquely until a normalized extension ships.",
               "bomType": "cbom",
               "format": "cyclonedx",
               "document": {
@@ -4187,7 +4215,6 @@
               }
             },
             {
-              "$comment": "Normalized ai-model BOM: CISA/G7-aligned fields live in the model extension, never at the component root or shared base.",
               "bomType": "ai-model",
               "format": "cyclonedx-ml",
               "model": {
@@ -4227,7 +4254,6 @@
               }
             },
             {
-              "$comment": "Normalized dataset BOM with lineage — a filtered derivative of a base dataset, referenced by an ai-model via datasetRefs.",
               "bomType": "dataset",
               "format": "croissant",
               "dataset": {
@@ -4462,9 +4488,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/system/v3.7.0",
       "title": "HDF System Primitives",
       "description": "Types for describing system architecture, authorization boundaries, and components.",
       "$defs": {
@@ -4515,7 +4541,7 @@
               "description": "Rationale for why this override is needed."
             },
             "approvedBy": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Identity",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Identity",
               "description": "Identity of the person or system that approved this override."
             }
           },
@@ -4597,9 +4623,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/hdf-results/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/hdf-results/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/hdf-results/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/hdf-results/v3.7.0",
       "type": "object",
       "unevaluatedProperties": false,
       "required": [
@@ -4609,7 +4635,7 @@
         "externalReferences": {
           "type": "array",
           "items": {
-            "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/External_Reference"
+            "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/External_Reference"
           },
           "description": "Optional references to external artifacts (CTI/STIX, BOMs, advisories, runbooks, or any URI-addressable artifact) relevant to this assessment as a whole. Inert context; see External_Reference."
         },
@@ -4626,7 +4652,7 @@
         "components": {
           "type": "array",
           "items": {
-            "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.5.0#/$defs/Component"
+            "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/component/v3.7.0#/$defs/Component"
           },
           "description": "The components that were assessed. Each component describes a system element (host, container, cloud resource, application, etc.) with optional identity, SBOM, and external references."
         },
@@ -4638,27 +4664,38 @@
           "description": "Information on the baselines that were evaluated, including findings."
         },
         "statistics": {
-          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/statistics/v3.5.0#/$defs/Statistics",
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/statistics/v3.7.0#/$defs/Statistics",
           "description": "Statistics for the assessment run, including duration and result counts."
         },
         "generator": {
-          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/Generator",
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/Generator",
           "description": "Information about the tool that generated this file."
         },
         "tool": {
-          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/Tool",
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/Tool",
           "description": "The security tool that produced the assessment data in this file."
         },
         "integrity": {
-          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/Integrity",
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/Integrity",
           "description": "Cryptographic integrity information for verifying this file."
         },
+        "preAmendmentChecksum": {
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
+          "description": "Hash of this results document as it stood immediately before the most recent amendment application. Written by `hdf amend apply` when it applies at least one override; an apply that matches nothing leaves the document untouched. The hash covers the results file's RAW BYTES as read, not a canonical form, so reproducing it requires the byte-identical original — reformatting or re-serializing the source changes the value. Only the most recent pre-application state is recorded: applying amendments to an already-amended document REPLACES this value, so it is a single link back one step, not a growing chain. Distinct from the `previousChecksum` inside an override, which chains amendments to each other and is computed over a canonical JSON form.",
+          "$comment": "Example 1: the real SHA-256 of hdf-converters/converters/nessus-to-hdf/fixtures/expected/sample.nessus.hdf.json, reproducible with `shasum -a 256` on that file — chosen over a synthetic digest so a reader can verify the hash basis is the raw file bytes.",
+          "examples": [
+            {
+              "algorithm": "sha256",
+              "value": "9599ce7889e99b70ef5d0f3efa4215e35059c10a7e89b9314cbf4ded8fdbad38"
+            }
+          ]
+        },
         "runner": {
-          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/runner/v3.5.0#/$defs/Runner",
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/runner/v3.7.0#/$defs/Runner",
           "description": "Information about the test execution environment where the security tool was run. Distinct from targets (what is being tested)."
         },
         "remediation": {
-          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Remediation",
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Remediation",
           "description": "Optional reference to automated remediation resources (Ansible playbooks, Terraform scripts, etc.) for fixing failing requirements found in this assessment."
         },
         "systemRef": {
@@ -4672,7 +4709,7 @@
           "description": "Reference to an hdf-plan document describing the assessment plan that produced these results. May be a relative path, absolute URI, or fragment identifier."
         },
         "derivation": {
-          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/events/v3.5.0#/$defs/Derivation",
+          "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/events/v3.7.0#/$defs/Derivation",
           "description": "Present ONLY on reconciled result sets: lineage recording the seed snapshot and event watermark this document was reassembled from (ADR-0005). Documents produced directly by a scan omit this field. When present, generator names the reconciling tool."
         },
         "extensions": {
@@ -4770,14 +4807,14 @@
           ],
           "allOf": [
             {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Baseline_Metadata"
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Baseline_Metadata"
             }
           ],
           "properties": {
             "depends": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Dependency"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Dependency"
               },
               "description": "The set of dependencies this baseline depends on."
             },
@@ -4790,15 +4827,15 @@
               "description": "The description - should be more detailed than the summary."
             },
             "integrity": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/Integrity",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/Integrity",
               "description": "Cryptographic integrity information for verifying this baseline has not been tampered with."
             },
             "originalChecksum": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
               "description": "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."
             },
             "resultsChecksum": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
               "description": "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."
             },
             "statusMessage": {
@@ -4816,14 +4853,14 @@
             "groups": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Requirement_Group"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Requirement_Group"
               },
               "description": "A set of descriptions for the requirement groups."
             },
             "inputs": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/parameter/v3.5.0#/$defs/Input"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/parameter/v3.7.0#/$defs/Input"
               },
               "description": "Typed inputs used to parameterize this baseline at execution time. See the Input primitive for the full schema."
             },
@@ -4848,7 +4885,7 @@
           ],
           "allOf": [
             {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Requirement_Core"
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Requirement_Core"
             }
           ],
           "properties": {
@@ -4856,7 +4893,7 @@
               "type": "array",
               "minItems": 1,
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0#/$defs/Requirement_Description"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0#/$defs/Requirement_Description"
               },
               "contains": {
                 "type": "object",
@@ -4872,37 +4909,37 @@
               "description": "Array of labeled descriptions. At least one description with label 'default' must be present. Convention: place default description first. Common labels: 'default', 'check', 'fix', 'rationale'."
             },
             "severity": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Severity",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Severity",
               "description": "Explicit severity rating. Typically derived from impact score but provided explicitly for clarity."
             },
             "sourceLocation": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Source_Location",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Source_Location",
               "description": "The explicit location of the requirement within the source code."
             },
             "results": {
               "type": "array",
               "minItems": 1,
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0#/$defs/Requirement_Result"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0#/$defs/Requirement_Result"
               },
               "description": "The set of all tests within the requirement and their results."
             },
             "statusOverrides": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/Status_Override"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/Status_Override"
               },
               "description": "Chronological history of all overrides applied to this requirement. Overrides are intentional changes to the compliance status and/or impact score (waivers, attestations, false positives, risk adjustments). Most recent override should be first in array. Preserves full audit trail."
             },
             "poams": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.5.0#/$defs/POAM"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.7.0#/$defs/POAM"
               },
               "description": "Plan of Action and Milestones for tracking remediation, mitigation, or risk acceptance. POAMs do NOT change effectiveStatus - they track the work being done to address a failure. Separate from statusOverrides which DO change status."
             },
             "effectiveStatus": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0#/$defs/Result_Status",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0#/$defs/Result_Status",
               "description": "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."
             },
             "effectiveImpact": {
@@ -4912,33 +4949,33 @@
               "description": "The current effective impact score (0.0–1.0) after applying the most recent non-expired override with an impact field. Absent when no impact overrides apply; consumers should use the requirement's impact field in that case."
             },
             "disposition": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.5.0#/$defs/Override_Type",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.7.0#/$defs/Override_Type",
               "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."
             },
             "effectiveChecksum": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
               "description": "Checksum of this requirement's resolved effective posture, for per-control change detection in continuous monitoring.\n\nsha256 over the canonical JSON object with keys status, impact, disposition (in that order), holding the resolved effective status, resolved effective impact, and governing override type (null when nothing governs), with override expiry anchored to the document timestamp.\n\nFlips exactly when the operative status, impact, or disposition changes; stable under all other churn (result details, timestamps, tags).\n\nOptional; stamped by tooling (hdf convert, hdf amend apply)."
             },
             "evidence": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Evidence"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Evidence"
               },
               "description": "Supporting evidence for this requirement's findings, such as screenshots, code samples, or log excerpts."
             },
             "cvss": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.5.0#/$defs/Cvss"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/cvss/v3.7.0#/$defs/Cvss"
               },
               "description": "Structured CVSS scoring data for vulnerability findings. One entry per CVE — a finding may match multiple CVEs (common in vulnerability scanners). Captures vendor-supplied Base metrics plus optional consumer-owned Threat / Environmental / Supplemental groups for risk adjustment. See cvss.schema.json."
             },
             "epss": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/epss/v3.5.0#/$defs/Epss",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/epss/v3.7.0#/$defs/Epss",
               "description": "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."
             },
             "kev": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/kev/v3.5.0#/$defs/Kev",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/kev/v3.7.0#/$defs/Kev",
               "description": "CISA Known Exploited Vulnerabilities (KEV) catalog status. When inKev=true, dateAdded and dueDate carry the federal patching deadline."
             },
             "cwe": {
@@ -4952,14 +4989,14 @@
             "affectedPackages": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.5.0#/$defs/Affected_Package"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/affected-package/v3.7.0#/$defs/Affected_Package"
               },
               "description": "Packages affected by this vulnerability finding. Vulnerability-finding-scoped — see components[] on hdf-system for component-level package inventories. One entry per matched package signature (scanners often report multiple CPE variations per CVE)."
             }
           },
+          "$comment": "Examples, in order: 1) Passing requirement — no overrides, no disposition; 2) Waiver — AO accepted risk, status overridden to passed; 3) False positive (compliance scan) — STIG check was wrong, requirement actually passes; 4) False positive (CVE scan) — vulnerability does not apply to this build; 5) Risk adjustment — impact lowered, pass/fail unchanged; 6) Operational requirement — cannot remediate, remains open risk; 7) POAM — remediation tracked, status unchanged.",
           "examples": [
             {
-              "$comment": "Passing requirement — no overrides, no disposition",
               "id": "SV-230222",
               "title": "RHEL 9 must use SSH protocol version 2",
               "impact": 0.7,
@@ -4984,7 +5021,6 @@
               "effectiveStatus": "passed"
             },
             {
-              "$comment": "Waiver — AO accepted risk, status overridden to passed",
               "id": "SV-230300",
               "title": "RHEL 9 must enforce password complexity",
               "impact": 0.5,
@@ -5028,7 +5064,6 @@
               }
             },
             {
-              "$comment": "False positive (compliance scan) — STIG check was wrong, requirement actually passes",
               "id": "SV-230410",
               "title": "RHEL 9 must have sshd PermitRootLogin disabled",
               "impact": 0.7,
@@ -5068,7 +5103,6 @@
               "disposition": "falsePositive"
             },
             {
-              "$comment": "False positive (CVE scan) — vulnerability does not apply to this build",
               "id": "CVE-2026-12345",
               "title": "libxml2 buffer overflow in xmlParseEntityDecl",
               "impact": 0.9,
@@ -5108,7 +5142,6 @@
               "disposition": "falsePositive"
             },
             {
-              "$comment": "Risk adjustment — impact lowered, pass/fail unchanged",
               "id": "CVE-2026-67890",
               "title": "OpenSSL timing side-channel in RSA decryption",
               "impact": 0.7,
@@ -5151,7 +5184,6 @@
               "disposition": "riskAdjustment"
             },
             {
-              "$comment": "Operational requirement — cannot remediate, remains open risk",
               "id": "SV-230500",
               "title": "RHEL 9 must disable USB mass storage",
               "impact": 0.5,
@@ -5191,7 +5223,6 @@
               "disposition": "operationalRequirement"
             },
             {
-              "$comment": "POAM — remediation tracked, status unchanged",
               "id": "SV-230350",
               "title": "RHEL 9 must be patched within 30 days of release",
               "impact": 0.7,
@@ -5247,9 +5278,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/statistics/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/statistics/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/statistics/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/statistics/v3.7.0",
       "title": "HDF Statistics Primitives",
       "description": "Statistics types for tracking assessment run metrics.",
       "$defs": {
@@ -5318,9 +5349,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/runner/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/runner/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/runner/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/runner/v3.7.0",
       "title": "HDF Runner Primitive",
       "description": "Information about the test execution environment where the security tool/scanner was executed.",
       "$defs": {
@@ -5364,7 +5395,7 @@
               "description": "The container instance identifier. Example: 'a1b2c3d4e5f6', 'security-scan-job-xyz123'. Can be a Docker container ID, Kubernetes pod name, or other container runtime identifier."
             },
             "operator": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Identity",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Identity",
               "description": "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."
             }
           },
@@ -5413,9 +5444,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/events/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/events/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/events/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/events/v3.7.0",
       "title": "HDF Change Event Primitives",
       "description": "Shared building blocks for HDF change-event wire documents. The envelope is entity-agnostic: hdf-requirement-change-event composes it today, and any future sibling event type (e.g. component change events — hdf-comparison already models componentDiffs alongside requirementDiffs) reuses it verbatim.",
       "$defs": {
@@ -5469,7 +5500,7 @@
             "priorChecksum": {
               "oneOf": [
                 {
-                  "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum"
+                  "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum"
                 },
                 {
                   "type": "null"
@@ -5478,23 +5509,22 @@
               "description": "The effectiveChecksum of the entity state this event supersedes, forming a per-key hash chain: a mismatch or gap against stored state is detectable, letting a consumer mark the key unverified instead of serving stale posture.\n\nNull at chain start (no prior state, e.g. a new entity or the first event after a seed).\n\nThe chain provides tamper/gap evidence given a trusted head; completeness is anchored out-of-band by periodic re-centering rescans."
             }
           },
+          "$comment": "Examples, in order: 1) Steady-state envelope: mid-chain event from an InSpec producer. priorChecksum links to the previous effectiveChecksum for this key; 2) Chain-start envelope: first event for a key after seeding — priorChecksum is null (the CloudTrail null-previous-digest convention), sequence starts low.",
           "examples": [
             {
-              "$comment": "Steady-state envelope: mid-chain event from an InSpec producer. priorChecksum links to the previous effectiveChecksum for this key.",
               "eventId": "0190f6f2-1c4e-7c3a-9f2a-3b1d5e7a9c01",
               "source": "inspec://web01/rhel9-stig",
               "sequence": 412,
               "systemRef": "apptier.hdf-system.json",
               "componentId": "6e0f2a3b-9c01-4d5e-8f7a-1b2c3d4e5f60",
               "timestamp": "2026-07-22T14:03:11Z",
-              "schemaRef": "https://mitre.github.io/hdf-libs/schemas/hdf-requirement-change-event/v3.5.0",
+              "schemaRef": "https://mitre.github.io/hdf-libs/schemas/hdf-requirement-change-event/v3.7.0",
               "priorChecksum": {
                 "algorithm": "sha256",
                 "value": "704f62b2d0803438ad6b7b9bab45e2c4f350b7344135a2a7f8ef986d98669021"
               }
             },
             {
-              "$comment": "Chain-start envelope: first event for a key after seeding — priorChecksum is null (the CloudTrail null-previous-digest convention), sequence starts low.",
               "eventId": "0190f6f2-2a5b-7e4d-b1c8-4f2e6a8b0d12",
               "source": "inspec://web01/rhel9-stig",
               "sequence": 1,
@@ -5542,7 +5572,7 @@
           ],
           "properties": {
             "effectiveStatus": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.5.0#/$defs/Result_Status",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.7.0#/$defs/Result_Status",
               "description": "The resolved effective compliance status at this point in the chain."
             },
             "effectiveImpact": {
@@ -5552,14 +5582,13 @@
               "description": "The resolved effective impact score (0.0–1.0) at this point in the chain."
             }
           },
+          "$comment": "Examples, in order: 1) Prior posture of a failing SSH-cipher control before remediation; 2) Prior posture of a control passing under a waiver (the projection carries the resolved status; the governing override type travels in the requirement payload, not here).",
           "examples": [
             {
-              "$comment": "Prior posture of a failing SSH-cipher control before remediation.",
               "effectiveStatus": "failed",
               "effectiveImpact": 0.5
             },
             {
-              "$comment": "Prior posture of a control passing under a waiver (the projection carries the resolved status; the governing override type travels in the requirement payload, not here).",
               "effectiveStatus": "passed",
               "effectiveImpact": 0.5
             }
@@ -5592,7 +5621,7 @@
                   "description": "URI to the seed snapshot document (relative path or absolute URL)."
                 },
                 "checksum": {
-                  "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.5.0#/$defs/Checksum",
+                  "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.7.0#/$defs/Checksum",
                   "description": "Checksum of the seed snapshot, REQUIRED: the derivation pins an immutable snapshot by content, not just location."
                 }
               },
@@ -5620,9 +5649,9 @@
               "description": "The posture-as-of time of this reconciled view (RFC 3339, trimmed UTC) — the analog of PROV's generatedAtTime."
             }
           },
+          "$comment": "Examples, in order: 1) A reconciled result set: reassembled from the pinned seed scan plus 3 change events through watermark 414. The document's generator names the reconciler, never the scanner.",
           "examples": [
             {
-              "$comment": "A reconciled result set: reassembled from the pinned seed scan plus 3 change events through watermark 414. The document's generator names the reconciler, never the scanner.",
               "seed": {
                 "uri": "apptier-seed-scan.hdf.json",
                 "checksum": {
@@ -5641,9 +5670,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/parameter/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/parameter/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/parameter/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/parameter/v3.7.0",
       "title": "HDF Parameter Primitives",
       "description": "Input/parameter type definitions for typed, traceable configuration values that bridge governance prose and scanner automation.",
       "$defs": {
@@ -5774,9 +5803,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/epss/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/epss/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/epss/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/epss/v3.7.0",
       "title": "HDF EPSS Primitive",
       "description": "Type for representing FIRST.org's Exploit Prediction Scoring System (EPSS) data for a vulnerability. EPSS estimates the probability that a CVE will be exploited in the wild in the next 30 days. See https://www.first.org/epss/ for the underlying model and methodology.",
       "$defs": {
@@ -5808,21 +5837,19 @@
               "description": "ISO 8601 date (YYYY-MM-DD) on which FIRST.org published this EPSS score."
             }
           },
+          "$comment": "Examples, in order: 1) High exploit probability and high percentile, characteristic of a widely-exploited vulnerability like Log4Shell (CVE-2021-44228) shortly after disclosure; 2) Low score but moderate percentile, the common case for CVEs that have some observed exploitation evidence but are not under active mass exploitation; 3) Very low score, typical of a CVE with no known exploitation activity or proof-of-concept availability.",
           "examples": [
             {
-              "$comment": "High exploit probability and high percentile, characteristic of a widely-exploited vulnerability like Log4Shell (CVE-2021-44228) shortly after disclosure.",
               "score": 0.97532,
               "percentile": 0.99987,
               "date": "2026-05-26"
             },
             {
-              "$comment": "Low score but moderate percentile, the common case for CVEs that have some observed exploitation evidence but are not under active mass exploitation.",
               "score": 0.04521,
               "percentile": 0.78432,
               "date": "2026-05-26"
             },
             {
-              "$comment": "Very low score, typical of a CVE with no known exploitation activity or proof-of-concept availability.",
               "score": 0.00042,
               "percentile": 0.10215,
               "date": "2026-05-26"
@@ -5833,9 +5860,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/kev/v3.5.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/kev/v3.7.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/kev/v3.5.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/kev/v3.7.0",
       "title": "HDF Kev Primitives",
       "description": "Types for representing CISA Known Exploited Vulnerabilities (KEV) catalog membership. The KEV catalog (https://www.cisa.gov/known-exploited-vulnerabilities-catalog) flags CVEs that are confirmed actively exploited in the wild and drives federal patching urgency under CISA Binding Operational Directive 22-01.",
       "$defs": {
@@ -5881,23 +5908,21 @@
               "description": "CISA's notes describing the vulnerability, observed exploitation, or remediation guidance."
             }
           },
+          "$comment": "Examples, in order: 1) High-urgency case: recently added KEV entry with a short federal patching deadline; 2) Older KEV entry whose due date has already passed — useful for reporting overdue remediation; 3) Vulnerability evaluated against the KEV catalog and confirmed not present — dateAdded/dueDate are not required when inKev is false.",
           "examples": [
             {
-              "$comment": "High-urgency case: recently added KEV entry with a short federal patching deadline.",
               "inKev": true,
               "dateAdded": "2026-03-15",
               "dueDate": "2026-04-05",
               "notes": "Active ransomware exploitation observed; apply vendor patch immediately."
             },
             {
-              "$comment": "Older KEV entry whose due date has already passed — useful for reporting overdue remediation.",
               "inKev": true,
               "dateAdded": "2023-11-07",
               "dueDate": "2023-11-28",
               "notes": "Apply mitigations per vendor instructions or discontinue use of the product if mitigations are unavailable."
             },
             {
-              "$comment": "Vulnerability evaluated against the KEV catalog and confirmed not present — dateAdded/dueDate are not required when inKev is false.",
               "inKev": false
             }
           ],