Reference

ShapeFingerprintComputer

Package Trax.Api.GraphQL.PersistedOperationsNamespace Trax.Api.GraphQL.PersistedOperations.ShapeDiffSource ShapeFingerprintComputer.cs

Computes a canonicalized structural hash (sha-256, hex) of the response shape produced by a GraphQL operation. Two documents that produce byte-compatible JSON shapes hash to the same fingerprint; documents that would change a shipped client's deserialization hash differently.

The storage layer calls this on every UpsertAsync and stores the result in shape_fingerprint. The shape-diff guardrail in the store compares old vs new on every edit of an existing id and refuses a change unless UpsertOptions.BypassShapeDiff is set.

Signature

public static string Compute(string document, string? operationName = null);

Parameters

ParameterNotes
documentFull GraphQL document text. Required.
operationNameDisambiguates when the document contains multiple operations. When null and the document has exactly one operation, that one is used.

Returns

The sha-256 hash of the canonical shape, as lowercase hex.

Behavior

Throws InvalidOperationException when the document has no executable operation, when multiple operations are present without a name, or when the named operation is missing.

Algorithm

  1. Parse the document via Utf8GraphQLParser.
  2. Locate the executable operation.
  3. Inline fragment spreads with their type conditions. Cycles are broken by a recursion guard.
  4. For every field emit (parentType, responseKey, fieldName, hasInclude, hasSkip) where responseKey is the alias when present, else the field name.
  5. Sort sibling tuples by (parentType, responseKey, fieldName).
  6. Recurse into nested selections, indented by depth.
  7. Hash the canonical string with sha-256.

What is "same shape"

Same fingerprintWhy
Whitespace, indentation, commentsLexed away.
Field order within a selection setCanonical sort.
Argument value changesArguments do not affect response shape.
Argument additions / removalsSame.
Variable type widening (Int! -> ID!)Variables are inputs.
Adding a new optional variableOld clients ignore it.
Default variable value changesSame.
Pure-resolver-path swaps with identical projectionSame response keys.

What is "different shape"

Different fingerprintWhy
Adding / removing / renaming a selected fieldResponse keys differ.
Adding or changing an aliasResponse key differs even if underlying field is the same.
Fragment-spread vs inlined fieldsConservative: fragment carries a type condition that may matter on unions/interfaces. Operators rewriting can set BypassShapeDiff if they have verified the type is concrete.
Inline-fragment branch added or removed (e.g. on a union)Real shape change.
Adding @include or @skip to a fieldField becomes conditional.
Mutation vs query, subscription vs queryOperation type is part of the canonical form.

False positives

The fingerprint is conservative: a change it flags may still be shape-safe for a given client, and BypassShapeDiff (the upload mutation's bypassShapeDiff, the dashboard editor's bypass checkbox) stores it anyway. It does not pass a change that alters the response keys. The cases are pinned by ShapeFingerprintComputerTests in Trax.Api.Tests.PersistedOperations.UnitTests.

Example

var before = ShapeFingerprintComputer.Compute("query U { user(id: 1) { id name } }");
var after = ShapeFingerprintComputer.Compute("query U { user(id: 2) { name id } }");
 
Console.WriteLine(before == after); // True: argument values and field order do not change the shape

See also