Backend API
Define data collections and their API behavior. There are many standard models configured by default, such as products, orders, and others. Data models can be created manually in the Swell dashboard under Developer > Models, or may be installed automatically by Swell Apps, thereby expanding your database and available API endpoints.
See the Data model customization guide for details on what you can do with custom models, or see Apps model reference to learn how to configure data models in Swell Apps.
Fields
id
stringautoUnique identifier for the model.
name
stringrequiredSlug-formatted name of the model.
fields
objectrequiredModel fields and their properties applied for each record of a collection.
Fields are named by the key of each property in this object, for example:
"fields": { "name": { "type": "string" }, ... }
While Swell's API supports working with record values that are not defined by a field, it is strongly recommended to define fields for known values.
fields.*
objectrequiredThe key of each field property is the desired name of the field.
*.type
stringrequiredType of the field. Defaults to string.
Scalar types:
- string
- int
- float
- bool
- date
- currency
- objectid
Complex types:
- array
- object
- collection
- link
- file
*.value_type
enumDefines the value-type of an array or link field.
- array: Allows any value-type except collection or record.
- link: Allows collection or record.
Possible enum values:
*.fields
objectNested fields of an array or object type field. The fields of an array or object are of the same schema as the top-level fields property.
*.required
booleanIndicates the field must be defined with a non-null value when the record is created or updated.
*.default
mixedDefault value of the field, applied when a record is first created or updated while the field is otherwise undefined.
*.enum
array of valueArray of possible values that can be set on this field. System returns an error if a value is passed that does not match one of the defined enum options.
*.format
stringAutomatically 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.
*.formula
stringAn expression used to calculate the value of the field when a record is created or updated. See Formula documentation for more details.
The expression may reference its own value. For example, to force-uppercase a field named code:
"formula": "upper(code)"
If the expression results in an undefined value, the field itself will become undefined.
*.unique
mixedIf 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"]
*.readonly
booleanIndicates the field cannot be changed by an API call after initially being defined. Note: a formula field may still change the value dynamically.
*.object_types
objectDefine type-specific fields for records that are applied according to an adjacent type field that is itself automatically defined. This is used when certain fields may be required or have different properties only when the record type matches one of these definitions. Object type fields are merged over regular fields, allowing the model to change the behavior of any existing field as well.
For example:
"object_types": { "individual": { "full_name": { "required": true } } }
When defining object_types, a type field is automatically defined on the object, however you may also define it via configuration in order to enumerate each acceptable type.
object_types.*
objectrequiredThe key of each object_type property is the desired name of the object type.
*.fields
objectSet of fields to be applied to the object given its type.
fields.*
objectDefine the fields to be applied to a record given its type. The fields of an object type are of the same schema as the top-level fields property.
*.key
stringFor link only, specifies the foreign key to reference the primary key of a linked collection.
*.extends
stringFor array and object only, this extends the object by applying nested fields from an adjacent field. The value should refer to another field from the top-level schema.
*.model
stringFor link only, specifies the model of a linked collection.
*.label
stringThe label of the field.
*.description
stringA brief description of the field.
*.auto
mixedCauses the field value to be automatically resolved depending on the field type.
Examples:
- auto: true combined with enum values will automatically apply the first value.
- auto: true on an objectid field will automatically create a new value when the record is created.
- auto: true on a date field will automatically set the value to the current datetime when a record is created or updated.
- auto: [insert|update] on a date field will automatically set the value to the current datetime when a record is either created or updated respectively.
- auto: true on an int field combined with increment.start: 1 will automatically increment the field value when a record is created, starting from 1.
- auto: true on a string field combined with increment.pattern: "EXAMPLE-{0000}" will automatically increment the string pattern, maintaining characters outside of the {} brackets, when a record is created.
*.increment
objectUsed in combination with auto: true, defines how to automatically increment numerical values on int and string fields.
increment.start
intNumber to begin incrementing from. This value applies globally for this collection, for example start: 1 would set the number to 1, 2, 3, ... on each record created respectively in this collection.
increment.pattern
stringFor string fields, defines the pattern including the numeric portion of a string in {} brackets, used to automatically set the string value.
For example: increment.pattern: "EXAMPLE-{0000}" would result in a value of "EXAMPLE-0001" on the first record created in the collection.
*.rules
array of ruleTrigger a system error when one or more rules are matched to record values.
Triggers:
- expression: Using a formula expression.
- conditions: Using the equivalent format and operators of query filtering.
Effects:
- required: Cause the field to be required when triggered.
- error: Error message to return when triggered.
rule.expression
stringA formula expression used to evaluate when the effect of the rule is triggered. See Formula documentation for details.
rule.conditions
objectA query object used to match record values. When matched, the rule is triggered. Rule conditions support the equivalent format and operators of query filtering.
rule.required
booleanIf true, cause the field to be required when the rule is triggered.
rule.error
stringError message to return when the rule is triggered.
*.length
intRequires an exact length of a string field.
*.minlength
intRequires a minimum length of a string field.
*.maxlength
intRequires a maximum length of a string field.
*.min
floatRequires a minimum value of an int or float field.
*.max
floatRequires a minimum value of an int or float field.
*.sort
enumAutomatically sorts an array field in ascending or descending order.
Possible enum values:
*.public
booleanIndicates that a field value is made accessible by a public API call, assuming the parent model does not have public: true.
*.localized
booleanIndicates that a string or currency value can be localized by locale and currency codes.
namespace
stringOptional namespace used in the model's API endpoint, for example "content" results in the endpoint /content/model-name.
version
stringautoSemver-formatted version number. This value is automatically incremented when the model is modified.
label
stringPlural name of a model collection.
singular
stringSingular name of a model record.
public
booleanIndicates the model collection and its values are public by default.
public_permissions
objectRestrictive public query parameters for storefront API calls, if applicable.
public_permissions.scope
stringSet to `account` to limit public permissions to logged-in users only.
public_permissions.fields
array of fieldArray of model fields to allow read access for.
public_permissions.query
objectDefault parameters used when querying the model collection from a public API.
query.where
objectDefault filter used when querying the model collection from a public API.
query.limit
intDefault number of records to return when querying the model collection from a public API.
query.window
intDefault number of pages in a pagination window to calculate when querying the model collection from a public API.
query.sort
stringDefault sort parameter used when querying the model collection from a public API.
public_permissions.input
objectPermissions allowed for write access when called from a public API.
input.scope
stringSet to `account` to limit public permissions to logged-in users only.
input.fields
array of fieldArray of model fields to allow write access for.
single
booleanIndicates the model only only has one record, instead of a collection.
abstract
booleanIndicates the model can be extended by another model, but cannot be instantiated as a collection.
primary_field
stringThe primary field used to look up records in the model collection.
secondary_field
stringOptional secondary field used to look up records in the model collection.
name_field
stringThe field used as a label for each record by default.
query
objectDefault parameters used when querying the model collection.
query.where
objectDefault filter used when querying the model collection.
query.limit
intDefault number of records to return when querying the model collection.
query.window
intDefault number of pages in a pagination window to calculate when querying the model collection.
query.sort
stringDefault sort parameter used when querying the model collection.
storefront
objectStorefront rendering options.
storefront.enabled
booleanIndicates that model data may be displayed in a storefront.
storefront.list
booleanIndicates that model data may be displayed in a storefront list view.
storefront.list_slug
stringThe URL slug used to play modal data in a storefront list view.
storefront.list_title
stringTitle of the page to display a list of records in a storefront.
storefront.list_description
stringA description to display on a storefront list view.
storefront.page
booleanIndicates that model data may be displayed in a storefront page view.
storefront.page_slug_field
stringReference to a URL slug field used to play modal data in a storefront page view.
storefront.page_title_field
stringReference to a title field to display on a storefront page view.
storefront.page_description_field
stringReference to a description field to display on a storefront page view.
events
objectModel event configuration. By default, each model is configured with created, updated, and deleted events. Custom events can be automatically triggered based on conditions, or manually triggered via API call.
events.enabled
booleanIndicates that model events will be triggered by the system. Defaults to true.
events.types
array of event_typeEvent types triggered by the system for this model.
event_type.id
stringID of the event. Should be a short ID, such as created, while a fully-qualified event name is referenced in the following format: [model-name].[event-name].
event_type.conditions
objectA query object used to match record values. When matched, the event is triggered. Event conditions support the equivalent format and operators of query filtering.
event_type.fields
array of fieldArray of model fields to include in the event payload, which are sent to webhooks and app functions, as well as recorded in the system /events collection.
event_type.hooks
array of stringEnumerated hooks triggered by the event type. One of: before, after. Hooks allow app functions to block API call processing and modify values before and after an event is triggered.
event_type.hook_timeout
intMaximum time in milliseconds to wait for a hook function to complete before timing out. Defaults to 60000 (60 seconds).
event_type.hook_reject_error
booleanIndicates whether the event will reject requests when an error occurs in a configured hook function. Defaults to false.
event_type.hook_retry_attempts
intMaximum number of times to retry a hook function when an unknown error occurs. Must be between 0 and 3.
events.root
stringautoRoot name of event types used in webhooks. Defaults to a singularized version of the model name, for example product.
extends
stringReference to a parent model to extend properties from.
extends_version
stringautoAutomatically assigned version of an extended model, if applicable.
content_id
stringID of a content model that defined this model, if applicable.
deprecated
booleanIndicates the model is deprecated and may be removed in a future API version.
date_created
dateautoDate the model was created.
date_updated
dateautoDate the model was last updated.
The data model
{
"version": "1.0.0",
"label": "Blog",
"plural": "Blogs",
"extends": "base",
"fields": {
"title": {
"type": "string",
"required": true
},
"slug": {
"type": "string",
"format": "slug",
"default": {
"$formula": "slug(title)"
}
},
"author_id": {
"type": "objectid",
"required": true
},
"author": {
"type": "link",
"model": ":users",
"key": "author_id",
"data": {
"fields": "email,name,username"
}
},
"category_id": {
"type": "objectid",
"required": true
},
"category": {
"type": "link",
"model": "content/blog-categories",
"key": "category_id"
},
"content": {
"type": "string",
"format": "html",
"multiline": true
},
"summary": {
"type": "string",
"format": "html",
"multiline": true
},
"image": {
"type": "object",
"fields": {
"file": {
"type": "file"
}
}
},
"tags": {
"type": "array",
"value_type": "string",
"unique": true
},
"published": {
"type": "bool",
"default": false
},
"date_published": {
"type": "date",
"label": "Publish Date"
},
"meta_title": {
"type": "string",
"label": "Page Title"
},
"meta_keywords": {
"type": "string"
},
"meta_description": {
"type": "string",
"multiline": true
}
},
"query": {
"sort": "name asc"
},
"name_field": "title",
"secondary_field": "slug",
"events": {
"enabled": true,
"types": [{ "id": "created" }, { "id": "updated" }, { "id": "deleted" }]
}
}