model

connector.model(fn)

Used to define your data model. This model validates inserted data and Netlify uses it to create the GraphQL schema for your connector.

Takes a function with an object as a parameter. The object contains the following properties:

Parameter	Description
`define`	Object that contains a number of methods to define models and types on your data model.
`options`	Object that contains the configuration values set for options defined using `defineOptions` in `addConnector`.
`state`	Object that contains data stored in `initState` when `addConnector` runs.

Learn more about defining your data model.

define

Contains methods to define models and types on your data model.

Method	Description
`crossReference()`	Define a cross reference type.
`document()`	Define a document model.
`enum()`	Define an enum type.
`inlineEnum()`	Define an enum type without an explicit name set in the definition.
`inlineObject()`	Define an object type without an explicit name set in the definition.
`inlineUnion()`	Define a union type without an explicit name set in the definition.
`locales()`	Define all available locales in your data source.
`object()`	Define an object type.
`union()`	Define a union type.

crossReference

define.crossReference()

Used to define a cross-reference type. Cross-reference fields allow you to specify reference fields across different connectors or across different instances of the same connector. These are cross-references that your data source can resolve.

Cross-references defined by users

Netlify also offers the ability for Connect and Visual Editor users to define cross-references across different types of data sources. For example, from Drupal to Contentstack. These cross-references are resolved by Netlify, instead of the individual data source. Connect users can define cross-references in the Netlify UI, and Visual Editor users can do the same using stackbit.config.ts.

Pass in an object with the following property:

Property	Description
`to`	Object or array of objects containing the `modelName`, `connectorName`, and `instanceID` to cross-reference to.

Usage example

// Reference a single model
connector.model(async ({ define }) => {
  const myCrossReference = define.crossReference({
      to: {
        modelName: `ExampleDocument`,
        connectorName: `example-connector`,
        instanceID: `1234`,
      },
  });
});

// Reference multiple models
connector.model(async ({ define }) => {
  const myCrossReference = define.crossReference({
      to: [
        {
          modelName: `ExampleDocument`,
          connectorName: `example-connector`,
          instanceID: `1234`,
        },
        {
          modelName: `AnotherDocument`,
          connectorName: `another-connector`,
          instanceID: `5678`,
        },
      ],
  });
});

// Define the cross-reference inline
connector.model(({ define })=>{
  define.document({
    name: `ExampleDocument`,
    fields: {
      exampleFieldName: {
        type: define.crossReference({
          to: {
            modelName: `AnotherDocument`,
            connectorName: `another-connector`,
            instanceID: `5678`,
          },
        }),
      },
    },
  })
})

document

define.document()

Used to define a document model. Pass in an object with the following properties:

Property	Description
`name`	String representing the name of the document model. For example, `Post` or `User`.
`cacheFieldName`	(optional) String representing the field to use for caching each document.
`editor`	(optional) Defines how Netlify should render the document in Visual Editor. There is also the option to define this in object and field definitions.
`fields`	Object containing each of the document model’s fields.
`isPage`	(optional) Boolean. Set to true to indicate that the document is a `page` type for Netlify Visual Editor.
`localized`	(optional) Boolean. Set to true to specify that the model is document-localized.

Note that every document has an id that is defined by default. This is the unique ID within your document model type. You don’t need to define an id property manually in your model, but you will need to set the value when you sync documents.

Usage example

connector.model(async ({ define }) => {
  define.document({
    name: "Post",
    cacheFieldName: "updatedAt",
    fields: {
      title: {
        type: "String",
      },
      updatedAt: {
        type: "String",
        required: true,
      },
    },
  });
});

editor

For use with Netlify Visual Editor only.

Property on the document that defines how Netlify should render the document in Visual Editor. There is also the option to define this in object and field definitions.

Object with the following properties:

Property	Description
`fieldGroups`	(optional) Array of objects, each with a `name`, `label` and optional `icon` — all Strings. Defines the field groups for a document model and is used in tandem with `editor.group` on the field.
`isPage`	(optional) Boolean. Set to `true` to defines the document as a Visual Editor `page` type.
`preview`	(optional) Object or function that defines how to display the document in the preview pane in Visual Editor.
`singleInstance`	(optional) Boolean. Set to `true` to define the document as a `single instance` type and ensure only one instance of the document can be created.

Usage example

define.document({
  name: `Product`,
  editor: {
    isPage: true,
    preview: () => ({
      title: `Product Title`,
      subtitle: `This is a product`,
    }),
    fieldGroups: [
      {
        name: `General`,
        label: `General Information`,
        icon: `info`,
      },
      {
        name: `SEO`,
        label: `Search Engine Optimization`,
      }
    ]
  },
  fields: {
    title: {
      type: `String`,
      editor: {
        group: `SEO`,
      },
    },
  },
});

enum

define.enum()

Used to define an enum type. Pass in an object with the following properties:

Property	Description
`name`	String representing the name of the enum.
`values`	Array of objects containing `label` and `value` string pairs.

For unnamed enum types, you can also define the models inline using inlineEnum().

Usage example

connector.model(async ({ define }) => {
  define.enum({
    name: "ExampleEnumStoplight",
    values: [
      {
        label: "Green light", // used as the GraphQL description
        value: "GREEN" // the actual enum member value
      },
      {
        label: "Yellow light",
        value: "YELLOW"
      },
      {
        label: "Red light",
        value: "RED"
      },
    ]
  })
})

inlineEnum

define.inlineEnum()

Used to define an enum type without an explicit name set in the definition. Pass in an object with the following property:

Property	Description
`values`	Array of objects containing `label` and `value` string pairs.

Usage example

connector.model(async ({ define }) => {
  define.document({
    name: "Post",
    fields: {
      content: {
        type: define.inlineEnum({
          values: [
            {
              label: "Green light", // used as the GraphQL description
              value: "GREEN" // the actual enum member value
            }
          ]
        })
      }
    }
  })
})

inlineObject

define.inlineObject()

Used to define an object type without an explicit name set in the definition. Pass in an object with the following property:

Property	Description
`fields`	Object containing each of the object’s fields.
`name`	(optional) String representing the name of the object. It will only be used to prefix the generated name.

Usage example

connector.model(async ({ define }) => {
  define.document({
    name: "Post",
    fields: {
      content: {
        type: define.inlineObject({
          fields: {
            title: {
              type: "String",
            },
          }
        })
      },
      bonusContent: {
        type: define.inlineObject({
          name: `example_name`, // generated name: inline_example_name_j2kjl4
          fields: {
            heading: {
              type: `String`,
            },
          },
        })
      }
    }
  })
})

inlineUnion

define.inlineUnion()

Used to define a union type without an explicit name set in the definition. Pass in an object with the following property:

Property	Description
`types`	Array of strings representing object types or document models.

Usage example

connector.model(async ({ define }) => {
  define.document({
    name: "Post",
    fields: {
      content: {
        type: define.inlineUnion({
          types: ["Post", "News"]
        })
      }
    }
  })
})

locales

define.locales()

Used to define all available locales in your data source. Pass in an array of objects containing the following properties:

Property	Description
`code`	String representing the locale code.
`default`	(optional) Boolean used to designate a default locale. If not set, the first locale in the array becomes the default.

Usage example

connector.model(({ define }) => {
  define.locales([
    {
      code: "en-US",
      default: true,
    },
    {
      code: "ca-FR",
    },
  ]);
});

object

define.object()

Used to define an object type. Pass in an object with the following properties:

Property	Description
`name`	String representing the name of the object.
`editor`	(optional) Defines how Netlify should render the object in Visual Editor. There is also the option to define this in document and field definitions.
`fields`	Object containing each of the object’s fields.

For unnamed object types, you can also define the models inline using inlineObject().

editor

For use with Netlify Visual Editor only.

Defines how Netlify should render the object in Visual Editor. There is also the option to define this in document and field definitions.

Object with the following properties:

Property	Description
`fieldGroups`	(optional) Array of objects, each with a `name`, `label` and optional `icon` — all Strings. Defines the field groups for an object and is used in tandem with `editor.group` in field definitions.
`preview`	(optional) Object or function that defines how to display the object in the preview pane in Visual Editor.

Usage example

// defines a Content object type
const Content = define.object({
  name: "Content",
  fields: {
    title: {
      type: "String",
    },
    editor: {
      preview: `Preview title`,
    }
  }
});

union

define.union()

Used to define a union type. Pass in an object with the following properties:

Property	Description
`name`	String representing the name of the union.
`types`	Array of strings representing object types or document models.

For unnamed union types, you can also define the models inline using inlineUnion().

Usage example

const Content = define.union({
  name: "ExampleContentUnion",
  types: ["Post", "News"]
})

connector.model(async ({ define }) => {
  const UserModel = define.document({
    name: "User",
    fields: {
      posts: {
        type: Content,
        list: true
      },
      mostPopularPost: {
        type: Content
      }
    }
  })

  define.document({
    name: "News"
    fields: {
      title: {
        type: "String"
      }
    }
  })

  define.document({
    name: "Post",
    fields: {
      author: {
        type: UserModel
      }
    }
  })
})

fields

Object used to define fields for a document model, an object type, or an inline object type. Use an object with the following properties:

Property	Description
`{field_name}`	Defined using the object property name for that field. You can use any field name except for `internal`, `id`, and `fields`. Review the usage example below for an example of how to set the name.
`editor`	(optional) Object used to set how Netlify should render the field in Visual Editor. You also have the option to specify editor settings in the document and object definitions.
`type`	String or model definition that defines the type of the field. Learn more about field types.
`required`	(optional) Boolean. Set to `true` to mark the field as required.
`list`	(optional) Boolean. Set to `true` to indicate the field is a list. To make the list required, set this property to `required` instead of `true`. For example, `list: required`.
`localized`	(optional) Boolean. Set to `true` to mark the field as localized.

editor

For use with Netlify Visual Editor only.

Defines how Netlify should render the field in Visual Editor. You also have the option to specify editor settings in document and object definitions.

Object that contains the following properties:

Property	Description
`controlType`	(optional) String that defines the UI element to display for this field. Review control type options below.
`group`	(optional) String that defines which field group a field belongs to.
`hidden`	(optional) Boolean. Set to true to hide the field.
`initialValue`	(optional) String that defines the initial value of the field that Netlify will display in the Visual Editor. Note that this does not set a default value for the field when syncing data.
`label`	(optional) String representing the label to display.
`numberOptions`	(optional) Object. Specify the `min`, `max`, `step`, and `unit` values for number fields. Can use with or without the controlType `slider`.
`preview`	(optional) Object or function that defines how to display the field in the preview pane in Visual Editor. For each field type, the function signature is different, check the TypeScript types in your editor for the exact signature.
`readOnly`	(optional) Boolean. Set to true to display the field as read-only.

Control type options

You can set controlType to the following values, depending on the field type:

Field type	Supported Control Types
Enum	`button-group`, `dropdown`, `palette`, `palette-colors`
Boolean	`button-group`, `checkbox`
Number	`slider`
Asset	`file` (default), `image`

Usage example

const EnumExample = define.enum({
  name: `EnumExample`,
  options: [`Option 1`, `Option 2`, `Option 3`],
});

// Netlify will display a dropdown picker for the first field, and a button group picker
// for the second field in Visual Editor
define.document({
  name: `Product`,
  fields: {
    dropdownField: {
      type: EnumExample,
      editor: {
        controlType: `dropdown`,
      },
    },
    buttonGroupField: {
      type: EnumExample,
      editor: {
        controlType: `button-group`,
      },
    },
  },
});

// This field will have the label "Product Title" in Visual Editor
define.document({
  name: `Product`,
  fields: {
    title: {
      type: `String`,
      editor: {
        label: `Product Title`,
        readOnly: true,
      },
    },
  },
})

// Note that preview doesn’t need to be a function, it can be an object instead.
// The function receives args relevant to the type of field the preview is for
define.document({
  name: `Product`,
  fields: {
    title: {
      type: `String`,
      editor: {
        preview: ({ document }) => ({
          title: document.fields.title.value,
          subtitle: document.fields.content.value.substring(0, 20),
          image: document.fields.seo.fields.image.fields.url
        })
      },
    },
  },
})


// This field will have the initial value of `Initial Title` in the Visual Editor
define.document({
  name: `Product`,
  fields: {
    title: {
      type: `String`,
      editor: {
        initialValue: `Initial Title`,
      },
    },
  },
})

// This will place the `title` field in the `SEO` field group
define.document({
  name: `Product`,
  editor: {
    fieldGroups: [
      {
        name: `General`,
        label: `General Information`,
        icon: `info`,
      },
      {
        name: `SEO`,
        label: `Search Engine Optimization`,
      }
    ]
  },
  fields: {
    title: {
      type: `String`,
      editor: {
        group: `SEO`,
      },
    },
  },
})

// When the controlType is `slider`, Netlify will display an interactive slider in the Visual
// Editor. If controlType is ommited, an input field will be displayed by default.
define.document({
  name: `Product`,
  fields: {
    price: {
      type: "Float",
      editor: {
        controlType: `slider`,
        numberOptions: {
          min: 0,
          max: 100,
          step: 0.01,
          unit: `USD`,
        },
      },
    },
  },
})

Field types

The fields on your document model or object type can use the following as a type:

Type	Description
Built-in scalars	`String`, `Int`, `Float`, `Boolean`, `JSON`, and `Date`.
Mapped built-in scalars	`string` (mapped to `String`), `integer` (`Int`), `number` (`Float`), `boolean` (`Boolean`), `json` (`JSON`), `date` (`Date`).
Built-in types to support visual editor features	`Asset`, `url`, `slug`, `markdown`, `html`, `datetime`, `color`, `richText`, `file`, `enum`, `image`, `reference`, `style`.
Cross-reference	Cross-reference type that you’ve defined.
Documents	Another document model you’ve defined. Setting a document model as the type of a field automatically makes that field a relationship field.
Enums	Enum type that you’ve defined.
Objects	Object type that you’ve defined.
Unions	Union type that you’ve defined.

If you have a type that is only used once, you can define it inline within another field definition. This can be convenient when automatically generating models and types.

Usage example

connector.model(async ({ define }) => {
  // this defines an object type that we store in a variable called ContentType
  const ContentType = define.object({
    name: "Content",
    fields: {
      title: {
        type: "String",
      },
    },
  });

  // this defines a document model `Post` with two fields: `title`, and `content`.
  // `title` is a field with `String` type and is required.
  // `content` is a field with the `ContentType` object type, defined above
  define.document({
    name: "Post",
    fields: {
      title: {
        type: "String",
        required: true,
      },
      content: {
        type: ContentType,
      },
    },
  });
});

Got it!

Your feedback helps us improve our docs.

model

define

crossReference

Usage example

document

Usage example

editor

Usage example

enum

Usage example

inlineEnum

Usage example

inlineObject

Usage example

inlineUnion

Usage example

locales

Usage example

object

editor

Usage example

union

Usage example

fields

editor

Control type options

Usage example

Field types

Usage example

Did you find this doc useful?

Got it!