# Models

# Concept

# Content Type's models

Models are a representation of the database's structure and life cycle. They are split into two separate files. A JavaScript file that contains the life cycle callbacks, and a JSON one that represents the data stored in the database and their format. The models also allow you to define the relationships between them.

Path β€” ./api/restaurant/models/Restaurant.js.

module.exports = {
  // Before saving a value.
  // Fired before an `insert` or `update` query.
  beforeSave: (model, attrs, options) => {},

  // After saving a value.
  // Fired after an `insert` or `update` query.
  afterSave: (model, attrs, options) => {},

  // ... and more
};

Path β€” ./api/restaurant/models/Restaurant.settings.json.

{
  "kind": "collectionType",
  "connection": "default",
  "info": {
    "name": "restaurant",
    "description": "This represents the Restaurant Model"
  },
  "attributes": {
    "cover": {
      "collection": "file",
      "via": "related",
      "plugin": "upload"
    },
    "name": {
      "default": "",
      "type": "string"
    },
    "description": {
      "default": "",
      "type": "text"
    }
  }
}

In this example, there is a Restaurant model which contains the attributes cover, name and description.

# Component's models

It also exist another type of models named components. A component is a data structure that can be used in one or many other API's model. There is no lifecycle related, only a JSON file definition

Path β€” ./components/default/simple.json

{
  "connection": "default",
  "collectionName": "components_default_simples",
  "info": {
    "name": "simple",
    "icon": "arrow-circle-right"
  },
  "options": {},
  "attributes": {
    "name": {
      "type": "string"
    }
  }
}

In this example, there is a Simple component which contains the attributes name. And the component is in the category default.

# Where are the models defined?

For Content Types, models are defined in each ./api/**/models/ folder. Every JavaScript or JSON file in these folders will be loaded as a model. They are also available through the strapi.models and strapi.api.**.models global variables. Usable everywhere in the project, they contain the ORM model object that they refer to. By convention, a model's name should be written in lowercase.

For Components, models are defined in ./components folder. Every components has to be under a subfolder (the category name of the component).

# How to create a model?

TIP

If you are just starting out it is very convenient to generate some models with the Content Type Builder, directly in the admin interface. You can then review the generated model mappings on the code level. The UI takes over a lot of validation tasks and gives you a feeling for available features.

# For Content Types models

Use the CLI, and run the following command strapi generate:model restaurant name:string description:text.
Read the CLI documentation for more information.

This will create two files located at ./api/restaurant/models:

  • Restaurant.settings.json: contains the list of attributes and settings. The JSONΒ format makes the file easily editable.
  • Restaurant.js: imports Restaurant.settings.json and extends it with additional settings and life cycle callbacks.

TIP

When you create a new API using the CLI (strapi generate:api <name>), a model is automatically created.

# For Components models

To create a component you will have to use the Content Type Builder from the Admin panel, there is no generator for components.

Or you can create your component manually by following the file path discribed previously and by following the file structure discribed below.

# Model settings

Additional settings can be set on models:

  • kind (string) - Define if the model is a Collection Type (collectionType) of a Single Type (singleType) - only for Content Types
  • connection (string) - Connection name which must be used. Default value: default.
  • collectionName (string) - Collection name (or table name) in which the data should be stored.
  • globalId (string) - Global variable name for this model (case-sensitive) - only for Content Types
  • attributes (object) - Define the data structure of your model. Find available options below.

Path β€” Restaurant.settings.json.

{
  "kind": "collectionType",
  "connection": "mongo",
  "collectionName": "Restaurants_v1",
  "globalId": "Restaurants",
  "attributes": {}
}

In this example, the model Restaurant will be accessible through the Restaurants global variable. The data will be stored in the Restaurants_v1 collection or table and the model will use the mongo connection defined in ./config/environments/**/database.json

WARNING

If not set manually in the JSON file, Strapi will adopt the filename as globalId. The globalId serves as a reference to your model within relations and Strapi APIs. If you chose to rename it (either by renaming your file or by changing the value of the globalId), you'd have to migrate your tables manually and update the references. Please note that you should not alter Strapi's models globalId (plugins and core ones) since it is used directly within Strapi APIs and other models' relations.

TIP

The connection value can be changed whenever you want, but you should be aware that there is no automatic data migration process. Also if the new connection doesn't use the same ORM you will have to rewrite your queries.

# Model information

The info key on the model-json states information about the model. This information is used in the admin interface, when showing the model.

  • name: The name of the model, as shown in admin interface.
  • description: The description of the model.
  • icon: The fontawesome V5 name - only for Components

Path β€” Restaurant.settings.json.

{
  "info": {
    "name": "restaurant",
    "description": ""
  }
}

# Model options

The options key on the model-json states.

  • timestamps: This tells the model which attributes to use for timestamps. Accepts either boolean or Array of strings where first element is create date and second element is update date. Default value when set to true for Bookshelf is ["created_at", "updated_at"] and for MongoDB is ["createdAt", "updatedAt"].

Path β€” User.settings.json.

{
  "options": {
    "timestamps": true
  }
}

# Define the attributes

The following types are currently available:

  • string
  • text
  • richtext
  • email
  • password
  • integer
  • biginteger
  • float
  • decimal
  • date
  • time
  • datetime
  • boolean
  • enumeration
  • json
  • uid

# Validations

You can apply basic validations to the attributes. The following supported validations are only supported by MongoDB connection. If you're using SQL databases, you should use the native SQL constraints to apply them.

  • required (boolean) β€” If true, adds a required validator for this property.
  • unique (boolean) β€” Whether to define a unique index on this property.
  • index (boolean) β€” Adds an index on this property, this will create a single field index that will run in the background. Only supported by MongoDB.
  • max (integer) β€” Checks if the value is greater than or equal to the given maximum.
  • min (integer) β€” Checks if the value is less than or equal to the given minimum.

Security validations

To improve the Developer Experience when developing or using the administration panel, the framework enhances the attributes with these "security validations":

  • private (boolean) β€” If true, the attribute will be removed from the server response (it's useful to hide sensitive data).
  • configurable (boolean) - if false, the attribute isn't configurable from the Content Type Builder plugin.

# Exceptions

  • uid β€” This field type allows a targetField key. The value is the name of an attribute that has string of text type.

# Example

Path β€” Restaurant.settings.json.

{
  ...
  "attributes": {
    "title": {
      "type": "string",
      "min": 3,
      "max": 99,
      "unique": true
    },
    "description": {
      "default": "My description",
      "type": "text",
      "required": true
    },
    "slug": {
      "type": "uid",
      "targetField": "title"
    }
    ...
  }
}

# Relations

Relations let you create links (relations) between your Content Types.

# Components

Component field let your create a relation between your Content Type and a Component structure.

# Example

Lets say we created an openinghours component in restaurant category.

Path β€” ./api/restaurant/models/Restaurant.settings.json.

{
  "attributes": {
    "openinghours": {
      "type": "component",
      "repeatable": true,
      "component": "restaurant.openinghours"
    }
  }
}
  • repeatable (boolean): Could be true or false that let you create a list of data.
  • component (string): It follows this format <category>.<componentName>.

# Dynamic Zone

Dynamic Zone field let your create flexible space to content based on a component list.

# Example

Lets say we created an slider and content component in article category.

Path β€” ./api/article/models/Article.settings.json.

{
  "attributes": {
    "body": {
      "type": "dynamiczone",
      "components": ["article.slider", "article.content"]
    }
  }
}
  • components (array): Array of components, that follows this format <category>.<componentName>.

# Life cycle callbacks

WARNING

The life cycle functions are based on the ORM life cycle and not on the Strapi request. We are currently working on it to make it easier to use and understand. Please check this issue on GitHub.

The following events are available by default:

Callbacks on:

# Example