Schema

This page summarizes the declaration surface exported by ramose/db. Definitions are immutable values; declare and export them at module scope.

New here? Start with Schemas and traits.

Named schema

const AppSchema = Ramose.Schema("app-v1", {
  account: Account,
  organization: Organization,
})

AppSchema.applyPolicy(({ policy }) => {
  policy.account.read.never()
  policy.organization.read.never()
})

A named schema is the closed model installed for one database. It contains entity and trait definitions, operation identities, descriptions, and policy used by the server, browser client, and MCP discovery.

Public keys are persistent contract names. Keep them stable once deployed.

Entity

const Task = Ramose.Entity("task", {
  title: Ramose.string(),
  done: Ramose.boolean({ default: () => false }),
  createdAt: Ramose.timestamp(),
}, {
  doc: "A work item that can be completed",
  traits: [Assignable],
})

An entity definition gives stored records a type, fields, traits, relationships, and owned operations. Ramose supplies stable entity identity separately from user fields.

Trait

const Assignable = Ramose.Trait("assignable", {
  assignee: Ramose.ref(Account, { optional: true }),
})

A trait is a reusable capability. Entities that implement it are substitutable in trait-rooted queries and inherit its fields, relationships, and operations.

Stored fields

Common constructors include:

Constructor	Stored value
`string()`	UTF-8 text
`boolean()`	`true` or `false`
`int()`	integer number
`float()`	finite number
`timestamp()`	ordered instant
`uuid()`	UUID value
`bytes()`	binary data
`enumeration([...])`	one declared string value
`ref(EntityOrTrait)`	stable entity reference

Field modifiers declare cardinality, optionality, defaults, uniqueness, indexing, and ownership. Exact modifier availability depends on the stored value and relationship kind; TypeScript rejects invalid combinations.

References and relationships

ref(Target) stores a checked reference to a compatible entity. A many relationship is modeled as related entities or an explicit many-valued relationship, not an unbounded application array.

References stay within one database. Use an application-level locator when a workflow must point into another database, then resolve and authorize it explicitly.

Evolution rules

Additive changes are normally compatible. Changes to value representation, cardinality, uniqueness, required fields on existing records, or type identity require an explicit migration. Catalog installation refuses incompatible changes by default.