# GraphQL Query Validator

- Human page: https://happytails.ai/en/developer-tools/graphql-query-validator/
- Markdown: https://happytails.ai/en/developer-tools/graphql-query-validator.md
- Structured JSON: https://happytails.ai/agents/en/developer-tools/graphql-query-validator/index.json
- Visibility: public

## Tool capabilities

| Property | Value |
| --- | --- |
| Tool ID | `graphql-query-validator` |
| Category | developer-tools |
| Implementation | Registered implementation. Registration alone is not a production-quality guarantee. |
| Browser execution | Use the visible action or interactive controls. |
| Browser processing | Browser; see tool notes for network behavior. |
| HTTP API | Not callable through HTTP. |
| Browser-agent interface | run_current_tool |

### Implementation notes

Runs in your browser in a background worker. Accepts up to 200000 characters of operations and a schema of up to 1000000 characters.

### Inputs and settings

Text input: GraphQL operations.

Example or placeholder shown in the interface (not a validated fixture):

```text
query BookPage($id: ID!) { book(id: $id) { title } }
```

Queries, mutations, subscriptions and fragments. Put the schema in the Schema field. Up to 200,000 characters. Review the settings before running.

| Setting | Meaning | Control type | Default | Constraints |
| --- | --- | --- | --- | --- |
| `schema` | Schema | textarea | "" |  |
| `variables` | Variables, optional | textarea | "" |  |

### Browser-agent workflow

1. Open the human page in a browser that supports WebMCP.
2. Discover the interface exposed by that page; use its actual schema.
3. Select files on the page first when the tool requires files.
4. Call `run_current_tool` with valid input and settings.
5. Inspect the returned result or error and the displayed output. Retrieve files from the displayed download links.

Calls do not automatically copy or download results. Browser permissions still apply. Interface availability alone is not proof of successful execution.

### Planning specification

Accepts up to 200,000 characters of operations, a schema of up to 1,000,000 characters and variables of up to 200,000 characters. Documents are limited to 100,000 tokens and 64 nesting levels, and schemas to 10,000 types. Validation runs in your browser in a background worker and nothing is sent to a GraphQL server. Downloads are a JSON report and a CSV list of errors.

This describes intended requirements. Use the implementation notes, interface schema and observed output to determine current support.

### Complete machine-readable capability record

```json
{
  "id": "graphql-query-validator",
  "category": "developer-tools",
  "built": true,
  "requirements": "Accepts up to 200,000 characters of operations, a schema of up to 1,000,000 characters and variables of up to 200,000 characters. Documents are limited to 100,000 tokens and 64 nesting levels, and schemas to 10,000 types. Validation runs in your browser in a background worker and nothing is sent to a GraphQL server. Downloads are a JSON report and a CSV list of errors.",
  "implementation": {
    "fields": [
      {
        "key": "schema",
        "label": "Schema",
        "value": "",
        "type": "textarea",
        "maxLength": 1000000,
        "help": "GraphQL SDL, or introspection JSON with a __schema object. It needs a Query type."
      },
      {
        "key": "variables",
        "label": "Variables, optional",
        "value": "",
        "type": "textarea",
        "maxLength": 200000,
        "help": "A JSON object such as {\"id\":\"1\"}. Leave it empty to skip checking variable values."
      }
    ],
    "registrationFamily": "api-contracts-schemas",
    "codeDirection": "ltr",
    "inputMaxLength": 200000,
    "inputErrorCode": "API_CONTRACTS_SCHEMAS_TOO_LONG_GRAPHQL_QUERY_VALIDATOR",
    "note": "Runs in your browser in a background worker. Accepts up to 200000 characters of operations and a schema of up to 1000000 characters.",
    "experience": {
      "automatic": false,
      "single": false,
      "inputMaxLength": 200000,
      "inputMode": "text",
      "label": "GraphQL operations",
      "placeholder": "query BookPage($id: ID!) { book(id: $id) { title } }",
      "help": "Queries, mutations, subscriptions and fragments. Put the schema in the Schema field. Up to 200,000 characters. Review the settings before running.",
      "helpParts": [
        "Queries, mutations, subscriptions and fragments. Put the schema in the Schema field.",
        "Up to 200,000 characters.",
        "Review the settings before running."
      ],
      "action": null
    },
    "mode": "explicit",
    "interactive": false
  },
  "execution": "Browser interface",
  "api": null,
  "browser_agent": {
    "supported": true,
    "name": "run_current_tool",
    "discovery": "WebMCP on the human page in a supporting browser",
    "verification": "See audit/API-AUDIT.md; availability is not verification"
  }
}
```

## Page guide

Check GraphQL queries, mutations and fragments against your schema before you send them. Paste SDL or introspection JSON and see supported validation failures, with its line and column.

### How to use GraphQL Query Validator

1. Paste your GraphQL operations and fragments in the main box.
2. Paste the schema as SDL or introspection JSON in the Schema field.
3. Optionally add the variables as a JSON object.
4. Run the check, then review each failed rule and download the JSON or CSV report.

How can we improve this tool?

Report a problem or share an idea.

Please leave out private information. Your message and the tool name go to our team via PostHog.

## Useful next steps

- [GraphQL Schema Explorer](https://happytails.ai/en/developer-tools/graphql-schema-explorer/) ([Markdown](https://happytails.ai/en/developer-tools/graphql-schema-explorer.md))

- [GraphQL Query Cost Estimator](https://happytails.ai/en/developer-tools/graphql-query-cost-estimator/) ([Markdown](https://happytails.ai/en/developer-tools/graphql-query-cost-estimator.md))

- [JSON formatter](https://happytails.ai/en/developer-tools/json-formatter/) ([Markdown](https://happytails.ai/en/developer-tools/json-formatter.md))

Accepts up to 200,000 characters of operations, a schema of up to 1,000,000 characters and variables of up to 200,000 characters. Documents are limited to 100,000 tokens and 64 nesting levels, and schemas to 10,000 types. Validation runs in your browser in a background worker and nothing is sent to a GraphQL server. Downloads are a JSON report and a CSV list of errors.

## What is checked

The validator checks supported rules for fields and return types, leaf and object selections, arguments and required arguments, fragment names, targets, cycles and unused fragments, values and input objects including @oneOf, directives and their locations, and variable definitions, usage and types. When you add variables, their values are checked against the declared types too. The limitations below describe where the custom implementation stops.

### How it works

Happytails.ai uses its own bounded GraphQL parser and validator, not graphql-js. Response-name conflicts are compared across fragments and merged child selections, including return shape, arguments and mutually exclusive object branches. \_\_schema and \_\_type require a selection set, but their introspection subfields are not validated. This is not a full GraphQL implementation.

### Reading the report

Each error names the rule, a short explanation and the line and column in your operations. The schema itself must be usable: a missing Query type or a field that points to an undefined type stops the check with a message instead of a list.