@mitre/hdf-schema 2.0.0 → 3.0.1

package/README.md

@@ -138,6 +138,18 @@ pnpm build:schemas
 pnpm build:types
 ```
 
-## Schema Version
+## Versioning
 
-This package uses **JSON Schema draft/2020-12**.
+This package has two version numbers that serve different purposes:
+
+- **Package version** (`package.json` `version`): Follows npm semver. Bumped on every release — bug fixes, new helpers, type generation improvements, dependency updates. This is what consumers see in `npm install @mitre/hdf-schema@3.0.1`.
+
+- **Schema version** (`$id` URL in each `.schema.json`): Identifies the schema structure itself. Only changes when the schema structure changes — new fields, removed fields, type changes, constraint changes. Example: `https://mitre.github.io/hdf-libs/schemas/hdf-results/v3.0.0`.
+
+These versions are aligned at major boundaries (both are 3.x to signal this is the successor to the heimdall2 v2.x ecosystem) but can diverge at minor/patch levels. A package patch release (e.g., 3.0.1 → 3.0.2) that only fixes a converter bug or updates a helper function does not change the schema `$id`. A schema structural change (e.g., adding a new required field) bumps the schema version in the `$id` URL regardless of where the package version stands.
+
+The `$id` URLs are also the canonical hosted location for each schema: `https://mitre.github.io/hdf-libs/schemas/`.
+
+### JSON Schema dialect
+
+All schemas use **JSON Schema draft/2020-12**.

package/dist/helpers.js

@@ -142,50 +142,10 @@ export function createSourceLocation(ref, line) {
   return { ref, line };
 }
 
-/**
- * Map a severity string to an impact score.
- *
- * Impact bands align with CVSS 3.x severity ratings normalized to 0-1:
- *   critical=0.9 (CVSS 9.0), high=0.7 (CVSS 7.0), medium=0.5 (CVSS 5.0),
- *   low=0.3 (CVSS 3.0), informational=0.0 (CVSS 0.0)
- *
- * Each value is the floor of its band, preserving sub-band precision:
- *   0.9-1.0=critical, 0.7-0.8=high, 0.4-0.6=medium, 0.1-0.3=low, 0.0=informational
- *
- * @param {string} severity - Severity level
- * @returns {number} Impact score between 0.0 and 1.0
- */
-export function severityToImpact(severity) {
-  const normalized = severity.toLowerCase();
-  switch (normalized) {
-    case 'critical':
-      return 0.9;
-    case 'high':
-      return 0.7;
-    case 'medium':
-      return 0.5;
-    case 'low':
-      return 0.3;
-    case 'informational':
-    case 'info':
-      return 0.0;
-    default:
-      return 0.5;
-  }
-}
-
-/**
- * Map an impact score to a severity string
- * @param {number} impact - Impact score (0.0 to 1.0)
- * @returns {string} Severity level
- */
-export function impactToSeverity(impact) {
-  if (impact >= 0.9) return 'critical';
-  if (impact >= 0.7) return 'high';
-  if (impact >= 0.4) return 'medium';
-  if (impact > 0.0) return 'low';
-  return 'informational';
-}
+// Re-export severity mapping from @mitre/hdf-utilities (canonical location).
+// Kept here for backwards compatibility — consumers importing from
+// @mitre/hdf-schema/helpers still get these functions.
+export { severityToImpact, impactToSeverity } from '@mitre/hdf-utilities';
 
 /**
  * Compute the effective status of a requirement from its results and impact.

package/dist/index.d.ts

@@ -15,14 +15,14 @@ export type { HdfBaseline, BaselineRequirement } from './ts/hdf-baseline.js';
 // No export * from hdf-comparison — shared types duplicate hdf-results.
 export type {
   HdfComparison, RequirementDiff, ComparisonSummary, Source,
-  Annotation, BaselineDiff, BaselineRef, FieldChange, MatchingConfig,
-  ScannerConflict, SeverityBreakdown, StateCounts, PerSourceSummary,
-  DescriptionElement, Value,
+  Annotation, BaselineDiff, BaselineRef, ComponentDiff, FieldChange, MatchingConfig,
+  PackageDiff, ScannerConflict, SeverityBreakdown, StateCounts, PerSourceSummary,
+  Value,
 } from './ts/hdf-comparison.js';
 export {
-  AnnotationCategory, CapturedByType, ChangeReason, ComparisonMode,
+  AnnotationCategory, BaselineDiffState, ChangeReason, ComparisonMode,
   ConflictResolution, FormatVersion, MatchStrategy, Op, OriginalFormat,
-  RequirementState, SourceRole, State, TypeEnum,
+  PackageDiffState, RequirementState, SourceRole, Type,
 } from './ts/hdf-comparison.js';
 
 // Re-export system types
@@ -43,12 +43,10 @@ export {
 } from './ts/hdf-plan.js';
 
 // Re-export amendments types
+// No OverrideType enum — already exported by hdf-results via export *.
 export type {
   HdfAmendments, StandaloneOverride,
 } from './ts/hdf-amendments.js';
-export {
-  OverrideType,
-} from './ts/hdf-amendments.js';
 
 // Re-export evidence-package types
 export type {

package/dist/index.js

@@ -8,9 +8,9 @@ export * from './ts/hdf-results.js';
 
 // Re-export comparison-specific enums (runtime values not in hdf-results)
 export {
-  AnnotationCategory, CapturedByType, ChangeReason, ComparisonMode,
+  AnnotationCategory, BaselineDiffState, ChangeReason, ComparisonMode,
   ConflictResolution, FormatVersion, MatchStrategy, Op, OriginalFormat,
-  RequirementState, SourceRole, State, TypeEnum,
+  PackageDiffState, RequirementState, SourceRole, Type,
 } from './ts/hdf-comparison.js';
 
 // Re-export system enums (runtime values)
@@ -23,10 +23,7 @@ export {
   PlanType,
 } from './ts/hdf-plan.js';
 
-// Re-export amendments enums (runtime values)
-export {
-  OverrideType,
-} from './ts/hdf-amendments.js';
+// No amendments enum re-export — OverrideType already from hdf-results via export *.
 
 // Re-export evidence-package enums (runtime values)
 export {

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://mitre.github.io/hdf-libs/schemas/hdf-amendments/v2.0.0",
+  "$id": "https://mitre.github.io/hdf-libs/schemas/hdf-amendments/v3.0.0",
   "title": "HDF Amendments",
   "description": "Waivers, attestations, exceptions, and POA&Ms that modify requirement compliance status. Amendments are standalone documents that can be applied to results via merge operations.",
   "type": "object",
@@ -29,18 +29,18 @@
       "description": "URI to the hdf-system document these amendments apply to."
     },
     "appliedBy": {
-      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Identity",
+      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Identity",
       "description": "Default identity of who created this amendments document. Individual overrides may specify their own appliedBy."
     },
     "approvedBy": {
-      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Identity",
+      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Identity",
       "description": "Identity of the authorizing official who approved these amendments."
     },
     "overrides": {
       "type": "array",
       "minItems": 1,
       "items": {
-        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v2.0.0#/$defs/Standalone_Override"
+        "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.0.0#/$defs/Standalone_Override"
       },
       "description": "The set of amendments (waivers, attestations, exceptions, POA&Ms)."
     },
@@ -52,11 +52,11 @@
       "description": "Optional key-value labels for grouping and querying amendments."
     },
     "integrity": {
-      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v2.0.0#/$defs/Integrity",
+      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.0.0#/$defs/Integrity",
       "description": "Cryptographic integrity information for verifying this amendments document has not been tampered with."
     },
     "signature": {
-      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Signature",
+      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Signature",
       "description": "Document-level digital signature covering all amendments."
     },
     "version": {
@@ -64,7 +64,7 @@
       "description": "Version of this amendments document."
     },
     "generator": {
-      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v2.0.0#/$defs/Generator",
+      "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.0.0#/$defs/Generator",
       "description": "Information about the tool that generated this document."
     }
   },
@@ -101,9 +101,9 @@
     }
   ],
   "$defs": {
-    "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0",
       "title": "HDF Common Primitives",
       "description": "Shared building blocks used by hdf-results and hdf-baseline schemas.",
       "$defs": {
@@ -919,9 +919,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v2.0.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.0.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v2.0.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.0.0",
       "title": "HDF Amendment Primitives",
       "description": "Types for waivers, attestations, exceptions, and POA&Ms that modify requirement compliance status.",
       "$defs": {
@@ -963,7 +963,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/v2.0.0#/$defs/Result_Status",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.0.0#/$defs/Result_Status",
               "description": "The new status this amendment sets. For POA&Ms, this is the current status (POA&Ms track work, they don't change status)."
             },
             "reason": {
@@ -971,7 +971,7 @@
               "description": "Justification for this amendment."
             },
             "appliedBy": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Identity",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Identity",
               "description": "Identity of who applied this amendment."
             },
             "appliedAt": {
@@ -987,22 +987,22 @@
             "evidence": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Evidence"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Evidence"
               },
               "description": "Supporting evidence (screenshots, logs, URLs, documents)."
             },
             "signature": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Signature",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Signature",
               "description": "Digital signature for non-repudiation."
             },
             "previousChecksum": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Checksum",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Checksum",
               "description": "Checksum of the prior amendment in the chain. Creates a tamper-evident linked list. Null for the first amendment."
             },
             "milestones": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Milestone"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Milestone"
               },
               "description": "Remediation milestones (primarily for POA&M type amendments)."
             },
@@ -1083,9 +1083,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/result/v2.0.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.0.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v2.0.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.0.0",
       "title": "HDF Result Primitives",
       "description": "Types for representing assessment results and statuses.",
       "$defs": {
@@ -1216,9 +1216,9 @@
         }
       }
     },
-    "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v2.0.0": {
+    "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.0.0": {
       "$schema": "https://json-schema.org/draft/2020-12/schema",
-      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v2.0.0",
+      "$id": "https://mitre.github.io/hdf-libs/schemas/primitives/extensions/v3.0.0",
       "title": "HDF Extension Primitives",
       "description": "Extension types for waivers, attestations, generators, and integrity.",
       "$defs": {
@@ -1235,11 +1235,11 @@
           ],
           "properties": {
             "type": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v2.0.0#/$defs/Override_Type",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/amendments/v3.0.0#/$defs/Override_Type",
               "description": "The type of status override applied to this requirement."
             },
             "status": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v2.0.0#/$defs/Result_Status",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/result/v3.0.0#/$defs/Result_Status",
               "description": "The new status this override sets for the requirement. This intentionally changes the compliance status."
             },
             "reason": {
@@ -1247,7 +1247,7 @@
               "description": "Explanation for why this status override was applied."
             },
             "appliedBy": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Identity",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Identity",
               "description": "Identity of who applied this status override. For simple cases, use type 'simple' with just an identifier."
             },
             "appliedAt": {
@@ -1261,18 +1261,18 @@
               "description": "Timestamp when this status override expires and must be reviewed/renewed. REQUIRED - no permanent status overrides allowed. ISO 8601 format."
             },
             "signature": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Signature",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.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/v2.0.0#/$defs/Evidence"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Evidence"
               },
               "description": "Supporting evidence for this status override, such as screenshots demonstrating manual verification for attestations."
             },
             "previousChecksum": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Checksum",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Checksum",
               "description": "SHA-256 checksum of the previous amendment in chronological order. Creates a tamper-evident chain of amendments (similar to blockchain). Null for the first amendment on a requirement."
             }
           },
@@ -1342,7 +1342,7 @@
               "description": "Detailed explanation of the plan, including what actions will be taken."
             },
             "appliedBy": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Identity",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Identity",
               "description": "Identity of who created this POA&M. For simple cases, use type 'simple' with just an identifier."
             },
             "appliedAt": {
@@ -1358,23 +1358,23 @@
             "milestones": {
               "type": "array",
               "items": {
-                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Milestone"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Milestone"
               },
               "description": "Optional array of milestones tracking progress toward completion."
             },
             "signature": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Signature",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.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/v2.0.0#/$defs/Evidence"
+                "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.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/v2.0.0#/$defs/Checksum",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Checksum",
               "description": "SHA-256 checksum of the previous amendment in chronological order. Creates a tamper-evident chain of amendments (similar to blockchain). Null for the first amendment on a requirement."
             }
           },
@@ -1525,7 +1525,7 @@
           },
           "properties": {
             "algorithm": {
-              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v2.0.0#/$defs/Hash_Algorithm",
+              "$ref": "https://mitre.github.io/hdf-libs/schemas/primitives/common/v3.0.0#/$defs/Hash_Algorithm",
               "description": "The hash algorithm used for the checksum."
             },
             "checksum": {