A static GraphQL check needs the right schema snapshot
Understand what a local schema check can establish, why multi-operation documents stay whole, and how source evidence helps review API changes.
The snapshot is part of the result
A downloaded introspection response is evidence about one schema at one point in time. A perfectly valid document checked against yesterday’s snapshot can still meet a different schema today. Keep the snapshot with the operation instead of forwarding a green status alone.
SDL and introspection JSON describe the same kind of local contract through different source formats. Introspection can also arrive wrapped in a response that contains errors or incomplete type references. Schema validation must finish before an operation result has meaning.
Check the complete document you will hand off
A document may contain several named operations and shared fragments. Choosing an operation for execution does not make other definitions suitable for a static whole-document review. Duplicate names, anonymous-operation rules and cycles can affect the document itself.
Neatbo keeps this review boundary explicit: it validates all operations and fragments together and returns every diagnostic up to the fixed complete-report limits. There is no operationName filter that can hide an invalid definition.
- Confirm which API environment produced the schema snapshot, and keep that exact source with the operation document.
- Check every operation and shared fragment together; resolve document diagnostics before selecting an operation for execution.
- Download the complete report and both originals, then compare their byte lengths and SHA256 values when handing them off.
- Test runtime variables and custom scalar behavior in the intended API environment after the static review.
Literal syntax cannot stand in for runtime behavior
A custom scalar defines behavior outside the built-in standard scalar rules. Without the application’s coercion implementation, a static checker can establish where that scalar is expected, but cannot verify its business meaning. Running a user-supplied resolver to fill the gap would change this task into code execution.
Numeric literals illustrate the distinction. The pinned mature validators accept 1e400 for a Float literal in a static document, while a large value supplied where Int is expected produces a standard diagnostic. Neither result establishes valid runtime inputs or serializable response data.
| Input or concern | What this local check establishes | What to verify in the API environment |
|---|---|---|
| Whole operation document | Syntax and standard document rules against the supplied valid schema, including every operation and fragment. | Execute the intended operation with its actual variables and credentials. |
| Local SDL or introspection schema | Structure and schema rules for the exact snapshot identified in the report. | Confirm the snapshot still corresponds to the target API and its current permissions. |
| Custom scalar | Where the schema expects the scalar; no application scalar coercion is run. | Verify the application’s scalar coercion and business rules. |
| Runtime variable values | Variable declarations and their static use in the document; a variables payload is not accepted by this tool. | Validate and supply the actual values when executing the operation. |
A refusal is better evidence than an incomplete pass
One thousand diagnostics can be complete; the first diagnostic beyond the fixed limit must cause a refusal. Returning the first thousand as a successful full report would conceal that the scan stopped. The same rule applies to the report byte budget and automatic Worker deadline.
Preserving both source originals, their byte lengths and SHA256 values makes a result reviewable. Those hashes identify the exact inputs; they do not establish schema freshness or authorize an operation. Bring the identified inputs and full report to the intended API environment for the remaining execution checks.
References
- Downloaded schema and mutation validation question
The author already has introspection JSON and asks for static checks; browser preference and demand scale remain unknown.
- GraphQL.js reference implementation
Pinned GraphQL.js 17.0.2 parsing and standard validation. This tool never executes an operation.
Tools in this category
Expand a tool to see its steps, options and supported formats, then open its workspace.
GraphQL document validatorCheck a whole GraphQL document against local SDL or introspection JSON and download complete static diagnostics with exact originals.
Check every operation and fragment against a schema you already have. Review source locations and retain both originals with the full validation report.
Steps
- Paste the whole GraphQL operation document in the first box.
- Choose the schema format and paste local SDL or introspection JSON, or select one schema file.
- Run the static check and inspect schemaValid, documentValid and every diagnostic location.
- Download both exact originals and validation-report.json; then test execution in the intended API environment.
Available options
- Local schema format
- GraphQL SDL · Introspection JSON
Select the format explicitly; a selected file replaces only the schema text.
Capabilities and limits
- Paste a whole operation document up to 1 MiB and a schema up to 2 MiB as UTF-8. Or select one schema file up to 2 MiB: it replaces only the schema box; your operation document stays in place. Choose SDL or introspection explicitly. Original filename labels allow 512 UTF-8 bytes.
- Only standard static rules from GraphQL.js 17.0.2 run. All operations and fragments are checked together; no operationName selection, React/JavaScript extraction, endpoint request, custom validation rule, resolver or scalar coercion. A passing result does not establish that a query can execute or a response is valid.
- Schema syntax/type errors and operation syntax/semantic errors produce complete diagnostic reports. Schema errors leave documentValid null. Locations use one-based lines and UTF-16 columns; CRLF is one line break. Structural introspection errors without original-source coordinates have no invented location.
- Use fatal UTF-8 decoding and paired Unicode scalar values. One leading BOM is accepted and retained in original bytes and SHA256. Introspection JSON must be strict: decoded duplicate keys, ambiguous __schema plus data.__schema, or an errors member produce schema diagnostics. Escaped unpaired surrogates are refused atomically.
- Introspection metadata numbers must be finite IEEE 754 values; integer-valued numbers must lie within ±9,007,199,254,740,991. No overwritten duplicate array names in types, fields, arguments, enum values or directives. Extra envelope metadata is ignored semantically and its keys are listed; originals remain exact.
- SDL allows 100,000 syntax tokens and 100,000 AST nodes; the operation document allows 50,000 of each. Both allow 64 nested braces, brackets or parentheses; acyclic fragment chains allow 64 definitions. Tokens exclude comments, commas and whitespace. AST counts include Document and Name nodes, excluding location links.
- Introspection JSON allows 128 object/array levels and 100,000 tree nodes, including property and key nodes. Reachable non-__ schema types allow 2,000 including injected scalars. Embedded introspection default values share the schema token/AST budgets and 64-level limit; they are parsed as GraphQL const values.
- Allow at most 1,000 complete diagnostics and a 1 MiB UTF-8 report. If another diagnostic or byte would exceed these limits, no partial report is published. The two separate originals allow up to 3 MiB together. A disposable Worker has an automatic 10-second deadline; cancellation, timeout, capacity or encoding refusal returns no output.
- The screen previews 4,000 Unicode codepoints of the report. Copy and downloads retain the complete report. GraphQL Float literal 1e400 and arbitrary custom-scalar literals can pass standard static rules; this tool performs no runtime numeric or custom-scalar coercion. Inputs stay in this browser.