Custom Scalars

Define custom scalar types like DateTime, JSON, and URL with specification URLs, serialisation formats, and coercion rules.

February 4, 2026

Custom scalars extend GraphQL's type system beyond the five built-in scalars (String, Int, Float, Boolean, ID). Use custom scalars to represent domain-specific values with clear serialisation rules and validation.

Built-in Scalars

GraphQL provides five built-in scalar types:

Scalar	Description	Example
String	UTF-8 character sequence	"hello"
Int	32-bit signed integer	42
Float	Double-precision floating point	3.14
Boolean	True or false	true
ID	Unique identifier (serialised as string)	"user-123"

Custom Scalar Properties

Property	Required	Description
id	Yes	Unique identifier
name	Yes	Scalar type name (e.g., "DateTime")
description	No	Explanation of the scalar's purpose and format
specUrl	No	URL to specification (e.g., RFC document)
serializationFormat	No	Wire format description
exampleValues	No	Array of example values
coercesFrom	No	Types that can be coerced to this scalar
coercesTo	No	Types this scalar can be coerced to

Common Custom Scalars

Specification URLs

Link to authoritative specifications for standard formats:

Format	Specification URL
DateTime	https://www.iso.org/iso-8601-date-and-time-format.html
UUID	https://datatracker.ietf.org/doc/html/rfc4122
Email	https://datatracker.ietf.org/doc/html/rfc5322
URL	https://datatracker.ietf.org/doc/html/rfc3986
JSON	https://www.json.org/
Duration	https://www.iso.org/iso-8601-date-and-time-format.html

Coercion Rules

Coercion defines how values convert between types. Document coercion to help clients understand type compatibility.

{
  "id": "scalar-positive-int",
  "name": "PositiveInt",
  "description": "Integer greater than zero",
  "exampleValues": ["1", "42", "1000"],
  "coercesFrom": ["Int", "String"],
  "coercesTo": ["Int", "String", "Float"]
}

coercesFrom - Types that can be converted to this scalar. For example, a PositiveInt can be created from an Int or a numeric String.

coercesTo - Types this scalar can be converted to. For example, a PositiveInt can be used where an Int, String, or Float is expected.

Example Values

Provide representative example values to illustrate the expected format:

{
  "id": "scalar-phone",
  "name": "PhoneNumber",
  "description": "Phone number in E.164 format",
  "specUrl": "https://www.itu.int/rec/T-REC-E.164",
  "serializationFormat": "+[country code][subscriber number]",
  "exampleValues": [
    "+44 20 7946 0958",
    "+1 415 555 2671",
    "+81 3 1234 5678"
  ]
}

Using Scalars in Operations

Reference custom scalars in arguments and return types by their name:

{
  "name": "createEvent",
  "operationType": "mutation",
  "arguments": [
    {
      "name": "title",
      "typeName": "String",
      "nullable": false
    },
    {
      "name": "startTime",
      "typeName": "DateTime",
      "nullable": false,
      "description": "Event start time in ISO 8601 format"
    },
    {
      "name": "endTime",
      "typeName": "DateTime",
      "nullable": false
    },
    {
      "name": "notificationEmail",
      "typeName": "Email",
      "nullable": true,
      "description": "Email address for event reminders"
    }
  ],
  "returnTypeName": "Event!"
}