RUNNING

Table

A Table as RunningLake's configuration repository declares it, at tables/<name>.yaml. Generated from the Go types the control plane decodes this file into, so it checks the shape the gate reads — field names and types, and which fields may exist. The gate also applies rules no schema can express — required fields inside spec among them — so a file this schema accepts can still be refused by `rl diff`. Take #/properties/spec for the spec alone.

File: tables/<name>.yaml

Fields

Field	Type	Required	Meaning
`apiVersion`	string	Yes	The config schema's version, which is independent of the HTTP API's (rule unsupported-api-version). Values: `runninglake.io/v1alpha1`
`kind`	string	Yes	The kind this file declares. A kind that disagrees with the file's path is refused (rule kind-mismatch). Values: `Table`
`metadata`	object	Yes	No description
`metadata.name`	string	Yes	The resource's name, which is also its path segment. It must be the name this file's path gives it (rule name-mismatch).
`metadata.labels`	map of string	No	No description
`metadata.annotations`	map of string	No	No description
`spec`	object	No	Which table this is — its catalog identity — and what the catalog is told when the table is first made.
`spec.namespace`	array of string	No	Namespace is the multi-level Iceberg namespace: [bronze, stripe]. Its first level is the table's layer, and a table directly in a layer — [bronze] — is legal. Each level matches [a-z][a-z0-9_-]{0,62}, and a declared table's namespace has at most two levels, a layer and a schema: a policy or a Grant names a table as layer.schema.table and no deeper, so a table nested below a schema could be neither masked, filtered nor granted on.
`spec.table`	string	No	Table names the table. Empty means metadata.name, the common case: a resource called charges in [bronze, stripe] is bronze.stripe.charges. Either way the name matches [a-z][a-z0-9_-]{0,62}.
`spec.routing`	object	No	The table's format, which is required; see format.
`spec.routing.format`	string	No	The table format: iceberg, hudi or ducklake, in any case. Required (rules format-required and format-unknown). Choose it once: a plan that changes the format of a table the platform has already reported is refused (rule format-is-immutable), and a Pipeline's is held to its tables' once the tree declares a Layer (rule asset-format). A change pushed straight to the repository's branch does not go through a plan, so it is not refused, and does not change a table that already exists.
`spec.routing.engine`	string	No	An engine to pin, or empty to leave the choice to the router. On a pipeline, the authoring gate refuses a pin no rule permits for its format and operations, and names the rule that fired. Nothing runs a pipeline yet, so nothing is routed today.
`spec.routing.train`	string	No	A release-train FAMILY to pin, written YYYY.MM (for example 2026.11), or empty to follow the train of the plane the environment runs on. A Pipeline's setting; on a Table it is read by nothing. A pin names a family and not a serial: the serials inside a family are the same engines and move with the plane, and a family does not move while a pipeline pins it. A serial is refused (rule train-pin-is-a-family), and so is a family this control plane's runtime index does not hold (train-unknown) or one outside its support window, the current family plus two (train-out-of-support). When a family is pinned, spec.routing.engine is judged against the engines that family runs, and not against the plane's.
`spec.routing.consumers`	array of object	No	Who reads or writes the table, and how fresh they need it. Recorded; nothing reads it yet, so a consumer constrains no engine and no storage mode today.
`spec.routing.consumers[].engine`	string	No	No description
`spec.routing.consumers[].access`	string	No	Either read or write. Recorded; nothing reads it yet.
`spec.routing.consumers[].freshnessSla`	string	No	How fresh this consumer needs the table, as a Go duration string, e.g. "5m". Recorded; nothing reads it yet.
`spec.routing.consumers[].queryShape`	string	No	No description
`spec.schema`	map of any value	No	Schema, PartitionSpec and WriteOrder are Iceberg's own objects, passed through.
`spec.partitionSpec`	map of any value	No	No description
`spec.writeOrder`	map of any value	No	No description
`spec.location`	string	No	A table does not choose where it is written: the authoring gate refuses this field (rule location-asserted), and the table's folder is rendered from its layer, schema and name.
`spec.properties`	map of string	No	Iceberg table properties. Keys beginning rl. are the platform's: `rl diff` and the plan refuse them (rule reserved-property), as the catalog does when the table is made.

A nested field is written with its parents, spec.a.b; an item of a list is [] and a value of a map is *. Required means the parent object must carry the field; the rules a schema cannot express, such as a field that is required only inside spec, are checked by rl diff.

The schema

This page is read from the kind’s published schema, at https://runninglake.com/schema/v1alpha1/table.json. An editor that follows it checks a file of this kind as you type. To see the fields of a kind’s spec from the command line, run rl schema with the kind’s name: it works offline and prints what the gate accepts. The command reference has the rest.

All kinds