Event Grid CloudEvents Schema

CloudEvents is a specification for describing event data in a common way, hosted by the Cloud Native Computing Foundation (CNCF). It aims to provide interoperability across services, platforms, and cloud providers. Before CloudEvents, every event producer defined its own event format. For example, Azure Blob Storage events had a different structure than Azure Event Hubs events, and AWS S3 events were different again. This forced event consumers to write custom logic for each producer. CloudEvents defines a set of required and optional attributes that every event should include, along with an extensibility model. The current stable version is 1.0.

Azure Event Grid natively supports both its own Event Grid schema and the CloudEvents schema. When you create an Event Grid topic or domain, you choose the input schema (the format events are published in) and the output schema (the format delivered to subscribers). The default is the Event Grid schema. CloudEvents schema is an option.

CloudEvents uses a set of context attributes to describe the event. The required attributes are:

Optional attributes include:

When an event is published to an Event Grid topic configured for CloudEvents input schema, the publisher must format the event as a CloudEvent. The event is then stored internally in the CloudEvents format. When delivered to a subscriber, the event can be delivered as-is (if the output schema is also CloudEvents) or transformed to the Event Grid schema (if output schema is Event Grid schema).

To create an Event Grid topic that accepts CloudEvents schema, use Azure CLI:

az eventgrid topic create \
  --name mytopic \
  --resource-group myrg \
  --location eastus \
  --input-schema cloudeventschemav1_0

To verify the input schema of an existing topic:

az eventgrid topic show \
  --name mytopic \
  --resource-group myrg \
  --query inputSchema

When publishing a CloudEvent, the HTTP request must include the Content-Type header set to application/cloudevents+json and the body must be a JSON object conforming to the CloudEvents spec. Example:

{
    "specversion": "1.0",
    "type": "Microsoft.Storage.BlobCreated",
    "source": "/subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/{account}",
    "id": "9aeb0fdf-c01e-0131-0922-9eb54906e209",
    "time": "2023-11-01T12:00:00Z",
    "subject": "blobServices/default/containers/mycontainer/blobs/myblob.txt",
    "datacontenttype": "application/json",
    "data": {
        "api": "PutBlob",
        "clientRequestId": "some-id",
        "requestId": "some-request-id",
        "eTag": "0x8D...",
        "contentType": "text/plain",
        "contentLength": 100,
        "blobType": "BlockBlob",
        "url": "https://myaccount.blob.core.windows.net/mycontainer/myblob.txt",
        "sequencer": "00000000000000000000000000000000000",
        "storageDiagnostics": {}
    }
}

| Attribute | Event Grid Schema | CloudEvents Schema | |-----------|-------------------|-------------------| | Event format | Proprietary JSON | Standardized JSON | | Required attributes | id, eventType, subject, eventTime, data, dataVersion, metadataVersion, topic | id, source, specversion, type | | Interoperability | Azure-only | Multi-cloud, multi-platform | | Extensibility | Limited | Extension contexts | | Batching | Supported natively | Supported via batch content type |

A large enterprise uses Azure for most services but also runs workloads on AWS and GCP. They want to aggregate events from all clouds into a central Azure Event Grid topic for processing. Using CloudEvents schema, each cloud's event producer (e.g., AWS S3, GCP Cloud Storage) publishes events in the standard CloudEvents format. This eliminates the need for custom adapters. The topic is configured with input schema CloudEventSchemaV1_0. The events are then delivered to an Azure Function that normalizes and routes them. In production, they set TTL to 60 minutes to reduce storage costs. They also enable dead-lettering to a Storage Queue for failed deliveries. A common issue is that some third-party libraries produce CloudEvents with incorrect specversion (e.g., 0.3), causing validation failures. They mitigate this by implementing a custom validation layer before publishing.

A manufacturing company uses Azure IoT Hub to collect telemetry from thousands of devices. They want to publish device lifecycle events (device created, device deleted) to Event Grid for downstream processing. By using CloudEvents schema, they ensure that the event format is consistent with other event sources in the enterprise. They create an Event Grid topic with CloudEvents input schema. IoT Hub's built-in Event Grid integration (for device lifecycle events) supports CloudEvents automatically. The events are then consumed by Logic Apps and third-party analytics tools. In production, they handle high throughput (10,000 events/second) by using Event Grid's batching capability: they set the output schema to CloudEvents and deliver batches of up to 10 events using application/cloudevents-batch+json. A common misconfiguration is forgetting to set the output schema to CloudEvents, causing the Logic Apps to receive Event Grid schema (which they don't parse correctly). They also set up alerts on PublishFailCount to detect schema validation errors.

A SaaS provider offers a service that runs on Azure and wants to allow customers to subscribe to custom events. They choose CloudEvents to ensure customers can use any cloud or on-premises listener. They create an Event Grid domain with CloudEvents input schema. Customers publish events using the CloudEvents format via the domain's topic endpoints. The domain routes events to customer-specific topics. The SaaS provider uses the source attribute to identify the customer's resource. In production, they enforce a maximum event size of 64 KB to keep latency low. They also use extension contexts like traceparent for distributed tracing. A common problem is that customers include non-standard attributes that are not in the CloudEvents specification; the SaaS provider must ignore them or reject the event. They provide a validation endpoint that customers can test against. The domain's output schema is set to CloudEvents to preserve the format for subscribers.