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
Unique identifier for the model.
Slug-formatted name of the model.
Model 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.
The key of each field property is the desired name of the field.
Type of the field. Defaults to string.
Scalar types:
- string
- int
- float
- bool
- date
- currency
- objectid
Complex types:
- array
- object
- collection
- link
- file
Defines 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:
Nested 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.
Indicates the field must be defined with a non-null value when the record is created or updated.
Default value of the field, applied when a record is first created or updated while the field is otherwise undefined.
Array 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.
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.
An 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.
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"]
Indicates the field cannot be changed by an API call after initially being defined. Note: a formula field may still change the value dynamically.
Define 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.
The key of each object_type property is the desired name of the object type.
Set of fields to be applied to the object given its type.
Define 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.
For link only, specifies the foreign key to reference the primary key of a linked collection.
For 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.
For link only, specifies the model of a linked collection.
The label of the field.
A brief description of the field.
Causes 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.
Used in combination with auto: true, defines how to automatically increment numerical values on int and string fields.
Number 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.
For 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.
Trigger 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.
A formula expression used to evaluate when the effect of the rule is triggered. See Formula documentation for details.
A query object used to match record values. When matched, the rule is triggered. Rule conditions support the equivalent format and operators of query filtering.
If true, cause the field to be required when the rule is triggered.
Error message to return when the rule is triggered.
Requires an exact length of a string field.
Requires a minimum length of a string field.
Requires a maximum length of a string field.
Requires a minimum value of an int or float field.
Requires a minimum value of an int or float field.
Automatically sorts an array field in ascending or descending order.
Possible enum values:
Indicates that a field value is made accessible by a public API call, assuming the parent model does not have public: true.
Indicates that a string or currency value can be localized by locale and currency codes.
Optional namespace used in the model's API endpoint, for example "content" results in the endpoint /content/model-name.
Semver-formatted version number. This value is automatically incremented when the model is modified.
Plural name of a model collection.
Singular name of a model record.
Indicates the model collection and its values are public by default.
Restrictive public query parameters for storefront API calls, if applicable.
Set to `account` to limit public permissions to logged-in users only.
Array of model fields to allow read access for.
Default parameters used when querying the model collection from a public API.
Default filter used when querying the model collection from a public API.
Default number of records to return when querying the model collection from a public API.
Default number of pages in a pagination window to calculate when querying the model collection from a public API.
Default sort parameter used when querying the model collection from a public API.
Permissions allowed for write access when called from a public API.
Set to `account` to limit public permissions to logged-in users only.
Array of model fields to allow write access for.
Indicates the model only only has one record, instead of a collection.
Indicates the model can be extended by another model, but cannot be instantiated as a collection.
The primary field used to look up records in the model collection.
Optional secondary field used to look up records in the model collection.
The field used as a label for each record by default.
A string pattern used to derive record names with string substitution, which can reference any field in the record. If defined, it is used instead of name_field.
For example: {name} - {sku}
The pattern may also reference nested or link fields, for example:
{parent.name} - {sku}
Default parameters used when querying the model collection.
Default filter used when querying the model collection.
Default number of records to return when querying the model collection.
Default number of pages in a pagination window to calculate when querying the model collection.
Default sort parameter used when querying the model collection.
Storefront rendering options.
Indicates that model data may be displayed in a storefront.
Indicates that model data may be displayed in a storefront list view.
The URL slug used to play modal data in a storefront list view.
Title of the page to display a list of records in a storefront.
A description to display on a storefront list view.
Indicates that model data may be displayed in a storefront page view.
Reference to a URL slug field used to play modal data in a storefront page view.
Reference to a title field to display on a storefront page view.
Reference to a description field to display on a storefront page view.
Model 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.
Indicates that model events will be triggered by the system. Defaults to true.
Event types triggered by the system for this model.
ID 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].
A query object used to match record values. When matched, the event is triggered. Event conditions support the equivalent format and operators of query filtering.
Array 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.
Enumerated 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.
Maximum time in milliseconds to wait for a hook function to complete before timing out. Defaults to 60000 (60 seconds).
Indicates whether the event will reject requests when an error occurs in a configured hook function. Defaults to false.
Maximum number of times to retry a hook function when an unknown error occurs. Must be between 0 and 3.
Root name of event types used in webhooks. Defaults to a singularized version of the model name, for example product.
Name of a parent model to extend properties from.
For example, to extend the standard product model in the definition of a new model:
"extends": "products"
All properties of the extended model will be inherited and merged under the new schema. Any property can be overridden or modified in the definition of the extending model, including field attributes.
For example, if a parent model has an optional field sku and you want to make it required in the extending model:
{
"extends": "products",
"fields": {
"sku": {
"required": true
}
}
}Automatically assigned version of an extended model, if applicable.
ID of a content model that defined this model, if applicable.
Indicates the model is deprecated and may be removed in a future API version.
Date the model was created.
Date 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" }]
}
}