Yorkie

Schema Validation

Schema Validation allows you to declaratively define document structures and enforce them during collaborative editing. When a schema is attached to a document, every local edit is validated against the schema rules, preventing invalid changes from being applied.

How It Works

Schemas are defined using a TypeScript-like DSL, stored on the server, and delivered to clients when they attach a document. The SDK validates every doc.update() call against the schema rules before applying changes.

1. Define a schema in the Dashboard using the Schema DSL
2. A client attaches a document with a schema reference
3. The server validates that the existing document conforms to the schema
4. Schema rules are sent to the client along with the document
5. The client calls doc.update() to edit the document
6. The SDK validates the updated document against the schema rules
7. If valid, changes are applied; if invalid, the update is rejected with an error

Defining a Schema

Schemas use a TypeScript Type Alias syntax to define document structures. You can create schemas in the Dashboard's schema editor.

Basic Example

1type Document = {
2  title: string;
3  completed: boolean;
4  priority: integer;
5};

Rich Document Example

1type Document = {
2  title: string;
3  content: yorkie.Tree<{
4    doc: { content: "block+"; };
5    paragraph: { content: "text*"; marks: "bold italic link"; group: "block"; };
6    heading: { content: "text*"; marks: "bold"; group: "block"; };
7    blockquote: { content: "block+"; group: "block"; };
8    text: {};
9  }>;
10  tags: yorkie.Array<string>;
11  metadata: {
12    author: string;
13    updatedAt: date;
14  };
15};

Supported Types

Tree Schema

For yorkie.Tree, you can define node types with ProseMirror-compatible content expressions:

Content expression syntax:

Attaching a Schema to a Document

Specify a schema when attaching a document using the schema option:

1import yorkie from 'yorkie-js-sdk';
2
3const client = new yorkie.Client('https://api.yorkie.dev');
4await client.activate();
5
6const doc = new yorkie.Document('my-doc');
7await client.attach(doc, {
8  schema: 'my-schema@1', // Format: "schema-name@version"
9});

The schema reference uses the format name@version, where:

Handling Validation Errors

When a doc.update() call violates the schema, the SDK throws an error. Use try-catch to handle validation failures:

1try {
2  doc.update((root) => {
3    root.title = 123; // Error: schema expects string
4  });
5} catch (err) {
6  if (err.code === 'ErrDocumentSchemaValidationFailed') {
7    console.error('Schema violation:', err.message);
8    // e.g., "schema validation failed: expected string at path $.title"
9  }
10}

Validation Behavior in Concurrent Editing

Schema validation uses a best-effort approach for collaborative environments:

This means that after receiving remote changes, the document may temporarily be in a state that doesn't conform to the schema. The next local edit will be validated against the current state, so any structural issues must be resolved before further local edits can succeed.

Schema Version Management

Schemas are managed immutably. Each update creates a new version:

• v1: Initial schema definition
• v2: Updated schema with new fields or modified constraints
• v3: Further revisions

Documents remain bound to the schema version they were attached with. To use a new schema version, detach and reattach the document with the updated schema reference.

Use Cases

• Structured documents: Enforce consistent structure for collaborative forms, surveys, or configuration editors
• Rich text editors: Define allowed node types, content models, and marks for ProseMirror-compatible editors
• Data integrity: Prevent invalid data types from being written to shared documents
• Multi-client consistency: Ensure all clients editing a document follow the same structural rules

Related Documentation

• JS SDK - Client and Document usage
• Dashboard - Schema creation and management
• Security - Auth Webhook for access control