Add canonical document-merge semantics to enable composition of multiple TARAs into a whole-vehicle TARA

[github-actions]

Motivation

OEMs and integrators must combine supplier- or subsystem-level TARAs into a single whole-vehicle TARA (ISO/SAE 21434 Clause 7/Clause 15 guidance and practical practice). RDX already targets "whole vehicle TARA" use cases (RDX-075) but does not specify a machine-readable, canonical merge/compose recipe or conflict-resolution rules. In practice, combining risk documents from many suppliers requires stable rules for namespacing, authoritative source selection, id collision handling (bomRef / BOM-Link), and how to represent upstream vs. integrated changes so that imports are deterministic and verifiable. CycloneDX provides BOM-Link for composing BOMs; RDX should adopt a complementary, explicit merge/compose model so tools can reliably build whole-vehicle riskSets from multiple RDX fragments and produce reproducible, auditable results.

Proposed change

1. Add a top-level optional composition object to the RDX document that declares how a document was produced (source fragments and merge recipe). Suggested JSON shape (extend spec/json/rdx.schema.json and XSD accordingly):

"composition": {
  "sources": [
    { "docRef": "urn:cdx:.../1", "role": "supplier", "authoritative": true, "checksum": "sha256:...", "created": "2026-07-01T12:00:00Z" }
  ],
  "mergeRecipe": {
    "strategy": "union|overlay|authoritative-first|latest-first",
    "namespacePrefixing": "auto|preserve|require",
    "conflictResolution": [
      { "path": "riskSet.controls[]:controlId", "rule": "authoritative|latestTimestamp|highestCAL|manual" }
    ],
    "generationTimestamp": "2026-07-10T15:00:00Z",
    "tool": { "name": "rdx-merge", "version": "0.3.0" }
  },
  "mergerSignature": { "alg": "RSASSA-PSS", "value": "...", "keyRef": "urn:cdx:..." }
}

2. Define available strategy values and exact semantics (minimum: union (union of objects, dedupe by id), overlay (apply later documents over earlier), authoritative-first (respect authoritative: true source flags), and latest-first (prefer higher created timestamp)). Add normative rules for id deduplication (ids colliding are namespaced or folded according to namespacePrefixing) and a required warning/diagnostic list in the merged output containing conflicts and how they were resolved.

3. Require a machine-readable mergeReport[] entry be produced in merged documents listing: source docRef, objects added, objects overridden (with before/after snapshots or bom-ref pointers), and any unresolved conflicts (must be human-reviewed). mergeReport must be checksumed and signable.

4. Provide canonical CycloneDX embedding guidance: when embedding in a CycloneDX BOM that references multiple supplier RDX fragments via BOM-Link, the composition object must record the referenced BOM-Link urns and chosen resolution strategy. Use the CycloneDX bomLink patterns for docRef values.

5. Add two small tooling deliverables to the repo: (a) tools/rdx-merge.py reference implementation demonstrating the merge strategies and producing mergeReport, and (b) unit tests/examples in examples/ showing merging 2–4 supplier TARAs into a whole-vehicle TARA.

Related RDX requirements (how this extends/relates):

• Relates to RDX-075 (Enable whole vehicle TARA by combining existing TARAs).
• Extends RDX-032 (documentId / riskSet top-level) by specifying composition metadata for multi-document assembly.
• Relates to RDX-099 / RDX-100 (CycloneDX integration / embedding) by using BOM-Link semantics.
• Relates to RDX-062 (unique IDs) — provides canonical rules when IDs collide.

New requirement introduced: RDX-200 (new requirement) — "RDX MUST define machine-readable composition/merge semantics and a mergeReport format to support deterministic composition of multiple RDX documents into a single whole-vehicle riskSet."

References

• CycloneDX BOM-Link and spec (bomLink usage and URN patterns). (CycloneDX docs).
  https://cyclonedx.org/docs/1.7/json/.
• Practical discussion of supplier evidence handover and whole-vehicle TARA composition (industry guidance). Uraeus: Tier-2 to Tier-1 to OEM Evidence Handover.
  https://uraeus.io/resources/tier2-tier1-oem-evidence-handover/
• ISO/SAE 21434 high-level requirement to support whole-vehicle TARA and supplier interface (informative context). (ISO/SAE 21434 commentary).
  https://legalclarity.org/iso-21434-certification-process-costs-and-timeline/ (informational)

Acceptance criteria

• Schema: spec/json/rdx.schema.json and spec/xml/rdx.xsd include the new optional composition and mergeReport structures with JSON Schema/XSD examples.
• Examples: Add at least two new examples under examples/ demonstrating (a) a supplier-A and supplier-B RDX documents and (b) a merged whole-vehicle RDX with composition and mergeReport fields. Examples must validate against both JSON Schema and XSD.
• Tools: Add tools/rdx-merge.py (reference merge implementation) and unit tests that exercise union, overlay, and authoritative-first strategies and confirm deterministic outputs (checksum matches expected fixtures).
• Documentation: Update methodology/UseCases.md and README to document merge semantics and recommended practices for suppliers/OEMs when publishing fragments (including how to set authoritative flags and stable documentId).
• CI: ./tools/validate.sh must validate new examples; merge tool tests must run in CI (or be runnable locally) and exit zero.
• Backwards compatibility: Existing RDX documents without composition must remain valid and unaffected; merge features are additive and optional.

---

Generated by tools/ai_idea_scout.py via the AI Idea Scout workflow.
Review the proposal, refine the title/body/labels, and close if not desired.