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.
Creating a schema via the dashboard is straightforward. Simply navigate to the “Schemas” page in the project you want to add the schema to, 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.
If you would like to work through an example, you can follow along by using the Multiplayer Form example.
Let’s create a new schema called collaborative-form
in your dashboard, with
the following definition:
Schemas are automatically versioned to facilitate migrations. By saving the new
schema, we have created the first version, named collaborative-form@1
.
To attach the schema we just created to a room, call the following endpoint:
To demonstrate the importance of schema validation and how unsafe operations
will now fail, we will change the name
field in our storage mutation to
organization
to simulate a bug:
with
After updating and running locally, we should now see the following error because our deployed schema will reject the mutation:
Other examples where schema validation would catch the error include:
name
variable to a number, as it is
defined as a stringname
variable: it was not defined as optional in
the schemaWhen an instance like this occurs, it’s indicative of a bug in your app. You should fix it, just like you would, for a TypeScript bug.
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.