Messages

(Previously known as the Orbital Standard Message, OSM)

An Orbital Message is a NATS JetStream message that always follows a strict, predefined structure. Each Message includes a mandatory set of root-level metadata properties, commonly referred to as the Message header.

Depending on its usage context (see Message categories below), a Message may include additional predefined header properties. Beyond these, a Message cannot contain arbitrary root-level properties and never includes properties specific to a single Ørb.

Message categories and lifecycles

Message categories are not defined by an explicit property. Instead, they are determined by how they are intended to be used and their specific lifecycle.

There are currently three Message categories:

Managed
Declarative
Transactional

Each category includes a sub-set of standardized header properties, but from a Jetstream perspective, all Messages are managed identically.

flowchart TD

  subgraph Messages["Messages"]
    direction TB

    %% Level 1
    subgraph MessageCategory["Message Category"]
      direction LR
      declarative["declarative"]
      managed["managed"]
      transactional["transactional"]
    end

    %% Level 2
    subgraph ModuleType["Module Type"]
      direction LR
      settings["settings"]
      config["config"]
      content["content"]
      rules["rules"]
      transactions["transactions"]
    end

    %% Level 3 (renamed)
    subgraph MessageRole["Message Role"]
      direction LR
      settings_entries["entries"]

      config_schemas["schemas"]
      config_entries["entries"]

      content_schemas["schemas"]
      content_entries["entries"]

      rules_entries["entries"]

      transactions_schema["schema"]
      transactions_entries["entries"]
    end

    %% Category -> Module Type
    declarative --> settings
    managed --> config
    managed --> content
    managed --> rules
    transactional --> transactions

    %% Module Type -> Message Role
    settings --> settings_entries

    config --> config_schemas
    config --> config_entries

    content --> content_schemas
    content --> content_entries

    rules --> rules_entries

    transactions --> transactions_schema
    transactions --> transactions_entries
  end

Managed Messages

Managed Messages represent data that can transition between non-linear explicit states. The most common lifecycle includes:

SAVED, PUBLISHED, UNPUBLISHED, ARCHIVED

Managed Messages support versioning. Any change to Message content or state results in a new version.

Examples of Managed Messages:

Type	Description
Content Entries	Unpublishing an entry removes it from production by changing its state
Market Configurations	Disabling a market removes it from downstream Ørbs, preventing content generation and configuration for the market
Frontend Rules	Disabling/Unpublishing a rule prevents it from being evaluated
Backend Rules	Disabling a rule prevents it from being evaluated
Capsule Configurations	Disabling a capsule prevents it from being rendered

Declarative Messages

Declarative Messages can be updated but not disabled nor unpublished. It’s a one-off, and is usually not restricted by a specific Schema.

For example, a service configuration may be re-saved with a new log level, but the service itself cannot be removed by unpublishing its configuration.

Declarative Messages support versioning, and each save produces a new version.

Examples include:

Ørb/Service configurations
Back Office or product webclient base settings

Transactional Messages

Transactional Messages represent stateful processes with a strictly linear lifecycle.

Only changes to the Message status create new versions, for example:

INITIATED → PENDING → COMPLETED

Transactional Messages cannot be deleted, unpublished, disabled, or manually altered.

Examples include:

Wallet transaction data

Message Structure

While header properties vary slightly between Message categories, all Messages share the same fundamental structure:

Header — Root-level identity and metadata fields (id, slug, role, displayName, metadata)
Spec — Kind-specific data stored under the spec property

This ensures the payload remains independent of location, enabling rename and move operations without payload changes.

Standard Message Header

These Message header properties are shared across all Ørbs and streams, regardless of purpose:

{
  "id": String,
  "slug": String,
  "kind": String,
  "displayName": String,
  "description": String,
  "metadata": {
    "createdAt": String,
    "createdBy": {
      "type": String,
      "name": String
    },
    "updatedAt": String,
    "updatedBy": {
      "type": String,
      "name": String
    },
    "status": String,
    "version": Int,
    "market": String,
    "language": String
  },
  "spec": Object
}

Property	Description
`id`	Unique identifier. User-defined for definitions (Orb/Module/Schema), system-generated (xid) for Entries
`slug`	Optional user-friendly identifier. Only needed for Entries where `id` is system-generated. Falls back to `id` if omitted
`kind`	Item type: `Orb`, `Module`, `Schema`, or `Entry`
`displayName`	Human-readable name for UI
`description`	Optional description
`metadata`	Standard metadata block (see below)

ID vs Slug

Kind	`id`	`slug`	Notes
Orb	User-defined (`games`)	Omitted	`id` is human-readable
Module	User-defined (`catalog`)	Omitted	`id` is human-readable
Schema	User-defined (`game`)	Omitted	`id` is human-readable
Entry	System xid (`cq9k2x...`)	User-defined (`sweet-bonanza`)	Both needed

Actor

The createdBy and updatedBy fields identify who made changes:

Property	Description
`type`	Actor type: `user`, `orb`
`name`	Identifier (email or userId for users, Ørb ID for system)

Category-Specific Header Properties

Managed and Transactional Messages

Both Managed and Transactional Messages include a status property in the metadata that represents the current lifecycle state.

The status field supports:

Managed: SAVED, PUBLISHED, UNPUBLISHED, ARCHIVED
Transactional: INITIATED → PENDING → COMPLETED

Managed and Declarative Messages

Both Managed and Declarative Messages support structured change tracking via the changeLog field in metadata. This records both human-readable comments and automatic change diffs.

Scheduled Activation

Managed Messages may also include validFrom and validTo properties in their metadata, enabling scheduled activation and deactivation across the platform.

Spec (aka Payload TBD)

The spec property contains kind-specific data:

Kind	Spec Contains
`Orb`	Module list, registry exposure settings
`Module`	Type (CONTENT/CONFIG), schema references, routing config
`Schema`	Field definitions with types and validation
`Entry`	Actual data conforming to its Schema

The Spec structure is defined by the Item’s Kind and, for Entries, validated against the referenced Schema.