Content models

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.

👉

Refer to the Data model customization guide for details on how to work with content models.

Fields

id

stringauto

Unique identifier for the model.

label

string

Plural name of the content model collection.

name

stringrequiredauto

System name of the model. Defaults to [collection].[root].

source_type

enumrequiredauto

Indicates the source of the content model, app or custom. The value is automatically set to custom when created from the Swell dashboard.

Possible enum values:

appcustom

app_id

objectId

ID of a Swell App that defined this model, if applicable.

date_created

dateauto

Date the model was created.

date_updated

dateauto

Date the model was last updated.

public

boolean

Indicates that collection records are accessible by a public API call.

fields

array of fieldrequired

Content fields and their properties applied for each record of a collection.

field.id

stringrequired

String ID of the content field representing the name of a model field. This must be unique when combined with the root property.

For example: my_field

field.label

string

Optional label of the field used in the Swell dashboard.

field.description

string

A brief description of the field.

field.type

stringrequired

Type of the field. Content fields present a configurable UI in the Swell dashboard, and also apply relevant data types to their respective data model, as defined by collection.

Basic types have a number of ui options that affect how the field is displayed in the dashboard.

short_text
- ui: default (text), slug, email, phone, url
- data type: string
long_text
- ui: default (textarea), rich_text, basic_html, rich_html, markdown, liquid
- data type: string
boolean
- ui: default (checkbox), toggle
- data type: bool
select
- ui: default (dropdown), radio, checkboxes
- data type: array<string>
number
- ui: default (integer), float, currency, slider
- data type: int, float, currency
date
- ui: default (date), time, datetime
- data type: date
asset
- ui: default (flexible), image, video, document
- data type: file
tags
- Default ui renders a tag input
- data type: array<string>
color
- Default ui renders a color picker
- data type: string
icon
- Default ui renders an icon picker
- data type: string
lookup
- Default ui render a lookup component
- data type: objectid
collection
- An array of nested objects
- data type: array<object>
field_group
- Wrapper that renders a group fields vertically
field_row
- Wrapper that renders a group fields horizontally

The following are UI-specific aliases for configurations intended to help simplify many CMS use cases. When used as a type, their respective properties are automatically applied to the field and can each be overridden.

text
- type: short_text
textarea
- type: long_text
rich_text
- type: long_text
- ui: rich_text
checkbox
- type: boolean
checkboxes
- type: select
- ui: checkboxes
- multi: true
toggle
- type: boolean
- ui: toggle
radio
- type: select
- ui: radio
dropdown
- type: select
integer
- type: number
- digits: 0
float
- type: number
- digits: 2
currency
- type: number
- ui: currency
percent
- type: number
- unit: %
slider
- type: number
- ui: slider
- increment: 1
time
- type: date
- ui: time
datetime
- type: date
- ui: datetime
phone
- type: short_text
- ui: phone
email
- type: short_text
- ui: email
url
- type: short_text
- ui: url
slug
- type: short_text
- ui: slug
html
- type: long_text
- ui: basic_html
basic_html
- type: long_text
- ui: basic_html
rich_html
- type: long_text
- ui: rich_html
markdown
- type: long_text
- ui: markdown
liquid
- type: long_text
- ui: liquid
image
- type: asset
- asset_types: [image]
document
- type: asset
- asset_types: [document]
video
- type: asset
- asset_types: [video]
child_collection
- type: collection
- child: true
product_lookup
- type: lookup
- collection: products
variant_lookup
- type: lookup
- collection: products:variants
category_lookup
- type: lookup
- collection: categories
customer_lookup
- type: lookup
- collection: accounts

field.ui

string

Enumerated UI-types, when combined with type, allows you to render various different components in the Swell dashboard for the same underlying data field. Each ui only works relative to a specific type. See the field.type documentation for details.

Note: ui values are different than type aliases as documented, however they may share the same name.

field.fields

array of field

Required for field_group, field_row, and collection only, defines the nested fields of the group. The fields of a group are of the same schema as the top-level fields property.

field.value_type

enum

Optionally specify the data type used to store this value in a model collection. Content field type is cast to value_type when a record is created or updated. Defaults to the appropriate data type for a given content field type.

Possible enum values:

arrayboolcollectioncurrencydatefloatlinkstringobjectobjectid

field.item_types

array of item_type

For collection only, define groups of nested fields that are applied to collection records. In the respective data model, these are defined as object_types according to the nested content field schema.

field.conditions

object

A query object used to match record values. When matched, the field is visible, otherwise it is hidden. Field conditions support the equivalent format and operators of query filtering.

field.required

boolean

Indicates the field must be defined with a non-empty value when the record is created or updated.

field.default

mixed

Global default value of the field, applied to all records at runtime when retrieved by the API. The Swell dashboard supports overriding this value per-record, and also the ability to reset the value to the global default.

If fallback is set to false, then the default is stored on the record locally when created from the Swell dashboard.

field.public

boolean

Indicates that a field value is made accessible by a public API call, assuming the parent content model does not have public: true.

field.fallback

boolean

Indicates the default value should fallback to the global default. Defaults to true.

field.enum

array of value

Enumerated set of values accepted by the system.

field.format

string

Automatically format the value of a string field. This may be an alternative to a more complex formula for simple use cases.

One of:

uppercase: value => VALUE
lowercase: VALUE => value
underscore: TextValue => text_value
slug: TextValue => text-value
slugid: TextValue.Example => text-value.example
currency-code: usd => USD
url: example.com => https://example.com
email: user name@example.com => user+name@example.com
semver: 1 => 1.0.0
password: example => bcrypt(example)
- Password-formatted fields are automatically hashed with the bcrypt algorithm.

field.formula

string

An expression used to calculate the value of the field when a record is created or updated. See Formula documentation for more details.

field.readonly

boolean

Indicates the field cannot be changed after initially being defined. Note: a formula field may still change the value dynamically.

field.unique

mixed

If set to true, indicates the value must be unique across the entire collection. If set as an array of adjacent fields, indicates the combination of values must be unique across the entire collection.

For example, the following would specify a field must be unique when combined with account_id:

"unique": ["account_id"]

field.localized

boolean

Indicates that a string or currency value can be localized by locale and currency codes in the Swell dashboard.

field.hint

string

Text hint typically displayed below the field input in the Swell dashboard.

field.root

mixed

The object path data fields will be applied to in the respective model collection. For example, on the accounts collection, to root a field to the shipping object, set root: shipping.

If undefined, the field will be rooted to the model's content object, which is accessible by a public API call.

If true, the field will be rooted at the top-level of the model schema.

field.admin_span

int

Number of columns for the field to span, between 1 and 4. The Swell dashboard interface supports a grid of up to 4 columns on a page. Defaults to 4.

field.admin_zone

string

Specifies the area of the Swell admin dashboard for the field to appear. Most standard collections have pre-defined zones that are distributed throughout the dashboard UI. Some zones will change the root of the content fields, for example scoping fields to a variant record instead of the parent product.

If the admin_zone is empty, the field is hidden from the UI.

The following are zones displayed by each standard collection. Note: app-defined or custom collections only support the content zone.

products:

details: The main details section.
pricing: The pricing section.
options: The options section.
option-edit: The interface to edit an option.
- root: options
option-value-edit: The interface to edit an option value.
- root: options.values
variant-edit: The interface to edit a variant.
- root: variants
related: The related products section.
attributes: The attributes tab.
inventory: The inventory tab.
shipping: The shipping tab.
content: The content section at the bottom of the page.

categories:

details: The main details section.
content: The content section at the bottom of the page.

accounts:

details: The main details section.
contact: The interface used to edit contact information.
billing: The interface used to edit billing information.
- root: billing
shipping: The interface used to edit shipping information.
- root: shipping

orders:

details: The main details section.
content: The content section at the bottom of the page.

subscriptions:

details: The main details section.
content: The content section at the bottom of the page.

invoices:

details: The main details section.
content: The content section at the bottom of the page.

carts:

details: The main details section.
content: The content section at the bottom of the page.

payments:

charge: The interface to charge a payment method.
refund: The interface to refund a payment.
- root: refunds

shipments:

order: The interface for an order fulfillment.

returns:

order: The interface for an order return.

attributes:

content: The content section at the bottom of the page.

giftcards:

content: The content section at the bottom of the page.

coupons:

content: The content section at the bottom of the page.

promotions:

content: The content section at the bottom of the page.

purchaselinks:

content: The content section at the bottom of the page.

content/pages:

content: The content section at the bottom of the page.

content/blogs:

content: The content section at the bottom of the page.

field.multi

boolean

For select only, indicates the value should support multiple selections.

field.model

string

For lookup only, specifies the model to query when looking up records in the Swell dashboard.

field.key

string

For lookup only, optionally specifies the foreign key to reference the primary key of a linked collection. Defaults to the primary key of the linked collection.

field.key_field

string

For lookup only, optionally specifies the field containing a foreign key to reference the primary key of a linked collection. Important: a key field is automatically created for a lookup field in the format of [lookup-field-name]_id.

field.limit

int

For lookup only, limits the number of results to display in a lookup query UI.

field.min

float

Requires a minimum value of a number field.

field.max

float

Requires a maximum value of a number field.

field.digits

int

For number only, determines the number of decimal digits rounded to.

field.item_label

string

For collection only, refers to the collection field that should be used as a label in the collection list.

field.icon

string

For collection only, specifies an icon to be displayed next to each row of a collection list.

field.asset_types

array of asset_type

For asset only, indicates the file types acceptable for upload. Defaults to allow any file type.

defaults

objectauto

Aggregate global default values derived from field defaults. These values are automatically applied to API responses when using the $content: true operator.

views

array of view

Content views allowing you to configure different layouts for list and record pages. List views allow you to add fields and filters to collection lists, while record views allows you to add fields to record pages.

Fields

id

label

name

source_type

app_id

date_created

date_updated

public

fields

field.id

field.label

field.description

field.type

field.ui

field.fields

field.field

field.value_type

field.item_types

item_type.id

item_type.name

item_type.fields

field.field

field.conditions

field.required

field.default

field.public

field.fallback

field.enum

field.format

field.formula

field.readonly

field.unique

field.localized

field.hint

field.root

field.admin_span

field.admin_zone

field.multi

field.model

field.key

field.key_field

field.limit

field.min

field.max

field.digits

field.item_label

field.icon

field.asset_types

defaults

views

view.id

view.type

view.label

view.fields

field.field

view.tabs

tab.id

tab.label

tab.query

query.where

query.limit

query.sort