cloudevents — CloudEvent payload JSON Schemas

cyoda-go version 0.6.2

cloudevents

NAME

cloudevents — JSON Schemas for every CloudEvent payload exchanged over the gRPC CloudEventsService bidirectional stream.

SYNOPSIS

cyoda help cloudevents            # narrative (this page)
cyoda help cloudevents json       # full schemas tree as a single JSON document

DESCRIPTION

cyoda-go uses CloudEvents v1.0 as the transport envelope for event-driven processing. Every payload carried inside a CloudEvent — workflow calculation requests, calculation responses, entity transaction events, snapshot state, model descriptors — is validated against a JSON Schema (Draft 2020-12).

The canonical schema tree lives at docs/cyoda/schema/ in this repo and is embedded into the binary at build time. It is the single source of truth for:

• Runtime validation of inbound CloudEvent payloads (in cyoda-go and external compute members).
• Code generation via scripts/generate-events.sh — the Go types in api/grpc/events/types.go are derived from this tree.
• Downstream tooling: documentation pipelines and SDK generators extract the tree from the binary (see cyoda help cloudevents json), so every version of cyoda ships with a matching, self-describing schema bundle.

ORGANIZATION

The tree is organized by domain:

• common/ — shared envelope fragments: BaseEvent, DataPayload, CloudEventType, ModelSpec, ErrorCode. Every domain-specific payload extends BaseEvent.
• common/statemachine/ — workflow metadata descriptors: WorkflowInfo, TransitionInfo, ProcessorInfo.
• entity/ — entity create / update / delete / transition / audit requests and responses.
• model/ — model snapshot events and management requests.
• processing/ — compute-member protocol events: EntityCriteriaCalculationRequest/Response, EntityProcessorCalculationRequest/Response, CalculationMemberJoinEvent, CalculationMemberGreetEvent, EventAckResponse.
• search/ — search snapshot lifecycle events.

Every schema carries a $id in the form https://cyoda.com/cloud/event/<relative-path>. Inter-schema references use relative $ref paths (e.g. ../common/BaseEvent.json) so a materialized filesystem copy resolves out of the box.

ACTION: cyoda help cloudevents json

Emits the entire tree as a single JSON document. Shape:

{
  "schema": 1,
  "version": "<binary-version>",
  "specVersion": "https://json-schema.org/draft/2020-12/schema",
  "baseId": "https://cyoda.com/cloud/event/",
  "schemas": {
    "common/BaseEvent.json":                { "$schema": "...", "$id": "...", ... },
    "common/statemachine/WorkflowInfo.json": { ... },
    "entity/EntityTransactionResponse.json": { ... },
    "processing/EntityCriteriaCalculationRequest.json": { ... },
    ...
  }
}

• schemas is a map keyed by relative path (identical to the directory layout). This lets downstream tooling fan the tree out to disk without renaming.
• Values are complete JSON Schema documents, structurally identical to the source file after normalizing whitespace and key ordering.
• $ref values stay relative — they are not rewritten to absolute URLs. A consumer that writes the tree to disk gets working resolution for free.
• Keys are lexicographically sorted — output is diff-stable across builds.
• baseId and specVersion are constants exposed for consumers that want to construct absolute IDs or validate against a specific meta-schema.

VERIFICATION

Count emitted schemas:

cyoda help cloudevents json | jq '.schemas | keys | length'

List every schema path:

cyoda help cloudevents json | jq -r '.schemas | keys[]'

Materialize the tree to a directory:

cyoda help cloudevents json \
  | jq -r '.schemas | to_entries[] | "\(.key)\t\(.value | tojson)"' \
  | while IFS=$'\t' read -r path body; do
      mkdir -p "$(dirname "schemas/$path")"
      printf '%s\n' "$body" > "schemas/$path"
    done

SEE ALSO

• grpc
• workflows
• errors.DISPATCH_TIMEOUT
• errors.DISPATCH_FORWARD_FAILED

See also

• cyoda help grpc — cyoda-go exposes one gRPC service: CloudEventsService (package org.cyoda.cloud.api.grpc). All gRPC methods use the CloudEvents Protobuf envelope (io.cloudevents.v1.CloudEvent) as both request and response types. The event type string in the CloudEvent envelope selects the operation; the JSON payload in text_data (or binary_data) carries the operation-specific body.
• cyoda help workflows — A workflow definition is a named finite state machine attached to an entity model. Workflows are stored per model reference (entityName, modelVersion). A model may have multiple workflow definitions; the engine selects the matching one per entity using the workflow-level criterion field evaluated at entity creation time. When no criterion matches, the engine uses the default built-in workflow.
• cyoda help errors DISPATCH_TIMEOUT — A workflow processor or criteria evaluation was dispatched to a compute member but the response did not arrive within the dispatch timeout window. The underlying task may or may not have completed on the remote node.
• cyoda help errors DISPATCH_FORWARD_FAILED — The cluster dispatcher attempted to forward a processor invocation or criteria evaluation to a peer node but the HTTP call to that peer failed (network error, peer crash, or connection refused). The operation has not been executed on the target node.

Raw formats

• /help/cloudevents.json — full descriptor (matches GET /help/{topic} envelope)
• /help/cloudevents.md — body only