Model definition JSON file

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

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>
</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 excludeBaseProperties = ['property-be-excluded-from-base-model']. excludeBaseProperties is recommended approach over previous approach of setting the base property to ‘null’ or ‘false’.

For example,

... 
"base": "User",
"excludeBaseProperties" = ["lastUpdated", "credentials", "challenges"],
"properties": {
  ...
}
...

Another example,

Excludes ‘id’ property from the base model, “Model”

... 
"base": "Model",
"excludeBaseProperties" = ["id"],
"properties": {
  ...
}
...

Below way of excluding base properties by setting the base property to ‘null’ or ‘false’ is not recommended. Instead, use excludeBaseProperties as shown above.

... 
"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 scopeskey 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 operation 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

The methods key defines remote methods for the model. Its value is an object with a string key for each remote method name:

• Instance method names must start with prototype..
• Static method names can be any legal name.

For example, the following defines a static remote method called “greet” and an instance method called “getProfile”.

...
  "methods": {
    "greet": {
      "accepts": [
        {
          "arg": "msg",
          "type": "string",
          "http": {
            "source": "query"
          }
        }
      ],
      "returns": {
        "arg": "greeting",
        "type": "string"
      },
      "http": {
        "verb": "get"
      }
    },
  "prototype.getProfile": {
      ... // Instance remote method - options
    }
...

Remote method options

You specify remote method options when you register a remote method, either as an argument to the Model.remoteMethod() method if you register it in code, or in the methods key if you register it in JSON. Either way, it’s a JavaScript object with the same set of properties.

Person.greet(name, age, callback)...

{  ...
accepts: [
 {arg: 'name', type: 'string'},
 {arg: 'age',  type: 'number'},
 ...],
... }

accessScopes: [
  'read',
  'read:user'
]

returns: {arg: 'greeting',
          type: 'string'}

[
 "Lorem ipsum dolor sit amet, consectetur adipiscing elit,",
 "sed do eiusmod tempor incididunt ut labore et dolore",
 "magna aliqua."
]

http property

The http property provides information on HTTP route at which the remote method is exposed.

http: {path: '/sayhi'}

http: {path: '/sayhi',
       verb: 'get'}

http: {status: 201}

http: {errorStatus: 400}

Argument descriptions

The accepts and returns options properties define either a single argument as an object or an ordered set of arguments as an array. The following table describes the properties of each individual argument.

For example, a single argument, specified as an object:

{arg: 'myArg', type: 'number'}

Multiple arguments, specified as an array:

[
  {arg: 'arg1', type: 'number', required: true},
  {arg: 'arg2', type: 'array'}
]

Returning a file (stream) response

Specify { type: 'file', root: true } for a callback argument that will be sent directly as the response body. A file argument can be set to one of the following values:

• String
• Buffer
• ReadableStream (anything that exposes .pipe() method)

Example:

module.exports = function(MyModel) {
  MyModel.download = function(cb) {
    // getTheStreamBody() can be implemented by calling http.request() or fs.readFile() for example
    getTheStreamBody(function(err, stream) {
      if (err) return cb(err);
      // stream can be any of: string, buffer, ReadableStream (e.g. http.IncomingMessage)
      cb(null, stream, 'application/octet-stream');
    });
  };

  MyModel.remoteMethod('download', {
    returns: [
      {arg: 'body', type: 'file', root: true},
      {arg: 'Content-Type', type: 'string', http: { target: 'header' }}
    ]
  });
};

HTTP mapping of input arguments

There are two ways to specify HTTP mapping for input parameters (what the method accepts):

• Provide an object with a source property
• Specify a custom mapping function

Using an object with a source property

To use the first way to specify HTTP mapping for input parameters, provide an object with a source property that has one of the values shown in the following table.

For example, an argument getting the whole request body as the value:

{ arg: 'data', type: 'object', http: { source: 'body' } }

Another example showing the Express HTTP request and response objects:

[
 {arg: 'req', type: 'object', 'http': {source: 'req'}},
 {arg: 'res', type: 'object', 'http': {source: 'res'}}
]

Using a custom mapping function

The second way to specify HTTP mapping for input parameters is to specify a custom mapping function; for example:

{
  arg: 'custom',
  type: 'number',
  http: function(ctx) {
    // ctx is LoopBack Context object

    // 1\. Get the HTTP request object as provided by Express
    var req = ctx.req;

    // 2\. Get 'a' and 'b' from query string or form data and return their sum.
    return -req.param('a') - req.param('b');
  }
}

If you don’t specify a mapping, LoopBack will determine the value as follows (assuming name as the name of the input parameter to resolve):

1. If there is an HTTP request parameter args with JSON content, then it uses the value of args['name'].
2. Otherwise, it uses req.param('name').

Returning data outside of a JSON field

Specifying a return argument with the arg property will automatically return a JSON object with your data stored within a field of the same name.

If you want to return data as the main response, for example an array, you can do so by setting the root property within the returns object and omitting arg. 

returns: {type: 'array', root: true}

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"
    }
},
...