Octokit GraphQL Schema

To update the schema files in a local development environment, run the update script. This requires a GITHUB_TOKEN (which requires no specific scopes) to fetch the latest schema from GitHub.

GITHUB_TOKEN=... npm run update

You can import types directly from @octokit/graphql-schema to provide type safety when using @octokit/graphql. This allows you to cast the results of a GraphQL query to the specific shape defined by the GitHub schema.

import { graphql } from "@octokit/graphql";
import { Repository } from "@octokit/graphql-schema";

const { repository } = await graphql<{ repository: Repository }>( 
  `
    {
      repository(owner: "octokit", name: "graphql.js") {
        issues(last: 3) {
          edges {
            node {
              title
            }
          }
        }
      }
    }
  `,
  {
    headers: {
      authorization: `token secret123`,
    },
  },
);

The @octokit/graphql-schema package exports a schema object that provides direct access to the GitHub GraphQL schema in two formats:

• schema.json: The schema in JSON format.
• schema.idl: The schema in Interface Description Language (IDL) format.

import { schema } from "@octokit/graphql-schema";

schema.json; // JSON version
schema.idl; // IDL version

Use the validate function to check if a GraphQL query string conforms to the current GitHub GraphQL schema. The function returns an array of error objects; if the array is empty, the query is valid.

import { validate } from "@octokit/graphql-schema";
const errors = validate(`
{
  viewer {
    login
  }
}
`);

// errors is an array. Contains errors if any

The schema object provides programmatic access to the GitHub GraphQL schema in two formats:

• schema.idl: A getter that returns the schema as an Interface Definition Language (IDL) string, read directly from schema.graphql.
• schema.json: The schema parsed as a JavaScript object from schema.json.

Use these to inspect the schema structure or to provide the schema to other tools (like code generators) that require the raw IDL or JSON representation.

import { schema } from '@octokit/graphql-schema';

const idl = schema.idl;
const json = schema.json;
console.log(idl);
console.log(json);

The validate function is used to check the validity of GraphQL queries against the bundled schema. It returns an array of GraphQLError objects if the queries are invalid.

Parameters:

• query: A single string or a ReadonlyArray<string> containing one or more GraphQL queries to validate.

Returns:

• ReadonlyArray<GraphQLError>: An array of errors found during validation. If the array is empty, the queries are valid.

The schema object provides programmatic access to the GraphQL schema definition. It contains two primary representations:

• idl: A string containing the GraphQL Interface Definition Language (IDL) representation of the schema.
• json: A JsonSchema object representing the schema in JSON format.

Use schema.idl for raw schema strings or schema.json for structured schema data.