Model definition JSON file

Overview

The LoopBack Model generator creates a model JSON file for each model in either the server/models or the common/models directory (depending on your response to the generator’s prompts). The file is named model-name.json, where model-name is the model name; for example, customer.json. The model JSON file defines models, relations between models, and access to models. 

For example, here is an excerpt from a model definition file for a customer model that would be in /common/models/customer.json:

{
  "name": "Customer",  // See Top-level properties below
  "description": "A Customer model representing our customers.",
  "base": "User",
  "idInjection": false,
  "strict": true,
  "options": { ... }, // See Options below - can also declare as top-level properties
  "properties": { ... }, // See Properties below
  "hidden": [...], // See Hidden properties below
  "validations": [...],  // See Validations below
  "relations": {...},  // See Relations below
  "acls": [...],  // See ACLs below
  "scopes": {...},  // See Scopes below
  "indexes" : { ...}, // See Indexes below
  "methods": [...],  // See Methods below - New for LB2.0 - Remoting metadata
  "http": {"path": "/foo/mypath"}
}

Top-level properties

Properties are required unless otherwise designated.

[
  "Lorem ipsum dolor sit amet, consectetur adipiscing elit",

      "sed do eiusmod tempor incididunt ut labore et dolore",
 "magna aliqua."
] 

Options

The options key specifies advanced options, for example data source-specific options.

Advanced options

Data source-specific options

When a model is attached a data source of certain type such as Oracle or MySQL, you can specify the name of the database schema and table as properties under the key with the name of the connector type. The value of this key must match the value of the corresponding connector property in datasources.json. For example, in the snippet below, there would be an entry in datasources.json like this:  "myDB": { "name": "myDB",  "connector": "mysql", ... }.

...
  "options": {
    "mysql": {
      "table": "location"
    },
    "mongodb": {
      "collection": "location"
    },
    "oracle": {
      "schema": "BLACKPOOL",
      "table": "LOCATION"
    }
  },
  ...

Properties

The properties key defines one or more  properties, each of which is an object that has keys described in the following table. Below is an example a basic property definition:

...
"properties": {
  "firstName": {
    "type": "String", 
    "required": "true"
  },
  "id": {
    "type": "Number", 
    "id": true, 
    "description": "User ID"
},
...

General property properties

Each model property can have the properties described in the following table. Only the type property is required; for properties with only a type, you can use the following shorthand:

"propertyName": "type"

For example:

...
"emailVerified": "boolean",
"status": "string",
...

[
  "Lorem ipsum dolor sit amet, consectetur adipiscing elit",

      "sed do eiusmod tempor incididunt ut labore et dolore",
 "magna aliqua."
]  

ID properties

A model representing data to be persisted in a database usually has one or more ID properties that uniquely identify the model instance. For example, the user model might have user IDs.

By default, if no ID properties are defined and the idInjection property is true (or is not set, since true is the default), LoopBack automatically adds an id property to the model as follows:

id: {type: Number, generated: true, id: true}

The generated property indicates the ID will be automatically generated by the database. If true, the connector decides what type to use for the auto-generated key. For relational databases, such as Oracle or MySQL, it defaults to number. If your application generates unique IDs, set it to false.

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).
• Positive number, such as 1 or 2: the property is the index of a composite ID.

In database terms, ID properties are primary key column(s). Such properties are defined with the ‘id’ attribute set to true or a number as the position for a composite key.

For example,

{
  "myId": {
    "type": "string", 
    "id": true 
   }
}

Then:

1. If a model doesn’t have explicitly-defined ID properties, LoopBack automatically injects a property named “id” unless the idInjection option is set to false.
2. 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.
3. LoopBack CRUD methods expect the model to have an “id” property if the model is backed by a database.
4. A model without any “id” properties can only be used without attaching to a database.

Composite IDs

LoopBack supports the definition of a composite ID that has more than one property. For example:

var InventoryDefinition = { 
  productId: {type: String, id: 1}, 
  locationId: {type: String, id: 2}, 
  qty: Number 
}

The composite ID is (productId, locationId) for an inventory model.

Data mapping properties

When using a relational database data source, you can specify the following properties that describe the columns in the database.

For example, to map a property to a column in an Oracle database table, use the following:

...
"name": {
      "type": "String",
      "required": false,
      "length": 40,
      "oracle": {
        "columnName": "NAME",
        "dataType": "VARCHAR2",
        "dataLength": 40,
        "nullable": "Y"
      }
    }
...

<div class="table-wrap">
  <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>
</div>

Exclude properties from base model

By default, a model inherits all properties from the base. To exclude some base properties from being visible, you need to set the property to false or null.

For example,

... 
"base": "User",
"properties": {
  "lastUpdated": false,
  "credentials": null,
  "challenges": null,
  "modified": "date"
}
...

Hidden properties

A hidden property is not sent in the JSON data in the application’s HTTP response. The property value is an array of strings, and each string in the array must match a property name defined for the model.

An example of a hidden property is User.password:

{
  ...
  "properties": {
    ...
    "password": {
      "type": "string",
      "required": true
    },
    ...
  },
  "hidden": ["password", "verificationToken"],
  ...
}

If you want to white-list the fields returned instead of black-listing them, consider:

• Applying the fields of the model’s defaultscope. This will operate at the database response layer so limiting your ability to check a field in the database that you otherwise would not wish exposed to the outside world (a private flag, for example).
• Overriding your model’s toJSON method

See discussion of white-listing on GitHub.

Protected properties

The protected property is an array of strings, and each string in the array must match a property name defined for the model.

A protected property is not sent in HTTP response JSON data if the object is nested inside another object. For instance, suppose there is an Author object and a Book object. Book has a relation to Author, and Book is a public API. The Author model has personal information (such as social security number) which should be “protected” so anyone looking up the author of the book will not get that information.

An example configuring email as a protected property:

{
  ...
  "properties": {
    ...
    "email": {
      "type": "string",
      "required": true
    },
    ...
  },
  "protected": ["email"],
  ...
}

Validations

Specify constraints on data with validations properties. See also Validatable class.

For example:

"username": {
  "type": "string", 
  "description": "User account name",  
  "min": 6, 
  "max": 24
}

Relations

The relations key defines relationships between models through a JSON object. Each key in this object is the name of a related model, and the value is a JSON object as described in the table below.

For example:

...
"relations": {
  "accessTokens": {
    "model": "accessToken",
    "type": "hasMany",
    "foreignKey": "userId"
  },
  "account": {
    "model": "account",
    "type": "belongsTo"
  },
  "transactions": {
    "model": "transaction",
    "type": "hasMany"
  }
}, 
...

Example of hasManyThrough:

"patient": {
    "model": "physician",
    "type": "hasMany", 
    "through" : "appointment"
}

ACLs

The value of the acls key is an array of objects that describes the access controls for the model. Each object has the keys described in the table below.

"acls": [
    {
      "permission": "ALLOW",
      "principalType": "ROLE",
      "principalId": "$everyone",
      "property": "myMethod"
    }, 
    ...
]

Scopes

Scopes enable you to specify commonly-used queries that you can reference as method calls on a model.

The scopes key defines one or more scopes (named queries) for models. A scope maps a name to a predefined filter object to be used by the model’s find() method; for example:

"scopes": {
	"vips": {"where": {"vip": true}}, 
	"top5": {"limit": 5, "order": "age"}
}

The snippet above defines two named queries for the model:

• vips: Find all model instances with vip flag set to true
• top5: Find top five model instances ordered by age

Within the scopes object, the keys are the names, and each value defines a filter object for PersistedModel.find().

You can also define a scope programmatically using a model’s scope() method, for example:

User.scope('vips', {where: {vip: true}});
User.scope('top5', {limit: 5, order: 'age'});

Now you can call the methods defined by the scopes; for example:

User.vips(function(err, vips) {
  //...
});

Default scope

If you wish for a scope to be applied across all queries to the model, you can use the default scope for the model itself.

For example:

{
  "name": "Product",
  "properties": {
    ...
  }
  "scope": {
    "order": "name",
    "limit": 100
    "where": {
      "deleted": false
    }
  }
}

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

Product.find({offset: 0}, cb);

Becomes the equivalent of this:

Product.find({order: "name", offset: 0, limit: 100, where: {deleted: false}}, cb)

Default scopes with where filters

Adding a scope to a model definition (in the model.json file) automatically adds a method to model called defaultScope(). LoopBack will call this method whenever a model is created, updated, or queried.

Each time a model instance is created or updated, the generated defaultScope() method will modify the model’s properties matching the where filter to enforce the values specified.

If you don’t want to have the default scope applied in this way, use named scopes where possible.

If you must use a default scope, but don’t want it to affect upsert(), for example, simply override the model’s defaultScope() method prior to calling upsert(); for  example:

var defaultScope = Report.defaultScope;
  Report.defaultScope = function(){};
  Report.upsert({id: reportId, 'deleted': true}, function(...) {
    Report.defaultScope = defaultScope;
    //...
  });

Methods

You can declare remote methods here. Until this feature is implemented, you must declare remote methods in code. See Remote methods.

Indexes

Declare indexes for a model with the indexes property, for example:

"indexes": {
  "name_age_index": {
    "keys": {"name": 1, "age": -1}
  },
  "age_index": {"age": -1}
}

The snippet above creates two indexes for the declaring model:

• A composite index named name_age_index with two keys: name in ascending order and age in descending order.
• A simple index named age_index with one key: age in descending order.

The full syntax for an individual index is:

"<indexName>": {
  "keys": {
     "<key1>": 1,
     "<key2>": -1
   },
   "options": {
     "unique": true
   }
}

If you don’t need to specify any options, you can use a shortened form:

"<indexName>": {
  "<key1>": 1,
  "<key2>": -1
}

You can specify indexes at the model property level too, for example:

{
  "name": {
    "type": "String",
    "index": true
  },
  "email": {
    "type": "String",
    "index": {
      "unique": true
    }
  },
  "age": "Number"
}

This example creates two indexes: one for the name key and another one for the email key. The email index is unique.

MySQL indexes

For MySQL, you can declare multi-column indexes as follows (for example):

...
"indexes":
{
    "UNIQUE_INDEX":  {
        "columns": "column1,column2,...",
        "kind": "unique"
    }
},
...