# CloudEvents spec: what the CNCF event envelope actually standardises

> The cloudevents/spec repository is the normative document set behind CloudEvents, not an SDK. This review covers what the v1.0.2 core spec fixes, how the JSON and HTTP bindings fit together, and where the spec stops short of solving your problem.

**cloudevents/spec** — CloudEvents Specification

- Repository: https://github.com/cloudevents/spec
- Website: https://cloudevents.io
- Stars: 5,910 · Forks: 613
- Language: Python
- License: Apache-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/cloudevents-spec

## The problem cloudevents/spec was written to fix

Every event producer invents its own envelope. One service sends `{"type": "order.created", "ts": 1699999999, "payload": {...}}`, another sends `{"eventName": "OrderCreated", "timestamp": "...", "data": {...}}`, and a third just publishes the raw business object with no metadata at all. The README states the consequence plainly: the lack of a common way of describing events means developers must constantly re-learn how to consume events, and it limits what libraries, routers and tracing systems can do with the data.

CloudEvents is a specification for describing event data in common formats, so that the envelope is portable across services, platforms and systems. The target reader is not an application developer looking for a helper library. It is the person who has to decide what goes on the wire between an event producer and an event consumer that were built by different teams, possibly on different clouds, possibly over different protocols. That includes platform engineers wiring a broker to a function runtime, SDK authors who need a normative reference to implement against, and architects writing an internal event standard who would rather cite an existing one.

The repository is the specification itself. The top level holds `cloudevents/`, `cesql/`, `subscriptions/`, `docs/` and `tools/`. There is no server, no client and no CLI in the tree.

## How the core spec, bindings and formats divide the work

The design separates three concerns that are usually tangled together. The core specification in `cloudevents/spec.md` defines the abstract event: a set of attributes with defined names, types and required-ness, plus an opaque data payload. It says nothing about how those attributes are encoded or transported.

Event formats handle encoding. The JSON Event Format and the Protobuf Event Format are the two released formats at v1.0.2; AVRO is also released, and an AVRO Compact Event Format exists only as a working draft. Protocol bindings handle transport. HTTP, Kafka, MQTT, NATS and AMQP each have a v1.0.2 binding, and the WebSockets binding is listed with no release at all, only a working draft. That means the same event can travel over Kafka as a binary-encoded message and be re-emitted over HTTP as a structured JSON body without the consumer's understanding of the event changing.

The README also points at material outside the core: a Primer for orientation, `cloudevents/SDK.md` for SDK requirements, `cloudevents/adapters/README.md` for adapters, and `cloudevents/extensions/README.md` for documented extensions. The Registry and Pagination specifications have moved out to the xRegistry/spec repository, so anyone arriving with an older link should follow that pointer rather than look for them here.

## Reading the spec and picking a binding: a first pass

There is nothing to install. The repository is documentation, schemas and tooling, and the README directs readers to the tagged releases rather than to a package. The most recent release of the CloudEvents specifications is reachable through the `ce@stable` tag, and the CESQL specification through `cesql@stable`. Cloning the repository gives you the working drafts alongside the released text, which is useful but easy to confuse.

```bash
git clone https://github.com/cloudevents/spec.git
cd spec
git checkout ce@stable
```

After the checkout, `cloudevents/spec.md` is the core specification you should read first, and `cloudevents/bindings/` contains the per-protocol documents. If you only read one binding, read the one for the protocol you actually run; the others will mislead you about framing details.

The repository also ships a `tools/` directory. The README does not document what each tool does, so treat that directory as something to inspect rather than something to invoke from a tutorial. The released JSON Schema for the JSON Event Format is the artefact most people want when they are writing validation; it lives under `cloudevents/formats/` in the tagged tree.

For CESQL, the separate tag matters. It is versioned independently of the core spec, and the released CESQL specification is v1.0.0, which is a different version line from the ce@ tags. Mixing the two tags up is a common source of confusion when people quote version numbers at each other.

## Where the specification deliberately stops

The spec defines an envelope, not a system. It does not tell you how to guarantee delivery, how to order events, how to deduplicate them, or what to do when a consumer is down. Those are properties of the transport and the broker, and the bindings only describe how the envelope maps onto the transport's own framing. If your actual problem is exactly-once processing or replay, CloudEvents is orthogonal to it.

Coverage is uneven across bindings, and the README's table makes that visible. HTTP, Kafka, MQTT, NATS and AMQP have v1.0.2 releases. WebSockets has no release, only a working draft. XML has no release, only a working draft, and there is no XML Event Format at v1.0.2 at all. If your integration depends on XML payloads or a WebSocket transport, the normative text you need is a draft that can change, and you should plan for that rather than assume the guarantee the released bindings carry.

The release cadence is also worth stating as a fact rather than an impression. The core specification releases are ce@v1.0 from 2019-10-24, ce@v1.0.1 from 2020-12-12 and ce@v1.0.2 from 2022-02-06. The repository's last push was on 2026-09-03, so work continues, but it is work on drafts, tooling and auxiliary specifications rather than a stream of new core releases. Anyone expecting frequent breaking revisions to the envelope should recalibrate: the stability is the point, and it also means a mistake in your attribute mapping will be with you for a long time.

Finally, the specification cannot enforce itself. Nothing in this repository validates the events your services emit. If you adopt CloudEvents and do not add schema validation on the producer side, you will get events that are CloudEvents-shaped in the happy path and malformed in the incident.

## CloudEvents and AsyncAPI are not competing answers

The comparison people reach for is CloudEvents versus AsyncAPI, and the honest answer is that they operate at different layers. CloudEvents standardises the event: what attributes an individual event carries and how those attributes are encoded and transported. AsyncAPI describes an API: which channels exist, what messages flow over them, and how a client discovers and subscribes to them.

A concrete difference follows from that. CloudEvents has nothing to say about discovery or about the shape of a channel; a CloudEvents event can travel over a Kafka topic whose contract is documented in AsyncAPI, and the two documents do not conflict. If you need a machine-readable description of your event-driven interface so that code generators can produce clients, AsyncAPI is the tool for that job and CloudEvents will not substitute for it. If you need a stable envelope so that a consumer can route on event type and source without parsing the payload, CloudEvents is the tool and AsyncAPI will not substitute for it. Choosing between them is usually a sign that the requirement has not been separated properly.

The same reasoning applies to proprietary event formats from cloud vendors. The repository's `cloudevents/proprietary-specs.md` exists to track those relationships, which is a more useful starting point than a blog comparison when you are trying to work out how a vendor's format maps onto the standard attributes.

## Maintenance cost, licence and what you actually take on

The repository is not archived and the last push was on 2026-09-03. The core specification has been stable at the 1.0 line since 2019, with two patch releases since, so the upgrade cost for the envelope itself is close to zero: you are reading a document, not tracking a dependency. The cost sits elsewhere.

Every producer and consumer you touch has to agree on the attribute mapping. `source`, `type` and `id` have to be populated consistently or routing breaks, and that agreement is social and organisational, not technical. When you upgrade, the thing you will actually be upgrading is the SDK or the broker's CloudEvents support, not this repository, and those are separate projects with separate release schedules. The README lists `cloudevents/SDK.md` as the requirements document for SDKs, which is the right place to check whether a given implementation claims conformance.

On licensing: the repository carries Apache-2.0. The specification text is meant to be implemented, and implementations in other languages are separate works under their own licences. Nothing in the README or the repository layout suggests a grant beyond Apache-2.0, and this is not legal advice; if you are building a product around conformance claims, read the LICENSE file in the tree and take your own counsel on trademark and conformance language.

The maintenance burden that does land on you is validation. Since the specification is prose plus schema, the only thing standing between a typo in an attribute name and a broken consumer is whatever validation you put in your own pipeline.

## Conclusion

Adopt cloudevents/spec as a reference when you are choosing an event envelope for a system that crosses vendor or protocol boundaries, and read the v1.0.2 core spec plus the binding for the protocol you actually run before writing any producer code. Do not adopt it expecting a library, a broker or a validation service: this repository is prose and JSON Schema, and the SDKs live elsewhere. Teams that only move events between two services they own, on one protocol, with one team writing both ends, will pay the attribute-mapping cost for interoperability they never use. Before committing, verify three things in the repository itself: that the binding you need has a v1.0.2 release rather than only a working draft (WebSockets and XML do not), that the CESQL tag you plan to depend on exists, and whether the extensions you want are documented in cloudevents/extensions/README.md or only proposed.

## FAQ

### What is the purpose of CloudEvents?

CloudEvents is a specification for describing event data in common formats so that events are interoperable across services, platforms and systems. The README frames the problem as producers describing events differently, which forces developers to re-learn how to consume each one and limits what SDKs, routers and tracing systems can do.

### Is cloudevents/spec a library I can install?

No. The repository holds the specification documents, schemas and a tools directory; the top level is cloudevents/, cesql/, subscriptions/, docs/ and tools/. The README points to cloudevents/SDK.md for SDK requirements, and implementations live in separate projects.

### Which CloudEvents version should I read?

The README directs readers to the ce@stable tag for the most recent release of the CloudEvents specifications, which is ce@v1.0.2 from 2022-02-06. The working drafts in the main branch are linked alongside each released document and are marked WIP.

### Does CloudEvents have a Kafka binding?

Yes. The Kafka Protocol Binding is listed at v1.0.2 in the README's specification table, alongside HTTP, MQTT, NATS and AMQP. Each binding has its own document under cloudevents/bindings/ in the released tree.

## Sources

- [cloudevents/spec on GitHub](https://github.com/cloudevents/spec)
- [License: Apache-2.0](https://github.com/cloudevents/spec/blob/main/LICENSE)
- [Project website](https://cloudevents.io)
- [README](https://github.com/cloudevents/spec/blob/main/README.md)
- [Releases](https://github.com/cloudevents/spec/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cloudevents-spec