{
  "topic": "cloudevents",
  "path": [
    "cloudevents"
  ],
  "title": "cloudevents — CloudEvent payload JSON Schemas",
  "synopsis": "cyoda-go uses [CloudEvents v1.0](https://cloudevents.io) 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).",
  "body": "# cloudevents\n\n## NAME\n\ncloudevents — JSON Schemas for every CloudEvent payload exchanged over the gRPC `CloudEventsService` bidirectional stream.\n\n## SYNOPSIS\n\n```\ncyoda help cloudevents            # narrative (this page)\ncyoda help cloudevents json       # full schemas tree as a single JSON document\n```\n\n## DESCRIPTION\n\ncyoda-go uses [CloudEvents v1.0](https://cloudevents.io) 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).\n\nThe 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:\n\n- **Runtime validation** of inbound CloudEvent payloads (in cyoda-go and external compute members).\n- **Code generation** via `scripts/generate-events.sh` — the Go types in `api/grpc/events/types.go` are derived from this tree.\n- **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.\n\n## ORGANIZATION\n\nThe tree is organized by domain:\n\n- **`common/`** — shared envelope fragments: `BaseEvent`, `DataPayload`, `CloudEventType`, `ModelSpec`, `ErrorCode`. Every domain-specific payload extends `BaseEvent`.\n- **`common/statemachine/`** — workflow metadata descriptors: `WorkflowInfo`, `TransitionInfo`, `ProcessorInfo`.\n- **`entity/`** — entity create / update / delete / transition / audit requests and responses.\n- **`model/`** — model snapshot events and management requests.\n- **`processing/`** — compute-member protocol events: `EntityCriteriaCalculationRequest`/`Response`, `EntityProcessorCalculationRequest`/`Response`, `CalculationMemberJoinEvent`, `CalculationMemberGreetEvent`, `EventAckResponse`.\n- **`search/`** — search snapshot lifecycle events.\n\nEvery 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.\n\n## ACTION: `cyoda help cloudevents json`\n\nEmits the entire tree as a single JSON document. Shape:\n\n```json\n{\n  \"schema\": 1,\n  \"version\": \"<binary-version>\",\n  \"specVersion\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"baseId\": \"https://cyoda.com/cloud/event/\",\n  \"schemas\": {\n    \"common/BaseEvent.json\":                { \"$schema\": \"...\", \"$id\": \"...\", ... },\n    \"common/statemachine/WorkflowInfo.json\": { ... },\n    \"entity/EntityTransactionResponse.json\": { ... },\n    \"processing/EntityCriteriaCalculationRequest.json\": { ... },\n    ...\n  }\n}\n```\n\n- **`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.\n- **Values are complete JSON Schema documents**, structurally identical to the source file after normalizing whitespace and key ordering.\n- **`$ref` values stay relative** — they are not rewritten to absolute URLs. A consumer that writes the tree to disk gets working resolution for free.\n- **Keys are lexicographically sorted** — output is diff-stable across builds.\n- **`baseId`** and **`specVersion`** are constants exposed for consumers that want to construct absolute IDs or validate against a specific meta-schema.\n\n## VERIFICATION\n\nCount emitted schemas:\n\n```bash\ncyoda help cloudevents json | jq '.schemas | keys | length'\n```\n\nList every schema path:\n\n```bash\ncyoda help cloudevents json | jq -r '.schemas | keys[]'\n```\n\nMaterialize the tree to a directory:\n\n```bash\ncyoda help cloudevents json \\\n  | jq -r '.schemas | to_entries[] | \"\\(.key)\\t\\(.value | tojson)\"' \\\n  | while IFS=$'\\t' read -r path body; do\n      mkdir -p \"$(dirname \"schemas/$path\")\"\n      printf '%s\\n' \"$body\" > \"schemas/$path\"\n    done\n```\n\n## SEE ALSO\n\n- grpc\n- workflows\n- errors.DISPATCH_TIMEOUT\n- errors.DISPATCH_FORWARD_FAILED\n",
  "sections": [
    {
      "name": "NAME",
      "body": "cloudevents — JSON Schemas for every CloudEvent payload exchanged over the gRPC `CloudEventsService` bidirectional stream."
    },
    {
      "name": "SYNOPSIS",
      "body": "```\ncyoda help cloudevents            # narrative (this page)\ncyoda help cloudevents json       # full schemas tree as a single JSON document\n```"
    },
    {
      "name": "DESCRIPTION",
      "body": "cyoda-go uses [CloudEvents v1.0](https://cloudevents.io) 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).\n\nThe 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:\n\n- **Runtime validation** of inbound CloudEvent payloads (in cyoda-go and external compute members).\n- **Code generation** via `scripts/generate-events.sh` — the Go types in `api/grpc/events/types.go` are derived from this tree.\n- **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."
    },
    {
      "name": "ORGANIZATION",
      "body": "The tree is organized by domain:\n\n- **`common/`** — shared envelope fragments: `BaseEvent`, `DataPayload`, `CloudEventType`, `ModelSpec`, `ErrorCode`. Every domain-specific payload extends `BaseEvent`.\n- **`common/statemachine/`** — workflow metadata descriptors: `WorkflowInfo`, `TransitionInfo`, `ProcessorInfo`.\n- **`entity/`** — entity create / update / delete / transition / audit requests and responses.\n- **`model/`** — model snapshot events and management requests.\n- **`processing/`** — compute-member protocol events: `EntityCriteriaCalculationRequest`/`Response`, `EntityProcessorCalculationRequest`/`Response`, `CalculationMemberJoinEvent`, `CalculationMemberGreetEvent`, `EventAckResponse`.\n- **`search/`** — search snapshot lifecycle events.\n\nEvery 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."
    },
    {
      "name": "ACTION: `cyoda help cloudevents json`",
      "body": "Emits the entire tree as a single JSON document. Shape:\n\n```json\n{\n  \"schema\": 1,\n  \"version\": \"<binary-version>\",\n  \"specVersion\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"baseId\": \"https://cyoda.com/cloud/event/\",\n  \"schemas\": {\n    \"common/BaseEvent.json\":                { \"$schema\": \"...\", \"$id\": \"...\", ... },\n    \"common/statemachine/WorkflowInfo.json\": { ... },\n    \"entity/EntityTransactionResponse.json\": { ... },\n    \"processing/EntityCriteriaCalculationRequest.json\": { ... },\n    ...\n  }\n}\n```\n\n- **`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.\n- **Values are complete JSON Schema documents**, structurally identical to the source file after normalizing whitespace and key ordering.\n- **`$ref` values stay relative** — they are not rewritten to absolute URLs. A consumer that writes the tree to disk gets working resolution for free.\n- **Keys are lexicographically sorted** — output is diff-stable across builds.\n- **`baseId`** and **`specVersion`** are constants exposed for consumers that want to construct absolute IDs or validate against a specific meta-schema."
    },
    {
      "name": "VERIFICATION",
      "body": "Count emitted schemas:\n\n```bash\ncyoda help cloudevents json | jq '.schemas | keys | length'\n```\n\nList every schema path:\n\n```bash\ncyoda help cloudevents json | jq -r '.schemas | keys[]'\n```\n\nMaterialize the tree to a directory:\n\n```bash\ncyoda help cloudevents json \\\n  | jq -r '.schemas | to_entries[] | \"\\(.key)\\t\\(.value | tojson)\"' \\\n  | while IFS=$'\\t' read -r path body; do\n      mkdir -p \"$(dirname \"schemas/$path\")\"\n      printf '%s\\n' \"$body\" > \"schemas/$path\"\n    done\n```"
    },
    {
      "name": "SEE ALSO",
      "body": "- grpc\n- workflows\n- errors.DISPATCH_TIMEOUT\n- errors.DISPATCH_FORWARD_FAILED"
    }
  ],
  "see_also": [
    "grpc",
    "workflows",
    "errors.DISPATCH_TIMEOUT",
    "errors.DISPATCH_FORWARD_FAILED"
  ],
  "stability": "stable",
  "actions": [
    "json"
  ]
}