CloudEvents Specification

CloudEvents SQL Expression Language (CESQL) is a SQL-like expression language designed to define predicates for filtering CloudEvent instances. It is a total pure functional programming language, ensuring that expression evaluation always terminates and does not mutate the input CloudEvent instance.

Key Characteristics:

• Purpose: Computing values and matching CloudEvent attributes against complex expressions (similar to SQL WHERE clauses).
• Output Types: The primary output of an expression is always a boolean, an integer, or a string. Evaluation also produces a set of errors (which may be empty).
• Limitations: CESQL does not support handling the data field of CloudEvent instances due to its polymorphic nature.
• Environment Agnostic: It can be implemented in producers, intermediaries, or sources using any technology stack.

A compliant CloudEvents SDK must facilitate the transition between a high-level canonical Event object and transport-specific encoded messages. The expected data flow is:

1. Encoding: Event $\rightarrow$ Message $\rightarrow$ Transport (e.g., sending an event via HTTP).
2. Decoding: Transport $\rightarrow$ Message $\rightarrow$ Event (e.g., receiving an event via HTTP).

Key tasks an SDK must support:

• Compose an Event: Create new events from raw data or mutate existing CloudEvents.
• Encode an Event: Convert an Event into a transport-specific format (e.g., structured or binary mode for HTTP).
• Decode an Event: Convert a transport-specific message or request/response back into a canonical Event object.
• Data Unpacking: Provide methods to unpack event data from formats like base64 or json into the language's native format.

The Correlation extension provides two attributes to track relationships in distributed systems:

1. correlationid: Groups all events belonging to the same logical flow or business transaction. Use this to answer: "Which events are part of the same business transaction?"
2. causationid: Tracks the direct parent-child relationship. This SHOULD be the id of the event that directly triggered the current event. Use this to answer: "Which specific event directly triggered this event?"

Both attributes are OPTIONAL but, if present, MUST be non-empty strings.

CloudEvents Extension Attributes are additional metadata attributes used when transforming generic events into CloudEvents. While the core CloudEvents specification defines a minimal set of mandatory attributes, extensions provide additional metadata to improve interoperability for specific use cases.

Key characteristics of extensions:

• Optional Support: Implementations are not required to support any specific extension.
• Experimental Nature: Extensions may have a lower level of maturity than core attributes and can be changed or removed without the same rigorous process required for the core specification.
• Compliance: Even though they are not part of the core specification, extension attributes MUST follow the same serialization rules defined by the format and protocol binding specifications (e.g., JSON, binary).

The CloudEvents community maintains official SDKs for several programming languages to speed up integration. These SDKs are designed to work with the CloudEvents specification and provide idiomatic implementations for their respective languages.

Supported SDKs include:

• C#/.NET
• Go
• Java
• JavaScript
• Kotlin
• PHP
• PowerShell
• Python
• Ruby
• Rust

The recordedtime extension allows you to represent bitemporal data in CloudEvents by providing two distinct timestamps for every event:

1. Occurrence time: The timestamp of when the event actually happened (represented by the standard time attribute).
2. Recorded time: The timestamp of when the CloudEvent was created by a producer (represented by the recordedtime extension attribute).

This distinction is useful for analytics, data science, and determining latency between producers and consumers.

The Severity Extension provides a standardized way to describe the 'severity' or 'log-level' of a CloudEvent. This extension is designed to interoperate with OpenTelemetry Severity Fields.

When using this extension, you can include two attributes: severitytext and severitynumber. If both are used, the severitytext values SHOULD have a one-to-one and onto relationship with the severitynumber values produced by the same source.

CloudEvents logos are hosted in the CNCF artwork repository. The assets are provided in multiple formats, layouts, and color versions to suit different design requirements.

Available Formats:

• PNG
• SVG
• AI

Available Layouts:

• Horizontal (landscape format)
• Stacked (square-like layout)
• Icon (square icon only, excludes the project name)

Available Color Versions:

• Color
• Black
• White

For guidance on using CloudEvents terms in text, refer to the CNCF Style Guide.

The Auth Context extension allows you to embed information about the principal (the entity/user) that triggered a CloudEvent. This enables consumers to perform user-dependent actions without needing to parse the data or source fields for user IDs.

Warning: This extension is purely informational and is not intended to secure CloudEvents.

When implementing adapters for specific services, follow the proposed algorithms to ensure interoperability. The following service-specific adapter documentation is available:

• AWS S3: Mapping AWS S3 events to CloudEvents.
• AWS SNS: Mapping AWS SNS events to CloudEvents.
• CouchDB: Mapping CouchDB events to CloudEvents.
• GitHub: Mapping GitHub webhooks/events to CloudEvents.
• GitLab: Mapping GitLab webhooks/events to CloudEvents.