Epic: Implement GraphQL MVP for Concepts and Sources

[filiperochalopes]

@snyaggarwal Related to:

• TBv3 Add References form: Show concept display names via GraphQL on ID entry #2577
• Defer GraphQL permission decorators until group authorization service is complete #2356
• perf(graphql): align concept search with REST and add Elasticsearch safe-path oclapi2#816
• Create GraphQL service permission archtecture oclapi2#838
• Bump strawberry-graphql from 0.285.0 to 0.315.7 oclapi2#877

User story

As an OCL API consumer, I want a GraphQL interface for Concepts and Sources so that applications can request only the data they need while preserving OCL as the authoritative source.

Use case

CIEL Lab frequently needs authoritative reads from OCL, especially around concept retrieval and validation after writes.

Using the full REST representation can add unnecessary payload and latency when only a small subset of fields is required.

Check this benchmark bench-concept-editor-detail-load.md

The GraphQL MVP should focus on Concepts and Sources, with a shared authorization model across REST and GraphQL.

Requirements

• Add a GraphQL endpoint to OCL.
• Support queries for Concepts.
• Support queries for Sources.
• Allow clients to select only the fields required by the request.
• Reuse the same permission and visibility rules used by the REST API.
• Centralize permission evaluation so REST and GraphQL do not implement divergent authorization logic.
• Preserve the existing REST API behavior.

Query execution strategy

• Allow GraphQL query execution to select the most efficient backend based on the requested fields.
• If the requested payload can be fully satisfied by Elasticsearch, return the result directly from Elasticsearch without unnecessary database hydration.
• If requested fields require authoritative relational data, enrich/hydrate the Elasticsearch result using the database.
• Avoid database queries when the requested GraphQL selection set does not require them.
• Ensure both execution paths respect the same authorization rules.

Acceptance criteria

• An authenticated client can query Concepts through GraphQL.
• An authenticated client can query Sources through GraphQL.
• The client can explicitly control the returned fields through the GraphQL selection set.
• Simple queries that can be satisfied entirely by Elasticsearch do not unnecessarily access the database.
• Queries requiring additional fields correctly hydrate data from the database.
• REST and GraphQL apply the same permissions for equivalent resources.
• GraphQL responses remain consistent with OCL authoritative data.
• Existing REST consumers are unaffected.

[ocl-automation]

Automated Triage — 2026-09-07

Dimension	Score
Complexity	5
Scope	5
Clarity	2
Dependency	3
Risk	3

Decision: decision/human-review
Type: type/feature
Signals: signal/large-scope, signal/needs-spec, signal/has-dependencies

This is an epic requiring architectural changes to add GraphQL support across multiple entities and systems. Very complex implementation with system-wide scope. Clarity is low as it's a high-level epic without detailed implementation steps or acceptance criteria.

---

Generated by ticket-triage pipeline v3. Model: anthropic/claude-sonnet-4 (openrouter).

[filiperochalopes]

@snyaggarwal

Evidence

A local benchmark against CIEL HEAD compared GraphQL with REST using 3 warm-ups and 10 measured repetitions.

20 predefined concepts	Requests	p50	Payload
GraphQL, ES-only	1	65 ms	4.9 KB
GraphQL with mappings	1	158 ms	15 KB
REST, concurrency 8	20	1,472 ms	241 KB

For 20 concepts, GraphQL with mappings was 9.3× faster and transferred 94% less data than REST.

The maximum ES-only concept payload currently supports:

conceptId
display
externalId
conceptClass
datatype { name }

Mappings are partially indexed as source, map_type, and code, but are not exposed as an ES-backed GraphQL projection. In particular, the index contains the source URL rather than toSource.name. Therefore, selecting mappings currently falls back to database hydration.

Even with that fallback, a single GraphQL bulk request is substantially more efficient than one REST request per concept.