The ontology model

Everything in Aerandil is expressed with three primitives. Learn these and the REST API, the MCP tools, and the SDKs all read the same way.

Objects

An object is a typed, versioned record — a booking, a folio, a rate_plan, a guest_profile. Every object has:

• a type drawn from the ontology (the hospitality domain lives in aerandil-schema);
• a stable id;
• a monotonic version that increments on every change;
• a tenant it belongs to (Aerandil is multi-tenant end to end).

Objects are never hard-deleted — they are soft-deleted (marked, not removed) so history stays intact.

Links

A link is a typed, directional relationship between two objects — a booking stays in a room, a payment settles a folio. Links are first-class and typed by the ontology, not foreign keys you assemble by hand.

Actions

An action is the only way state changes. Rather than PUT-ing arbitrary fields, you apply a named, validated action — apply_payment, assemble_package_sale, assign_operator_to_venue — and Aerandil validates it, mutates the affected objects and links atomically, and appends an immutable event describing what happened.

This is the core idea: reads are open, writes are actions. Every mutation is a named verb with a schema, an authorization scope, and an audit trail.

The ontology, live

This is not an illustration — the graph below is generated from the kernel’s schema registry at build time, so it is exactly the ontology the API, the MCP tools, and the SDKs speak. Pick a domain, then click any object type to see its properties and the actions that can change it, or any arrow to see the link’s cardinality.

Click an object type or a link to inspect it. Every box, arrow, property, and action here is generated from the kernel's schema registry.

Concurrency and idempotency

Because objects are versioned, writes are safe under contention:

• Versions — every read returns the object’s version as a strong ETag. An action reads its target’s current state when it runs, and a change that no longer fits is refused with 409 rather than silently clobbering a concurrent one.
• Idempotency — send an Idempotency-Key on a create/apply and a retry returns the original result instead of duplicating the effect.

Where to go next

• Quickstart — apply your first action end to end.
• Authentication — OAuth 2.1 and action scopes.
• API reference — every object type, link, and action in full.