Fully Qualified Operation Names (FQON)
1Introduction
This document specifies Fully Qualified Operation Name (FQON), a human‑readable, unambiguous identifier for GraphQL operations.
The primary motivation is to define a “lookup key” that may be used in static configuration files (e.g. for alerting rules per operation) which correctly targets operations, but without having to update the configuration each time a document id changes.
This specification assumes usage of trusted documents and Git version control.
Example
Given the following operation defined in a Git repository named yelp/frontend, and in a package named styleguide:
Example № 1query GetHeaderData {
...
}
The FQON for this operation may be defined as:
Example № 2GetHeaderData:styleguide:yelp/frontend:1
When defining alerting rules for this operation, we can target all versions of this operation by omitting the version suffix:
Example № 3GetHeaderData:styleguide:yelp/frontend
Motivation
We may identify operations using either:
- The operation name (e.g. "GetHeaderData")
- The document id produced by hashing the operation body (e.g. "605fad0ee0a88...")
Because GraphQL operation names are not be guaranteed to be globally unique, they cannot reliably identify an operation across multiple platforms or deployment versions. On the other hand, a document id is guaranteed to be unique but is inconvenient for humans to read and maintain.
Use Cases
- A FQON may be printed instead of the operation name in application logs. This encourages correct behavior when humans use this identifier to look up the operation body in the document registry or codebase.
- A partial FQON may be used instead of a document id as lookup keys in static configuration files (e.g. alerting rules) in order to avoid duplication and extra steps when an operation is updated (and thus, its document id).
2Definition
- OperationName
- The Name of the operation as declared on the OperationDefinition node.
- Project
- The identifier for the package or directory containing the operation.
- This is defined only for operations that live in a monorepo.
- RepoFullName
- The full name of the Git repository (in the format of "owner/repo").
- Version
- A positive integer that increments each time the document body changes.
- The tuple of OperationName, Project and RepoFullName identifies a document; the Version part distinguishes its revisions.
- The trusted document registry or other persistence layer must calculate or store version numbers, starting at 1 and increasing monotonically.
Examples
A Fully Qualified Operation Name with all parts:
Example № 4GetHeaderData:styleguide:yelp/frontend:1
A Fully Qualified Operation Name which omits Project (i.e. petstore/website is not a monorepo, and has no concept of “projects”):
Example № 5AllPets::petstore/website:1
3Partial Matches
Any FQON part may be omitted to perform a partial match.
With the exception of omitting Project, partial matches must also omit the :Version suffix.
The primary use case of this specification is to omit :Version for use as lookup keys in static configuration files, as a way to target to all versions of an operation.
Examples
| Pattern | Matches |
|---|---|
GetFoo:: |
All operations named "GetFoo" |
::bazcorp/qux |
All operations inside the "bazcorp/qux" Git repository |
GetFoo:barpkg:bazcorp/qux |
All operations named "GetFoo" inside the "barpkg" package inside the "bazcorp/qux" Git repository |
4Security Considerations
It is recommended to avoid exposing FQONs in client code to avoid leaking potentially sensitive internal repository names or project/directory names.
Clients should still send only the document id over the wire, which is opaque.