Create a Amazon EventBridge schema - Amazon EventBridge

Create a Amazon EventBridge schema

Schemas are defined using JSON files using either the OpenAPI Specification or the JSONSchema Draft4 specification. You can create or upload your own event schemas in EventBridge using either of these specifications. You can download a template, or you can edit a template directly in the EventBridge console.

To create an OpenAPI schema from a downloaded template

  1. Open the Amazon EventBridge console at https://console.aws.amazon.com/events/.

  2. In the navigation pane, choose Schema registry.

  3. In the Getting started section under Schema template, choose Download.

  4. Alternatively, you can copy the JSON 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" } } } } } }
  5. Edit the template so that the schema matches your events. For more information on events, see Amazon EventBridge events.

To upload a schema file

  1. Open the Amazon EventBridge console at https://console.aws.amazon.com/events/.

  2. In the navigation pane, choose Schemas and then Create schema.

  3. Optionally, select or create a schema registry.

  4. Under Schema details enter a name for your schema.

  5. Optionally, enter a description for the schema to create.

  6. For Schema type, choose either OpenAPI 3.0 or JSON Schema Draft 4.

  7. With the Create tab selected, either drag your schema file to the text box, or paste the schema source.

  8. Select Create.

To edit a template directly in the console

  1. Open the Amazon EventBridge console at https://console.aws.amazon.com/events/.

  2. In the navigation pane, choose Schemas and then Create schema.

  3. Optionally, select or create a schema registry.

  4. Under Schema details enter a name for your schema.

  5. For Schema type, choose either OpenAPI 3.0 or JSON Schema Draft 4.

  6. Optionally, enter a description for the schema to create.

  7. For Schema type, choose either OpenAPI 3.0 or JSON Schema Draft 4.

  8. With the Create tab selected, choose Load template.

  9. Edit the template so that the schema matches your events. For more information on events, see Amazon EventBridge events.

  10. Select Create.

To create a schema using the EventBridge Schema Registry API, use the CreateSchema API action.

Generate a Schema from Event JSON

With the JSON of an event, you can automatically generate a schema for those types of events. Given existing event code, you can quickly generate a custom schema. Once the schema has been generated, you can download code bindings to help create applications for those types of events.

To generate an EventBridge schema based on event JSON

  1. Open the Amazon EventBridge console at https://console.aws.amazon.com/events/.

  2. In the navigation pane, choose Schemas and then Create schema.

  3. Optionally, select or create a schema registry.

  4. Under Schema details enter a name for your schema.

  5. Optionally, enter a description for the schema you created.

  6. For Schema type, choose OpenAPI 3.0.

    You cannot use Discover from JSON to create a JSONSchema schema.

  7. Select Discover from JSON

  8. In the text box under JSON, paste or drag the JSON source of an event.

    As an 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 } }
  9. Choose Discover schema.

  10. EventBridge generates an OpenAPI schema for the event. For example, the following is the generated schema for the event you pasted in.

    { "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" } } } } } }
  11. Once the schema has been generated, select Create.

Generate a Schema Based on Events on an Event Bus

Amazon EventBridge can infer schemas based on events on an event bus. Enabling event discovery on an event bus will generate schemas for events on that bus.

Note

Enabling event discovery on an event bus may incur a cost. The first five million ingested events in each month is free.

To enable schema discovery on an event bus

  1. Open the Amazon EventBridge console at https://console.aws.amazon.com/events/.

  2. In the navigation pane, choose Event buses.

  3. To enable discovery on the Default event bus, select Start discovery.

  4. To enable discovery on a Custom event bus, select the radio button for the custom event bus and choose Start Discovery.

Discovered schemas will show up in the Discovered schemas registry on the Schemas page. Changes to the contents of events on that bus will create new versions of the related EventBridge schema in the Discovered schemas registry.