Schema validation is essential for future-proofing your application and ensuring that implementing new features or data structures into your app will keep the integration you have established with Liveblocks.
We currently mitigate the risk of introducing client-side errors by allowing you
to type your storage in
liveblocks.config.ts. Still, we want to go one step
further to help you protect your application by attaching a schema to a room
that rejects invalid modifications.
By using schema validation, you will be able to:
The primary purpose of schema validation is to prevent corrupted data from being loaded from the server. To add schema validation to your application, take the following steps:
By default, a room storage accepts any modifications coming from the client. But once you attach a schema to a room, Liveblocks will reject any modifications to the storage that do not match the schema you provided. Situations like this should only happen in development mode, and the developer is responsible for fixing them.
You can interact with the schemas you create through the dashboard or by calling the REST API. In this guide, we will cover the following operations:
Creating a schema via the dashboard is straightforward. Simply navigate to the “Schemas” page in the project you want to add the schema, and click on the “Create schema” button. Provide a name and a definition that describes the shape of the data you want to store in your rooms.
To create a schema, provide the name and body in the JSON payload. Example:
Note that in this example, the outermost
body field is the body of the HTTP
request (required by the
fetch API), whereas the innermost
body field is
consumed by our API to read the schema text.
In the dashboard, you can delete a schema by navigating to the schema in question and clicking on the trash icon next to the schema version you want to delete. If you have attached a schema to a room, you will need to detach the schema from the room before you can delete it. If this schema is frozen, the trash icon will be greyed out.
If your schema is in a detached state, you can also delete it by using the delete schema API.
You can attach a schema to a room via the dashboard by navigating to the room in question and clicking on the “Attach schema” button.
Alternatively, you can use the attach schema API. For example:
You can use the dashboard to remove a schema from a room by navigating to the room in question and clicking on the dropdown menu which displays the currently attached schema. From there, you can click on the “Detach schema” button.
To detach a schema from a room using the detach schema API, use the following code:
If you would like to work through an example, you can follow along by using the Collaborative To-Do List.
Let’s create a new schema called
todo-list in your dashboard, with the
Schemas are automatically versioned to facilitate migrations. By saving the new
schema, we have created the first version, named
To attach the schema we just created to a room, you can:
To demonstrate the importance of schema validation and how unsafe operations
will now fail, we will change the
checked field in our schema as required,
which means that new items added to the list will have to be checked by default.
The new schema definition will look like this:
After updating the schema, and attaching the new version to our room, we can now
run our app locally by calling
npm run dev and adding a new item to the list.
The new item will cause the following error to be thrown:
Other examples where schema validation would catch the error include:
checkedvariable to a number, as it is defined as a boolean in the schema
checkedvariable: it was not defined as optional in the schema
When a schema validation error occurs, the LiveBlocks server will reject the operation
When an instance like this occurs, it’s indicative of a bug in your app. In production, an error like this should never occur. This is because you should address validation errors in the same way you address TypeScript errors. You don't ship to production when your app has TypeScript errors, and neither do you ship to prod when there are schema validation errors. Validation errors are the responsibility of the developer to resolve.
Our roadmap includes the ability to generate TypeScript types from the schema and tools to help you migrate your data from one schema version to the next. If you have any feedback or questions regarding schema validation, come talk to us on this GitHub discussion.