Field Types

Your schema is built up of GraphQL types. If you’re familiar working with GraphQL, you should feel right at home. GraphCMS supports all of the common GraphQL types you are used to, as well as some of its own.

You may also be interested in how input types work for filtering, ordering, paginating, and mutating data.

Here you will discover the core field types available when building your GraphCMS schema. Since your schema is automatically generated, it is recommended you browse the API Playground to get inspect all available field type definitions.

StringAnchor

GraphCMS supports a few variations of the String field type. Strings are just strings, but depending on the variation you add to your model, it will reflect how it appears to content editors.

All 3 variations of the String type are queried in the same way, and return the strings of the field they represent:

{
  products {
    singleLineTextField
    multiLineTextField
    markdownField
  }
}

{
  "data": {
    "products": [
      {
        "singleLineTextField": "GraphCMS Mug",
        "multiLineTextField": "Welcome to GraphCMS",
        "markdownField": "# Hello"
      }
    ]
  }
}

Rich TextAnchor

The RichText field type is an advanced String field that returns your content in 4 different formats; raw, html, markdown, and text.

The Rich Text field renders an advanced textarea with tools to add headings, links, tables, images, lists, etc.

When a Rich Text field is added to your model, it will automatically generate the following types:

type RichText {
  raw: RichTextAST!
  html: String!
  markdown String!
  text: String!
}

For example, we can query all of those on our RichText field type content:

{
  posts {
    content {
      raw
      html
      markdown
      text
    }
  }
}

{
  "data": {
    "posts": [
      {
        "content": {
          "raw": {
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "text": "GraphQL CMS"
                  }
                ]
              }
            ]
          },
          "html": "<p>GraphQL CMS</p>",
          "markdown": "GraphQL CMS\n",
          "text": "GraphQL CMS"
        }
      }
    ]
  }
}

You can also embed Assets inside Rich Text.

You will need to enable Rich Text Embeds. You can do this from inside the Field Settings when adding a new, or editing a Rich Text field.

With Rich Text Embeds enabled, your API will have some new types added. The name of your field will be now a type appended by RichText, and RichTextEmbeddedTypes inside your schema.

For example, if you had the model Post and field content, the types generates would be PostContentRichText, and PostContentRichTextEmbeddedTypes respectively.

The PostContentRichText type will look like the following:

type RichText {
  json: RichTextAST!
  html: String!
  markdown String!
  text: String!
  references: [PostContentRichTextEmbeddedTypes!]!
}

The references field will be a union relation to the types you embedded, for example Asset.

You should use the references field when querying json to get the url (with any transformations, handle, or any of the Asset fields.

{
  posts {
    content {
      json
      html
      markdown
      text
      references {
        __typename
        ... on Asset {
          url
          handle
        }
      }
    }
  }
}

{
  "data": {
    "posts": [
      {
        "content": {
          "json": {
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "text": "GraphCMS Rich Text Embeds"
                  }
                ]
              },
              {
                "type": "embed",
                "nodeId": "cko2lq2u0031r0844xnvurz05",
                "children": [
                  {
                    "text": ""
                  }
                ],
                "nodeType": "Asset"
              },
              {
                "type": "paragraph",
                "children": [
                  {
                    "text": ""
                  }
                ]
              }
            ]
          },
          "html": "<p>GraphCMS Rich Text Embeds</p><div data-gcms-embed-type=\"Asset\" data-gcms-embed-id=\"cko2lq2u0031r0844xnvurz05\"></div><p></p>",
          "markdown": "GraphCMS Rich Text Embeds\n\n\n",
          "text": "GraphCMS Rich Text Embeds\\n\\n",
          "references": [
            {
              "__typename": "Asset",
              "url": "https://media.graphcms.com/xSIoGkATQybd8S2SgA5Q",
              "handle": "xSIoGkATQybd8S2SgA5Q"
            }
          ]
        }
      }
    ]
  }
}

The html response will return gcms-embed-type and gcms-embed-id data attributes for the embedded types.

<div
  data-gcms-embed-type="Asset"
  data-gcms-embed-id="cko2lq2u0031r0844xnvurz05"
></div>

GraphCMS uses Slate 0.5 for RichTextAST.

IntegerAnchor

Integers are whole numbers, and are often used to reference price in cents, stock quantities etc..

For example, here we have products with a Int field for price:

{
  products {
    price
  }
}

{
  "data": {
    "products": [
      {
        "price": 1000
      }
    ]
  }
}

FloatAnchor

Floats are floating point numbers, and often represent fractional values. They are often used to describe values with precision, such as distance, weight, volume, etc.

For example, here we have products with a Float field for rating:

{
  products {
    rating
  }
}

{
  "data": {
    "products": [
      {
        "rating": 4.5
      }
    ]
  }
}

BooleanAnchor

Booleans default to null in GraphCMS, and can be true or false. You may opt to use a Boolean for specifying if a product is on sale, is part of a bundle, or a post accepts comments.

For example, here we have posts with a Boolean field for acceptsComments:

{
  products {
    acceptsComments
  }
}

{
  "data": {
    "products": [
      {
        "acceptsComments": true
      },
      {
        "acceptsComments": false
      },
      {
        "acceptsComments": null
      }
    ]
  }
}

DateAnchor

The Date field type adheres to ISO 8601 standard. This means, October 7, 1989 is represented as 1989-10-07.

For example, here we have events with a Date for start:

{
  events {
    start
  }
}

{
  "data": {
    "events": [
      {
        "start": "1989-10-07"
      }
    ]
  }
}

Date and TimeAnchor

Similar to the date field type, the DateTime field type adheres to ISO 8601 standard.

For example, here we have events with a DateTime for start:

{
  events {
    start
  }
}

{
  "data": {
    "events": [
      {
        "start": "1989-10-07T09:30:00+00:00"
      }
    ]
  }
}

JSONAnchor

GraphCMS has native field support for JSON (JavaScript Object Notation). This field is often used for storing large amounts of data from other systems.

For example, here we have products with a JSON field for metadata:

{
  products {
    metadata
  }
}

{
  "data": {
    "products": [
      {
        "metadata": {
          "values": [10, 20, 30],
          "analyticsId": "ifuhue398"
        }
      }
    ]
  }
}

AssetAnchor

Assets are connected to models through a reference field. Assets can be any file type, not just images.

The Asset model comes its own default asset fields.

For example, here we have posts with a the Asset field for coverImage, querying those asset fields:

{
  posts {
    coverImage {
      url
      handle
      fileName
      height
      width
      size
      mimeType
    }
  }
}

{
  "data": {
    "posts": [
      {
        "coverImage": {
          "url": "https://media.graphcms.com/bh4xr7efSZyBh4iVeGQq",
          "handle": "bh4xr7efSZyBh4iVeGQq",
          "fileName": "Examples - Swag Store.png",
          "height": 720,
          "width": 1280,
          "size": 116893,
          "mimeType": "image/png"
        }
      }
    ]
  }
}

{
  "data": {
    "ebooks": [
      {
        "file": {
          "url": "https://media.graphcms.com/pJOCAOncQO6K7azJbagS",
          "handle": "pJOCAOncQO6K7azJbagS",
          "fileName": "GraphCMS eBook - Navigating Towards Tomorrow-s Content with a Headless CMS.pdf",
          "height": null,
          "width": null,
          "size": 2345835,
          "mimeType": "application/pdf"
        }
      }
    ]
  }
}

Learn more about Assets.

ColorAnchor

The Color field is made up of HEX, RGBA and css color values.

type Color {
  hex: Hex!
  rgba: RGBA!
  css: String!
}

For example, here is posts with a Color field for backgroundColor, in all formats:

{
  posts {
    backgroundColor {
      hex
      rgba {
        r
        g
        b
        a
      }
      css
    }
  }
}

{
  "data": {
    "posts": [
      {
        "backgroundColor": {
          "hex": "#ffffff",
          "rgba": {
            "r": 255,
            "g": 255,
            "b": 255,
            "a": 1
          },
          "css": "rgb(255,255,255)"
        }
      }
    ]
  }
}

LocationAnchor

The Location field type returns latitude, longitude, and distance Float values.

type Location {
  latitude: Float!
  longitude: Float!
  distance(from: LocationInput!): Float!
}

To query the distance field, you must provide latitude and longitude values for the from argument.

For example, here we have all shop locations, with distance from the provided latitude/longitude:

{
  shops {
    location {
      latitude
      longitude
      distance(
        from: { latitude: 50.58153970000001, longitude: 8.665300199999999 }
      )
    }
  }
}

{
  "data": {
    "shops": [
      {
        "location": {
          "latitude": 48.7…,
          "longitude": -122.5…,
          "longitude": 8.66…
        }
      }
    ]
  }
}

EnumerationsAnchor

Enumerations, or enum for short, are predefined list of values. They are defined inside your GraphQL schema, and can be referenced by any of your content models.

For example, here is are products with its commodity type:

{
  products {
    commodity
  }
}

{
  "data": {
    "products": [
      {
        "commodity": "Digital"
      }
    ]
  }
}

ReferenceAnchor

References, often referred as relations, are a powerful field type that allows you to connect one or more models together, and even reference multiple models as a single field type with GraphQL Union Types.

For example, here we have an example of querying all products, with categories they belong to.

{
  products {
    name
    category {
      name
    }
  }
}

{
  "data": {
    "products": [
      {
        "name": "ACME Hammer",
        "category": [
          {
            "name": "ACME Products"
          },
          {
            "name": "Shop Tools"
          }
        ]
      },
      {
        "name": "ACME Shovel",
        "category": [
          {
            "name": "ACME Products"
          },
          {
            "name": "Garden Tools"
          }
        ]
      }
    ]
  }
}

One-way referencesAnchor

One-way references - also called unidirectional relations - only exist in one direction. This type of reference is most useful when there is no need to know where a model is being referenced from, such as a model that is used many times. One-way references only show up on the model for which the reference is configured, and can only be queried from that side as well. This also means that for one-way references, no reverse field is configured on the referenced model. With one-way references, the content editor UI is kept clean by not showing irrelevant relations where they are not needed.

One-way references come in two forms:

To OneAnchor

For example, a category that can have only one product.

To manyAnchor

For example, a category that can have multiple products.

Two-way referencesAnchor

Two-way references - alternatively known as bidirectional relations - exist in two directions. This type of reference is useful for use cases where both sides of the reference are relevant, and need to be edited or queryable. Two-way references are configured and show up on both the referencing and referenced models, and can be queried from either side.

Two-way references come in four forms:

One to oneAnchor

For example, a category can only have one product, and one product can only have one category.

One to manyAnchor

For example, a category can have multiple products, but a product cannot belong to multiple categories.

Many to oneAnchor

For example, a category has one product, but a product can belong to multiple categories.

Many to manyAnchor

For example, a category can have many products, and products can belong to many categories.

UnionAnchor

GraphQL Union Types are great for referencing different models as a single field.

For example, here we have a typical GraphQL query for fetching blocks on a page.

This field is configured to be either of type Hero, Grid, and/or Gallery:

{
  pages {
    blocks {
      __typename
      ... on Hero {
        title
        ctaLink
      }
      ... on Grid {
        title
        subtitle {
          markdown
        }
      }
      ... on Gallery {
        photos {
          url
          handle
        }
      }
    }
  }
}

Please note that unions are always two-way references.

RemoteAnchor

Remote fields allow you to define an external resolver through the management SDK. Remote fields consist of two parts, defining any custom type that will represent the returning shape from the external resolver, defining the resolver itself.

Return TypesAnchor

Return types can be any valid GraphQL Scalar (ID, String, Boolean, Int, Float), any GraphCMS Custom Scalar (Long, JSON, DateTime, Date), any GraphCMS Type (Color, Location, RichText) or any custom type as defined by the user.

Learn about creating custom types.

Resolver configurationAnchor

Resolvers are functions that accept standard HTTP requests (GET, PUT, POST) and can have custom headers and payloads. Resolvers make use of a replacer pattern and can support string interpolation in either the header or the url. Data can be sent either using the string interpolation method, as automatically appended query parameters, or as a JSON payload.

Using our product example from above, let's add a remote field that fetches real-time inventory numbers from our warehouse.

{
  products {
    name
    inventory {
      available # Coming from our remote resolver
    }
  }
}

{
  "data": {
    "products": [
      {
        "name": "ACME Hammer",
        "inventory": {
          "available": true
        }
      },
      {
        "name": "ACME Shovel",
        "inventory": {
          "available": true
        }
      }
    ]
  }
}

Field VisibilityAnchor

GraphCMS field types allow for different visibility options via the Advanced tab during field creation. Below is a reference for the different options and how they are different.

Note that these options are available for all field types except for References.