GraphQL Schema

Declare a Sanity schema using GraphQL SDL syntax

Community contributed

Install command

yarn add sanity-graphql-schema

sanity-graphql-schema

Declare a Sanity schema using GraphQL SDL syntax. Try the demo?

Auto-infers title from type/field names (leadAsset -> Lead asset)
Type names are automatically camelcased (BlogPost -> blogPost)
Types that implement "Document" is made into document types
Document types as field type assumed to be references, object types as inline
- Use @inline directive to use document type embedded into parent document
Directives for most schema type options
"Non null" treated as "required" validation rule (only enforced in Studio)

Installation

# In your Sanity studio folder
yarn add sanity-graphql-schema

Basic usage

In your schema entry point (usually schemas/schema.js), you normally have something along the lines of this:

import createSchema from 'part:@sanity/base/schema-creator'
import schemaTypes from 'all:part:@sanity/base/schema-type'

import author from './author'

export default createSchema({
  name: 'default',
  types: schemaTypes.concat([author])
})

To use this module, import it, call the imported function with a GraphQL schema defined in the GraphQL schema definition language, and replace the value passed to createSchema() with the output:

import createSchema from 'part:@sanity/base/schema-creator'
import {fromGQL, graphql} from 'sanity-graphql-schema'

const schema = graphql`
  type Author implements Document {
    name: String!
    profileImage: Image
  }

  type BlogPost implements Document {
    title: String!
    slug: Slug
    body: Text
    leadImage: CaptionedImage
    tags: [String!]! @display(layout: "tags")
    author: Author!
  }

  type CaptionedImage implements Image {
    caption: String!
  }
`

export default createSchema({
  name: 'default',
  types: fromGQL(schema)
})

Directives

@display(title: String, icon: String, layout: String) Allows you to:
- Set title of fields and types, overriding the auto-generated title
- Set layout mode for a field (for instance, set tags as layout for an array field)
- Set icon for document types by passing an icon ID (see example below)

@fieldsets(from: [SanitySchemaFieldSet!]!) Set the fieldsets available for an object/document type. Takes an array of {name, title} pairs
@fieldset(set: String!) Assign a field to a given fieldset
@orderings(from: [SanitySchemaOrdering!]!) Set the available ordering options for a document type. Takes an array of {name, title, by} pairs - see Sanity documentation for more information

@enum(values: [SanityNameTitlePair!]!, layout: String, direction: String) Set on string fields if you only want to allow certain values.
- values takes an array of {name, title} pairs.
- layout can be one of dropdown or radio, dropdown being the default.
- direction determines which way radio buttons flow (horizontal, vertical)

@extract(metadata: [String!]!, originalFilename: Boolean) Set on fields of type Image or File to determine which metadata to extract, and whether or not to store the original filename
@slug(source: String, maxLength: Int) Set on fields of type Slug, determines which field to generate slugs from, or set maximum length of the slug.
@hotspot Set on image fields to opt-in to the hotspot/crop functionality
@inline Set on fields that use a document type as it's value if you want to embed the value instead of referencing an existing document
@hidden Set on fields to hide them from the user interface, yet still be recognized by the underlying schema machinery
@readOnly Set on fields to that should not be editable from the studio

Todo

Generate GQL types for custom types (color input, for instance)
Custom scalars (markdown)
Throw on non-reference union fields
Better error handling
Blocks/spans
Validation directives
Inject icons, input components as options argument
JSON scalar for arbitrary input for custom types? Or options as dotpath? Both?

Developing

git clone git@github.com:rexxars/sanity-graphql-schema.git
cd sanity-graphql-schema
npm install
npm test