@mitre/hdf-schema 3.7.2-rc.2 → 3.8.0-next.42532249979.1

package/README.md

@@ -189,6 +189,15 @@ All schemas use **JSON Schema draft/2020-12**.
 Interactive schema reference documentation is published at:
 **<https://mitre.github.io/hdf-libs/schemas/>**
 
+### What's new in v3.8.0
+
+- **`extensions` is now a closed object. BREAKING.** Its only members are `passthrough` and `rawSourceArtifacts`; any other key is invalid. Producer data HDF does not model goes inside `passthrough`, which stays deliberately permissive. Typed consumers break at compile time rather than silently: `Extensions` becomes a struct in both languages, so `results.Extensions["key"]` becomes `results.Extensions.Passthrough["key"]`. Closure uses `additionalProperties: false` rather than the house `unevaluatedProperties: false`, because the shipped Go validator is a draft-07 engine that ignores the latter. A legacy document carrying a sibling such as `extensions.audit` is relocated into `passthrough` by the SAF-supplement normalizers; one that reaches validation untouched now fails.
+- **`extensions.rawSourceArtifacts[]` — the converter's input, carried as bytes.** An array of `External_Reference` entries, one per artifact a conversion consumed. `content` + `encoding` is the only embedding mode: `document` is refused here by the schema, because a parsed JSON object cannot hold the original whitespace, key order or duplicate keys, which would make the artifact unreconstructable and its checksum unverifiable. `mediaType` is required on any entry that embeds. An entry that only points at a location may omit all three. This is stricter than HDF v2, whose `passthrough.raw` held a parsed structure in every heimdall2 mapper but one.
+- **`results[].rawSourceRecord` — the source tool's own record for one result.** A closed object (`content`, `encoding`, `mediaType`, optional `pointer`) carrying the single input record that produced a result, scoped to the result because that is where the native record lives: one (vulnerability, package) pair is one result, so a CVE reported against two packages has two different records. `pointer` locates the record inside its artifact, which is what makes carriage verifiable rather than merely present.
+- **`External_Reference` gains `content` and `encoding`**, and its `anyOf` widens so an entry that only embeds is valid.
+- **Mutual-requirement rules are now enforced by the shipped validators. Tightening.** The `content`/`encoding` pair on `External_Reference` and the `algorithm`/`checksum` pair on `Integrity` were written with `dependentRequired`, a 2019-09 keyword that both shipped validators ignore — the Go one is draft-07, and `hdf-validators` builds a default Ajv — so neither rule was ever applied by `hdf validate`. Both are `if`/`then` pairs now. A document with `encoding` but no `content`, or `algorithm` but no `checksum`, previously validated and now does not.
+- **Compatibility.** The additive fields validate v3.7.x documents cleanly. The three breaking items are the `extensions` closure, the refusal of `document` on a raw-source entry, and the two newly-enforced mutual requirements.
+
 ### What's new in v3.7.0
 
 - **`Milestone.title` — optional single-line label.** A short label on each POA&M `Milestone`, suitable where a consumer needs a title (for example an OSCAL POA&M remediation or task). It is optional and does not replace `description`, which remains the full milestone text; a consumer needing a title where none is supplied derives one. The value carries the project's single-line-label constraint — `minLength: 1` plus a pattern (OSCAL's `StringDatatype`, spelled with explicit character classes so ECMA-262 and Go regexp engines agree) banning line breaks and leading/trailing whitespace.