> ## Documentation Index
> Fetch the complete documentation index at: https://trytilde.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Objects and links

> Define typed object types over your models, decide which properties the source owns and which the ontology owns, link objects together, and resolve one entity across systems.

An object type is a typed noun, such as `Customer` or `Invoice`. It maps a model's columns to properties, and names the property that keys it. Handlers, policies, analytics SQL, and agent tools all use the object's property names.

## Define an object type

```ts ontology/sales.ts theme={"system"}
import { object, sql, t } from "@tilde/ontology";
import { customers, invoices } from "./models.ts";

export const Customer = object("Customer", {
  id: "customer",                 // stable: keep it when you rename the object
  key: "customerId",
  source: customers,
  description: "A paying customer, from Stripe.",
  properties: {
    customerId: t.string().map(sql`customer_id`),
    name: t.string().map(sql`name`),
    tier: t.enum("bronze", "silver", "gold").map(sql`tier`),
    accountManager: t.ref("Employee").optional().map(sql`account_manager`),
    internalNotes: t.string().optional().owned(),
  },
});

export const Invoice = object("Invoice", {
  id: "invoice",
  key: "invoiceId",
  source: invoices,
  properties: {
    invoiceId: t.string().map(sql`invoice_id`),
    customer: t.ref("Customer").map(sql`customer_id`),
    amount: t.decimal(12, 2).map(sql`amount`),
    status: t.string().map(sql`status`),
    dueDate: t.date().map(sql`due_date`),
    disputed: t.bool().owned(),
  },
});
```

### Property types

| Type | Value in handlers |
| - | - |
| `t.string()`, `t.enum(...values)` | A string. |
| `t.int()`, `t.float()` | A number. Use `t.string()` for integers beyond ±2^53. |
| `t.bool()` | A boolean. |
| `t.decimal(precision, scale)` | Exact decimal text. |
| `t.date()`, `t.timestamp()` | `YYYY-MM-DD`, or RFC 3339 text. |
| `t.array(type)` | An array. |
| `t.ref("Object")` | The other object's key, always as a string. |

Chain `.optional()` for nullable values, `.describe(text)` for documentation, and `.id(name)` to keep a stored name when you rename a property.

## Who owns a property

Every property has one owner.

* **Source-owned** properties `.map()` a SQL expression over the object's model. Only the source system changes them.
* **Ontology-owned** properties are `.owned()`. Only the ontology's [actions](https://trytilde.ai/docs/ontology/views-and-actions.md#actions) change them, and Tilde keeps every edit in an audited log.

An object with no `source` is entirely ontology-owned, and its properties need no `.owned()`. Actions create and delete it, such as a note or a follow-up task. Its key is always a string.

```ts theme={"system"}
export const CustomerNote = object("CustomerNote", {
  id: "customer_note",
  key: "noteId",
  properties: {
    noteId: t.string(),
    customer: t.ref("Customer"),
    body: t.string(),
    author: t.string(),
  },
});
```

Actions cannot edit source-owned properties. To change one, an action calls the source system, and can show the expected value as **pending** until the source confirms it. See [Pending values](https://trytilde.ai/docs/ontology/views-and-actions.md#pending-values).

## Links

A link is a relationship between two object types.

```ts theme={"system"}
import { link, sql } from "@tilde/ontology";

// 1:N through a ref property on the `to` side.
export const CustomerInvoices = link("CustomerInvoices", {
  id: "customer_invoices", from: Customer, to: Invoice, cardinality: "one_to_many", via: "customer",
});

// N:M through its own model.
export const AccountTeam = link("AccountTeam", {
  id: "account_team", from: Employee, to: Customer, cardinality: "many_to_many",
  source: accountTeam,
  map: { from: sql`payload->>'employee_id'`, to: sql`payload->>'customer_id'` },
});
```

List links in `ontology({ links })`.

## Entity resolution

The same customer often appears in several systems. A resolution matches members of different object types into one entity, with deterministic rules and optional fuzzy matching.

```ts theme={"system"}
import { member, resolution, sql } from "@tilde/ontology";

export const CustomerIdentity = resolution("CustomerIdentity", {
  id: "customer_identity",
  features: { email: "email", domain: "domain", name: "text" },
  members: [
    member(Customer, { email: sql`email`, domain: sql`split_part(email, '@', 2)`, name: sql`name` }),
    member(SalesforceAccount, { domain: sql`website`, name: sql`"accountName"` }),
  ],
  rules: [{ name: "same_email", on: ["email"] }, { name: "same_domain_and_name", on: ["domain", "name"] }],
  fuzzy: { on: "name", threshold: 0.9 },
});
```

Each feature names a normalizer: `exact`, `text`, `email`, `domain`, or `phone`. List resolutions in `ontology({ resolutions })`.

## History

Set `history: true` on an object to keep every change of its properties from then on, by your actions or in the source system. Add `historyAt` to date source-side changes with one of the object's own timestamps.

```ts theme={"system"}
export const Invoice = object("Invoice", { id: "invoice", key: "invoiceId", source: invoices, history: true, historyAt: "updatedAt", properties: { /* ... */ } });
```

A [read](https://trytilde.ai/docs/ontology/views-and-actions.md#reads) declares `history(Invoice)` to query it. Each row has the key, the property, its value before and after, when it changed, and whether an action or the source changed it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.