# cloudevents/spec architecture

> Architecture diagram of the GitHub repository cloudevents/spec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudevents/spec
- Repository: https://github.com/cloudevents/spec

## Overview

This repository is primarily a standards-documentation project, not an event-processing service. Its main user workflow is to consult the CloudEvents core specification to describe interoperable events, then use optional format, protocol-binding, webhook, or adapter specifications for particular environments. CESQL and Subscriptions are separate specifications. The README establishes these capability areas, but sampled source does not show a runtime that wires them together, so the graph shows documented relationships only; it does not imply execution order.

Main entry points: [`cloudevents/spec.md`](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md) (CloudEvents core), [`cloudevents/adapters/README.md`](https://github.com/cloudevents/spec/blob/main/cloudevents/adapters/README.md) (CloudEvents adapters), [`cloudevents/primer.md`](https://github.com/cloudevents/spec/blob/main/cloudevents/primer.md) (Primer), [`cloudevents/formats/json-format.md`](https://github.com/cloudevents/spec/blob/main/cloudevents/formats/json-format.md) (JSON format)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core Event Model"]
  node_core_spec["CloudEvents core<br/>[spec.md]"]
  node_primer["Primer<br/>[primer.md]"]
end

subgraph group_transport["Formats and Transport"]
  node_json["JSON format<br/>[json-format.md]"]
  node_avro["Avro format<br/>[avro-format.md]"]
  node_protobuf["Protobuf format<br/>[protobuf-format.md]"]
  node_protobuf_schema["Protobuf schema<br/>[cloudevents.proto]"]
  node_http["HTTP binding"]
  node_amqp["AMQP binding"]
  node_kafka["Kafka binding"]
  node_mqtt["MQTT binding"]
  node_nats["NATS binding"]
  node_websockets["WebSockets binding"]
  node_webhook["Web hook<br/>[http-webhook.md]"]
end

subgraph group_extensions["Extensions and Adapters"]
  node_extensions["Extensions<br/>[README.md]"]
  node_adapters["CloudEvents adapters<br/>[README.md]"]
end

subgraph group_query["Related Specifications"]
  node_cesql["CESQL<br/>[spec.md]"]
  node_cesql_grammar["CESQL grammar<br/>[CESQLParser.g4]"]
  node_subscriptions["Subscriptions<br/>[spec.md]"]
end

subgraph group_operations["Repository Tooling"]
  node_verifier["Document verifier<br/>[verify.py]"]
end

node_implementers(("Event implementers"))

node_implementers -->|"consults"| node_core_spec
node_core_spec -->|"introduces"| node_primer
node_implementers -->|"adapts producers"| node_adapters
node_adapters -->|"produces events"| node_core_spec
node_implementers -->|"uses format"| node_json
node_implementers -->|"uses format"| node_avro
node_implementers -->|"uses format"| node_protobuf
node_implementers -->|"uses binding"| node_http
node_implementers -->|"uses binding"| node_amqp
node_implementers -->|"uses binding"| node_kafka
node_implementers -->|"uses binding"| node_mqtt
node_implementers -->|"uses binding"| node_nats
node_implementers -->|"uses draft"| node_websockets
node_implementers -->|"uses webhook"| node_webhook
node_implementers -->|"consults extensions"| node_extensions
node_implementers -->|"consults specification"| node_cesql
node_implementers -->|"consults specification"| node_subscriptions

click node_core_spec "https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md"
click node_primer "https://github.com/cloudevents/spec/blob/main/cloudevents/primer.md"
click node_json "https://github.com/cloudevents/spec/blob/main/cloudevents/formats/json-format.md"
click node_avro "https://github.com/cloudevents/spec/blob/main/cloudevents/formats/avro-format.md"
click node_protobuf "https://github.com/cloudevents/spec/blob/main/cloudevents/formats/protobuf-format.md"
click node_protobuf_schema "https://github.com/cloudevents/spec/blob/main/cloudevents/formats/cloudevents.proto"
click node_http "https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/http-protocol-binding.md"
click node_amqp "https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/amqp-protocol-binding.md"
click node_kafka "https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/kafka-protocol-binding.md"
click node_mqtt "https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/mqtt-protocol-binding.md"
click node_nats "https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/nats-protocol-binding.md"
click node_websockets "https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/websockets-protocol-binding.md"
click node_webhook "https://github.com/cloudevents/spec/blob/main/cloudevents/http-webhook.md"
click node_extensions "https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/README.md"
click node_adapters "https://github.com/cloudevents/spec/blob/main/cloudevents/adapters/README.md"
click node_cesql "https://github.com/cloudevents/spec/blob/main/cesql/spec.md"
click node_cesql_grammar "https://github.com/cloudevents/spec/blob/main/cesql/CESQLParser.g4"
click node_subscriptions "https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md"
click node_verifier "https://github.com/cloudevents/spec/blob/main/tools/verify.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_core_spec,node_primer toneBlue
class node_json,node_avro,node_protobuf,node_protobuf_schema,node_http,node_amqp,node_kafka,node_mqtt,node_nats,node_websockets,node_webhook toneAmber
class node_extensions,node_adapters toneMint
class node_cesql,node_cesql_grammar,node_subscriptions toneRose
class node_verifier,node_implementers toneIndigo
```

## Components

### Core Event Model

- [CloudEvents core](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md): `cloudevents/spec.md`
- [Primer](https://github.com/cloudevents/spec/blob/main/cloudevents/primer.md): `cloudevents/primer.md`

### Formats and Transport

- [JSON format](https://github.com/cloudevents/spec/blob/main/cloudevents/formats/json-format.md): `cloudevents/formats/json-format.md`
- [Avro format](https://github.com/cloudevents/spec/blob/main/cloudevents/formats/avro-format.md): `cloudevents/formats/avro-format.md`
- [Protobuf format](https://github.com/cloudevents/spec/blob/main/cloudevents/formats/protobuf-format.md): `cloudevents/formats/protobuf-format.md`
- [Protobuf schema](https://github.com/cloudevents/spec/blob/main/cloudevents/formats/cloudevents.proto): `cloudevents/formats/cloudevents.proto`
- [HTTP binding](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/http-protocol-binding.md): `cloudevents/bindings/http-protocol-binding.md`
- [AMQP binding](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/amqp-protocol-binding.md): `cloudevents/bindings/amqp-protocol-binding.md`
- [Kafka binding](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/kafka-protocol-binding.md): `cloudevents/bindings/kafka-protocol-binding.md`
- [MQTT binding](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/mqtt-protocol-binding.md): `cloudevents/bindings/mqtt-protocol-binding.md`
- [NATS binding](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/nats-protocol-binding.md): `cloudevents/bindings/nats-protocol-binding.md`
- [WebSockets binding](https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/websockets-protocol-binding.md): `cloudevents/bindings/websockets-protocol-binding.md`
- [Web hook](https://github.com/cloudevents/spec/blob/main/cloudevents/http-webhook.md): `cloudevents/http-webhook.md`

### Extensions and Adapters

- [Extensions](https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/README.md): `cloudevents/extensions/README.md`
- [CloudEvents adapters](https://github.com/cloudevents/spec/blob/main/cloudevents/adapters/README.md): `cloudevents/adapters/README.md`

### Related Specifications

- [CESQL](https://github.com/cloudevents/spec/blob/main/cesql/spec.md): `cesql/spec.md`
- [CESQL grammar](https://github.com/cloudevents/spec/blob/main/cesql/CESQLParser.g4): `cesql/CESQLParser.g4`
- [Subscriptions](https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md): `subscriptions/spec.md`

### Repository Tooling

- [Document verifier](https://github.com/cloudevents/spec/blob/main/tools/verify.py): `tools/verify.py`

### Other components

- **Event implementers**

## Connections

- Event implementers → CloudEvents core: consults (evidence: `README.md`)
- CloudEvents core → Primer: introduces (evidence: `README.md`)
- Event implementers → CloudEvents adapters: adapts producers (evidence: `README.md`)
- CloudEvents adapters → CloudEvents core: produces events (evidence: `README.md`)
- Event implementers → JSON format: uses format (evidence: `README.md`)
- Event implementers → Avro format: uses format (evidence: `README.md`)
- Event implementers → Protobuf format: uses format (evidence: `README.md`)
- Event implementers → HTTP binding: uses binding (evidence: `README.md`)
- Event implementers → AMQP binding: uses binding (evidence: `README.md`)
- Event implementers → Kafka binding: uses binding (evidence: `README.md`)
- Event implementers → MQTT binding: uses binding (evidence: `README.md`)
- Event implementers → NATS binding: uses binding (evidence: `README.md`)
- Event implementers → WebSockets binding: uses draft (evidence: `README.md`)
- Event implementers → Web hook: uses webhook (evidence: `README.md`)
- Event implementers → Extensions: consults extensions (evidence: `README.md`)
- Event implementers → CESQL: consults specification (evidence: `README.md`)
- Event implementers → Subscriptions: consults specification (evidence: `README.md`)
