Object

The object type is the bread and butter of your data model. You use it to define custom types that has fields of strings, numbers, arrays as well as other object types.

Note: By default, object types can not be represented as standalone documents in the data store. If you want to define an object type that you'd like to be represented as a document with an id, revision and created and updated timestamps, you should define it using the document type instead. Apart from these additional fields, there's no semantic difference between a document and an object.

Protip

If you plan to use your schemas with the GraphQL API, you'll need to import object types on the top-level (called “hoisting”). Learn more about how to make “strict schemas” in our GraphQL documentation.

Properties

  • REQUIREDtypestring

    Value must be set to object.

  • REQUIREDfieldsarray

    The fields of this object. At least one field is required. See documentation below.

  • fieldsetsarray

    A list of fieldsets that fields may belong to. Documentation below.

  • previewobject

    Use this to implement an override for the default preview for this type. Documentation here.

Options

  • collapsibleboolean

    If set to true, the object will make the fields collapsible. By default, objects will be collapsible when reaching a depth/nesting level of 3. This can be overridden by setting collapsible: false

  • collapsedboolean

    Set to true to display fields as collapsed initially. This requires the collapsible option to be set to true and determines whether the fields should be collapsed to begin with.

Validation

  • required()function

    Ensures that this field exists.

  • custom(fn)function

    Creates a custom validation rule.

Fields

Fields are what gives an object its structure. Every field must have a name and a type. You may specify the properties and options that are supported for the given type, e.g.:

{
  title: 'Address',
  name: 'address',
  type: 'object',
fields: [
{name: 'street', type: 'string', title: 'Street name'},
{name: 'streetNo', type: 'string', title: 'Street number'},
{name: 'city', type: 'string', title: 'City'}
]
}

Once a type is added to the schema, it can be reused as the type for other fields, so lets use it in our screening:

Input

{
  title: 'Screening',
  name: 'screening',
  type: 'document',
  fields: [
    // ... 
      {
      title: 'Cinema address',
      name: 'address',
      type: 'address'
    }
    // ... 
  ]
}

Output

{
  "_type": "screening",
  "_id": "2106a34f-315f-44bc-929b-bf8e9a3eba0d",
  "title": "Welcome to our premiere of Valerian and the City of a Thousand Planets!",
  //...
  "address": {
    "_type": "address",
    "street": "Dronningens gate",
    "streetNo": "16",
    "city": "Oslo"
  }
  //...
}

Field names

A field name must start with a letter from a-z, and can can only include:

  • Letters
  • Numbers
  • Underscores

This means field names can't contain hyphens. We also recommend using the camel case naming convention for field names.

Additional Field options

Sometimes you may have fields which are not meant to be exposed to the editors through the studio, but are populated by backend services or scripts. By setting the hidden property to true, you can make sure that the field is still included in the schema but not displayed in the studio. Example:

{
  title: 'Movie',
  name: 'movie',
  type: 'document',
  fields: [
    // ... other fields
    {
      title: 'Last synchronized',
      name: 'lastSynced',
      description: 'Timestamp the movie was last synced with external service. Not shown in studio.',
      type: 'datetime',
      hidden: true
    }
  ]
}

Fieldsets

Sometimes it makes sense to group a set of fields into a fieldset. Say you want the social fieldset, to be grouped together in Sanity Studio like this:

Input

{
  type: 'object',
  name: 'person',
  fieldsets: [
    {name: 'social', title: 'Social media handles'}
  ],
  fields: [
    {
      title: 'String',
      name: 'name',
      type: 'string'
    },
    {
      title: 'Twitter',
      name: 'twitter',
      type: 'string',
      fieldset: 'social'
    },
    {
      title: 'Instagram',
      name: 'instagram',
      type: 'string',
      fieldset: 'social'
    },
    {
      title: 'Facebook',
      name: 'facebook',
      type: 'string',
      fieldset: 'social'
    }
  ]
}

Output

// Values will still appear at the same level in the data
{
  "name": "Somebody",
  "twitter": "@somebody",
  "instagram": "@somebody",
  "facebook": "somebody"
}

Fieldsets takes the same collapsible options as described for objects above, e.g.:

{
  title: 'Social media handles',
  name: 'social',
options: {collapsible: true, collapsed: false}
}