Add an optional top-level index + BOM-Link partial references for streaming / partial consumption

[github-actions]

Motivation

RDX documents embedded in CycloneDX BOMs or used as large standalone risk repositories can grow large (whole-vehicle TARAs, multiple CAL/TAF assessments, HBOM/SBOM cross-links). Tooling that needs only parts of a document (e.g., the itemDefinition or a single riskValue) would benefit from a machine-readable index to locate and optionally fetch or reference sub-documents without loading the entire payload. CycloneDX already supports BOM‑Link URIs and bom-ref identifiers for cross-file references; RDX should adopt an optional index/manifest pattern that is CycloneDX-friendly, supports BOM‑Link URIs, and enables partial updates/patches.

Related RDX requirements: RDX-032 (document structure), RDX-036/RDX-040 (CycloneDX embedding), RDX-099 (CycloneDX integration). Proposed new requirement: RDX-201 (optional index/manifest for partial consumption). (new requirement)

Proposed change

Add an optional top-level index object to the RDX schema with the following shape (JSON and XSD):

• indexVersion (string) — index format version (e.g., 1.0).
• entries (array of objects): each entry contains:
  • id (string) — the RDX object id (UUID or object id).
  • path (string) — JSON Pointer (RFC 6901) to the object inside the RDX document when co-located.
  • bomLink (string, optional) — CycloneDX BOM-Link URI (e.g., urn:cdx:...#bom-ref) or external URL where the referenced object or a separate RDX fragment lives.
  • mediaType (string, optional) — application/json / application/xml etc.
  • byteRange (object, optional) — { "start": <int>, "end": <int> } if the RDX transport encodes a byte-rangeable artifact (helps HTTP range fetches).
  • hash (object, optional) — { "alg": "SHA-256", "value": "..." } for integrity of the referenced fragment.
  • summary (string, optional) — short human summary for UI.

Behavioural notes:

• When bomLink is present, it MUST be a valid CycloneDX BOM‑Link or HTTP(S) URL. Implementations should resolve bomLink per CycloneDX BOM-Link guidance.
• path and bomLink are complementary: path is for in-document pointers; bomLink is for externalized fragments.
• A consumer that recognizes index may fetch only the fragment(s) it needs; consumers that don't recognize index must ignore it and operate on the full payload.

Schema/encoding changes:

• Add index optional object to spec/json/rdx.schema.json and spec/xml/rdx.xsd.
• Update tools/validate.sh to accept example files that demonstrate embedding where index.entries[].bomLink points to examples/cyclonedx-embedded.json using a BOM-Link URI.

Implementation guidance:

• Provide an example examples/rdx-indexed.json and examples/rdx-indexed.xml demonstrating:
  • An index entry referencing an in-document attackPath via path.
  • An index entry referencing an external RDX fragment via a CycloneDX BOM-Link URI.
• Add small utility tools/rdx_indexer.py that generates index entries from an RDX document (for maintainers and CI).

References

• CycloneDX BOM‑Link and guidance. See CycloneDX JSON reference and BOM-Link docs. https://cyclonedx.org/docs/1.7/json/ and https://cyclonedx.captnemo.in/capabilities/bomlink/. (cyclonedx.org)
• CycloneDX Authoritative Guide to CBOM (reference on cross-BOM linking). https://cyclonedx.org/guides/OWASP_CycloneDX-Authoritative-Guide-to-CBOM-en.pdf. (cyclonedx.org)
• JSON Patch / JSON Pointer (partial updates / pointers). https://jsonpatch.com/ (RFC 6901 for JSON Pointer). (jsonpatch.com)

Acceptance criteria

1. Schema: add optional index object to JSON Schema and XSD, with fields as defined above. Update REQUIREMENTS.md with RDX-201.
2. Examples: add examples/rdx-indexed.json and examples/rdx-indexed.xml showing at least two index.entries (in-document pointer and external BOM-Link).
3. Tooling: add tools/rdx_indexer.py (or similar) that generates index entries from an RDX file; include unit tests that verify generated path pointers point to valid JSON Pointer targets.
4. Docs: update methodology/Methodology.md and README embedding section to document index semantics and BOM-Link resolution rules.
5. CI: ensure tools/validate.sh still validates all examples and the new examples pass validation.
6. Backwards compatibility: documents without index remain valid and unchanged; consumers that ignore index must not fail validation.

---

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.