Core Concepts
Metadata Fields
Typed, JSON-Schema-validated properties you declare on instances and deployment zones — rendered in the console, enforced on every write, readable by targeting rules.
Instances and deployment zones carry a metadata object for the properties that are yours, not Kaiten's: the environment an instance serves, the compliance profile a zone is certified for, the cloud region it lives in. A metadata field is the declaration that makes one of those properties typed. Declare it once for a resource type, and every write of that resource is validated against it, the console shows it under its label, and targeting rules can read it.
What a field declares
A field belongs to one resource type — INSTANCE or DEPLOYMENT_ZONE — and has a key (the property name inside metadata, immutable once created, unique among the type's active fields), a label for the console, a JSON Schema (draft 2020-12) describing the value, and a display order. Kaiten Sushi Shop declares environment on instances — an enum of production, staging, demo — and, on deployment zones, compliance_profile (standard or pci-dss), a free-text region, and a boolean dedicated, true on the zone reserved for one customer.
Writing an instance with any other environment value is rejected; the console shows Environment on every instance, demo on Demo Restaurant's. The value itself always lives on the resource, in metadata; the field only says what is allowed there.
Lifecycle
Create the field (POST /metadata-fields) and it starts validating immediately. Use it by writing the key inside metadata when creating or updating a resource. Edit its label or schema (PATCH /metadata-fields/{id}): a schema change that alters what is valid can be previewed first with a dry run (POST /metadata-fields/{id}/dry-run), which counts the existing resources that would no longer conform and samples a few — without changing anything. Some transitions are refused outright because existing data could not survive them: changing the type, changing cardinality, switching a free string to an enum or back. Reorder fields to arrange the console (POST /metadata-fields/reorder).
Fields are archived, not deleted. Archiving takes the field out of the active schema — it stops validating writes — while the values already stored stay interpretable; the key is released, so a new field may reuse it. Unarchiving restores the field — and fails with a conflict if the key has since been taken. GET /metadata-fields lists a resource type's active fields; includeArchived=true adds the archived ones, each with its archivedAt.
Every step of that lifecycle is an event: METADATA_FIELD_CREATED, METADATA_FIELD_UPDATED, METADATA_FIELD_ARCHIVED, METADATA_FIELD_UNARCHIVED, METADATA_FIELD_REORDERED.
Why it is part of the model
Free-form tags cannot be trusted by anything but the human who wrote them. Because metadata is typed, the console renders it, the API enforces it, and a flag's targeting rule can read it — __kaiten.instance.metadata and __kaiten.deploymentZone.metadata are among the facts a rule sees. A rule such as __kaiten.deploymentZone.metadata.compliance_profile == 'pci-dss' can be written with confidence, because every zone that carries the property carries it in the shape the schema guarantees.
Where to go next
Instances and zones, the two resources that carry metadata: Customers & Instances and Releases & Deployments.
Exact reference: data model.
Events & Webhooks
Every change and every evaluation becomes a domain event, written with the change itself — delivered to managed webhook endpoints on Kaiten Cloud, consumed from your own broker when self-hosted.
The Audit Trail
Every change and every evaluation, recorded in one trail — the memory of the system, and the answer to "who had access to what, when?"