Logo
NeoArc Studio

Custom Scalars

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

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:

Custom Scalar Properties

Common Custom Scalars

Specification URLs

Link to authoritative specifications for standard formats:

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!"
}

Related Content