Core Data Model

The core data model lives in @blocknote/block-view/core. All entities auto-register with an EntityRegistry on construction, enabling automatic relationship resolution.

Collection

The schema definition for a set of documents. A collection owns the property schema and tracks its documents.

import { Collection } from "@blocknote/block-view/core";

Properties

Property	Type	Description
id	string	Unique identifier
name	string	Display name
schema	Record<string, Property>	Property definitions keyed by property ID
documents	Map<string, Document>	Documents keyed by document ID
size	number	Number of documents
view	CollectionView	The primary view (resolved via registry)
role	"editor" | "reader"	Current user’s permission level
createdBy	Reference	Who created this collection
createdAt	number	Creation timestamp
updatedAt	number	Last update timestamp
updatedBy	Reference	Who last updated
registry	EntityRegistry	The registry this entity belongs to

Methods

collection.getDocument(id: string): Document | undefined
collection.toJSON(): CollectionJSON
Collection.fromJSON(json: CollectionJSON, registry: EntityRegistry): Collection

Example

// Access the schema
const nameProperty = collection.schema["name"];
console.log(nameProperty.label); // "Name"
console.log(nameProperty.type); // "string"

// Iterate documents
for (const [id, doc] of collection.documents) {
  console.log(id, doc.getProp("name")?.value);
}

CollectionView

A presentation layer over a collection. Controls which columns are visible, their widths, filters, sorts, and row ordering.

import { CollectionView } from "@blocknote/block-view/core";

Properties

Property	Type	Description
id	string	Unique identifier
type	"table" | "kanban" | "calendar" | "gallery"	View type
collectionId	string	Parent collection ID
collection	Collection	Parent collection (resolved via registry)
columns	Array<{ property: Property; width?: number; visible?: boolean }> | undefined	Column configuration
filters	Filter[] | undefined	Active filters
sorts	Array<{ property: Property; desc: boolean }> | undefined	Active sorts
manualSortOrder	Array<string>	Manual row ordering (document IDs)
role	"editor" | "reader"	Permission level
createdBy	Reference	Creator
createdAt	number	Creation timestamp
updatedAt	number	Last update timestamp
updatedBy	Reference	Last updater

Methods

view.toJSON(): CollectionViewJSON
CollectionView.fromJSON(json: CollectionViewJSON, registry: EntityRegistry): CollectionView

JSON Shape

When serialized (e.g., for data sources), a CollectionView looks like:

{
  id: "view-1",
  type: "table",
  collectionId: "tasks",
  manualSortOrder: ["doc-1", "doc-2", "doc-3"],
  filters: undefined,
  sorts: undefined,
  columns: [
    { propertyId: "name", width: 250, visible: true },
    { propertyId: "status", width: 150, visible: true },
  ],
  createdBy: { type: "user", id: "me" },
  createdAt: 1700000000000,
  updatedAt: 1700000000000,
  updatedBy: { type: "user", id: "me" },
  role: "editor",
}

Document

A single row/record in a collection. Contains property values as key-value pairs.

import { Document } from "@blocknote/block-view/core";

Properties

Property	Type	Description
id	string	Unique identifier
collectionId	string	Parent collection ID
collection	Collection	Parent collection (resolved via registry)
props	Record<string, PropertyValue>	Values keyed by property ID
meta	Record<string, unknown> | undefined	Optional metadata
role	"editor" | "reader"	Permission level
createdBy	Reference	Creator
createdAt	number	Creation timestamp
updatedAt	number	Last update timestamp
updatedBy	Reference	Last updater

Methods

document.getProp(propertyId: string): PropertyValue | undefined
document.toJSON(): DocumentJSON
Document.fromJSON(json: DocumentJSON, registry: EntityRegistry): Document

Example

const doc = collection.documents.get("doc-1");
const name = doc.getProp("name");
console.log(name?.value); // "Design data model" (always a string)

Property

A column/property definition in the collection schema. Describes the type, label, and constraints for a property.

import { Property } from "@blocknote/block-view/core";

Properties

Property	Type	Description
id	string	Unique identifier
collectionId	string	Parent collection ID
collection	Collection	Parent collection (resolved via registry)
label	string	Display label
type	string	Property type ("string", "number", "date", "checkbox", "single-select", "multi-select", or custom)
description	string | undefined	Optional description
icon	string | undefined	Optional icon identifier
readonly	boolean	Whether the property is read-only
enum	readonly PropertyEnumOption[] | undefined	Options for select types
format	string | undefined	Format hint ("date", "date-time", "email", "uri", etc.)
minimum	number | undefined	Minimum value (for numbers)
maximum	number | undefined	Maximum value (for numbers)

PropertyEnumOption

type PropertyEnumOption = {
  value: string | number | boolean;
  label?: string;
  color?: string;
};

Used by single-select and multi-select properties to define the available choices:

{
  type: "single-select",
  enum: [
    { value: "todo", label: "To Do", color: "gray" },
    { value: "in-progress", label: "In Progress", color: "blue" },
    { value: "done", label: "Done", color: "green" },
  ],
}

PropertyValue

A single cell value. All values are stored as strings for CRDT compatibility. The string is parsed at display time based on the property’s type.

import { PropertyValue } from "@blocknote/block-view/core";

Properties

Property	Type	Description
id	string	Unique identifier
value	string	The stored value (always a string)
ref	Reference | undefined	Optional reference to an external resource
documentId	string	Parent document ID
propertyId	string	Parent property ID
document	Document	Parent document (resolved via registry)
property	Property	Parent property (resolved via registry)

Value Storage

Values are always strings, regardless of property type:

Property type	Stored value example
string	"Hello world"
number	"42"
date	"2024-01-15"
checkbox	"true" or "false"
single-select	"done"
multi-select	"tag1,tag2,tag3" (comma-separated)

Reference

A typed reference to an external resource (user, document, workspace, etc.).

import { Reference } from "@blocknote/block-view/core";

Properties

Property	Type	Description
type	string	Resource type (e.g., "user", "document")
id	string	Resource ID

Example

const userRef = new Reference({ type: "user", id: "alice" });
console.log(userRef.type); // "user"
console.log(userRef.id); // "alice"

EntityRegistry

Central lookup system for all entities. Entities auto-register on construction. Enables relationship resolution — when you access document.collection, the registry resolves it.

import { EntityRegistry } from "@blocknote/block-view/core";

You rarely interact with the registry directly. It’s created internally by initializeCollection and passed to all entities.

Filter Types

import { isFilterRule, isFilterGroup } from "@blocknote/block-view/core";

FilterRule

interface FilterRule {
  id: string;
  propertyId: string;
  operator: string;
  value: string;
}

FilterGroup

interface FilterGroup {
  id: string;
  logicalOperator: "AND" | "OR";
  children: Array<Filter>;
}

Filter

type Filter = FilterRule | FilterGroup;

Type Guards

isFilterRule(filter: Filter): filter is FilterRule
isFilterGroup(filter: Filter): filter is FilterGroup

Error Classes

import {
  DatabaseError,
  NotFoundError,
  ValidationError,
  NetworkError,
} from "@blocknote/block-view/core";

Class	Extends	Description
DatabaseError	Error	Base error for all library errors
NotFoundError	DatabaseError	Entity not found
ValidationError	DatabaseError	Invalid input data
NetworkError	DatabaseError	HTTP/network failure. Has optional statusCode: number