In order to make data composable, there need to be rules. Models help OrbisDB and other applications in the ecosystem understand the data that’s coming in.

Definition

Models are a Ceramic-native concept used to determine the way data is created and how it relates to other data. Models utilize JSON Schema (link) to define value data types, rules for validation and the overall shape of data.

Models also contain additional information, such as relations which help build robust relational data systems.

A basic Model definitions is as follows

{
  "name": "Model name",
  "views": {},
  "schema": {
    "type": "object",
    "$defs": {},
    "$schema": "<https://json-schema.org/draft/2020-12/schema>",
    "required": [], // Required fields
    "properties": {} // Keys, values and their data types
    },
    "additionalProperties": false
  },
  "version": "2.0",
  "interface": false,
  "relations": {}, // If any of the keys are related to other data
  "implements": [],
  "immutableFields": [],
  "description": "Model description",
  "accountRelation": {
    "type": "list | single | set" // Account relation type
  }
}

Account Relation

Account Relations define the number of entries per account. You should view them as table constraints.

There are 3 Account Relations available: list (default), single, set.

List (unlimited)

This is the default Account Relation and means - the author can add as many entries as they want.

Set (one per value)

This Account Relation can be viewed as UNIQUE (account, ...fields). Only a single entry per author and unique field value can be created.

An example use case is product reviews in which case each user should only be able to leave 1 review per product.

If the user were to try and add another review for an existing product, the original review would be updated. However, they would be able to post reviews on other products as expected.

Single (one)

As the name suggests, this Account Relation ensures only a single entry per Account can be created. This is tied to the Model, so a user can only create a single entry for this Model across all apps and Contexts.

In SQL-ish format, this would be equal to UNIQUE (account, model).

An example use case would be a user profile shared across the ecosystem.

If the user were to try and create a new entry, instead of adding a new row, the original one will be updated.