# Amazon EventBridge schemas
A schema defines the structure of [events](eb-events.md) that are sent to EventBridge. EventBridge provides schemas for all events that are generated by AWS services. You can also [create or upload custom schemas](eb-schema-create.md) or [infer schemas](eb-schemas-infer.md) directly from events on an [event bus](eb-event-bus.md). Once you have a schema for an event, you can download code bindings for popular programming languages and speed up development. You can work with code bindings for schemas and manage schemas from the EventBridge console, by using the API, or directly in your IDE by using the AWS toolkits. To build serverless apps that use events, use AWS Serverless Application Model.
**Note**
When using the [input transformer](eb-transform-target-input.md) feature, the original event is inferred by schema discovery, not the transformed event that's sent to the target.
EventBridge supports both OpenAPI 3 and JSONSchema Draft4 formats.
For [AWS Toolkit for JetBrains](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/eventbridge-schemas.html) and [AWS Toolkit for VS Code](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/working-with-aws.html), you can browse or search for schemas and download code bindings for schemas directly in your IDE.
The following video gives an overview of schemas and schema registries:
## Schema registry API property value masking
Some property values of events that are used to create a schema registry may contain sensitive customer information. To protect the customer's information, the values will be masked with asterisks (\$1). Because we're masking these values, EventBridge recommends not building applications that explicitly depend on the following properties or their values:
+ **[CreateSchema](https://docs.aws.amazon.com/eventbridge/latest/schema-reference/v1-registries-name-registryname-schemas-name-schemaname.html#CreateSchema)** – The `Content` property of the `requestParameters` body
+ **[GetDiscoveredSchema](https://docs.aws.amazon.com/eventbridge/latest/schema-reference/v1-discover.html#GetDiscoveredSchema)** – The `Events` property of the `requestParameters` body and the `Content` property of the `responseElements` body
+ **[SearchSchemas](https://docs.aws.amazon.com/eventbridge/latest/schema-reference/v1-registries-name-registryname-schemas-search.html#SearchSchemas)** – The `keywords` property of the `requestParameters`
+ **[UpdateSchema](https://docs.aws.amazon.com/eventbridge/latest/schema-reference/v1-registries-name-registryname-schemas-name-schemaname.html#UpdateSchema)** – The `Content` property of the `requestParameters`
# Finding an AWS service event schema in Amazon EventBridge
EventBridge includes [schemas](eb-schema.md) for all AWS services that generate events. You can find these schemas in the EventBridge console, or you can find them by using the API action [https://docs.aws.amazon.com/eventbridge/latest/schema-reference/v1-registries-name-registryname-schemas-search.html](https://docs.aws.amazon.com/eventbridge/latest/schema-reference/v1-registries-name-registryname-schemas-search.html).
**To find schemas for AWS services in the EventBridge console**
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. In the navigation pane, choose **Schemas**.
1. On the **Schemas** page, select **AWS event schema registry**.
The first page of available schemas is displayed.
1. To find a schema, in **Search AWS event schemas**, enter a search term**.**
A search returns matches for both the name and contents of the available schemas, and then displays which versions of the schema contain matches.
1. Open an event schema by selecting the name of the schema.
# Schema registries in Amazon EventBridge
Schema registries are containers for schemas. Schema registries collect and organize schemas so that your schemas are in logical groups. The default schema registries are:
+ **All schemas** – All the schemas from the AWS event, discovered, and custom schema registries.
+ **AWS event schema registry** – The built-in schemas.
+ **Discovered schema registry** – The schemas discovered by Schema discovery.
You can create custom registries to organize the schemas you create or upload.
**Note**
Exporting custom schemas from the EventBridge Schema Registry is not supported.
**To create a custom registry**
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. In the navigation pane, choose **Schemas** and then choose **Create registry**.
1. On the **Registry details** page, enter a **Name**.
1. (Optional) Enter a description for your new registry.
1. Choose **Create**.
To [create a custom schema](eb-schema-create.md) in your new registry, select **Create custom schema**. To add a schema to your registry, select that registry when you're creating a new schema.
To create a registry by using the API, use [https://docs.aws.amazon.com/eventbridge/latest/schema-reference/v1-registries-name-registryname.html#v1-registries-name-registryname-http-methods](https://docs.aws.amazon.com/eventbridge/latest/schema-reference/v1-registries-name-registryname.html#v1-registries-name-registryname-http-methods). For more information, see [Amazon EventBridge Schema Registry API Reference](https://docs.aws.amazon.com/eventbridge/latest/schema-reference/index.html).
For information about using the EventBridge schema registry through AWS CloudFormation, see [EventSchemas Resource Type Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/AWS_EventSchemas.html) in CloudFormation.
# Creating an event schema in Amazon EventBridge
You create schemas by using JSON files with either the [OpenAPI Specification](https://swagger.io/specification/) or the [JSONSchema Draft4 specification](https://json-schema.org/specification-links.html#draft-4). You can create or upload your own schemas in EventBridge by using a template or generating a schema based on the JSON of an [event](eb-events.md). You can also infer the schema from events on an [event bus](eb-event-bus.md). To create a schema by using the EventBridge Schema Registry API, use the [https://docs.aws.amazon.com/eventbridge/latest/schema-reference/v1-registries-name-registryname-schemas-name-schemaname.html#v1-registries-nam](https://docs.aws.amazon.com/eventbridge/latest/schema-reference/v1-registries-name-registryname-schemas-name-schemaname.html#v1-registries-nam) API action.
When you choose between OpenAPI 3 and JSONSchema Draft4 formats, consider the following differences:
+ JSONSchema format supports additional keywords that aren't supported in OpenAPI, such as `$schema, additionalItems`.
+ There are minor differences in how keywords are handled, such as `type` and `format`.
+ OpenAPI doesn't support JSONSchema Hyper-Schema hyperlinks in JSON documents.
+ Tools for OpenAPI tend to focus on build-time, whereas tools for JSONSchema tend to focus on run-time operations, such as client tools for schema validation.
We recommend using JSONSchema format to implement client-side validation so that events sent to EventBridge conform to the schema. You can use JSONSchema to define a contract for valid JSON documents, and then use a [JSON schema validator](https://json-schema.org/tools) before sending the associated events.
After you have a new schema, you can download [code bindings](eb-schema-code-bindings.md) to help create applications for events with that schema.
# Creating a schema by using a template in Amazon EventBridge
You can create a schema from a template file you download, or by editing a template directly in the EventBridge console.
## Create a schema from a template file
To get the template, you download it from the console. You can edit the template so that the schema matches your events. Then upload your new template through the console.
**To download the schema template**
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. In the navigation pane, choose **Schema registry**.
1. In the **Getting started** section under **Schema template**, choose **Download**.
Alternatively, you can copy the JSON template from the following code example.
```
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Event"
},
"paths": {},
"components": {
"schemas": {
"Event": {
"type": "object",
"properties": {
"ordinal": {
"type": "number",
"format": "int64"
},
"name": {
"type": "string"
},
"price": {
"type": "number",
"format": "double"
},
"address": {
"type": "string"
},
"comments": {
"type": "array",
"items": {
"type": "string"
}
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
```
**To upload a schema template**
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. In the navigation pane, choose **Schemas** and then choose **Create schema**.
1. (Optional) Select or create a schema registry.
1. Under **Schema details**, enter a name for your schema.
1. (Optional) Enter a description for your schema.
1. For **Schema type**, choose either **OpenAPI 3.0** or **JSON Schema Draft 4**.
1. On the **Create** tab, in the text box, either drag your schema file to the text box, or paste the schema source.
1. Select **Create**.
## Edit a schema template directly in the console
You can create a schema directly in the EventBridge console.
**To edit a schema in the console**
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. In the navigation pane, choose **Schemas** and then choose **Create schema**.
1. (Optional) Select or create a schema registry.
1. Under **Schema details**, enter a name for your schema.
1. For **Schema type**, choose either **OpenAPI 3.0** or **JSON Schema Draft 4**.
1. (Optional) Enter a description for the schema to create.
1. On the **Create** tab, choose **Load template**.
1. In the text box, edit the template so that the schema matches your [events](eb-events.md).
1. Select **Create**.
# Creating a schema from event JSON in Amazon EventBridge
If you have the JSON of an event, you can automatically create a schema for that type of event.
**To create a schema based on the JSON of an event**
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. In the navigation pane, choose **Schemas** and then choose **Create schema**.
1. (Optional) Select or create a schema registry.
1. Under **Schema details** enter a name for your schema.
1. (Optional) Enter a description for the schema you created.
1. For **Schema type**, choose **OpenAPI 3.0**.
You can't use JSONSchema when you create a schema from the JSON of an event.
1. Select **Discover from JSON**
1. In the text box under **JSON**, paste or drag the JSON source of an event.
For example, you could paste in the source from this AWS Step Functions event for a failed execution.
```
{
"version": "0",
"id": "315c1398-40ff-a850-213b-158f73e60175",
"detail-type": "Step Functions Execution Status Change",
"source": "aws.states",
"account": "012345678912",
"time": "2019-02-26T19:42:21Z",
"region": "us-east-1",
"resources": [
"arn:aws:states:us-east-1:012345678912:execution:state-machine-name:execution-name"
],
"detail": {
"executionArn": "arn:aws:states:us-east-1:012345678912:execution:state-machine-name:execution-name",
"stateMachineArn": "arn:aws:states:us-east-1:012345678912:stateMachine:state-machine",
"name": "execution-name",
"status": "FAILED",
"startDate": 1551225146847,
"stopDate": 1551225151881,
"input": "{}",
"output": null
}
}
```
1. Choose **Discover schema**.
1. EventBridge generates an OpenAPI schema for the event. For example, the following schema is generated for the preceding Step Functions event.
```
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "StepFunctionsExecutionStatusChange"
},
"paths": {},
"components": {
"schemas": {
"AWSEvent": {
"type": "object",
"required": ["detail-type", "resources", "detail", "id", "source", "time", "region", "version", "account"],
"x-amazon-events-detail-type": "Step Functions Execution Status Change",
"x-amazon-events-source": "aws.states",
"properties": {
"detail": {
"$ref": "#/components/schemas/StepFunctionsExecutionStatusChange"
},
"account": {
"type": "string"
},
"detail-type": {
"type": "string"
},
"id": {
"type": "string"
},
"region": {
"type": "string"
},
"resources": {
"type": "array",
"items": {
"type": "string"
}
},
"source": {
"type": "string"
},
"time": {
"type": "string",
"format": "date-time"
},
"version": {
"type": "string"
}
}
},
"StepFunctionsExecutionStatusChange": {
"type": "object",
"required": ["output", "input", "executionArn", "name", "stateMachineArn", "startDate", "stopDate", "status"],
"properties": {
"executionArn": {
"type": "string"
},
"input": {
"type": "string"
},
"name": {
"type": "string"
},
"output": {},
"startDate": {
"type": "integer",
"format": "int64"
},
"stateMachineArn": {
"type": "string"
},
"status": {
"type": "string"
},
"stopDate": {
"type": "integer",
"format": "int64"
}
}
}
}
}
}
```
1. After the schema has been generated, choose **Create**.
# Inferring schemas from event bus events in EventBridge
Amazon EventBridge can infer schemas by discovering events. To infer schemas, you turn on event discovery on an event bus and every unique schema is added to the schema registry, including those for cross-account events. Schemas discovered by EventBridge appear in **Discovered schemas registry** on the **Schemas** page.
If the contents of events on the event bus change, EventBridge creates new versions of the related EventBridge schema.
## Considerations when starting schema discovery on an event bus
Take into account the following considerations before enabling schema discover on an event bus:
+ Enabling event discovery on an event bus can incur a cost. The first five million processed events in each month are free.
+ EventBridge infers schemas from cross-account events by default but you can disable it by updating the `cross-account` property. For more information, see [Discoverers](https://docs.aws.amazon.com/eventbridge/latest/schema-reference/v1-discoverers.html) in the EventBridge Schema Registry API Reference.
**Note**
Schema discovery is not supported for event buses encrypted using a customer managed key. To enable schema discovery on an event bus, choose to use an AWS owned key. For more information, see [KMS key options](eb-encryption-at-rest-key-options.md).
**To start or stop schema discovery on an event bus (console)**
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. In the navigation pane, choose **Event buses**.
1. Select the event bus on which you want to start or stop schema discovery.
1. Do one of the following:
+ To start schema discovery, choose **Start discovery**.
+ To stop schema discovery, choose **Delete discovery**.
**To start or stop schema discovery on an event bus (AWS CLI)**
+ To start schema discovery, use [create-discoverer](https://docs.aws.amazon.com/cli/latest/reference/schemas/create-discoverer.html).
To stop schema discovery, use [delete-discoverer](https://docs.aws.amazon.com/cli/latest/reference/schemas/delete-discoverer.html).
**Note**
Schema discovery does not support events larger than 1000 KiB. These events will not be discovered and no error notification will be generated. To track schemas for larger events, you must manually create schemas using the schema registry.
# Generating code bindings for event schemas in Amazon EventBridge
You can generate code bindings for event [schemas](eb-schema.md) to speed up development in Golang, Java, Python, and TypeScript. Code bindings are available for AWS service events, schemas you [create](eb-schema-create.md), and for schemas you [generate](eb-schemas-infer.md) based on [events](eb-events.md) on an [event bus](eb-event-bus.md). You can generate code bindings for a schema by using the EventBridge console, the EventBridge [ Schema Registry API](https://docs.aws.amazon.com/eventbridge/latest/schema-reference/index.html), or in your IDE with an AWS toolkit.
**To generate code bindings from an EventBridge schema**
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. In the navigation pane, choose **Schemas**.
1. Find a schema that you want code bindings for, either by browsing the schema registries, or by searching for a schema.
1. Select the schema name..
1. On the **Schema details** page, in the **Version** section, choose **Download code bindings**.
1. On the **Download code bindings** page, select the language of the code bindings you want to download.
1. Select **Download**.
It may take a few seconds for your download to begin. The downloaded file is a zip file of code bindings for the language you selected.