Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท The Schema

Input Types, Custom Scalars and Introspection

Learn input objects, custom scalars like DateTime, the @deprecated directive and introspection queries (__schema, __type), with runnable stand-ins.

Three topics finish the schema vocabulary. Input types describe structured data a client sends. Custom scalars teach the schema about values such as dates and JSON. Introspection lets anyone ask a running server what its schema looks like, which is how tools such as GraphiQL give you auto-complete and documentation.

The real mechanisms live inside a GraphQL server, which cannot run on this site. SDL, queries and responses from a server are therefore read-only code blocks, and the runnable examples are stand-ins written in JavaScript: one validates input and converts a date scalar, the other builds a schema description from a type map. They show the idea, not the exact algorithms of a production library.

Input object types

An argument can be a scalar or an enum, but also a structured value. For that you declare an input type with the keyword input:

GRAPHQL
input NewBookInput {
  title: String!
  isbn: String
  authorId: ID!
  tags: [String!] = []
  published: PublishDate
}

input PublishDate {
  year: Int!
  month: Int
}

type Mutation {
  addBook(input: NewBookInput!): Book!
}

Why can't you reuse your normal object types as arguments? Because they play different roles:

Object type (type) Input type (input)
Used for Output, what the server returns Input, what the client sends
Fields can have Arguments, interface types, unions Only scalars, enums and other input types
Cycles / resolvers Resolvers per field No resolvers, plain data

An output type might contain a field author: Author with a resolver; an input has no resolver and cannot hold interfaces or unions. Input fields can have default values (tags: [String!] = []), and ! makes a field required, with the same rules as in Lists and Non-Null Types. In a query you pass an input as an object literal or, better, as a variable (Variables and Directives):

GRAPHQL
mutation Add($input: NewBookInput!) {
  addBook(input: $input) {
    id
    title
  }
}
JSON
{
  "input": {
    "title": "Graphs for Humans",
    "authorId": "7",
    "published": { "year": 2024 }
  }
}

Before a resolver runs, the server coerces the variables: missing required fields, unknown fields and wrong types are rejected with an error. That is the same job the stand-in below does.

Custom scalars

The five built-in scalars cannot say "this is a date". A custom scalar gives a name to a value and lets the server decide how to convert it. The SDL is just one line:

GRAPHQL
scalar DateTime
scalar JSON

The behaviour is code. A server library asks you for three functions: serialize (internal value to the response), parseValue (a JSON variable to an internal value) and parseLiteral (a value written in the query to an internal value). For DateTime you would typically store a JavaScript Date internally and send an ISO 8601 string over the wire.

Be careful with JSON scalars: they switch off the schema for that value. The client cannot select fields inside it, tools cannot document it and you cannot evolve it safely. Use it only for truly free-form data, and see Schema Design Best Practices.

Custom scalars are also the usual fix for numbers beyond 32 bits (a Long scalar serialized as a string).

JS Stand-in: input coercion and a DateTime scalar

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The valid input is accepted: authorId: 7 becomes the string "7", tags gets its default and the date is parsed and serialized back to ISO. The bad input produces all problems at once rather than stopping at the first one, which is what real servers do before executing anything.

Deprecating fields

Don't delete fields that clients may use. Mark them with the built-in @deprecated directive and say what to use instead:

GRAPHQL
type Book {
  id: ID!
  title: String!
  author: String @deprecated(reason: "Use `writer { name }` instead.")
  writer: Author!
}

Deprecated fields still work, but tools show them struck through and warn you. The same directive works on enum values and, in current versions of the spec, on arguments and input fields. This is the first step of the workflow in Schema Evolution, Federation and Tooling.

Introspection

Every GraphQL server can answer questions about its own schema, using the reserved fields __schema and __type. They are ordinary queries:

GRAPHQL
{
  __schema {
    queryType { name }
    types {
      name
      kind
    }
  }
}

To inspect one type:

GRAPHQL
{
  __type(name: "Book") {
    name
    kind
    description
    fields {
      name
      isDeprecated
      type { kind name ofType { kind name } }
    }
  }
}

A shortened response (read-only; real servers return much more, including all built-in types):

JSON
{
  "data": {
    "__type": {
      "name": "Book",
      "kind": "OBJECT",
      "description": "A book in the catalogue.",
      "fields": [
        { "name": "id", "isDeprecated": false,
          "type": { "kind": "NON_NULL", "name": null, "ofType": { "kind": "SCALAR", "name": "ID" } } },
        { "name": "title", "isDeprecated": false,
          "type": { "kind": "NON_NULL", "name": null, "ofType": { "kind": "SCALAR", "name": "String" } } }
      ]
    }
  }
}

Notice how a type like ID! is described: a NON_NULL wrapper whose ofType is the real ID. Lists are LIST wrappers in the same way, so [Int!]! is NON_NULL โ†’ LIST โ†’ NON_NULL โ†’ Int.

Who uses introspection?

GraphiQL Docs panel and auto-complete.
Codegen Generates typed client code.
Linters Check names and deprecations.

Tools read the schema from the server itself.

1 / 2

Introspection is great in development. In production some teams turn it off for public APIs to avoid handing attackers a map, although that is not a substitute for authorization. See Query Depth, Complexity and Other Attacks.

A stand-in: describing a schema from a type map

An introspection result is, at heart, a tree describing the type map. This stand-in takes a hand-written type map (like the one from SDL: Types and Scalars) and builds an introspection-style description of one type, including the NON_NULL / LIST wrapping.

JS Stand-in: build an introspection-style description

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The printer re-assembles [String!]! from the nested description, which is exactly what GraphiQL's docs panel does. Real introspection also includes arguments, interfaces, possible types, directives and more, but the nesting idea is the same.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can't you use an object type as an argument type?

    Object types describe output and may have resolvers, interfaces and unions. Inputs are plain data and need input types.
  2. 2. Which functions does a custom scalar usually define?

    serialize converts output values; parseValue and parseLiteral convert input from variables and from query text.
  3. 3. How does introspection describe the type ID!?

    Non-null and list modifiers are wrapper types with an ofType pointing at the wrapped type.
  4. 4. What is the recommended way to retire a field clients may still use?

    Deprecation keeps old clients working and tells tools and developers to migrate.

Summary

  • input types describe structured arguments; they can only contain scalars, enums and other input types, and fields can have defaults.
  • Variables are coerced and validated before any resolver runs, and all problems are reported together.
  • scalar Name declares a custom scalar; its behaviour (serialize, parseValue, parseLiteral) lives in server code. Use JSON scalars sparingly.
  • @deprecated(reason: "...") retires fields gradually.
  • Introspection (__schema, __type) lets tools read the schema from a server; NON_NULL and LIST wrap types.
  • Introspection is often disabled in production for public APIs, but is no replacement for authorization.
  • The examples that run here are stand-ins.

Next: Resolvers.