Page Contents

Overview

A model describes business domain objects, for example, Customer, Address, and Order. It usually defines a list of properties with name, type, and other constraints.

Models can be used for data exchange on the wire or between different systems. For example, a JSON object conforming to the Customer model definition can be passed in REST/HTTP payload to create a new customer or stored in a document database such as MongoDB. Model definitions can also be mapped to other forms, such as relational database schemas, XML schemas, JSON schemas, OpenAPI schemas, or gRPC message definitions, and vice versa.

There are two subtly different types of models for domain objects:

  • Entity: A domain object that has an identity (ID). Its equality is based on the identity. For example, Customer can be modeled as an Entity because each customer has a unique customer id. Two instances of Customer with the same customer id are equal since they refer to the same customer. For example, this is how a Customer can be modelled::
import {Entity, model, property} from '@loopback/repository';

@model()
export class Customer extends Entity {
  @property({id: true}) id: string;

  @property() name: string;

  @property() email: string;

  constructor(data?: Partial<Appointment>) {
    super(data);
  }
}
  • Value Object: A domain object that does not have an identity (ID). Its equality is based on the structural value. For example, Address can be modeled as a Value Object because two US addresses are equal if they have the same street number, street name, city, and zip code values. For example, this is how a Address can be modelled::
import {Model, model, property} from '@loopback/repository';

@model()
export class Address extends Model {
  @property() streetNum: number;

  @property() streetName: string;

  @property() city: string;

  @property() zipCode: string;

  constructor(data?: Partial<Address>) {
    super(data);
  }

Currently, we provide the @loopback/repository module, which provides special decorators @model and @property for adding metadata to your TypeScript/JavaScript classes. Please read on to learn more.

Definition of a Model

A typical LoopBack 4 model is written in TypeScript. We use decorators @model and @property to annotate or modify the class and class members respectively.

import {Entity, model, property} from '@loopback/repository';

@model({setting: {hiddenProperties: 'id'}})
export class User extends Entity {
  @property({
    type: 'number',
    id: true,
    generated: true,
  })
  id: number;

  @property({
    type: 'string',
    required: false,
  })
  des?: string;

  constructor(data?: Partial<Appointment>) {
    super(data);
  }
}

We also provide a useful command line interface (CLI) lb4 model to generate models.

At its core, a model in LoopBack is a simple JavaScript class. With the extensibility of @model and @property decorators, we are able to manipulate the metadata or even integrate with JSON Schema generation.

For example, the following is a simple model Customer:

import {model, property} from '@loopback/repository';

@model()
export class Customer {
  @property()
  email: string;
  @property()
  isMember: boolean;
  @property()
  cart: ShoppingCart;
}

The @model decorator can take jsonSchema to customize the JSON schema inferred for the model class. For example,

@model({
  jsonSchema: {
    title: 'Customer',
    required: ['email'],
  },
})
export class Customer {
  // ...
}

Defining a Model at Runtime

Models can also be created at runtime using the defineModelClass() helper function from the @loopback/repository class. It expects a base model to extend (typically Model or Entity), followed by a ModelDefinition object as shown in the example below.

const bookDef = new ModelDefinition('Book')
  .addProperty('id', {type: 'number', id: true})
  .addProperty('title', {type: 'string'});
const BookModel = defineModelClass<typeof Entity, {id: number; title?: string}>(
  Entity, // Base model
  bookDef, // ModelDefinition
);

You will notice that we are specifying generic parameters for the defineModelClass() function. The first parameter is the base model, the second one is an interface providing the TypeScript description for the properties of the model we are defining. If the interface is not specified, the generated class will have only members inherited from the base model class, which typically means no properties.

In case you need to use an existing Model as the base class, specify the Model as the base class instead of Entity.

// Assuming User is a pre-existing Model class in the app
import {User} from './user.model';
import DynamicModelCtor from '@loopback/repository';
const StudentModel = defineModelClass<
  typeof User,
  // id being provided by the base class User
  {university?: string}
>(User, studentDef);

If you want make this new Model available from other parts of the app, you can call app.model(StudentModel) to create a binding for it.

Model Discovery

Instead of creating models from scratch, LoopBack can automatically generate model definitions by discovering the schema of your database. See Discovering models for more details and a list of connectors supporting model discovery.

Model Metadata

As we mentioned before, LB4 uses @model and @property to collect metadata from a model class. To enable such decorators from module @loopback/repository, you will need to extend your classes from Entity and decorate them with the @model and @property decorators:

import {model, property, Entity} from '@loopback/repository';

@model()
export class Product extends Entity {
  @property({
    id: true,
    description: 'The unique identifier for a product',
  })
  id: number;

  @property()
  name: string;

  @property()
  slug: string;

  constructor(data?: Partial<Product>) {
    super(data);
  }
}

Except for definitions, there are a bunch of settings you can apply through @model and/or @property. For example, by default, LB4 classes forbid additional properties that are not specified in the type definition. Such constraints can be disabled through @model when it comes to NoSQL databases such as MongoDB, as they support free-form properties. Please check out the following Model decorator and Property decorator sections for details.

Model Decorator

The model decorator can be used without any additional parameters, or can be passed in a ModelDefinitionSyntax:

@model({
  name: 'Category',
  settings: {
    // etc...
  },
  // define properties by @property decorator below
})
class Category extends Entity {
  // etc...
  @property({type: 'number'})
  categoryId: number;
}

name can be omitted as the model decorator already knows the name of your model class:

@model()
class Product extends Entity {
  name: string;
  // other properties...
}

As for entries in settings, LoopBack 4 supports these built-in entries for now:

Supported Entries of Model Definition

Property Type Default Description
name String None Name of the model.
settings.description String None Optional description of the model. We only support string type for now. (see issue #3428 for more discussion.)
settings.forceId Boolean true Set it to true to prevent clients from setting the auto-generated ID value manually.
settings.hiddenProperties Array of String None The properties can be hidden from response bodies (.toJSON() output). See Hidden properties section below for details.
settings.scope Object N/A Scope enables you to set a scope that will apply to every query made by the model's repository. See Scope below for more details and examples.
settings.strict Boolean or String true In LB4, the default for this entry is set to be true.
Specifies whether the model accepts only predefined properties or not. One of:
  • true: Only properties defined in the model are accepted. It ensure the model accepts only predefined properties. If a model instance contains properties that are not predefined, LoopBack throws a ValidationError. In addition, SQL databases only support this mode.
  • false: The model is an open model and accepts all properties, including ones not predefined in the model. This mode is useful to store free-form JSON data to a schema-less database such as MongoDB and supported by such databases only.
  • "filter": Only properties defined in the model are accepted. If you load or save a model instance with properties that are not predefined, LoopBack will ignore them. This is particularly useful when dealing with old data that you wish to lose without a migration script.

To discover more about Model Decorator in LoopBack 4, please check legacy-juggler-bridge file and model-builder file.

Unsupported Entries

If you’re a LB3 user, the following entries that are no longer available in LB4:

Click to Expand
Property Description
acls (TBD)
base This entry is no longer being used. This is done by the typical Js/Tsc classes inheritance way in LB4:
@model() class MySuperModel extends MyBaseModel {...}
  
excludeBaseProperties (TBD)
http This entry affects HTTP configuration in LB3. Since in LB4 http configurations are inferred from controller members and the rest server, this field is not applicable.
options (TBD) see issue #2142 for further discussion.
plural This entry is part of HTTP configuration in LB3. So it's not applicable for the same reason as http above.
properties This entry is no longer being used as we introduced @property decorator in LB4. See @property decorator below to discover moer about how to define properties for your models.
relations With the introduction of repositories, now relations are defined by relations decorators in LB4. See Relations for more details.
remoting.
normalizeHttpPath
This entry is part of HTTP configuration in LB3. So it's not applicable for the same reason as http above.
replaceOnPUT This entry is no longer supported as LB4 controllers scaffolded by LB4 controller, PUT is always calling replaceById. Users are free to change the generated code to call patchById if needed.

Hidden Properties

The properties are stored in the database, available in JS/TS code, can be set via POST/PUT/PATCH requests, but they are removed from response bodies (.toJSON() output).

To hide a property, you can use the hiddenProperties setting like this:

@model({
  settings: {
    hiddenProperties: ['password']
  }
})
class MyUserModel extends Entity {
  @property({id: true})
  id: number;
   @property({type: 'string'})
  email: string;
   @property({type: 'string'})
  password: string;
  ...
}

Scope

Scope enables you to set a scope that will apply to every query made by the model’s repository.

If you wish for a scope to be applied across all queries to the model, set the scope to do so. For example:

@model({
  settings: {
    scope: {
      limit: 2,
      where: {deleted: false}
    },
  }
})
export class Product extends Entity {
  ...

Now, any CRUD operation with a query parameter runs in the default scope will be applied; for example, assuming the above scope, a find operation such as

await ProductRepository.find({offset: 0});

Becomes the equivalent of this:

await ProductRepository.find({
  offset: 0,
  limit: 2,
  where: {deleted: false},
});

Property Decorator

LoopBack 4 uses the property decorator for property definitions.

@model()
class Product extends Entity {
  @property({
    name: 'name',
    description: "The product's common name.",
    type: 'string',
  })
  public name: string;

  @property({
    type: 'number',
    id: true,
  })
  id: number;
}

Here are general attributes for property definitions:

Key Required? Type Description
default No Any* Default value for the property. The type must match that specified by type. NOTE: if you have both default value set and required set to true, you will still need to include the property in the request body of POST/PUT requests as LoopBack follows the OpenAPI standard that required means the user needs to provide the field in the request always.
defaultFn No String A name of the function to call to set the default value for the property. Must be one of:
  • "guid": generate a new globally unique identifier (GUID) using the computer MAC address and current time (UUID version 1).
  • "uuid": generate a new universally unique identifier (UUID) using the computer MAC address and current time (UUID version 1).
  • "uuidv4": generate a new universally unique identifier using the UUID version 4 algorithm.
  • "now": use the current date and time as returned by new Date()
NOTE: the value of defaultFn is generated by LoopBack itself. If you'd like to use database built-in uuid functions (MySQL or Postgres for example), please check the README file of the corresponding connector.
description No String or Array Documentation for the property. You can split long descriptions into arrays of strings (lines) to keep line lengths manageable. For example:
[
"LoopBack 4 is a highly extensible Node.js and TypeScript framework",
"for building APIs and microservices.",
"Follow us on GitHub: https://github.com/strongloop/loopback-next."
]
doc No String Documentation for the property. Deprecated, use "description" instead.
id No Boolean Whether the property is a unique identifier. Default is false. See ID properties section below for detailed explanations.
index No Boolean Whether the property represents a column (field) that is a database index.
required No Boolean Whether a value for the property is required in the request body for creating or updating a model instance.

Default is false. NOTE: As LoopBack follows the OpenAPI standard, required means the user needs to provide the field in the request always. POST/PUT requests might get rejected if the request body doesn't include the required property even it has default value set.
type Yes String Property type. Can be any type described in LoopBack types.

ID Properties

LoopBack 4 expects a model to have one ID property that uniquely identifies the model instance.

To explicitly specify a property as ID, set the id property of the option to true. The id property value must be one of:

  • true: the property is an ID.
  • false (or any value that converts to false): the property is not an ID (default).

In database terms, the ID property is primary key column. Such properties are defined with the ‘id’ attribute set to true.

For example,

  @property({
    type: 'number',
    id: true,
  })
  id: number;

In LoopBack, auto-migration helps the user create relational database schemas based on definitions of their models. Here are some id property settings that can be used for auto-migration / auto-update:

Key Required? Type Description
generated No Boolean For auto-migrate usage. The generated property indicates the ID will be automatically generated by the database. When it is set to true, the value of the id property will be generated by the database automatically with its default type (e.g integer for MySQL and string for MongoDB).
useDefaultIdType No Boolean For auto-migrate usage. Set it to false when it's needed to auto-generate non-default type property values. For example, for PostgreSQL, to use uuid as the id property, the id type should set to string, generated should set to true, and this field should be set to false. Please check each connector's README file for more information about auto-migration/auto-update.

Tips:

  1. LoopBack CRUD methods expect the model to have an “id” property if the model is backed by a database.
  2. A model without any “id” properties can only be used without attaching to a database.
  3. If an ID property has generated set to true, the connector decides what type to use for the auto-generated key. For example for SQL Server, it defaults to number. This can be overwritten by setting useDefaultIdType to false.
  4. Check out Database Migration if you’d like to have LoopBack 4 create relational database’s schemas for you based on model definitions. Always check Database Connectors for details and examples for database migration / discover.

Array Property Decorator

There is a limitation to the metadata that can be automatically inferred by LoopBack, due to the nature of arrays in JavaScript. In JavaScript, arrays do not possess any information about the types of their members. By traversing an array, you can inspect the members of an array to determine if they are of a primitive type (string, number, array, boolean), object or function, but this does not tell you anything about what the value would be if it were an object or function.

For consistency, we require the use of the @property.array decorator, which adds the appropriate metadata for type inference of your array properties.

@model()
class Order extends Entity {
  @property.array(Product)
  items: Product[];
}

@model()
class Thread extends Entity {
  // Note that we still require it, even for primitive types!
  @property.array(String)
  posts: string[];
}

Additionally, the @property.array decorator can still take an optional second parameter to define or override metadata in the same fashion as the @property decorator.

@model()
class Customer extends Entity {
  @property.array(String, {
    name: 'names',
    required: true,
  })
  aliases: string[];
}

Extra attributes for json schema can be supplied via the jsonSchema within the second parameter.

@model()
class Customer extends Entity {
  @property(String, {
    jsonSchema: {
      format: 'email',
    },
  })
  email: string;
}

For @property.array, the jsonSchema is for the item type instead of the array itself.

@model()
class TestModel {
  @property.array(String, {
    jsonSchema: {
      format: 'email',
      minLength: 5,
      maxLength: 50,
      transform: ['toLowerCase'],
    },
  })
  emails?: string[];
}

To define a nested array property, you must provide the jsonSchema field to describe the sub-array property. For example:

@model()
class TestModel {
  // alternatively use @property.array('array')
  @property.array(Array, {
    jsonSchema: {
      type: 'array',
      items: {type: 'string'},
    },
  })
  nestedArr: Array<Array<string>>;
}

If the jsonSchema field is missing, you will get an error saying

You must provide the “jsonSchema” field when define a nested array property’

Custom Validation Rules and Error Messages

You can also specify the validation rules in the jsonSchema field of the property option and configure them with custom error messages.

The validation rules and custom error messages are configured this way.

@model()
class Product extends Entity {
  @property({
    name: 'name',
    description: "The product's common name.",
    type: 'string',
    // JSON validation rules
    jsonSchema: {
      minLength: 10,
      maxLength: 30,
      errorMessage: 'Name should be between 10 and 30 characters.',
    },
  })
  public name: string;
}

In case you want to send an error message specific to the validation rule that did not pass, you can configure errorMessage this way.

jsonSchema: {
  minLength: 10,
  maxLength: 30,
  errorMessage: {
    // Corresponding error messages
    minLength: 'Name should be at least 10 characters.',
    maxLength: 'Name should not exceed 30 characters.',
  }
}

Check out the documentation of Parsing requests to see how to do it in details.

The property decorator leverages LoopBack’s metadata package to determine the type of a particular property.

Example:

export class StandardUser {
  public email: string;
  public anotherProperty: boolean;
}

@model()
export class UserModel {
  @property()
  public email: StandardUser['email']; // => results in \"__metadata(\"design:type\", Object)\" instead of \"__metadata(\"design:type\", String)\"
}

(see Issue #3863 for more details)

@model()
class Product extends Entity {
  @property()
  public name: string; // The type information for this property is String.
}

ENUM Property

The @property decorator can take in jsonSchema to customize the JSON schema inferred for the model property. For enum type, it can be used as follows:

enum QueryLanguage {
  JSON = 'json',
  SQL = 'sql',
  MONGO = 'mongo'
}

// ...

@property({
  type: 'string',
  required: true,
  jsonSchema: {
    enum: Object.values(QueryLanguage),
  },
})
queryLanguage: QueryLanguage;

How LoopBack Models Map to Database Tables/collections

A frequently asked question is, how can I configure a custom table/collection name different from model class name?

No matter you set up models and database tables/collections through the CLI lb4 model, Model migration, or Model discovery, models/properties would be mapped to corresponding tables/columns based on some conventions or connector-specific setting in model and/or property definitions.

When there is no any connector-specific settings, for example:

@model()
export class MyModel extends Entity {
  @property({
    type: 'number',
    required: true,
    id: true,
  })
  id: number;

  @property({
    type: 'string',
    required: false,
  })
  myName?: string;
}

connectors would map the model based on the convention they have. Take the Oracle connector as an example, it would look for a table named MYMODEL under the default schema in the database and also map properties id and name to columns named ID and MYNAME in that table as UPPERCASE is the default case of Oracle database. Similarly, with the PostgreSQL connector, it would look for a table named mymodel under the default schema and columns named id and myname. On one hand, it’s convenient if you have default values on your database. On the another hand, it might be troublesome if it fails to find tables/columns with default names.

The following shows the general idea of how you can specify database definition through the connector-specific settings to avoid the issue above.

Data Mapping Properties

The following fields of settings of the model definition can describe/customize schemas or tables/collections names in the database as settings.<connectorName>:

Property Type Description
[connectorName].schema String schema of the table.
[connectorName].table String the table name. For SQL databases.
[connectorName].collection String the table name. For NoSQL databases.

The following fields of settings of the model definition describe/customize schemas or tables/collections names in the database as settings.<connectorName>.<propName>:

The following are common fields of the property definition that describe the columns in the database as `.:

Property Type Description
columnName String Column name. For SQL databases.
fieldName String Column name. For NoSQL databases.
dataType String Data type as defined in the database
dataLength Number Data length
dataPrecision Number Numeric data precision
dataScale Number Numeric data scale
nullable Boolean If true, data can be null

The following example shows how to configure custom table/column names different from the model and some other settings in PostgreSQL database:

@model({
  settings: {
    postgresql: {schema: 'quarter2', table: 'my_model'}, // custom names
  },
})
export class MyModel extends Entity {
  @property({
    type: 'number',
    required: true,
    id: true,
    postgresql: {
      columnName: 'custom_id',
      dataType: 'integer',
      dataLength: null,
      dataPrecision: null,
      dataScale: 0,
      nullable: 'NO',
    },
  })
  id: number;

  @property({
    type: 'string',
    required: false,
    postgresql: {
      columnName: 'my_name',
      dataType: 'text',
      dataLength: 20,
      dataPrecision: null,
      dataScale: 0,
      nullable: 'NO',
    },
  })
  myName?: string;
}

With the mapping, you can configure custom names different from the model. In the above example, the model property (id) maps to the database column named (custom_id) in the table named my_model.

Non-public Information
Removed until https://github.com/strongloop/loopback-datasource-juggler/issues/128 is resolved.

Conversion and formatting properties

Format conversions are declared in properties, as described in the following table:

  <table>
    <tbody>
      <tr>
        <th>Key</th>
        <th>Type</th>
        <th>Description</th>
      </tr>
      <tr>
        <td>trim</td>
        <td>Boolean</td>
        <td>Whether to trim the string</td>
      </tr>
      <tr>
        <td>lowercase</td>
        <td>Boolean</td>
        <td>Whether to convert a string to lowercase</td>
      </tr>
      <tr>
        <td>uppercase</td>
        <td>Boolean</td>
        <td>Whether to convert a string to uppercase</td>
      </tr>
      <tr>
        <td>format</td>
        <td>Regular expression</td>
        <td>Format for a date property.</td>
      </tr>
    </tbody>
  </table>

JSON Schema Inference

Use the @loopback/repository-json-schema module to build a JSON schema from a decorated model. Type information is inferred from the @model and @property decorators. The @loopback/repository-json-schema module contains the getJsonSchema function to access the metadata stored by the decorators to build a matching JSON schema of your model.

import {model, property} from '@loopback/repository';
import {getJsonSchema} from '@loopback/repository-json-schema';

@model()
class Category {
  @property()
  name: string;
}

@model()
class Product {
  @property({required: true})
  name: string;
  @property()
  type: Category;
}

const jsonSchema = getJsonSchema(Product);

jsonSchema from above would return:

{
  "title": "Product",
  "properties": {
    "name": {
      "type": "string"
    },
    "type": {
      "$ref": "#/definitions/Category"
    }
  },
  "definitions": {
    "Category": {
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": ["name"]
}

If a custom type is specified for a decorated property in a model definition, then a reference $ref field is created for it and a definitions sub-schema is created at the top-level of the schema. The definitions sub-schema is populated with the type definition by recursively calling getJsonSchema to build its properties. This allows for complex and nested custom type definition building. The example above illustrates this point by having the custom type Category as a property of our Product model definition.

Supported JSON Keywords

Following are the supported keywords that can be explicitly passed into the decorators to better tailor towards the JSON Schema being produced:

Keywords Decorator Type Default Description
title @model string model name Name of the model
description @model string None Description of the model
array @property boolean None Used to specify whether the property is an array or not
required @property boolean false Used to specify whether the property is required or not

Other ORMs

You might decide to use an alternative ORM/ODM in your LoopBack application. LoopBack 4 no longer expects you to provide your data in its own custom Model format for routing purposes, which means you are free to alter your classes to suit these ORMs/ODMs.

However, this also means that the provided schema decorators will serve no purpose for these ORMs/ODMs. Some of these frameworks may also provide decorators with conflicting names (e.g. another @model decorator), which might warrant avoiding the provided juggler decorators.