The plugin helps you define schemas for your models. It supports a regular types, arrays, nested or reference models/collections, allows to define a custom data types and computable properties.

npm install backbone.schema
34 downloads in the last month


NPM Version Build Status Dependency Status

The plugin helps you define schemas for your models. It supports a regular types, arrays, nested or reference models/collections, allows to define a custom data types and computable properties.


Getting Started

Create model

Define the model. It should be an instance of Backbone.Model or its inheritor.

var model = new Backbone.Model();

Create schema

Backbone.Schema is a decorator. Just pass the model into constructor of class to getting started.

var schema = new Backbone.Schema(model);

Define properties

Use schema.define(attribute, options) method to define properties of your model. If you want to define a lot of properties in one action use schema.define(attributes) option.

Option type

Type string

Converts value to string. Represents as is.

schema.define('string-property', { type: 'string' });

model.set('string-property', 999999.99); // --> "999999.99"
model.get('string-property'); // <-- "999999.99"
Type boolean

Converts value to boolean. Represents as is.

schema.define('boolean-property', { type: 'boolean' });

model.set('boolean-property', 'true'); // --> true
model.get('boolean-property'); // <-- true
Type number

Converts value to number. Represents as is, or as formatted string (depends from option format).

Additional options:

schema.define('number-property', { type: 'number', format: 'n', culture: 'en' });

model.set('number-property', '999,999.99'); // --> 999999.99
model.get('number-property'); // <-- "999,999.99"
Type datetime

Converts value to Date, ISO 8601, or Unix time. Represents as is, or as formatted string (depends from option format).

Additional options:

  • format - see more about date formatting
  • standard (available values are iso and unix) - defines in which way date will be stored in the model (if not specified, date will be stored as Date)
  • culture - see more about cultures
schema.define('datetime-property', { type: 'datetime', format: 'd', standard: 'unix', culture: 'en' });

model.set('datetime-property', '12/12/2012'); // --> 1355263200000
model.get('datetime-property'); // <-- "12/12/2012"
Type locale

Converts value to key of localization. Represents as is, or as string of localization (depends from availability of localization).

Additional options:

Globalize.addCultureInfo('en', {
    messages: {
        'HELLO_WORLD': 'Hello, World!'

schema.define('locale-property', { type: 'locale', culture: 'en' });

model.set('locale-property', 'Hello, World!'); // --> "HELLO_WORLD"
model.get('locale-property'); // <-- "Hello, World!"

Define properties of array type

Option array

Besides listed above data types you can define arrays. To do this just use option array instead of type. For example: { array: 'string' }, { array: 'number' } etc. In this case each item in array will be processed by corresponding handler.

Define computed property

You can define a computed properties with your own custom logic.

Options getter and setter

Manipulate these two options to describe behavior of a computed property.

var User = Backbone.Model.extend({
    initialize: function () {
        var schema = new Backbone.Schema(this);

        schema.define('fullName', {
            getter: function (attribute, value) {
                var firstName = this.model.get('firstName'),
                    lastName = this.model.get('lastName');

                return firstName + ' ' + lastName;

            setter: function (attribute, value) {
                var fullName = value.match(/\S+/g);

                return {
                    firstName: fullName[0],
                    lastName: fullName[1]
var user = new User({
    firstName: 'Dmytro',
    lastName: 'Nemoga'

user.get('fullName'); // <-- "Dmytro Nemoga"
user.set('fullName', 'Andriy Serputko'); // --> firstName: "Andriy", lastName: "Serputko"

Define nested models and collections

Option model

Converts value to model, using value as a set of attributes. Represents as is.

Additional options:

  • clear - if true, model removes an existing attributes before setting new (otherwise merges them)
schema.define('nested-model', { model: Backbone.Model });

model.set('nested-model', { id: 0, value: 'foo' }); // --> new Backbone.Model({ id: 0, value: 'foo' })
model.get('nested-model'); // <-- instance of Backbone.Model

Option collection

Converts value to collection, using value as a set of attributes. Represents as is.

Additional options:

  • reset - if true, collection removes an existing models before creating new (otherwise merges them)
schema.define('nested-collection', { collection: Backbone.Collection });

model.set('nested-collection', [ // --> new Backbone.Collection([
    { id: 1, value: 'bar' },     //         { id: 1, value: 'bar' },
    { id: 2, value: 'baz' },     //         { id: 2, value: 'baz' },
    { id: 3, value: 'qux' }      //         { id: 3, value: 'qux' }
]);                              //     ])

model.get('nested-collection'); // <-- instance of Backbone.Collection

Define reference models and collections

Before using reference models or collections make sure that you have a source collection.

var sourceCollection = new Backbone.Collection([
    { id: 0, value: 'foo' },
    { id: 1, value: 'bar' },
    { id: 2, value: 'baz' },
    { id: 3, value: 'qux' }

Option source

If you pass collection in this option, plugin tries to get model from it.

Type model

Converts value (a model ID in the source collection) to model, keeping reference to original model. Represents as is.

schema.define('reference-model', { type: 'model', source: sourceCollection });

model.set('reference-model', 0); // --> sourceCollection.get(0)
model.get('reference-model'); // <-- instance of Backbone.Model
Type collection

Converts value (a set of model IDs in the source collection) to collection, keeping references to original models. Represents as is.

schema.define('reference-collection', { type: 'collection', source: sourceCollection });

model.set('reference-collection', [ // --> new Backbone.Collection([
    1,                              //         sourceCollection.get(1),
    2,                              //         sourceCollection.get(2),
    3                               //         sourceCollection.get(3)
]);                                 //     ])

model.get('reference-collection'); // <-- instance of Backbone.Collection

Keeping integrity

The plugin prevents setting undefined values, instead of this it assigns a default value or null for regular properties, {} for models and [] for collections and arrays.



  • Backbone.Schema could be extended


  • Added CommonJS support


  • Removed text type
  • number and datetime requires format option for string output


  • Fixed behavior for model and collection types


  • Renaming option reset to clear for model type
  • Changed default behavior for model and collection types


  • Renaming types to handlers
  • Method refresh moved from model to schema
  • Removed backward reference to schema


  • refresh affects only registered attributes
  • model and collection attributes cannot be null


  • Option arrayOf renamed to array
  • Option fromSource renamed to source


  • Added option to use a custom culture


  • Fixed serious issue with model type


  • Handlers currency and percent merged into number


  • Plugin implemented as decorator, not a class
  • Option reset for model and collection types


  • Properties are configurable with additional options
  • Formatters and converters merged into types
  • Added support of reference models and collections
  • A lot of fixes


  • Added support of nested models and collections


  • Support of arrays
  • Added type locale
  • Removed method toJSON


  • Formatters and converters takes only value argument


  • Static methods runs in correct context, now they may be used as independent helpers


  • Properties formatters and converters is static


  • Removed CommonJS support


  • Added CommonJS support


  • Integration with project Backbone.Accessors
  • Method defineProperty renamed to property
  • Methods addGetter/addSetter merged to method computed
  • Option advanced of toJSON method renamed to schema


  • Removed argument options of defineProperty method's


  • Method addProperty renamed to defineProperty


  • Initial release
npm loves you