This plugin allow you define schemas for your models. It provides type control, computable properties, references between models and collections, filters and localization.

Dependencies:

• Backbone >= 1.1.0
• Underscore >= 1.5.2

For date/number formatting:

• Globalize >= 0.1.1

Globalize is not a hard dependency, it is only needed if you wish to use date and numbers formatting, or localization features.

First you need to define model and schema.

var model = new Backbone.Model(), schema = new Backbone.Schema(model);

Now you got instances of model and schema and you can start defining properties of the model. Use schema.define(attribute, options) method to do it.

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"

Converts value to boolean. Represents as is.

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

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

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

Additional options:

• format - see more about number formatting
• culture - see more about cultures

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"

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"

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

Additional options:

• culture - see more about cultures and localization

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!"

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.

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

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"

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

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

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

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

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

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

Backbone.Schema allows you to choose between several alternatives for the JSON representation of an attribute.

Possible values:

• true (default) - the default Backbone behavior. The value will be the same value that is kept in the model.attributes array. In Backbone.Scheme context this is value after a setter method have set the value.
• 'getter' - JSON will be the value that is returned from a getter function, either an explicit getter, or an implicit getter of a Backbone.Scheme type.
• function - a function of the form function(attribute, value, options) will return the JSON representation.
• false - The attribute will not appear in the JSON representation.

Examples:

  schema.define({
      'json-getter': { type: 'datetime', format: 'd', toJSON: 'getter' },
      'json-function': { type: 'string', toJSON: function(attribute, value, options){
          return value.toLowerCase();
      } },
      'json-false': {type: 'string', toJSON: false},

      'json-getter-array': { array: 'datetime', format: 'd', toJSON: 'getter' },
      'json-function-array': { array: 'string', toJSON: function(attribute, value, options){
          return value.toLowerCase();
      } },
      'json-false-array': { array: 'string', toJSON: false}
  })

  model.set({
    'json-getter': '12/12/2012',
    'json-function': 'Hello World',
    'json-false': 'Should not be in json',

    'json-getter-array': ['12/12/2012', '11/11/2011'],
    'json-function-array': ['Hello', 'World'],
    'json-false-array': ['should', 'not', 'be', 'in', 'json']
  })

  model.toJSON() // returns:
    'json-getter': '12/12/2012',
    'json-function': 'hello world',

    'json-getter-array': ['12/12/2012', '11/11/2011'],
    'json-function-array': ['hello', 'world']
  {

  }

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.

• Added AMD support
• Added toJSON option
• bugfixes

• Fixed issue with nested models and collections
• Removed Globlize as hard dependency.

• Fixed issue with nested models and collections

• 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