syntax.mdx

---
meta:
  title: "Schema syntax"
  parentTitle: "Schema validation"
  description: "Liveblocks schema syntax"
---

This document describes the language rules for writing your own Liveblocks
schemas. It is an exhaustive account of all features that are implemented and
supported as part of the the public beta and is
[open source](https://github.com/liveblocks/liveblocks/tree/main/schema-lang).

We support: scalars, arrays, objects, optionals, `LiveObject`, `LiveList`,
`LiveMap`, and most unions. We’re sharing our plans for other syntaxes so you
can give us early feedback
[here](https://github.com/liveblocks/liveblocks/discussions/674).

## Storage root

Each schema must include the `Storage` type, a special type of “root” object.

```ts
type Storage {

}
```

## Scalars

Familiar scalar types are globally available when you create a schema:

- `string`
- `number`
- `boolean`
- `null`

A sample schema using only scalar types could look like this:

```ts
type Storage {
  name: string
  age: number
  hasSiblings: boolean
  favoritePet: string | null
}
```

And here are some updates that would be accepted and rejected by the schema:

```ts
// ✅ Valid storage updates
root.set("name", "Marie Curie");
root.set("age", 66);
root.set("hasSiblings", true);
root.set("favoritePet", "Cooper");
root.set("favoritePet", null);

// ❌ Invalid storage updates
root.set("name", true);
root.set("hasSiblings", null);
root.set("favoritePet", 0);
```

You can also use literal types to restrict values even further:

```ts
type Event {
  statusCode: 200 | 400
  info: string
}

type Storage {
  theme: "light" | "dark"
  history: LiveList<Event>
}
```

## Optionals

Each field inside an object type can be marked optional using the `?` operator.
An optional field means that it can be deleted.

For example, to make the `age` field optional:

```ts highlight="3"
type Storage {
  name: string
  age?: number
  height: number
  hasSiblings: boolean
}
```

Accepted and rejected updates:

```ts
// ✅
root.delete("age");

// ❌ Field 'name' is not optional
root.delete("name");
```

<Banner title="Comparison with GraphQL">
  Notice that we made the decision to make every field mandatory by default, as
  opposed to GraphQL.
</Banner>

## Objects

Our language supports two different ways to declare object types:

- Named object types

```ts
type Scientist {
  name: string
  age: number
}

type Storage {
  scientist: Scientist
}
```

- Anonymous object types (inlined)

```ts
type Storage  {
  scientist: { name: string, age: number }
}
```

These definitions are equivalent. Accepted and rejected updates:

```ts
// ✅
root.set("scientist", { name: "Marie Curie", age: 66 });

// ❌ Required field 'age' is missing
root.set("scientist", { name: "Marie Curie" });
```

## LiveObject

To use an object type definition as a “live” object, wrap it in the built-in
[`LiveObject`](/docs/api-reference/liveblocks-client#LiveObject) construct, like
so:

```ts
type Scientist {
  name: string
  age: number
}

type Storage {
  scientist: LiveObject<Scientist>
  //         ^^^^^^^^^^
}
```

Accepted and rejected updates:

```ts
// ✅
root.set("scientist", new LiveObject({ name: "Marie Curie"; age: 66 }));

// ❌ Should be a LiveObject
root.set("scientist", { name: "Marie Curie"; age: 66 });
```

## Arrays

Arrays can be defined like this:

```ts
type Storage {
  animals: string[]
}
```

Accepted and rejected updates:

```ts
// ✅
root.set("animals", ["🦁", "🦊", "🐵"]));

// ❌ Should contain strings
root.set("animals", [1, 2, 2]);
```

## LiveList

To use a “live” array instead of a normal array, wrap your item type in a
[`LiveList`](/docs/api-reference/liveblocks-client#LiveList) when you reference
it.

For example:

```ts
type Storage {
  animals: LiveList<string>
  //       ^^^^^^^^
}
```

Accepted and rejected updates:

```ts
// ✅
root.set("animals", new LiveList(["🦁", "🦊", "🐵"]));

// ❌ Should be a LiveList
root.set("animals", ["🦁", "🦊", "🐵"]);
```

## LiveMap

It’s also possible to define a
[`LiveMap`](/docs/api-reference/liveblocks-client#LiveMap) in your schema.

For example:

```ts
type Shape {
  x: number
  y: number
  fill: "red" | "yellow" | "blue"
}

type Storage {
  shapes: LiveMap<string, Shape>
  //      ^^^^^^^
}
```

The first argument to a `LiveMap` construct must always be `string`.

Accepted and rejected updates:

```ts
// ✅
root.set(
  "shapes",
  new LiveMap([["shapeId", { x: 100, y: 100, fill: "blue" }]])
);

// ❌ Required field 'fill' is missing
root.set("shapes", new LiveMap([["shapeId", { x: 100, y: 100 }]]));
```

## Unions

You can model a choice between two types using a union, which will be familiar
from TypeScript. Here are some examples:

```ts
type Storage {
  ids: (string | number)[]
  selectedId: string | null
  person: LiveObject<Person> | null
  people: LiveList<LiveObject<Person>> | null
}
```

## What’s to come

We’re also planning to support more language features. Discriminated unions,
regex, ranges, etc...

If you’re interested in a specific feature, please send your feedback on this
GitHub [discussion](https://github.com/liveblocks/liveblocks/discussions/674) so
we can prioritize it appropriately!