ModuleManifest

Concept: From Metadata to Database →

A module manifest — the parsed contents of a *_module.json5 file. A module declares a namespace that groups related objects and fields; every object belongs to exactly one module, and the module’s key forms the first segment of every qualified reference (e.g. core.Account).

The manifest is the authoritative declaration of a module’s identity, dependencies, contract surface, and upgrade behavior. manifestVersion: 1 is required — a manifest missing it fails to load.

Properties

Property	Type	Required/Default	Constraints	Meaning
moduleKey	string	Required	min length 1; max length 63; pattern ^[a-z][a-zA-Z0-9]*$	The module’s API name — first-party modules use a bare key (e.g. "core", "crm"); third-party modules combine it with vendor.key to form the effective module identity "vendor.module" (e.g. "acme.crm").
label	string	Required		Human-readable display name for the module.
description	string	Optional		Free-text description of the module’s purpose.
manifestVersion	integer (uint32)	Required	minimum 0	Manifest schema version.
version	string	Optional		Module release version (semver string, e.g. "1.2.0").
vendor	VendorInfo object	Optional		Vendor identity for third-party modules.
protectionMode	enum (ProtectionMode)	Optional		Protection mode governing structural mutability.
dependencies	object	Optional (default: {})		Declared module dependencies with version requirements and resolution sources.
moduleInterface	ExportDeclarations object	Optional		Contract surface — explicit declaration of what this module exports.
declaredRoles	array of RoleDecl object	Optional (default: [])		Roles declared by this module, available for assignment and composition.
expectedDestructiveOperations	array of DestructiveOperation	Optional (default: [])		Destructive schema changes pre-approved for this upgrade.
configSchema	array of ConfigField object	Optional (default: [])		Operator-facing configuration schema for this module — settings an operator may configure per install.
vendorKey	string	Optional	min length 1; max length 63; pattern ^[a-z][a-zA-Z0-9]*$	Deprecated — use vendor.key instead.
identity	IdentityConfig object	Optional		Visual identity (color + icon) for the module.

moduleKey

The module’s API name — first-party modules use a bare key (e.g. "core", "crm"); third-party modules combine it with vendor.key to form the effective module identity "vendor.module" (e.g. "acme.crm"). Must be unique across the metadata set. camelCase — a lowercase letter followed by letters and digits, no underscores, at most 63 characters.

description

Free-text description of the module’s purpose. Shown in the Module Manager and marketplace.

manifestVersion

Manifest schema version. Must be 1. Deserialization fails if absent.

Future breaking changes to the manifest schema will increment this value. Within manifestVersion: 1, fields may be added with defaults but not removed.

vendor

Vendor identity for third-party modules.

Absent for first-party modules. Trust tier is computed by the operator’s trust-policy.json5, not declared here.

protectionMode

Protection mode governing structural mutability.

Defaults to Local when absent (operator-authored, no restrictions).

dependencies

Declared module dependencies with version requirements and resolution sources.

Under manifestVersion: 1, every cross-module extends target and lookup target’s module must appear in this map.

moduleInterface

Contract surface — explicit declaration of what this module exports.

Only elements listed here are referenceable by other modules. Absent or empty means nothing is exported (private-by-default). Enforced during cross-module reference validation.

expectedDestructiveOperations

Destructive schema changes pre-approved for this upgrade.

The apply engine requires --destructive for any operation NOT listed here. Operations listed here are auto-approved; data is still vaulted before execution.

configSchema

Operator-facing configuration schema for this module — settings an operator may configure per install. Parsed and stored; not yet enforced.

vendorKey

Deprecated — use vendor.key instead. Preserved for backward compatibility with pre-v1 module files; when both vendorKey and vendor.key are present, vendor.key takes precedence. Same camelCase charset rule as vendor.key.

identity

Visual identity (color + icon) for the module.

Both subfields are optional; absent means platform defaults apply at render time.

BarcodeFormat

Barcode encoding format for a Barcode field.

Value	Status	Description
ean13		EAN-13: 13-digit numeric barcode (retail products).
ean8		EAN-8: 8-digit numeric barcode (smaller retail products).
upcA		UPC-A: 12-digit numeric barcode (North American retail).
isbn13		ISBN-13: 13-digit book identifier (EAN-13 subset).
isbn10		ISBN-10: 10-character book identifier (9 digits + check digit [0-9Xx]).
code128		Code 128: variable-length alphanumeric barcode (printable ASCII, [ -~]).
qr		QR code: arbitrary data payload.

ComponentExport — No effect yet

Contract surface export declaration for an HFX component. Parsed and stored; not yet enforced — HFX module-aware imports have not landed.

Property	Type	Required/Default	Constraints	Meaning
importable	boolean	Optional (default: false)		Whether other modules’ HFX files may import this component.
slots	array of string	Optional (default: [])		Named slots that other modules may inject content into.

ConfigField — No effect yet

A configuration field declared in the module’s operator-facing config schema. Parsed and stored; not yet enforced.

Property	Type	Required/Default	Constraints	Meaning
fieldKey	string	Required		Config field key, e.g. "maxLeadsPerAccount".
fieldType	ScalarType	Required		Scalar type of the config value.
label	string	Required		Display label for the config field.
operatorOverridable	boolean	Optional (default: false)		Whether operators may override this value per-instance.

DependencyDeclaration

A single entry in the manifest’s dependencies map, keyed by the depended-on module’s fully-qualified key (e.g. "core", "acme.billing").

Every extends target and lookup target whose module differs from the current module must have a corresponding entry here.

Property	Type	Required/Default	Constraints	Meaning
reason	enum (DependencyReason)	Required		Why this dependency is required.
source	DependencySource	Optional (default: {"name":"default","type":"registry"})		Where to resolve the module.
version	string	Required		Semver requirement, e.g. ">=1.0", "^2.1.3".

source

Where to resolve the module. Defaults to { type: "registry", name: "default" } when omitted.

DependencyReason

Why this module is listed as a dependency, authored as the reason property of a dependency entry: "inheritance", "lookup", "fieldContribution", or "peer".

Value	Status	Description
inheritance		This module inherits from an object defined in the dependency.
lookup		This module has a lookup field whose target is in the dependency.
fieldContribution		This module contributes fields to an object in the dependency.
peer		Declared peer dependency — no structural reference, but runtime coupling.

DependencySource

Where to resolve a declared dependency, authored as the source property of a dependency entry. An object with a type discriminator — "registry", "git", "path", or "actor". Defaults to { type: "registry", name: "default" } when source is omitted.

Only the "registry" form is honored today: dependency resolution reads from the named registry. The "git", "path", and "actor" forms parse and round-trip but resolve identically to { type: "registry", name: "default" } — they do not yet fetch from a git repository, local path, or federated actor.

Named registry entry.

Property	Type	Required/Default	Constraints	Meaning
name	string	Required		Registry name from the operator’s resolver config, e.g. "default".
type	"registry"	Required

name

Registry name from the operator’s resolver config, e.g. "default". Required when type: "registry" is authored explicitly.

Git repository at a specific revision. — No effect yet

Property	Type	Required/Default	Constraints	Meaning
rev	string	Optional		Commit SHA, tag, or branch.
type	"git"	Required
url	string	Required		Repository URL (HTTPS or SSH).

rev

Commit SHA, tag, or branch. Omitted means HEAD.

Local filesystem path, relative to the workspace root. — No effect yet

Property	Type	Required/Default	Constraints	Meaning
path	string	Required		Relative or absolute path to the module directory.
type	"path"	Required

Federated actor URL. — No effect yet

Property	Type	Required/Default	Constraints	Meaning
type	"actor"	Required
url	string	Required		Actor URL of the publishing instance.

DestructiveOperation

A single entry in the manifest’s expectedDestructiveOperations list — a destructive schema change pre-approved for this upgrade. An object with an op discriminator, e.g. { op: "dropField", object: "Lead", field: "legacyStatus" }.

Listing an operation here waives the --destructive flag the apply engine otherwise requires for it; data is still vaulted before the change executes.

Remove a field column from an object table.

Property	Type	Required/Default	Constraints	Meaning
field	string	Required		Field key to drop, e.g. "legacyStatus".
object	string	Required		Object key within this module, e.g. "Lead".
op	"dropField"	Required

Remove an object table entirely.

Property	Type	Required/Default	Constraints	Meaning
object	string	Required		Object key within this module, e.g. "LeadIndexCache".
op	"dropObject"	Required

Rename a field column (data preserved, column renamed in-place).

Property	Type	Required/Default	Constraints	Meaning
from	string	Required		Current field key.
object	string	Required		Object key within this module.
op	"renameField"	Required
to	string	Required		New field key.

Change a field’s scalar type (may require a data migration).

Property	Type	Required/Default	Constraints	Meaning
field	string	Required		Field key being changed.
from	string	Required		Current type name, e.g. "text".
object	string	Required		Object key within this module.
op	"changeType"	Required
to	string	Required		New type name, e.g. "int".

Remove a lookup relationship between two objects.

Property	Type	Required/Default	Constraints	Meaning
from	string	Required		Qualified name of the object owning the lookup field, e.g. "acme.crm.Contact".
op	"dropRelationship"	Required
to	string	Required		Qualified name of the lookup target, e.g. "core.Account".

EnumTransition

A state machine transition rule for an enum field.

Declares that a field value is allowed to change from from to any value in to. An empty to vec means the state is terminal (no transitions out).

Property	Type	Required/Default	Constraints	Meaning
from	string	Required		The source state this rule applies to.
to	array of string	Required		Allowed destination states.

to

Allowed destination states. Empty means terminal.

EventExport — No effect yet

Contract surface export declaration for a platform event. Parsed and stored; not yet enforced — the event runtime has not landed.

Property	Type	Required/Default	Constraints	Meaning
payloadStable	boolean	Optional (default: false)		Whether the event payload schema is stable across semver minor versions.
subscribable	boolean	Optional (default: false)		Whether other modules may subscribe to this event.

ExportDeclarations

The full contract surface declared by a module for cross-module consumption, authored as the manifest’s moduleInterface property.

Under manifestVersion: 1, only elements listed here are referenceable by other modules. An object not in objects is private — other modules cannot inherit from it, target it in lookups, or contribute fields to it.

Map keys are element keys within the module (e.g. "Lead", "Lead.email"). Violating a declared constraint is a compile-time error.

Property	Type	Required/Default	Constraints	Meaning
components	object	Optional (default: {})		HFX components exported for cross-module import (schema-only, Tier 1).
events	object	Optional (default: {})		Platform events exported for cross-module subscription (schema-only, Tier 1).
fields	object	Optional (default: {})		Fields exported for cross-module reads, writes, and overrides.
lookups	object	Optional (default: {})		Lookup relationships exported for cross-module traversal.
objects	object	Optional (default: {})		Objects exported for cross-module inheritance, lookups, and field contribution.
roles	object	Optional (default: {})		Roles exported for cross-module composition and extension.

FieldExport

Contract surface export declaration for a single field.

Property	Type	Required/Default	Constraints	Meaning
overridable	array of enum (OverridableProperty)	Optional (default: [])		Which aspects of this field inheriting child objects may override.
readable	boolean	Optional (default: false)		Whether other modules may read this field’s value.
writable	boolean	Optional (default: false)		Whether other modules may write this field’s value.

FloatSize

Floating-point storage width.

Selects between the two IEEE 754 approximate-float PG types. The default is Double (64-bit DOUBLE PRECISION). Use Single only when storage density outweighs the reduced precision.

Variant	PG type	Precision
Single	REAL	~6–7 significant digits
Double	DOUBLE PRECISION	~15–16 significant digits

Value	Status	Description
single		32-bit IEEE 754 → REAL.
double		64-bit IEEE 754 → DOUBLE PRECISION.

IdentityConfig

Visual identity (color and icon) for a module or object.

Both fields are optional; when absent, Studio falls back to platform defaults at render time.

Property	Type	Required/Default	Constraints	Meaning
color	enum (IdentityHue)	Optional		The identity hue.
icon	string	Optional		A Phosphor icon name in PascalCase, matching the icon’s export name from @phosphor-icons/react (e.g. "Cube", "Lock", "MagnifyingGlass").

color

The identity hue. Absent by default (platform default hue).

icon

A Phosphor icon name in PascalCase, matching the icon’s export name from @phosphor-icons/react (e.g. "Cube", "Lock", "MagnifyingGlass"). Absent by default (platform default icon).

Must be one of the curated icon set the platform ships with — an unrecognized name is rejected when the manifest loads.

IdentityHue

One of nine curated colors for module and object visual identity.

Written in kebab-case in *_module.json5 and *_object.json5 manifests (e.g. color: "indigo"). See IdentityConfig.

Value	Status	Description
blue		Blue — the recommended default for foundational modules.
cloud		Cloud — soft pale blue for ambient or utility surfaces.
electric		Electric — saturated cyan for high-energy contexts.
indigo		Indigo — deep blue-violet for analytic or data surfaces.
purple		Purple — for collaboration and people-centric modules.
violet		Violet — a softer, magenta-leaning purple.
teal		Teal — for operational or process-centric modules.
green		Green — for success, lifecycle, or billing flows.
orange		Orange — for warnings, sales, or time-sensitive flows.

IntSize

Integer storage width.

Selects between the three signed-integer PG types. The default is Big (64-bit BIGINT), which is always safe; downsize only when storage density matters.

Variant	PG type	Range
Small	SMALLINT	−32 768 … 32 767
Regular	INTEGER	~±2.1 B
Big	BIGINT	~±9.2 × 10¹⁸

Value	Status	Description
small		16-bit signed integer → SMALLINT.
regular		32-bit signed integer → INTEGER.
big		64-bit signed integer → BIGINT.

IntervalFields

Restricts which time components a TimeInterval field stores and accepts.

Maps directly to the PostgreSQL INTERVAL <fields> qualifiers. When absent (the default), all components (years through microseconds) are accepted.

Determines whether the field’s precision parameter (fractional-seconds digits) is meaningful: only qualifiers that include a SECOND component (Second, DayToSecond, HourToSecond, MinuteToSecond) accept one.

Value	Status	Description
year		YEAR
month		MONTH
day		DAY
hour		HOUR
minute		MINUTE
second		SECOND
yearToMonth		YEAR TO MONTH — billing periods, tenures.
dayToHour		DAY TO HOUR
dayToMinute		DAY TO MINUTE
dayToSecond		DAY TO SECOND — SLA windows, durations.
hourToMinute		HOUR TO MINUTE
hourToSecond		HOUR TO SECOND
minuteToSecond		MINUTE TO SECOND

LookupExport

Contract surface export declaration for a lookup relationship.

Property	Type	Required/Default	Constraints	Meaning
cardinalityStable	boolean	Optional (default: false)		Whether the cardinality (1:1, 1:N) is stable across semver minor versions.
traversable	boolean	Optional (default: false)		Whether other modules may traverse this relationship in queries.

ObjectExport

Contract surface export declaration for a single object.

Property	Type	Required/Default	Constraints	Meaning
fieldExtensible	boolean	Optional (default: false)		Whether other modules may contribute additional fields to this object.
inheritable	boolean	Optional (default: false)		Whether other modules may inherit from this object (extends: "this.Object").
lookupTargetable	boolean	Optional (default: false)		Whether other modules may create lookup fields targeting this object.
recordExtensible	boolean	Optional (default: false)		Whether operators may add configuration records to this object.

OverridableProperty

Which aspects of a field other modules may override in inheriting child objects.

Value	Status	Description
label		Display label shown in the UI.
helpText		Help text shown alongside the field.
validation		Validation rules (required, max length, pattern).
required		Whether the field is required in the child object.
picklistValues		Picklist values (for enumeration fields).

PercentScale

Accepted value range for a Percent field.

Value	Status	Description
zeroToOne		Values must be in the range [0.0, 1.0] (ratio).
zeroToHundred		Values must be in the range [0.0, 100.0] (percentage points).

ProtectionMode

Protection mode governing which structural modifications to the module’s objects and fields are permitted, authored as the manifest’s protectionMode property. Defaults to "local" when absent.

• "builtin" — compiled into the binary; immutable at runtime.
• "vendor" — structure is immutable; operators may add x_* extension fields.
• "local" — operator-authored; no restrictions.
• "system" — platform-managed metadata (e.g. operations schema tables).

Value	Status	Description
builtin		Compiled into the server binary; immutable at runtime.
vendor		Third-party vendor module; structure immutable, x_* extensions allowed.
local		Operator-authored; no restrictions beyond schema validity.
system		Platform-managed metadata (e.g. operations schema tables).

RoleDecl

A role declared by this module, available for assignment and composition. Registers the role’s existence for contract-surface and packaging purposes; the role’s permission set is authored in a separate role definition file.

Property	Type	Required/Default	Constraints	Meaning
label	string	Required		Display label for the role.
roleKey	string	Required		Role key within this module, e.g. "lead-editor".

RoleExport

Contract surface export declaration for a role.

Property	Type	Required/Default	Constraints	Meaning
composable	boolean	Optional (default: false)		Whether other modules may include this role in composite role definitions.
extendable	boolean	Optional (default: false)		Whether other modules may extend this role’s permission set.

ScalarType

Scalar type taxonomy for Henceforth field definitions.

Every scalar field declares its type via the kind property in the field’s .json5 file, for example {"kind": "bool"} or {"kind": "text", "maxLength": 255}. Parameterless kinds need no further properties; kinds with parameters list them alongside kind. Each variant below documents its kind value, its accepted parameters, and the PostgreSQL column type it compiles to.

BOOLEAN — true/false value.

Property	Type	Required/Default	Constraints	Meaning
kind	"bool"	Required

DATE — calendar date without time-of-day.

Property	Type	Required/Default	Constraints	Meaning
kind	"date"	Required

UUID — 128-bit universally unique identifier, for external identifiers.

Property	Type	Required/Default	Constraints	Meaning
kind	"uuid"	Required

BYTEA — arbitrary binary data; transmitted as base64 over the API.

Property	Type	Required/Default	Constraints	Meaning
kind	"binary"	Required

INET — IPv4 or IPv6 host or network address; host bits may be non-zero.

Property	Type	Required/Default	Constraints	Meaning
kind	"inet"	Required

CIDR — IPv4 or IPv6 network address; host bits must be zero (enforced at write boundary).

Property	Type	Required/Default	Constraints	Meaning
kind	"cidr"	Required

JSONB — binary JSON; supports GIN indexing and @> containment operators.

Property	Type	Required/Default	Constraints	Meaning
kind	"json"	Required
schema	any	Optional		Optional JSON Schema that incoming values must conform to.

schema

Optional JSON Schema that incoming values must conform to. Must be valid JSON Schema Draft 2020-12; an invalid schema is rejected when the module is compiled.

TIMESTAMPTZ — timezone-aware timestamp; always stored as UTC.

Property	Type	Required/Default	Constraints	Meaning
kind	"timestamp"	Required

Signed integer.

Property	Type	Required/Default	Constraints	Meaning
kind	"int"	Required
size	enum (IntSize)	Optional (default: "big")		Storage width.

size

Storage width. Defaults to Big (BIGINT).

Approximate floating-point.

Property	Type	Required/Default	Constraints	Meaning
kind	"float"	Required
size	enum (FloatSize)	Optional (default: "double")		Storage width.

size

Storage width. Defaults to Double (DOUBLE PRECISION).

Exact arbitrary-precision numeric.

Property	Type	Required/Default	Constraints	Meaning
kind	"decimal"	Required
precision	integer (uint16)	Optional	minimum 0; maximum 65535	Total significant digits (1–1000).
scale	integer (uint8)	Optional	minimum 0; maximum 255	Digits after the decimal point (0–precision).

precision

Total significant digits (1–1000). If absent, bare NUMERIC.

scale

Digits after the decimal point (0–precision). If absent with precision, defaults to 0.

Variable-length text.

Property	Type	Required/Default	Constraints	Meaning
kind	"text"	Required
maxLength	integer (uint32)	Optional	minimum 0	Maximum character length → VARCHAR(n).

maxLength

Maximum character length → VARCHAR(n). If absent, TEXT. Authored as maxLength.

Duration / time interval.

Property	Type	Required/Default	Constraints	Meaning
fields	enum (IntervalFields)	Optional		Restricts which time components are stored and accepted.
kind	"timeInterval"	Required
precision	integer (uint8)	Optional	minimum 0; maximum 255	Fractional-seconds precision (0–6).

fields

Restricts which time components are stored and accepted. If absent, all components (years through microseconds) are valid.

precision

Fractional-seconds precision (0–6). Meaningful only when fields includes a SECOND component; compile error otherwise.

Controlled vocabulary field — stores one of a declared set of string values.

Property	Type	Required/Default	Constraints	Meaning
kind	"enum"	Required
transitions	array of EnumTransition object	Optional		State machine transition rules.
values	array of string	Required		Ordered list of valid values.

transitions

State machine transition rules. If present, UPDATE operations must follow the declared transitions. Every from and to value must appear in values; an unlisted value is rejected when the module is compiled.

values

Ordered list of valid values. Must be non-empty, with no duplicate entries — both are rejected when the module is compiled.

RFC 5321-subset email address.

Property	Type	Required/Default	Constraints	Meaning
kind	"email"	Required

https?:// URL.

Property	Type	Required/Default	Constraints	Meaning
kind	"url"	Required

E.164-compatible phone number.

Property	Type	Required/Default	Constraints	Meaning
kind	"phone"	Required

URL-safe slug: [a-z0-9-]+.

Property	Type	Required/Default	Constraints	Meaning
kind	"slug"	Required

Markdown-formatted text.

Property	Type	Required/Default	Constraints	Meaning
kind	"markdown"	Required

HTML markup.

Property	Type	Required/Default	Constraints	Meaning
kind	"html"	Required
sanitize	boolean	Optional (default: false)		When true, disallowed tags and attributes are stripped before storing.

Numeric ratio or percentage.

Property	Type	Required/Default	Constraints	Meaning
kind	"percent"	Required
scale	enum (PercentScale)	Optional (default: "zeroToOne")		Accepted value range.

scale

Accepted value range. Defaults to ZeroToOne.

Barcode data in a specific format.

Property	Type	Required/Default	Constraints	Meaning
format	enum (BarcodeFormat)	Required		Barcode format; determines the CHECK pattern.
kind	"barcode"	Required

Ordered list of scalar values.

Property	Type	Required/Default	Constraints	Meaning
element_type	ScalarType	Required		The type of each element.
kind	"array"	Required
max_items	integer (uint32)	Optional	minimum 0	Maximum number of elements.
unique_elements	boolean	Optional (default: false)		When true, duplicate elements are rejected at the write boundary.

element_type

The type of each element. Must not be Array (no nesting), and must not be json, timeInterval, inet, cidr, markdown, html, binary, or barcode — none of these are valid array element kinds. An invalid element type is rejected when the module is compiled.

max_items

Maximum number of elements. Write-boundary enforced, not a DB constraint. When set, must be greater than zero.

VendorInfo

Vendor identity attached to a third-party module, authored as the manifest’s vendor property.

Trust tier is not declared here — it is computed by the operator’s trust-policy.json5 matching against key and publicKey. A vendor that declares its own trust level is not trusted.

Property	Type	Required/Default	Constraints	Meaning
actor	string	Optional		ActivityPub actor URL.
key	string	Required	min length 1; max length 63; pattern ^[a-z][a-zA-Z0-9]*$	The vendor’s namespace segment, e.g. "acme".
publicKey	string	Optional		PEM or base64-encoded public key used to verify module signatures.

actor

ActivityPub actor URL. Reserved for future federation support — the platform does not populate or read it.

key

The vendor’s namespace segment, e.g. "acme". Combines with moduleKey to form the module’s fully-qualified identity ("acme.crm"). camelCase — a lowercase letter followed by letters and digits, no underscores, at most 63 characters.

Example

{
  "label": "example",
  "manifestVersion": 0,
  "moduleKey": "example"
}