Model

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);
  }
}

• Model: 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 Model 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 {
  // ...
}

Common Tasks

• Define models at runtime
• Discover models from databases

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

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:

@model() class MySuperModel extends MyBaseModel {...}
  

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 model setting which allow hide properties defined in the parent model too, 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;
  ...
}

or at property level

@model()
class MyUserModel extends Entity {
  @property({id: true})
  id: number;
  @property({type: 'string'})
  email: string;
  @property({type: 'string', hidden: true})
  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:

[
"LoopBack 4 is a highly extensible Node.js and TypeScript framework",
"for building APIs and microservices.",
"Follow us on GitHub: https://github.com/loopbackio/loopback-next."
]

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:

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>:

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 `.:

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.

  <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:

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.