Docs

Lexemes

A lexeme is a named definition that describes what an atom represents. It provides a field contract, human-readable labels, and context for both UI surfaces and AI agents — without ever enforcing rigid validation on the underlying data.

How lexemes relate to atoms

Atoms store the data. Lexemes give that data meaning. An atom subscribes to one or more lexemes via its lexemeIds field. The relationship is loose by design — removing a lexeme does not destroy the atoms that referenced it, and a single atom can subscribe to multiple lexemes simultaneously.

Schema advisory

A lexeme suggests which keys an atom should have and what type of value each key holds. Atoms are never rejected for missing or extra keys.

Semantic grouping

Querying by lexemeId returns all atoms that share that shape — enabling consistent filtering, rendering, and agent instructions across many atoms at once.

AI context

The lexeme's description and field notes travel with the atom when it is passed to an AI agent, giving the agent rich context about what the data means and how it should be handled.

Anatomy

Every lexeme shares the same base structure. The data field holds the definition payload; the remaining fields control access, identity, and lifecycle — mirroring the same pattern used by atoms.

Field — the key name as it appears in the API request and response.

Description — what the field controls and when to use it.

Default — the value used when the field is omitted on create. required means the field must always be provided.

Field

name

string

Description

A short, human-readable label for the lexeme. Used in the UI to identify the lexeme at a glance — e.g. "Personal Identity", "Product", or "Task".

Default

Field

data

LexemeData

Description

The definition payload. Contains an optional description and an optional fields array that specifies the expected keys of any atom subscribing to this lexeme. The shape is flexible — additional top-level keys are allowed.

Default

{}

Field

data.description

string

Description

A prose explanation of what kind of thing this lexeme models. Shown to users and AI agents to provide context when working with subscribed atoms.

Default

undefined

Field

data.fields

FieldDefinition[]

Description

The ordered list of field definitions. Each entry describes one expected key in the data map of a subscribing atom. Fields are advisory — atoms are not blocked from storing keys that are not listed here.

Default

[]

Field

owner

ObjectId → User

Description

The user who created and controls this lexeme. Only the owner can modify or delete it. Ownership is always explicit.

Default

required

Field

sharedWith

{ user: ObjectId, role: 'reader' | 'editor' }[]

Description

Per-user access grants. A reader can view the lexeme and use it when creating atoms; an editor can update the lexeme definition. Sharing does not transfer ownership.

Default

[]

Field

isPublic

boolean

Description

When true, any authenticated user — and optionally unauthenticated guests — can read this lexeme and subscribe atoms to it. Does not affect write access.

Default

false

Field

version

number

Description

Auto-incremented each time the lexeme's data or sharedWith list changes. Useful for detecting stale reads or coordinating updates across clients.

Default

Field

deleted

boolean

Description

Soft-delete flag. Deleted lexemes are hidden from standard queries but not permanently removed. Atoms that reference a deleted lexeme retain their lexemeIds entry.

Default

false

FieldDescriptionDefault

name

string

A short, human-readable label for the lexeme. Used in the UI to identify the lexeme at a glance — e.g. "Personal Identity", "Product", or "Task".

data

LexemeData

{}

data.description

string

A prose explanation of what kind of thing this lexeme models. Shown to users and AI agents to provide context when working with subscribed atoms.

undefined

data.fields

FieldDefinition[]

[]

owner

ObjectId → User

The user who created and controls this lexeme. Only the owner can modify or delete it. Ownership is always explicit.

required

sharedWith

{ user: ObjectId, role: 'reader' | 'editor' }[]

Per-user access grants. A reader can view the lexeme and use it when creating atoms; an editor can update the lexeme definition. Sharing does not transfer ownership.

[]

isPublic

boolean

When true, any authenticated user — and optionally unauthenticated guests — can read this lexeme and subscribe atoms to it. Does not affect write access.

false

version

number

Auto-incremented each time the lexeme's data or sharedWith list changes. Useful for detecting stale reads or coordinating updates across clients.

deleted

boolean

Soft-delete flag. Deleted lexemes are hidden from standard queries but not permanently removed. Atoms that reference a deleted lexeme retain their lexemeIds entry.

false

Field definitions

Each entry in data.fields is a FieldDefinition object. Only key is required — all other properties are optional annotations.

Field

key

string

Description

The exact key this field definition describes — must match the corresponding key in an atom's data map. Case-sensitive.

Required

yes

Field

label

string

Description

A human-readable display name for the field. Used in the UI instead of the raw key. If omitted, the key is shown directly.

Required

Field

type

string

Description

A type hint for the expected value — e.g. "string", "number", "boolean", "date". Advisory only; the API does not enforce types on atom data.

Required

Field

required

boolean

Description

When true, indicates that subscribing atoms should provide this field. Advisory only — the API will not reject atoms that omit it.

Required

Field

notes

string

Description

Free-text notes visible to the lexeme owner or editors. Useful for documenting intent, valid values, or context for AI agents.

Required

FieldDescriptionRequired

key

string

The exact key this field definition describes — must match the corresponding key in an atom's data map. Case-sensitive.

yes

label

string

A human-readable display name for the field. Used in the UI instead of the raw key. If omitted, the key is shown directly.

type

string

A type hint for the expected value — e.g. "string", "number", "boolean", "date". Advisory only; the API does not enforce types on atom data.

required

boolean

When true, indicates that subscribing atoms should provide this field. Advisory only — the API will not reject atoms that omit it.

notes

string

Free-text notes visible to the lexeme owner or editors. Useful for documenting intent, valid values, or context for AI agents.

Examples

Below are four complete lexeme payloads — exactly what you would send to the API to create each one.

Personal Identity

Defines the expected fields of an atom representing a person. Any atom subscribing to this lexeme should provide at least firstName and lastName.

{
  "name": "Personal Identity",
  "data": {
    "description": "Represents a real or fictional person with contact and biographical information.",
    "fields": [
      {
        "key": "firstName",
        "label": "First name",
        "type": "string",
        "required": true
      },
      {
        "key": "lastName",
        "label": "Last name",
        "type": "string",
        "required": true
      },
      {
        "key": "email",
        "label": "Email address",
        "type": "string"
      },
      {
        "key": "bio",
        "label": "Biography",
        "type": "string"
      }
    ]
  }
}

Task

Models a unit of work with status tracking and priority. A consistent field contract lets apps filter and sort tasks across many atoms.

{
  "name": "Task",
  "data": {
    "description": "A discrete unit of work with a lifecycle: not started → in progress → done.",
    "fields": [
      {
        "key": "title",
        "label": "Title",
        "type": "string",
        "required": true
      },
      {
        "key": "status",
        "label": "Status",
        "type": "string",
        "required": true,
        "notes": "Allowed values: not-started, in-progress, done, cancelled"
      },
      {
        "key": "priority",
        "label": "Priority",
        "type": "string"
      },
      {
        "key": "dueDate",
        "label": "Due date",
        "type": "date"
      },
      {
        "key": "assignee",
        "label": "Assignee (user ID)",
        "type": "string"
      }
    ]
  }
}

Product

Standardises the fields of a product atom across a catalogue. Subscribing atoms can be queried together knowing they share this shape.

{
  "name": "Product",
  "data": {
    "description": "A physical or digital item available for sale or distribution.",
    "fields": [
      {
        "key": "name",
        "label": "Product name",
        "type": "string",
        "required": true
      },
      {
        "key": "sku",
        "label": "SKU",
        "type": "string"
      },
      {
        "key": "price",
        "label": "Price",
        "type": "number"
      },
      {
        "key": "currency",
        "label": "Currency code",
        "type": "string"
      },
      {
        "key": "inStock",
        "label": "In stock",
        "type": "boolean"
      }
    ]
  }
}

Journal Entry

Minimal structure for a personal note or diary entry. The lexeme provides just enough contract to allow chronological surfacing.

{
  "name": "Journal Entry",
  "data": {
    "description": "A timestamped personal note or diary entry.",
    "fields": [
      {
        "key": "title",
        "label": "Title",
        "type": "string"
      },
      {
        "key": "body",
        "label": "Body",
        "type": "string",
        "required": true
      },
      {
        "key": "mood",
        "label": "Mood",
        "type": "string",
        "notes": "Optional free-text mood tag, e.g. calm, anxious, energised"
      }
    ]
  }
}

Atoms and lexemes together

Once you have a lexeme, you can subscribe atoms to it by including the lexeme's _id in the atom's lexemeIds array. From that point on, the atom inherits the field contract and description of the lexeme — visible in the Studio and available to any AI agent working with that atom.