@mitre/hdf-openapi 3.8.0-next.42532249979.1 → 3.8.0-next.42533588944.1

package/dist/hdf-components.oas.json

@@ -40,10 +40,6 @@
             "type": "string",
             "description": "The name of the parent baseline if this is a dependency of another."
           },
-          "description": {
-            "type": "string",
-            "description": "The description - should be more detailed than the summary."
-          },
           "integrity": {
             "$ref": "#/components/schemas/Integrity",
             "description": "Cryptographic integrity information for verifying this baseline has not been tampered with."
@@ -54,7 +50,7 @@
           },
           "resultsChecksum": {
             "$ref": "#/components/schemas/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."
+            "description": "SHA-256 checksum of the raw results before any amendments (statusOverrides or POAMs). Used to detect tampering with test results. Amendment integrity is checked against the document-level preAmendmentChecksum at the root, not this per-baseline value: hdf amend apply writes it as the hash of the raw document bytes immediately before the most recent amendment application, one step back only."
           },
           "statusMessage": {
             "type": "string",
@@ -426,7 +422,6 @@
             "statusOverrides": [
               {
                 "type": "operationalRequirement",
-                "status": "failed",
                 "reason": "Air-gapped system requires USB transfer for classified data ingestion per operational procedure OP-2026-003. Compensating controls: USB ports are physically secured, all transfers are logged and require two-person integrity.",
                 "appliedBy": {
                   "type": "email",
@@ -493,6 +488,19 @@
         "description": "A requirement that has been evaluated, including any findings.",
         "title": "Evaluated Requirement"
       },
+      "External_Reference_Encoding": {
+        "type": "string",
+        "enum": [
+          "utf-8",
+          "base64"
+        ],
+        "description": "How an embedded copy's bytes are read back: 'utf-8' for text, 'base64' for anything that is not valid UTF-8 text.",
+        "title": "External Reference Encoding",
+        "examples": [
+          "base64"
+        ],
+        "$comment": "Examples, in order: 1) a binary artifact, embedded base64-encoded."
+      },
       "External_Reference": {
         "type": "object",
         "title": "External Reference",
@@ -608,12 +616,7 @@
             "description": "Optional lossless embedded copy of the artifact's bytes as a string, for artifacts `document` cannot hold: XML, CSV, NDJSON, plain text, a JSON array, or bytes that are not valid UTF-8 text at all.\n\n`encoding` states how to read it back and is required alongside it. Set `mediaType` so a consumer knows what the bytes are, and `checksum` so the copy can be verified against the source.\n\nCarried verbatim — never reformatted, re-indented, or re-serialized."
           },
           "encoding": {
-            "type": "string",
-            "title": "External Reference Encoding",
-            "enum": [
-              "utf-8",
-              "base64"
-            ],
+            "$ref": "#/components/schemas/External_Reference_Encoding",
             "description": "How to read `content` back into the artifact's bytes. 'utf-8' for text (XML, CSV, NDJSON, plain text, JavaScript-wrapped JSON); 'base64' for anything that is not valid UTF-8 text.\n\nRequired whenever `content` is present, and meaningless without it — an embedded copy whose encoding a consumer has to guess is not lossless."
           }
         },
@@ -697,7 +700,7 @@
           "sha512",
           "blake3"
         ],
-        "description": "Cryptographic hash algorithms a checksum or integrity record may name. blake3 covers container-image and other artifact digests that use it. HDF tooling verifies every algorithm in this enum, so any of them may be recorded where the checksum needs to be verifiable.",
+        "description": "Cryptographic hash algorithms a checksum or integrity record may name. blake3 covers container-image and other artifact digests that use it. HDF tooling verifies every algorithm in this enum, so any of them may be recorded where the checksum needs to be verifiable. md5 and sha1 are excluded deliberately: a checksum or integrity record exists to detect tampering, and both are collision-broken, so a digest in either would look verifiable while proving nothing. A source tool digest in an excluded algorithm is not recorded as a checksum. Admitting weak hashes as an application-level accept/reject decision was considered and rejected; widening this enum is a schema decision, not an oversight.",
         "title": "Hash Algorithm"
       },
       "Requirement_Group": {
@@ -1399,6 +1402,10 @@
             "type": "string",
             "description": "The title - should be human readable."
           },
+          "description": {
+            "type": "string",
+            "description": "Prose description of the baseline, more detailed than summary. Carried verbatim, like every HDF prose field."
+          },
           "maintainer": {
             "type": "string",
             "description": "The maintainer(s)."
@@ -1477,7 +1484,7 @@
           },
           "id": {
             "type": "string",
-            "description": "The requirement identifier. Example: 'SV-238196'."
+            "description": "The requirement identifier, naming the requirement itself rather than one finding of it. Example: 'SV-238196'. Several entries in one baseline may legitimately carry the same id (one scanner reporting one CVE against several packages, or an overlay restating what it inherits), so an id is not an instance key: index requirements as id to list, never id to one, and an amendment addressing an id applies to every entry carrying it."
           },
           "title": {
             "type": "string",
@@ -2648,6 +2655,25 @@
           }
         ]
       },
+      "Modality": {
+        "type": [
+          "string",
+          "array"
+        ],
+        "items": {
+          "type": "string"
+        },
+        "description": "A content modality such as text, image, audio, tabular or timeseries: one string, or a list when the content spans several.",
+        "title": "Modality",
+        "examples": [
+          "text",
+          [
+            "text",
+            "image"
+          ]
+        ],
+        "$comment": "Examples, in order: 1) a single modality; 2) multimodal content listed in full."
+      },
       "AI_Model_Extension": {
         "type": "object",
         "additionalProperties": true,
@@ -2749,13 +2775,7 @@
                 "description": "Input/output data types. Examples: string, byte[], float32, image."
               },
               "modality": {
-                "type": [
-                  "string",
-                  "array"
-                ],
-                "items": {
-                  "type": "string"
-                },
+                "$ref": "#/components/schemas/Modality",
                 "description": "Input/output modalities. String or array of strings. Examples: text, image, audio. Symmetric with Dataset_Extension.modality."
               },
               "contextLength": {
@@ -2795,13 +2815,7 @@
             "description": "Free-text statement of the dataset's intended use (CISA/G7 minimum element)."
           },
           "modality": {
-            "type": [
-              "string",
-              "array"
-            ],
-            "items": {
-              "type": "string"
-            },
+            "$ref": "#/components/schemas/Modality",
             "description": "Content modality/kind of the data (CISA/G7 'Dataset content: modality'). Examples: text, image, tabular, timeseries, audio. DISTINCT from datasetFormat, which is the physical encoding (parquet/csv). Resolves SPDX 3.0 dataset_datasetType, which is content-kind, not physical format. String or array of strings."
           },
           "provenance": {
@@ -3233,16 +3247,71 @@
           "appliedAt",
           "expiresAt"
         ],
-        "anyOf": [
+        "allOf": [
           {
-            "required": [
-              "status"
-            ]
+            "if": {
+              "properties": {
+                "type": {
+                  "enum": [
+                    "operationalRequirement"
+                  ]
+                }
+              },
+              "required": [
+                "type"
+              ]
+            },
+            "then": {
+              "not": {
+                "anyOf": [
+                  {
+                    "required": [
+                      "status"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "impact"
+                    ]
+                  }
+                ]
+              }
+            },
+            "else": {
+              "anyOf": [
+                {
+                  "required": [
+                    "status"
+                  ]
+                },
+                {
+                  "required": [
+                    "impact"
+                  ]
+                }
+              ]
+            }
           },
           {
-            "required": [
-              "impact"
-            ]
+            "if": {
+              "properties": {
+                "type": {
+                  "enum": [
+                    "riskAdjustment"
+                  ]
+                }
+              },
+              "required": [
+                "type"
+              ]
+            },
+            "then": {
+              "not": {
+                "required": [
+                  "status"
+                ]
+              }
+            }
           }
         ],
         "properties": {
@@ -3259,11 +3328,11 @@
           },
           "status": {
             "$ref": "#/components/schemas/Result_Status",
-            "description": "The new status this override sets for the requirement. Optional when only impact is being overridden."
+            "description": "The new status this override sets for the requirement. Optional when only impact is being overridden; forbidden on an operationalRequirement, which adjudicates nothing, and on a riskAdjustment, which re-rates impact only."
           },
           "impact": {
             "$ref": "#/components/schemas/Impact_Override",
-            "description": "Override to the requirement's impact score. At least one of status or impact must be set."
+            "description": "Override to the requirement's impact score. For every type except operationalRequirement, at least one of status or impact must be set; an operationalRequirement carries neither."
           },
           "reason": {
             "type": "string",
@@ -3308,7 +3377,7 @@
             "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.",
+        "$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. Example 7: operationalRequirement as it sits on the requirement after apply: no status, no impact; the finding stays failed and disposition reports operationalRequirement.",
         "examples": [
           {
             "type": "waiver",
@@ -3408,9 +3477,19 @@
                 }
               }
             ]
+          },
+          {
+            "type": "operationalRequirement",
+            "reason": "Air-gapped ingest requires USB transfer per operational procedure OP-2026-003. Ports are physically secured, transfers are logged and need two-person integrity.",
+            "appliedBy": {
+              "type": "email",
+              "identifier": "system-owner@agency.gov"
+            },
+            "appliedAt": "2026-01-20T10:00:00Z",
+            "expiresAt": "2099-12-31T00:00:00Z"
           }
         ],
-        "description": "An intentional change to a requirement's compliance status and/or impact score. At least one of status or impact must be set. Overrides change the effectiveStatus or impact of the requirement. All overrides must have an expiration date to enforce periodic review.",
+        "description": "An intentional change to a requirement's compliance status and/or impact score, as it sits on the requirement once applied. The same type-conditional rule as Standalone_Override: when type is 'operationalRequirement', neither status nor impact may be set, because the override records an accepted deviation without adjudicating the finding; it still governs disposition, and effectiveStatus stays what the results decided. When type is 'riskAdjustment', status may not be set: it re-rates the risk through impact and never changes pass/fail. For every other type, at least one of status or impact must be set. All overrides must have an expiration date to enforce periodic review.",
         "title": "Status Override"
       },
       "POAM": {
@@ -3685,7 +3764,7 @@
           "riskAdjustment",
           "operationalRequirement"
         ],
-        "description": "The type of amendment, aligned with FedRAMP deviation request categories.\n\n- 'waiver': risk accepted by Authorizing Official.\n- 'attestation': manually verified by assessor.\n- 'poam': remediation tracked (no status change).\n- 'inherited': control provided by another component or system.\n- 'falsePositive': scanner incorrectly identified a finding — for compliance scans (STIG, CIS), the check actually passes, so status is typically set to 'passed'; for vulnerability scans (CVE, SCA), the flagged vulnerability does not apply to this system, so status is typically set to 'notApplicable'. The disposition field on the requirement distinguishes false positives from genuinely not-applicable findings.\n- 'riskAdjustment': impact score adjusted based on environmental context (FedRAMP Risk Adjustment); does not change pass/fail status, only impact via the impact field.\n- 'operationalRequirement': deviation required by operational constraints (FedRAMP Operational Requirement); the finding cannot be remediated because the system requires the affected functionality. Remains an open risk.\n\nMigration note: 'exception' was removed in v3.1.0 — use 'waiver' with status 'notApplicable' instead.",
+        "description": "The type of amendment, aligned with FedRAMP deviation request categories.\n\n- 'waiver': risk accepted by Authorizing Official.\n- 'attestation': manually verified by assessor.\n- 'poam': remediation tracked (no status change).\n- 'inherited': control provided by another component or system.\n- 'falsePositive': scanner incorrectly identified a finding — for compliance scans (STIG, CIS), the check actually passes, so status is typically set to 'passed'; for vulnerability scans (CVE, SCA), the flagged vulnerability does not apply to this system, so status is typically set to 'notApplicable'. The disposition field on the requirement distinguishes false positives from genuinely not-applicable findings.\n- 'riskAdjustment': impact score adjusted based on environmental context (FedRAMP Risk Adjustment); does not change pass/fail status, only impact via the impact field; a status on it is rejected by validation.\n- 'operationalRequirement': deviation required by operational constraints (FedRAMP Operational Requirement); the finding cannot be remediated because the system requires the affected functionality. Remains an open risk.\n\nMigration note: 'exception' was removed in v3.1.0 — use 'waiver' with status 'notApplicable' instead.",
         "title": "Override Type"
       },
       "Justification": {
@@ -3725,7 +3804,7 @@
       },
       "Standalone_Override": {
         "type": "object",
-        "description": "A standalone override to a requirement's compliance status or risk impact.\n\nValidation has two branches gated on 'type': when type is 'operationalRequirement', neither 'status' nor 'impact' may be set — the override records accepted risk without changing the finding (documentation-only). For all other types, at least one of 'status' or 'impact' must be set.\n\nThis rule aligns with:\n- OSCAL Assessment Results — finding.target.status and finding.associated-risk[].facet[] are separate axes (https://pages.nist.gov/OSCAL/learn/concepts/layer/assessment/assessment-results/)\n- FedRAMP deviation request types — Risk Adjustment changes impact only, Operational Requirement documents acceptance only, False Positive changes status (https://www.ignyteplatform.com/blog/fedramp/fedramp-deviation-requests-submit/)\n- NIST SP 800-37 RMF — risk response (accept/mitigate/transfer) is a separate step from control assessment status (https://csrc.nist.gov/pubs/sp/800/37/r2/final).",
+        "description": "A standalone override to a requirement's compliance status or risk impact.\n\nValidation is gated on 'type': when type is 'operationalRequirement', neither 'status' nor 'impact' may be set — the override records accepted risk without changing the finding (documentation-only). When type is 'riskAdjustment', 'status' may not be set — it re-rates the risk through 'impact' and never changes the finding's pass/fail; an override that must change status is a waiver or falsePositive. For all other types, at least one of 'status' or 'impact' must be set.\n\nThis rule aligns with:\n- OSCAL Assessment Results — finding.target.status and finding.associated-risk[].facet[] are separate axes (https://pages.nist.gov/OSCAL/learn/concepts/layer/assessment/assessment-results/)\n- FedRAMP deviation request types — Risk Adjustment changes impact only, Operational Requirement documents acceptance only, False Positive changes status (https://www.ignyteplatform.com/blog/fedramp/fedramp-deviation-requests-submit/)\n- NIST SP 800-37 RMF — risk response (accept/mitigate/transfer) is a separate step from control assessment status (https://csrc.nist.gov/pubs/sp/800/37/r2/final).",
         "unevaluatedProperties": false,
         "required": [
           "type",
@@ -3735,48 +3814,73 @@
           "appliedAt",
           "expiresAt"
         ],
-        "if": {
-          "properties": {
-            "type": {
-              "enum": [
-                "operationalRequirement"
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "type": {
+                  "enum": [
+                    "operationalRequirement"
+                  ]
+                }
+              },
+              "required": [
+                "type"
+              ]
+            },
+            "then": {
+              "not": {
+                "anyOf": [
+                  {
+                    "required": [
+                      "status"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "impact"
+                    ]
+                  }
+                ]
+              }
+            },
+            "else": {
+              "anyOf": [
+                {
+                  "required": [
+                    "status"
+                  ]
+                },
+                {
+                  "required": [
+                    "impact"
+                  ]
+                }
               ]
             }
           },
-          "required": [
-            "type"
-          ]
-        },
-        "then": {
-          "not": {
-            "anyOf": [
-              {
-                "required": [
-                  "status"
-                ]
+          {
+            "if": {
+              "properties": {
+                "type": {
+                  "enum": [
+                    "riskAdjustment"
+                  ]
+                }
               },
-              {
-                "required": [
-                  "impact"
-                ]
-              }
-            ]
-          }
-        },
-        "else": {
-          "anyOf": [
-            {
               "required": [
-                "status"
+                "type"
               ]
             },
-            {
-              "required": [
-                "impact"
-              ]
+            "then": {
+              "not": {
+                "required": [
+                  "status"
+                ]
+              }
             }
-          ]
-        },
+          }
+        ],
         "properties": {
           "externalReferences": {
             "type": "array",
@@ -3792,7 +3896,7 @@
           "requirementId": {
             "type": "string",
             "minLength": 1,
-            "description": "The ID of the requirement being amended. Must match a requirement ID in the referenced baseline."
+            "description": "The id of the requirement being amended. An id names the requirement, not one finding, so the override applies to every requirement entry carrying that id in the baseline(s) it targets."
           },
           "baselineRef": {
             "type": "string",
@@ -3800,7 +3904,7 @@
           },
           "status": {
             "$ref": "#/components/schemas/Result_Status",
-            "description": "The new status this amendment sets. Optional when only impact is being overridden."
+            "description": "The new status this override sets for the requirement. Optional when only impact is being overridden; forbidden on an operationalRequirement, which adjudicates nothing, and on a riskAdjustment, which re-rates impact only."
           },
           "impact": {
             "$ref": "#/components/schemas/Impact_Override",
@@ -4108,11 +4212,7 @@
             "description": "The source tool's own record for this result, carrying every field the record had.\n\nCOMPLETE, NOT NECESSARILY BYTE-EXACT. A producer SHOULD write the record's bytes unchanged where it can. A producer that cannot — notably one implemented in two languages whose JSON serializers disagree on key order, HTML escaping and number rendering, and which therefore MUST canonicalize to stay byte-identical with its twin — MAY write a canonically serialized form instead. Such a form preserves every field and value but not the original key order, insignificant whitespace, or duplicate keys. A consumer MUST therefore compare records by parsing them, not by comparing bytes, and MUST NOT checksum this field and expect the result to match a checksum of the input.\n\nFor carriage that IS byte-exact, use `extensions.rawSourceArtifacts[]`, which forbids a parsed `document` precisely so the bytes and their checksum survive; `pointer` ties this record to its position within that artifact."
           },
           "encoding": {
-            "type": "string",
-            "enum": [
-              "utf-8",
-              "base64"
-            ],
+            "$ref": "#/components/schemas/External_Reference_Encoding",
             "description": "How to read `content`: 'utf-8' for text, 'base64' for bytes that are not valid UTF-8 text."
           },
           "mediaType": {
@@ -4832,7 +4932,8 @@
           },
           "allowedValues": {
             "type": "array",
-            "description": "Enumeration of permitted values."
+            "items": true,
+            "description": "Enumeration of permitted values. Each entry may be any JSON value, the same freedom Input.value has: an Array or Hash input enumerates container values, so no element type is imposed."
           }
         },
         "description": "Validation constraints for an input value.",
@@ -5467,7 +5568,7 @@
           "total": {
             "type": "integer",
             "minimum": 0,
-            "description": "Total number of unique requirements across all sources."
+            "description": "Total number of distinct requirement ids across all sources; an id carried by several entries counts once."
           },
           "matchedCount": {
             "type": "integer",
@@ -5552,6 +5653,21 @@
         "description": "Summary statistics for the overall comparison.",
         "title": "Comparison Summary"
       },
+      "Baseline_Diff_State": {
+        "type": "string",
+        "enum": [
+          "new",
+          "absent",
+          "unchanged",
+          "updated"
+        ],
+        "description": "How a baseline or component fared across the compared documents: new (only in the newer), absent (only in the older), unchanged, or updated (present in both with a changed version).",
+        "title": "Baseline Diff State",
+        "examples": [
+          "updated"
+        ],
+        "$comment": "Examples, in order: 1) a baseline present in both documents whose version moved."
+      },
       "Baseline_Diff": {
         "type": "object",
         "unevaluatedProperties": false,
@@ -5565,14 +5681,7 @@
             "description": "Name of the baseline being compared."
           },
           "state": {
-            "type": "string",
-            "title": "Baseline Diff State",
-            "enum": [
-              "new",
-              "absent",
-              "unchanged",
-              "updated"
-            ],
+            "$ref": "#/components/schemas/Baseline_Diff_State",
             "description": "The state of this baseline in the comparison."
           },
           "oldVersion": {
@@ -5604,14 +5713,7 @@
             "description": "Component name used for matching across system versions."
           },
           "state": {
-            "type": "string",
-            "title": "Baseline Diff State",
-            "enum": [
-              "new",
-              "absent",
-              "unchanged",
-              "updated"
-            ],
+            "$ref": "#/components/schemas/Baseline_Diff_State",
             "description": "The state of this component in the comparison."
           },
           "before": {
@@ -5871,6 +5973,10 @@
             "type": "string",
             "description": "The requirement title for human readability."
           },
+          "baseline": {
+            "type": "string",
+            "description": "Name of the baseline the requirement belongs to, so a consumer can group diffs the way hdf diff --group-by baseline does. '(multiple)' when the id appears in more than one baseline of the same document."
+          },
           "oldEffectiveStatus": {
             "type": "string",
             "description": "The effective status of the requirement in the old source."
@@ -5936,7 +6042,79 @@
           }
         },
         "description": "A comparison of a single requirement between sources, including state, changes, and full before/after snapshots.",
-        "title": "Requirement Diff"
+        "title": "Requirement Diff",
+        "examples": [
+          {
+            "id": "SV-257777",
+            "baseline": "rhel9-stig-baseline",
+            "title": "RHEL 9 must prevent the loading of the USB storage kernel module.",
+            "state": "fixed",
+            "changeReasons": [
+              "resultChanged"
+            ],
+            "before": {
+              "id": "SV-257777",
+              "title": "RHEL 9 must prevent the loading of the USB storage kernel module.",
+              "impact": 0.5,
+              "tags": {
+                "nist": [
+                  "CM-7"
+                ]
+              },
+              "sourceLocation": {},
+              "descriptions": [
+                {
+                  "label": "default",
+                  "data": "USB mass storage must be disabled unless an operational need is documented."
+                }
+              ],
+              "results": [
+                {
+                  "status": "failed",
+                  "codeDesc": "Kernel module usb-storage is loadable",
+                  "startTime": "2026-03-01T10:00:00Z"
+                }
+              ]
+            },
+            "after": {
+              "id": "SV-257777",
+              "title": "RHEL 9 must prevent the loading of the USB storage kernel module.",
+              "impact": 0.5,
+              "tags": {
+                "nist": [
+                  "CM-7"
+                ]
+              },
+              "sourceLocation": {},
+              "descriptions": [
+                {
+                  "label": "default",
+                  "data": "USB mass storage must be disabled unless an operational need is documented."
+                }
+              ],
+              "results": [
+                {
+                  "status": "passed",
+                  "codeDesc": "Kernel module usb-storage is blacklisted",
+                  "startTime": "2026-03-30T10:00:00Z"
+                }
+              ]
+            },
+            "oldEffectiveStatus": "failed",
+            "newEffectiveStatus": "passed",
+            "fieldChanges": [
+              {
+                "op": "replace",
+                "path": "/results/0/status",
+                "oldValue": "failed",
+                "newValue": "passed"
+              }
+            ],
+            "matchStrategy": "exactId",
+            "matchConfidence": 1
+          }
+        ],
+        "$comment": "Examples, in order: 1) a requirement fixed between two scans of the same baseline, carrying the owning baseline name and the exact-id match that paired it."
       },
       "Cross_System_Reference": {
         "type": "object",
@@ -6713,6 +6891,7 @@
           {
             "name": "ubuntu-2204-stig-baseline",
             "title": "Canonical Ubuntu 22.04 LTS STIG Baseline",
+            "description": "Requirements from the DISA STIG for Canonical Ubuntu 22.04 LTS, tailored for hosts in the CUI enclave; checks that need a graphical session are marked not applicable.",
             "version": "1.2.0",
             "maintainer": "DISA STIG Team",
             "license": "Apache-2.0",