Document Registry plugin

[magicmark]

Thoughts on standardizing a plugin that can be used to display persisted documents?

and then fields/types can be decorated with how many times they're used

bonus points for an indicator to show traffic usage per document (if you're able to supply that data)

We could define a simple callback interface for the user to define a getDocuments() callback method to return the manifest in a standardized format.

cc @benjie for persisted documents chatter.

(I searched "persisted documents" for prior discussion/issues on this topic in this repo and couldn't find anything, apologies if this has already been discussed elsewhere.)

[magicmark]

I wonder if GET /get-persisted-operations or a new introspection field could be a standardized to enable this plugin to work out the box. (introspection makes more sense to me as it's a dev only thing, but it's not really about describing the schema so idk)

The server will have access to the list of persisted documents anyway so this would be easier to implement vs dumping the whole registry to a json blob and serializing that onto the page or whatever you might otherwise do to implement getDocuments()

[yudin-s]

I would start with a client-side plugin contract first, then standardize server discovery separately.

For GraphiQL, a getDocuments() callback is probably the least controversial first step:

type PersistedDocument = {
  id: string
  name?: string
  operationName?: string
  operationType?: "query" | "mutation" | "subscription"
  document: string
  tags?: string[]
  stats?: {
    calls?: number
    lastUsedAt?: string
    errorRate?: number
    p95Ms?: number
  }
}

type DocumentRegistryPluginOptions = {
  getDocuments: () => Promise<PersistedDocument[]>
}

That lets teams wire it to whatever registry they already have without requiring a new GraphQL spec decision up front.

For automatic discovery, I would be cautious about introspection. Persisted documents are operational/application artifacts, not really schema metadata. They may also contain private operation names, internal fields, or traffic data that should not be exposed anywhere introspection is enabled.

A dedicated endpoint or well-known metadata document feels cleaner:

GET /.well-known/graphql/persisted-documents
GET /graphql/persisted-documents

with auth required by default.

The plugin could then support both:

documentRegistryPlugin({
  getDocuments,
})

documentRegistryPlugin({
  endpoint: "/.well-known/graphql/persisted-documents",
})

For the field/type decoration use case, the plugin can parse the returned documents and build usage counts locally against the current schema. If optional traffic stats are supplied per document, GraphiQL could surface both static usage and runtime usage without making those concepts part of introspection itself.

So my vote would be:

1. standardize the plugin manifest shape first
2. keep the transport pluggable
3. later discuss a server discovery convention once a few registry implementations prove what metadata is actually needed

[magicmark]

For automatic discovery, I would be cautious about introspection. Persisted documents are operational/application artifacts, not really schema metadata. They may also contain private operation names, internal fields, or traffic data that should not be exposed anywhere introspection is enabled.

That's actually precisely the reason why it makes sense as an introspection field -- introspection should almost always be disabled in production (unless perhaps it's specifically a public api that explicitly does not use trusted documents, such as the Github API - in which case, there's no document registry)

https://graphql.org/learn/introspection/#introspection-in-production

(although again, i'm not against decoupling this and using a seperate endpoint, or even something else that can be toggled independently by frameworks)

(Such extensions to GraphQL servers can be specified as a GAP, at least initially)

On the topic of "not really schema metadata" -- that's true, and why I hedged "but it's not really about describing the schema so idk". That said, service capabilities (which adds a new introspection type) also may describe things that aren't strictly about the schema, but about execution, so I feel like there's enough prior art/wiggle room to at least make an argument for new introspection types. Curious what others think! A GAP-specified endpoint or Query.trustedDocumentsManifest field would also work.

[magicmark]

The more I think about it, the more I want to double down on the idea that this should be baked into GraphQL somehow (either through introspection or endpoints defined by over-http spec) as a first class citizen to really encourage the fact we do want people to use trusted documents. This would help make it more "out the box", rather than a bolt on thing that you have to figure out yourself.

[yudin-s]

That framing makes sense. I agree that making trusted documents feel first-class would help adoption a lot.

The split I would still keep is: expose the capability through GraphQL, but not necessarily the full document registry through the normal schema introspection payload.

Something like this could be a workable middle ground:

type __TrustedDocumentsCapability {
  manifestUrl: String
  manifestFormat: String!
  hashAlgorithm: String!
  documentIdAlgorithm: String
  supportsTrafficStats: Boolean!
}

Then GraphiQL can discover:

this server supports trusted documents
the registry is available here
the IDs use sha256 / relay persisted IDs / custom IDs
traffic stats may or may not be available

without forcing every introspection response to include the actual operation bodies and usage data.

That gives you the “baked into GraphQL” ergonomics while keeping a clearer security boundary:

• introspection/capability discovery: tells tools what exists
• registry endpoint/query: returns the manifest, usually authenticated
• GraphiQL plugin: consumes either getDocuments() or the discovered registry

If this starts as a GAP, I would define two levels:

Level 1: client/plugin manifest shape
Level 2: discovery convention for servers

That way GraphiQL can ship a useful plugin before the ecosystem agrees on whether discovery belongs in introspection, GraphQL-over-HTTP, or a well-known endpoint.

I also think trusted documents is the better naming than persisted operations here. It nudges the concept toward the security/performance model people should adopt, instead of only describing the storage mechanism.