sphinx-needs JSON import adapter (needs.json)

[avrabe]

Context

Eclipse SCORE and many other automotive/safety-critical projects use sphinx-needs with its needs.json export format. There is no migration path from sphinx-needs to alternative tooling. SCORE has 50+ need types and hundreds of artifacts in this format.

Problem

Teams wanting to adopt Rivet from an existing sphinx-needs project have no import path. The needs.json format contains:

• All need objects with their types, attributes, and content
• Link information (incoming/outgoing with link types)
• Status, tags, and custom fields
• Metadata (docname, section, line number)

Proposed approach

New adapter needs-json that:

1. Parses needs.json (sphinx-needs export format)
2. Maps sphinx-needs types to Rivet schema types (configurable mapping in rivet.yaml)
3. Converts sphinx-needs links to Rivet link types
4. Preserves custom fields and metadata as Rivet fields
5. Handles ID format differences (sphinx-needs uses underscored IDs like stkh_req__name)

# rivet.yaml
sources:
  - path: imported/needs.json
    format: needs-json
    options:
      type-mapping:
        stkh_req: stakeholder-req
        feat_req: feature
        comp_req: sw-req
      id-transform: underscores-to-dashes

Rivet artifacts

• REQ-025
• FEAT-042

References

• SCORE's needs.json usage: their entire toolchain exports/consumes this format
• sphinx-needs docs: https://sphinx-needs.readthedocs.io/en/latest/configuration.html#needs-json
• SCORE metamodel issue: eclipse-score/score#1695

[avrabe]

Implemented in PR #27 (feat/phase3-integration)