Guides

Data models represent the underlying structure of your store's data, including products, orders, accounts, and system events. You can think of them as tables or collections in a database, but with a consistent schema and API endpoints for each.

All of Swell's built-in commerce functionality uses these models, and they are completely customizable—you can even create your own. We also have content models, which use a simpler configuration syntax that's perfect for setting up editable content structures in the dashboard.

Together, these allow for unlimited flexibility around data modeling, meaning custom business logic and content can be implemented without needing to use an external database or CMS.

👉

You can use the Model explorer in the dashboard to visualize all of your store's data models. If you want a JSON representation, this schema is a meta model available via the Backend API at /:models

Swell utilizes two different types of models, each with its own intended functionality:

  • Content models work similarly to a CMS and can be used to model editable structured content any way you like.
  • Data models are for Swell's built-in commerce functionality and can be customized to suit your business needs.

Content Models:

  • Expanded set of field types with input UI components and validation options
  • Fields on standard models can be placed in the dashboard and edited by admins
  • Models and their fields have dedicated places in the dashboard for managing items
  • Content models can have their own collection endpoint, attach fields to standard data models (e.g. products), or be abstract sets of fields used within other models
  • Models with custom collections have entries accessible at /content/[collection]

Data models:

  • Basic field types
  • Editing UI only for standard model
  • No UI for custom models or fields
  • All models have a top level endpoint
  • Content models automatically generate an associated data model if they need to be accessible via their own API endpoint

Since data models are low-level configurations with primitive field types like string and boolean, they're best used to store data that will be accessed programmatically or through a custom UI. If you want to provide the ability for admins to edit field values in the dashboard or storefront editor similarly to a CMS, content models are a better fit.

Content models are a layer above data models and have a simpler configuration syntax and allow for field values to be editable in the dashboard. They provide most of the functionality you'd expect from a dedicated CMS—with the additional benefit of making content available in the same API as standard models like products. While data models are limited to primitive field types like string, content models can define input UIs for fields like phone_number or url to provide a better editing experience. This ensures that the data is entered in the correct format.

Content models can be used to:

  • Add new fields to existing models that can be edited in the dashboard, like extra details about orders or customers.
  • Add new collections of custom content that are available via API, like pages or blogs.
  • Create repeatable and modular components that can be used to build custom page layouts with structured content blocks.

An example of a content model:

Example of a content model
{
	id: 'product_detail_page', // Required
  name: 'Product detail page', // Required
  description: "Page displaying a single product", // Optional
  collection: "products", // Optional
  fields: [
		{ ... },
		{ ... },
		{ ... }
	]
}

Content model attributes:

  • id is what the model is referred to in code
  • name and description are used in the dashboard to help admins understand what the model is and what it is used for
  • collection is used to determine where the content model will exist
  • fields are the set child fields the model contains

Content models work in a similar way to data models, but they have a simpler definition syntax. Their use is focused on building flexible content structures and an intuitive editing UI within the dashboard.

You can manage content models in three ways:

  • From the dashboard, under Developer > Models
  • Within the config folder for a storefront app
  • Via the Backend API

The collection attribute determines where the model's data is stored, and whether it has an API endpoint.

01
Within an existing data model

Using the ID of a data model will attach the content model to it. The fields of the content model become available on all entries in that collection.

⚠️

As data models are the underlying storage mechanism for all data in Swell, deleting a data model will also break any of its associated content models.

02
In a new model

A new collection and an underlying data model is created if the collection isn't a standard model. All objects of the content model will be available at that collection endpoint. e.g. defining a content model with a country field and collection: 'producers' would result in the entires being available at the /producers endpoint and producer.country

  • More detail on the model attribute, how to do embedded models vs models that have an endpoint
👉

You can put fields from content models on the object root of standard models instead of nested under content, however this may lead to unexpected behavior when using storefront apps which use content models like pages.

  • Field IDs can be arbitrary object paths, which allows for logical grouping of things, and reliable paths even when moving fields between the root and field groups.
  • Brief overview of the different field types and how the ui attribute is used
03
Floating/Detached

Omitting the collection attribute makes the model abstract, meaning there's no collection or API endpoint where entries can be fetched directly. This is ideal for defining smaller groups of fields that are used within other content models, without polluting the global schemamaking sets of fields reusable in multiple places makes the job of content editors and developers much simplerresulting in more consistent structures.

Fields are a powerful way to shape structured content and define appropriate input components for admins. A field's type and ui can be specified to determine the most appropriate formatting and editing experience from within the dashboard. If omitted or unspecified, the field type's relative default UI will be used.

💡

A full list of field types can be found in the Backend API reference.

Take the boolean field type for example:

{
  id: ...,
  label: ...,
  type: 'boolean', // Required
  ui: 'checkbox|toggle',
} //Here the supported UI types are either a checkbox or toggle.

{
  id: ...,
  label: ...,
  type: 'boolean', // Required
} //If unspecified, the field type will display as a checkbox in the dashboard.

The Collection field:

  • The collection field type can be used to infinitely nest fields and references to other content entries
  • Repeat fields
  • use abstract content models within fields

Being able to create native-level data models and add to existing ones provides the opportunity to make your store work exactly how you need it to. Here are a few ideas to help illustrate when you may want to edit or create a model.

  • Capture additional data for reporting
  • Build two-sided marketplaces with split payments to vendors
  • Customize events and notifications

Below are some examples of how to add custom fields to models and how to create new models.

This is useful if you want to add additional fields to existing models like products or orders. For example, you could add a manufacturer_name field to all products:

💡

All fields should be named using snake_case.

01
Define the field
// Define the field
await swell.put('/:models/products/fields', {
  manufacturer_name: {
		type: 'string'
	}
})

// Now that the field exists, you can set the value:

// Note that {id} in the endpoint string is substituted with id from the object, 
// but you could also pass the id directly in the endpoint string if you prefer.
await swell.put('/products/{id}', {
	id: 'everlasting-sunscreen',
  manufacturer_name: 'Acme Corporation'
})
02
Now that the field exists, you can set the value
// Note that {id} in the endpoint string is substituted with id from the object, 
// but you could also pass the id directly in the endpoint string if you prefer.
await swell.put('/products/{id}', {
	id: 'everlasting-sunscreen',
  manufacturer_name: 'Acme Corporation'
})
03
Fetching that product will show the newly-added field at the root level
await swell.get('/products/{id}', {
	id: 'everlasting-sunscreen'
})
04
Result
{
	id: '627d93e8ff7ce54cc71e380g',
	slug: 'everlasting-sunscreen',
  ...
	manufacturer_name: 'Acme Corporation'
	...
}
	
05
Using relationships allows for linking between models
// Basic and relationship fields
await swell.put('/:models/accounts/fields', {
	a_custom_field: {
		type: 'string',
    immutable: true,
  },
  an_important_relation: {
	  type: 'link',
    model: 'orders',
    key: 'a_custom_field',
  },
})

// You could populate the above field like so (note that {id} is substituted)
await swell.put('/accounts/{id}', {
  id: 'an_account_id',
  a_custom_field: '12345',
})

// And fetch the related order record
await swell.get('/accounts/{id}/an_important_relation', {
  id: 'an_account_id',
})

For additional details, see Admin API querying.

Creating a model is ideal if you want to implement unique functionality, like a vendors model for a marketplace. Once you have created a new model, you can interact with it just like any of our standard models.

POST/:models
await swell.post('/:models', {
  name: 'a-custom-model',
  fields: {
		a_custom_field: {
			type: 'string',
	    immutable: true,
	  },
	  an_important_relation: {
		  type: 'link',
	    model: 'orders',
	    key: 'a_custom_field',
	  },
  },
  // A secondary keys lets you refer to a record by this value
  // i.e. GET /accounts/{email} - email is a secondary key
  secondary_key: 'a_custom_field',
  // Custom events, can trigger custom webhooks if configured
  events: {
    types: [
      id: 'created_something_important',
      // Optional conditions
      conditions: {
        a_custom_field: { $exists: true },
      },
    ]
  },
})

Swell's data and content models provide unrestricted creative freedom. They are also scalable and can grow with your business needs. For additional resources regarding Swell models and their usage, see our core concepts guide series.