Function defineType

Helper function for defining a Sanity type definition. This function does not do anything on its own; it exists to check that your schema definition is correct, and help autocompletion in your IDE.

This function will narrow the schema type down to fields and options based on the provided type-string.

Schema types defined using defineType should typically be added to the Studio config under schema.types. Defined types can be referenced by their name. This is referred to as a type-alias.

When using type-aliases as type, defineType cannot know the base-type, so type-safety will be reduced. If you know the base type of the type-alias, provide defineOptions.aliasFor: <base type name>. This will enforce that the schema definition conforms with the provided type.

By default, defineType only allows known properties and options. Use defineOptions.strict: false to allow unknown properties and options.

Basic usage

defineType({
  type: 'object',
  name: 'custom-object',
  fields: [ {type: 'string', name: 'title', title: 'Title'}],
})
Copy

Usage with aliasFor narrowing

defineType({
  type: 'custom-object',
  name: 'redefined-custom-object',
  options: {
    columns: 2
  }
}, {aliasFor: 'object' })
Copy

Allow unknown properties

defineType({
  type: 'custom-object',
  name: 'redefined-custom-object',
  allowsUnknownProperties: true
  options: {
    columns: 2,
    allowsUnknownOptions: true
  }
}, {strict: false})
Copy

Maximum safety and best autocompletion

Use defineType, defineField and defineArrayMember:

 defineType({
   type: 'object',
   name: 'custom-object',
   fields: [
     defineField({
       type: 'array',
       name: 'arrayField',
       title: 'Things',
       of: [
         defineArrayMember({
           type: 'object',
           name: 'type-name-in-array',
           fields: [defineField({type: 'string', name: 'title', title: 'Title'})],
         }),
       ],
     }),
   ],
 })
Copy

Note on type-safety in the current implementation

Type-safety inside array-like properties (schema properties like fields and of) can only be guaranteed when defineField and defineArrayMember are used to wrap each value in the array.

For array-values without a function-wrapper, TypeScript will resolve to a union type of all possible properties across all schema types. This result in less precise typing.

Extending the Sanity Schema types

If you want to extend the Sanity Schema types with your own properties or options to make them typesafe, you can use TypeScript declaration merging.

With declaration merging, properties and options will be available in a type-safe manner, and strict: false will not be necessary.

Example: Add option to StringOptions

// string.ts

//redeclare the sanity module
declare module 'sanity' {
 // redeclare StringOptions; it will be merged with StringOptions in the sanity module
 export interface StringOptions {
   myCustomOption?: boolean
 }
}

// the option is now part of the StringOptions type, just as if it was declared in the sanity codebase:
defineType({
  type: 'string',
  name: 'my-string',
  options: {
    myCustomOption: true // this does not give an error anymore
  }
})

Copy

Example: Add a schema definition to "intrinsic-types"

//my-custom-type-definition.ts

// create a new schema definition based on object (we remove the ability to assign field, change the type add some options)
 export type MagicallyAddedDefinition = Omit<Schema.ObjectDefinition, 'type' | 'fields'> & {
   type: 'magically-added-type'
   options?: {
     sparkles?: boolean
   }
 }

 // redeclares sanity module so we can add interfaces props to it
declare module 'sanity' {
    // redeclares IntrinsicDefinitions and adds a named definition to it
    // it is important that the key is the same as the type in the definition ('magically-added-type')
    export interface IntrinsicDefinitions {
      'magically-added-type': MagicallyAddedDefinition
    }
}

// defineType will now narrow `type: 'magically-added-type'` to `MagicallyAddedDefinition`
defineType({
  type: 'magically-added-type'
  name: 'magic',
  options: {
    sparkles: true // this is allowed,
    //@ts-expect-error this is not allowed in MagicallyAddedDefinition.options
    sparks: true
  }
})
Copy