Versioning & Extension

18.1 Schema Version Field

Modules SHOULD declare the schema version they target via a top-level version field:

{
  "id": "my_module",
  "type": "module",
  "version": "1.0",
  ...
}

Field	Type	Required	Description
version	string	Recommended	Semver "major.minor" (e.g. "1.0", "1.2").

When absent, the SDK treats the module as compatible with the current runtime version and emits an informational note during validation. Modules using features introduced after v1.0 SHOULD declare the minimum required version.

Compatibility rules:

Module version vs SDK	Behaviour
Same or lower	Renders normally.
Higher minor (e.g. 1.3)	Renders with a warning. Unknown features show a placeholder view.
Higher major (e.g. 2.0)	Validation fails. The module cannot render correctly.
Absent	Treated as compatible. Validation emits a note.

18.2 Forward Compatibility

Unknown component types MUST NOT crash the runtime. The SDK renders an informational placeholder view in place of the unsupported component and emits a warning during validation. If the unknown component declares children, the SDK MUST attempt to decode and render those children — this allows known child components inside an unknown container to remain visible.

Unknown context keys, style keys, and event types MUST be silently ignored — they do not produce errors.

18.3 The onCustom Bridge

onCustom is the standard bridge between the host application and a running StemJSON module. The host triggers a named event at any time to start a JSON-defined action chain. This allows native logic to influence StemJSON flows without modifying the JSON payload.

18.4 Extension Points

• Custom service kinds: New service kinds can be registered without changing the StemJSON schema. The service action routes to them by id.
• Custom repository kinds: New repository kinds can be added without schema changes.