Module extensible_fields 

Per-tenant extensible fields for extensible JSON/JSONB columns.

A column declared "extensible": true in config becomes a extensible-fields bag: a JSON document whose keys are defined per tenant in a KV-stored registry, not in the schema. Those keys become first-class RSQL-filterable/sortable fields via the <column>.<key> dotted syntax (e.g. q=attributes.warrantyMonths=ge=12, sort=-attributes.voltage).

Registry storage

Definitions live in _sys_kv_data under the reserved namespace REGISTRY_NAMESPACE, one row per entity keyed by the entity’s path_segment. The stored value maps each extensible column name to its list of field definitions:

{
  "attributes": [
    { "key": "warrantyMonths", "type": "int",  "filterable": true, "sortable": true },
    { "key": "voltage",        "type": "decimal" }
  ]
}

Field keys are stored verbatim (no case conversion), so the convention is camelCase — that is exactly how they round-trip to API clients.

Structs

CachedRegistry

A cached registry plus the instant it was loaded (for TTL expiry).

ExtensibleFieldDef

One extensible-field definition: its key, declared type, and validation/query flags.

ExtensibleRegistry

Resolved extensible-field registry for a single entity: extensible column → (field key → def).

Enums

ValidateMode

Validation mode: Full enforces required extensible fields (create); Partial validates only the fields present in the request (update/PATCH).

Constants

REGISTRY_CACHE_TTL

How long a cached registry stays valid before it is reloaded from the config DB. Bounds cross-instance staleness when another node updates the registry (single-instance updates are evicted immediately on write).

REGISTRY_NAMESPACE

Reserved KV namespace under which extensible-field registries are stored.

Functions

apply_indexes

Execute index DDL statements against pool, best-effort. Returns (applied, errors): statements that succeeded, and (statement, message) for those that failed (e.g. a MySQL “duplicate key name” when the index already exists). Never fails the whole batch on one error.

delete_registry

Delete the registry document for one entity. Returns true when a row was removed.

index_ddl

Build CREATE INDEX statements for every filterable or sortable extensible field in the registry, one per (column, key), using the dialect’s typed JSON extraction so the index matches the expression the query builder emits.

load_registry

Load the extensible-field registry for one entity from the KV store.

load_registry_raw

Read the raw registry document for one entity (the value stored in _sys_kv_data), or None when no registry has been defined. Unlike load_registry, this returns the untouched JSON for display in the admin API rather than the parsed/indexed structure.

store_registry

Upsert the registry document for one entity into _sys_kv_data under the reserved REGISTRY_NAMESPACE, keyed by path_segment. Writes directly, bypassing the _sys_kv_stores namespace check the public KV API enforces.

validate_extensible_fields

Validate the extensible-fields bags in a (snake_cased top-level) request body against the per-tenant registry. Rejects unknown keys, type mismatches, and constraint violations with HTTP 422. Plain (non-extensible) JSON columns are ignored entirely.

validate_registry_document

Validate a raw registry document intended for entity: it must be a JSON object whose top-level keys are all extensible columns on the entity, and whose values parse as field definition lists. Returns the validated registry on success (HTTP 422 on any problem).

Type Aliases

RegistryCache

Process-shared, tenant-scoped registry cache keyed by (tenant_id, package_id, path_segment). Lives on AppState; read-through on load, evicted on admin write.