Appendix C. Schema file and registry

oxl.schema.lock fixes the tags of fields, variants and rpcs so that the schema of a package changes only compatibly (§9.2). The file is created and updated by the compiler; manual editing is allowed but is checked at build time.

C.1 Format#

TOML, UTF-8 encoding, keys are sorted so that diffs are stable.

toml

format = 1
package = "shop"
published = "0.3.0"                     # the last published version

[types."shop.orders.Order"]
kind = "data"
version = 1                             # @v(n)
fields.id        = { tag = 1, type = "shop.model.OrderId" }
fields.userId    = { tag = 2, type = "shop.model.UserId" }
fields.total     = { tag = 4, type = "shop.model.Money", repr = "i64" }
fields.status    = { tag = 6, type = "shop.model.Status", since = 1 }
reserved         = [3, 5]               # removed tags, forever
renamed          = { receipt = "receiptId" }

[types."shop.model.Status"]
kind = "enum"
open = true
variants = { New = 1, Paid = 2, Shipped = 3, Cancelled = 4 }

[services."shop.orders.Orders"]
version = 1
rpcs.recent = { tag = 1, attrs = ["readonly"] }
rpcs.create = { tag = 3, attrs = ["idempotent", "internal"] }

[codecs]
"shop.model.Money" = { schema = "sha256:9f2c…" }   # the hash of Codec.schema() or Repr

The type key is the full name package.module.Type.
type is the full name of the field type after alias expansion; for generics — with arguments (List<shop.model.Item>).
reserved are the tags of removed fields and variants; they cannot be reused.
codecs is the schema hash of a user codec or Repr (§9.5), so that a change of representation is noticed.

C.2 Update during the build#

The compiler builds the schema from the sources and compares it with the lock file.
New fields and variants get max(tags, reserved) + 1, new rpcs the next number in the service.
A field removed with @removed(n) is moved to reserved. Removed without @removed — the error schema-break.
Compatible changes are written to the file automatically; incompatible ones (§9.2) — an error naming the field and the rule.
oxl build --locked (for CI) forbids changing the lock file: the schema must already be committed.

C.3 Reconciliation with the registry#

The comparison is made against the last published version, not only against the local file — otherwise a deleted and recreated lock file would bypass the check.

oxl publish downloads from the registry the lock file of the version published (the registry stores the lock file of each published version).
It compares it with the current schema under the rules of §9.2.
It determines the minimum permissible version step:

Change	Minimum version
internal code only, the `pub(api)` schema did not change	patch
added fields, variants of an `@open` enum, rpcs, types	minor
any breaking change from §9.2	major, and the affected types and services MUST get `@v(n+1)`

If the version in oxl.toml is less than the minimum — a refusal with an explanation.
After publication the registry stores the lock file and published in the local file is updated.

C.4 Checking between versions#

oxl check --against <version|file> compares the schema with the lock file of another version, for example the one running in production.
During a rolling upgrade nodes compare schema hashes; a node with an incompatible schema receives no traffic and is flagged in the web interface.

Source: docs/spec/oxl-standard.en.md