Publish a GraphQL API profile for RDX (query/composition/pagination)

[github-actions]

Motivation

Large-scale TARA workflows (OEM whole-vehicle assembly, supplier networks, continuous monitoring) need efficient, partial queries (selectively fetch: itemDefinition + components + attackPaths for many TARAs), graph traversal (follow relationships), and composition endpoints for whole-vehicle TARA assembly. While there is an open request for an OpenAPI REST profile, GraphQL has proven useful for SBOM/knowledge-graph style workflows (GUAC exposes a stable GraphQL API for supply-chain graphs). Providing a canonical GraphQL SDL + recommended queries helps implementers expose RDX data for interactive viewers, composition services, streaming clients, and graph-based analytics without repeatedly re-inventing schemas.

Proposed change

Create a new API profile deliverable: tools/api/graphql/rdx.graphql (SDL) + reference query set and server mapping guidance.

Concrete deliverables and schema recommendations:

1. Add directory tools/api/graphql/ with:
   • rdx.graphql (GraphQL SDL) defining types for: RiskSet, ItemDefinition, Component, Model (if ML extension accepted), Asset, DamageScenario, ThreatScenario, AttackPath, AttackStep, AttackFeasibilityRating, ImpactRating, RiskValue, Control, Relationship, CAL objects, TAF objects, EvidenceRef.
   • rdx_queries.graphql — recommended queries and mutations (read-only first):
     • query riskSet(documentId: UUID!, page: PaginationInput, filter: RiskFilter): RiskSetResult
     • query riskSets(ids: [UUID!], filter: RiskFilter, page: PaginationInput): RiskSetConnection (cursor pagination)
     • query attackPaths(riskSetId: UUID!, filter: AttackPathFilter, limit:Int, cursor:String): AttackPathConnection
     • query search(type: SearchType!, q:String!, page:PaginationInput): SearchResult
     • mutation composeWholeVehicleTara(input: ComposeInput): ComposeJobRef — (server-side composition job that returns a job ref; composition follows canonical merge semantics already discussed in issue Add canonical document-merge semantics to enable composition of multiple TARAs into a whole-vehicle TARA #84)
   • type pagination/cursor scheme and canonical partial fetch patterns (select fields, nested relationships) to support large TARAs and whole-vehicle composition.
2. Provide mapping guidance in methodology/GraphQL-Profile.md describing how to map an RDX JSON document to the GraphQL backend (one document = one RiskSet node), how to expose CycloneDX-embedded RDX documents, and how to expose versioned artifact history using cursor pagination.
3. Provide an opinionated example GraphQL server implementation (small reference) in tools/api/graphql-server-example/ using an embedded dataset built from examples/rdx-*.json (Node.js or Python minimal server) plus a test suite that runs queries against the examples and asserts expected shapes.

Compatibility notes:

• Profile is optional and read-only by default; implementations may expose mutations for composition or streaming per policy.
• Should co-exist with OpenAPI REST profile (Add an OpenAPI-based RDX REST API profile with JSON Patch/merge semantics #82) — GraphQL is an additional consumer-facing profile.

Mapping to RDX requirements:

• RDX-099: Ensure non-invasive integration with CycloneDX tooling (GraphQL profile must support CycloneDX-embedded documents and BOM linking)
• RDX-075: Enable whole vehicle TARA by combining existing TARAs (GraphQL queries + compose job facilitate this use case)
• RDX-101: RDX Reader / online viewer use-case (Profile supports driving web viewers without full download)
• RDX-118 (new requirement): "RDX SHOULD publish a canonical GraphQL API profile (SDL + example server + queries) to enable efficient partial consumption, composition, and graph queries of RDX documents."

References

• GUAC project: public GraphQL API for supply-chain graphs showing practical precedent for GraphQL over BOM/attestation graphs. https://guac.sh/ and GUAC GraphQL docs.
• Examples of SBOM / security products exposing GraphQL for dependency/SBOM querying (Binary composition and tools). https://safeguard.sh/resources/blog/guac-v1-0-release-graph-supply-chain-2025 and product docs referencing GraphQL APIs.
• CycloneDX ecosystem: many tools produce CycloneDX BOMs and server APIs; GraphQL complements REST for large-graph queries. https://www.cyclonedx.org/

Acceptance criteria

1. Add tools/api/graphql/rdx.graphql (SDL) to the repo with types covering the RDX object model and recommended queries/mutations.
2. Add tools/api/graphql-server-example/ with a minimal working example server that loads the existing examples/ and responds to the canonical queries. Include tests that run against CI (example queries in tests/ that assert returned shapes/fields).
3. Add methodology/GraphQL-Profile.md documenting mapping rules (how to map CycloneDX-embedded RDX, pagination/cursor rules, composition job semantics) and update README referencing the profile.
4. Add REQUIREMENTS.md entry RDX-118 (new requirement) and link to the profile files.
5. CI: an automated smoke test invokes the example GraphQL server and runs at least 5 example queries to ensure expected responses.
6. Backwards compatibility: No changes to existing JSON/XSD schemas required for RDX documents; profile is an optional access layer.

---

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.