16  Interoperability and Federation

Interchange formats and external service integrations in Quarto-Needs are adapters and projections around the canonical engineering graph. External standards transport and federate requirements without compromising canonical identity or provenance.

16.1 Structured Interchange Formats

16.1.1 ReqIF 1.2

Export the canonical requirements graph to ReqIF (Requirements Interchange Format) for exchange with enterprise tools like IBM DOORS, PTC Integrity, or Polarion:

quarto-needs export --format reqif --output requirements.reqif

The exporter maps typed engineering objects, attributes, and canonical relation families to standard ReqIF SpecObjects, SpecTypes, and SpecRelations.

16.1.2 JSON-LD 1.1

Export the graph as Linked Data preserving semantic relation metadata:

quarto-needs export --format jsonld --output graph.jsonld

The JSON-LD projection uses deterministic IRIs, schema vocabularies, and full context mapping compatible with semantic web tooling.

16.2 Standards-Based Federation: OSLC RM

Quarto-Needs provides a bounded read-only adapter for OSLC Requirements Management (RM):

pip install 'quarto-needs[oslc]'

The optional dependencies provide JSON-LD, Turtle, and RDF/XML normalization. The public CLI exposes three operations:

  1. Catalog Inspection: Lists Service Provider and nested-catalog URIs without following nested catalogs:

    quarto-needs oslc catalog https://provider.example/oslc/catalog --format json

  2. Service Discovery: Inspects one RM Service Provider, its query capabilities, and advertised Resource Shapes:

    quarto-needs oslc discover https://provider.example/oslc/sp/requirements --format json

  3. Query Capability: Executes a bounded HTTP GET query in the context of an explicit Service Provider (or a configured profile), without recursively crawling members:

    quarto-needs oslc query https://provider.example/oslc/query/requirements \
  --service-provider-uri https://provider.example/oslc/sp/requirements

The query result reports member URIs, any nodes already inline in the response, and the response’s digest and retrieval timestamp. The CLI does not materialize independent requirement observations or reconcile them with local objects.

Those additional operations are Python library APIs: quarto_needs.oslc_observe.materialize_query_observations() produces external observations with individual provenance, and quarto_needs.oslc_reconcile.reconcile_external_requirements() compares observations with canonical objects using explicit URI-to-ID bindings. They require caller-supplied inputs and do not run implicitly after oslc query.

Credentials are provided securely via environment variables:

export OSLC_TOKEN="..."
quarto-needs oslc discover https://provider.example/oslc/sp/requirements --bearer-token-env OSLC_TOKEN

The command-line reference documents named profiles, cache behavior, retrieval limits, optional shape fetching, and every public OSLC command. It also covers JSON, CSV, SARIF, JUnit, and Markdown exports used by automation.

16.3 External Issue Trackers: GitHub Issues

The Python engine contains a read-only GitHub Issues adapter with bounded retrieval, provenance, conditional caching, reconciliation, and reviewed import/apply primitives. This adapter is a library/engine surface; there is no public quarto-needs github ... CLI command yet. The separate github-report --git BASE..HEAD command prints a projection of local Git changes; it does not retrieve issues.

The adapter:

  • normalizes issues into external observation envelopes;
  • handles pagination and conditional HTTP caching (If-None-Match / 304 Not Modified);
  • treats issue numbers as external data rather than overriding canonical IDs;
  • requires explicit apply review before any local requirement creation.

A dedicated command-line surface is deferred until its user-facing authentication and import workflow can be documented and tested as a stable contract.