Event Grid Event Schemas

An event schema defines the structure and format of an event. It tells publishers how to format the data when publishing and tells subscribers what fields to expect when processing. Azure Event Grid supports three event schema formats: Event Grid Schema, CloudEvents 1.0 Schema, and Custom Input Schema.

Why Event Schemas Matter

Imagine two people writing letters with no agreed format. One person writes the address at the top, another writes it at the bottom. The post office cannot process either consistently. Event schemas solve this problem — all parties agree on the format before communication begins.

In Event Grid, the schema is set at the topic level. Publishers send events in that format. Subscribers receive events in that same format. Mismatched formats cause delivery failures or parsing errors.

Schema 1: Event Grid Schema

Event Grid Schema is the original, default schema format for Azure Event Grid. All built-in Azure services (Blob Storage, Resource Manager, IoT Hub, etc.) use this schema when publishing through System Topics.

Event Grid Schema – Required Fields

Event Grid Schema – Full Example

[
  {
    "id": "evtgrd-001",
    "topic": "/subscriptions/abc123/resourceGroups/rg-prod/providers/Microsoft.Storage/storageAccounts/filestorage",
    "subject": "/blobServices/default/containers/documents/blobs/invoice_2024.pdf",
    "eventType": "Microsoft.Storage.BlobCreated",
    "eventTime": "2024-06-15T09:30:00.000Z",
    "data": {
      "url": "https://filestorage.blob.core.windows.net/documents/invoice_2024.pdf",
      "contentType": "application/pdf",
      "contentLength": 102400,
      "blobType": "BlockBlob"
    },
    "dataVersion": "1.0",
    "metadataVersion": "1"
  }
]

Events are sent as a JSON array even when publishing a single event. Event Grid processes each element in the array independently.

Schema 2: CloudEvents 1.0 Schema

CloudEvents is an open specification created by the Cloud Native Computing Foundation (CNCF). It standardizes event formats across different cloud platforms and vendors. Azure Event Grid supports CloudEvents 1.0 as an alternative to the Event Grid Schema.

CloudEvents is the recommended schema for new projects because it ensures portability. An application built with CloudEvents can switch between Azure Event Grid, Google Cloud Pub/Sub, or any other CloudEvents-compatible system without changing the event format.

CloudEvents 1.0 – Required Fields

CloudEvents 1.0 Schema – Full Example

{
  "specversion": "1.0",
  "type": "com.mycompany.order.placed",
  "source": "/mycompany/ordersystem/orders",
  "subject": "orders/ORD-9821",
  "id": "cloud-evt-001",
  "time": "2024-06-15T09:30:00Z",
  "datacontenttype": "application/json",
  "data": {
    "orderId": "ORD-9821",
    "customer": "Bob",
    "totalAmount": 499.00,
    "items": ["Laptop", "Mouse"]
  }
}

CloudEvents uses a single JSON object, not an array, when sending a single event via HTTP. The HTTP Content-Type header must be application/cloudevents+json for a single event or application/cloudevents-batch+json for a batch.

Event Grid Schema vs CloudEvents – Comparison

Schema 3: Custom Input Schema

A Custom Input Schema allows a Custom Topic to accept events in a non-standard JSON format. This is useful when integrating a legacy application that already produces events in a specific proprietary format and cannot be changed.

With a Custom Input Schema, a field mapping is configured at the topic level. The mapping tells Event Grid which field in the incoming JSON maps to the required Event Grid schema fields (id, eventType, subject, etc.).

Custom Input Schema Example

Suppose a legacy system publishes events in this format:

{
  "record_id": "LGC-001",
  "action": "product.sold",
  "product_path": "/products/SKU-500",
  "occurred_at": "2024-06-15T09:30:00Z",
  "payload": { "sku": "SKU-500", "quantity": 3, "price": 99.99 }
}

The field mapping for Custom Input Schema would be:

Event Grid reads the incoming JSON, maps fields according to the configuration, and routes the event as if it were in the standard Event Grid Schema. The legacy application needs no changes.

Choosing a Schema

Decision Tree:

Is the event source a built-in Azure service (Blob Storage, IoT Hub, etc.)?
  --> YES: Use Event Grid Schema (default, no configuration needed)

Is this a new custom application?
  --> YES: Use CloudEvents 1.0 (better portability and open standard)

Is the event source a legacy system with a fixed format?
  --> YES: Use Custom Input Schema with field mapping

Schema Selection at Topic Creation

The schema is selected when creating a Custom Topic. It cannot be changed after the topic is created. System Topics always use Event Grid Schema because Azure services define the format.

1. During Custom Topic creation in the Azure Portal, expand the Advanced tab
2. Choose Event Schema: Event Grid Schema, CloudEvents 1.0, or Custom Input Schema
3. For Custom Input Schema, define field mappings in the JSON configuration

Summary

Event Grid Schema is the native Azure format used by all built-in Azure services. CloudEvents 1.0 is the recommended format for new projects due to its portability and open-standard compliance. Custom Input Schema supports legacy systems without requiring changes to existing event publishers. Selecting the right schema at topic creation ensures consistent event processing throughout the entire pipeline.