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.
{
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.
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 entries 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 that 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.
Let's say we're an upscale beverage maker and want to have a list of ingredients for one of our fine tipples. Defining a content type with an ingredients field and model: 'products' stores the data on a product object at product.content.ingredients.
We want each ingredient to have a name and description, so we'll use a collection field to allow any number of ingredients with those two fields to be added. Collection fields can accommodate other content types using the item_types attribute and passing an array of content type IDs, or define a set of fields that each item in the collection will have. Some CMS call this a 'repeated field'.
// Create the content type
await swell.put('/:content', {
name: 'Product details', // The name shown in the dashboard
description: 'Additional info about the product', // An optional description to help admins understand what this content type is for
collection: 'products', // We're attaching these fields to every product
fields: [
{
id: 'ingredients', // The field's object key
label: 'Ingredient list', // The label shown in the dashboard
type: 'collection',
fields: [
{
id: 'name',
label: 'Ingredient name',
type: 'short_text'
},
{
id: 'description',
label: 'Description',
type: 'long_text'
}
]
}
]
})
// Add some ingredient data to an existing product with the slug 'elderflower-tonic'
await swell.put('/:content', {
id: 'elderberry-tonic',
'content.ingredients': [
{
name: 'Organic Elderflower',
description: 'Picked by hand in the Swiss Alps.'
},
{
name: 'Grapefruit peel',
description: 'Aromatic but not too tart.',
},
{
name: 'Cane sugar',
description: 'Just enough to balance out the grapefruit.'
},
{
name: 'Quinine',
description: 'The real stuff, direct from farmers in Congo'
}
]
})
// Fetch the newly-updated product with our ingredient list
const product = await swell.get('/products/elderflower-tonic')
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.
Let's say we're an upscale beverage maker and want to have a list of ingredients for one of our fine tipples. Defining a content type with an ingredients field and collection: 'products' stores the data on a product object at product.content.ingredients.
We want each ingredient to have a name and description, so we'll use a collection field to allow any number of ingredients with those two fields to be added. Collection fields can accommodate other content types using the item_types attribute and passing an array of content type IDs, or define a set of fields that each item in the collection will have. Some CMS call this a 'repeated field'.
// Create the content type
await swell.put('/:content', {
name: 'Product details', // The name shown in the dashboard
description: 'Additional info about the product', // An optional description to help admins understand what this content type is for
collection: 'products', // We're attaching these fields to every product
fields: [
{
id: 'ingredients', // The field's object key
label: 'Ingredient list', // The label shown in the dashboard
type: 'collection',
fields: [
{
id: 'name',
label: 'Ingredient name',
type: 'short_text'
},
{
id: 'description',
label: 'Description',
type: 'long_text'
}
]
}
]
})
// Add some ingredient data to an existing product with the slug 'elderflower-tonic'
await swell.put('/:content', {
id: 'elderberry-tonic',
'content.ingredients': [
{
name: 'Organic Elderflower',
description: 'Picked by hand in the Swiss Alps.'
},
{
name: 'Grapefruit peel',
description: 'Aromatic but not too tart.',
},
{
name: 'Cane sugar',
description: 'Just enough to balance out the grapefruit.'
},
{
name: 'Quinine',
description: 'The real stuff, direct from farmers in Congo'
}
]
})
// Fetch the newly-updated product with our ingredient list
const product = await swell.get('/products/elderflower-tonic')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.
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 schema—making sets of fields reusable in multiple places makes the job of content editors and developers much simpler—resulting 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.
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.
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',
})
Fetching that product will show the newly-added field at the root level
await swell.get('/products/{id}', {
id: 'everlasting-sunscreen',
})
Result
{
id: "627d93e8ff7ce54cc71e380g",
slug: "everlasting-sunscreen",
manufacturer_name: "Acme Corporation"
...
}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.
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.