Types and schema

A type describes the fields an object or relation has, and ECHO uses it to check every write and to tell other peers what the data means.

Model

A type is an Effect Schema with a typename and a version. Together they make the type’s DXN, dxn:<typename>:<version>, and every object stores the DXN of its type. Defining types builds the Person, Organization and Event types that the snippets on this page use.

import { Obj, Type } from '@dxos/echo';
import { Person } from './schema.ts';

Type.getTypename(Person); // 'com.example.type.person'
Type.getVersion(Person); // '0.1.0'
Type.getURI(Person); // 'dxn:com.example.type.person:0.1.0'

const ada = Obj.make(Person, { name: 'Ada' });
Obj.getTypename(ada); // 'com.example.type.person'

There are two kinds of type:

• An object type, made with Type.makeObject, describes a record such as a person.
• A relation type, made with Type.makeRelation, describes an entity that joins a source and a target, and can carry fields of its own. Objects and relations shows when to use one.

import * as Schema from 'effect/Schema';
import { DXN, Type } from '@dxos/echo';
import { Organization, Person } from './schema.ts';

export class WorksAt extends Type.makeRelation<WorksAt>(
  DXN.make('com.example.type.worksAt', '0.1.0'),
)({
  source: Person,
  target: Organization,
})({ role: Schema.String }) {}

Annotations add what the schema alone does not say: which field labels an object, which icon it has, how a form orders its fields. ECHO reads some of them itself; Obj.getLabel returns the field the label annotation names. Tools such as Composer read the rest. Annotation lists them.

import { Annotation, Obj, Type } from '@dxos/echo';
import { Event } from './schema.ts';

// The tutorial's Event names `title` as its label.
const labelFields = Annotation.LabelAnnotation.get(Type.getSchema(Event)); // Some(['title'])
const launch = Obj.make(Event, { title: 'Launch' });
Obj.getLabel(launch); // 'Launch'

Behavior

• A database accepts only objects of types it knows. Register types with the client, when you make it or later; types registered there apply to every space.

  import { Client } from '@dxos/client';
  import { types } from './schema.ts';
  import { WorksAt } from './works-at.ts';
  
  const client = new Client({ types });
  await client.initialize();
  await client.addTypes([WorksAt]);
  
  

• A type converts to and from JSON Schema, so a type can come from a form, an agent or another system as well as from code.

  import { JsonSchema, Type } from '@dxos/echo';
  import { Organization } from './schema.ts';
  
  const jsonSchema = JsonSchema.toJsonSchema(Type.getSchema(Organization));
  
  const Note = Type.makeObjectFromJsonSchema({
    typename: 'com.example.type.note',
    version: '0.1.0',
    jsonSchema: { type: 'object', properties: { title: { type: 'string' } } },
  });
  
  

• db.addType stores a type in the space, as an object of its own, so it replicates to the other members like data. Fields of a stored type can be added, changed and removed at runtime.

  import * as Schema from 'effect/Schema';
  import { Type } from '@dxos/echo';
  
  // Stored in the space, so it replicates to the other members.
  const note = await db.addType(Note);
  Type.addFields(note, { pinned: Schema.optional(Schema.Boolean) });
  
  

Versions and migrations

A change to a type that old data does not fit, such as a field that becomes an array, is a new version of the type. A migration moves objects from one version to the next:

• Migration.define reads an object of the old version and returns the fields of the new one.
• Migration.defineRename gives a type a new typename and points every reference at it.
• Migration.defineContent upgrades a content format that an object carries in a field, such as a drawing’s scene, without changing the type’s version.

import * as Schema from 'effect/Schema';
import { DXN, Format, Migration, Ref, Type } from '@dxos/echo';
import { Organization, Person } from './schema.ts';

// Version 0.2.0 of Person holds any number of email addresses.
class PersonV2 extends Type.makeObject<PersonV2>(
  DXN.make('com.example.type.person', '0.2.0'),
)(
  Schema.Struct({
    name: Schema.String,
    emails: Schema.Array(Format.Email),
    employer: Schema.optional(Ref.Ref(Organization)),
  }),
) {}

const personEmails = Migration.define({
  from: Person,
  to: PersonV2,
  transform: async ({ name, email, employer }) => ({
    name,
    emails: email ? [email] : [],
    employer,
  }),
  onMigration: async () => {},
});

// Points every reference to the old typename at the new one.
const renameEvent = Migration.defineRename({
  from: 'com.example.type.event',
  to: 'com.example.type.meeting',
});

A plugin contributes its migrations to Composer, which runs them on every space once the plugin is active. The API reference covers each kind.

Limits

• Objects of two versions of one type do not merge. Peers must run the same migration before they edit the same objects.
• The docs do not yet say how to run migrations outside a Composer plugin.
• Adding a field to a stored type is safe; changing or removing one leaves the old values in objects already written.