Data Modeling

Data Modeling

Edit on GitHub

In this lesson you will learn how to model the data for an application and the relationships between the different models.

Initially, the schema for a todo list application may look like the table below.

List Task
name name
owner complete

With the following schema relationships:

  1. A task belongs to a list.
  2. A list belongs to a user.

Throughout this lesson you will extend this basic data model to meet the requirements of the application.

From Tables to JSON

Couchbase Mobile stores data in documents rather than in table rows. A document is a JSON object containing a number of key-value pairs. This means that it can take any form as long as it is valid JSON. The following image represents the same schema as the table above but in JSON format.

We use the type property to store the entity type on each document.

Storing Dates

Another requirement of the application is to sort tasks by the time they were created at. JSON itself does not specify how dates should be represented. To keep chronological ordering with string dates, they should be stored in ISO-8601 format (YYYY-MM-DDThh:mm:ssZ). The following diagram adds a createdAt field on the task document with the date in ISO-8601 format.

Document IDs

The document ID is the primary identifier of a document in the database. It can be pre-defined by the application or automatically generated by the database during a write operation. It is unique in the system and does not change throughout the lifecycle of a document (CRUD operations). The image below adds unique document IDs on the List and Task models..

Note: You may notice that the document ID on the List model is prefixed with the owner. This design choice will be discussed in detail in the Access Control lesson.

Entity relationship

There is a one-to-many relationship between the List and Task documents. A List can hold several Tasks but a Task can only belong to one List. In Couchbase Mobile, relationships between different entities (1:1, 1:many and many:many) are implemented by keeping a reference from the child to the parent model. The document ID serves as the reference (foreign key) since it is unique and doesn't change. The image below adds a list property on the Task model.


Tasks can have an image attached to them. Attachments are also persisted to disc and synchronized with the document they belong to. The following diagram adds an attachment called photo of type image/jpg to the Task model.

Note: All the fields that start with "_" are Couchbase specific (i.e _id, _attachments). For this reason, it is not recommended to name your own properties with a leading underscore.


Well done! You've completed this lesson on modeling the data in different documents and the relationships between them. In the next lesson you'll learn how to design the security model for each type of document. Feel free to share your feedback, findings or ask any questions on the forums.