console.redhat.com CloudEvents

This repo contains jsonschema definitions for events generated by console.redhat.com apps.

Layout

• schemas/events/v1/events.json defines the overall schema for all console.redhat.com CloudEvents. All apps SHOULD produce events matching this schema, with the data property being app-specific. The dataschema field MUST be used to specify the schema of data.
• schemas/apps contains versioned subdirectories for each app's event data schemas.
  • e.g. schemas/apps/advisor/v1 contains advisor event data schema
• schemas/core contains versioned event data schemas for common subjects (e.g. systems). An app may use a core schema during development, but will usually need its own schema to contain additional app-specific data.

Adding a new schema

If the subject is a common object across console.redhat.com, then it should be defined in the core directory.

Any app-specific data should be defined in an app-specific schema in the apps directory.

New schemas MUST be added to schemas/events/v1/events.json -> oneOf -> data / dataschema section.

Schemas SHOULD make liberal use of "additionalProperties": false to enforce deliberate changes to properties.

Updating an existing schema

Updates SHOULD be backwards compatible. If a backwards incompatible change is needed, you must coordinate with consumers, and you SHOULD bump the version number for clarity.

Docs

See https://redhatinsights.github.io/event-schemas/ for generated documentation. Documentation can be generated locally via scripts/update-docs.sh.

Libraries

Libraries for multiple languages are generated using quicktype. Each one is keep on their own repository with it's own version.

• Java
• Python
• Golang

All libraries should use dependabot to ensure we are using the latest version of this schema.

Scripts

• scripts/update-docs.sh generates the docs/index.html and related files. If you do not run npm install first, it will fallback to the asyncapi generator container image, which is slower than direct node usage, but functionally equivalent.
• npm run validate validates the whole schema. If any input is received, validates the overall JSON, else it runs the validation on all examples.

cat examples/advisor.json | npm run validate
# or
npm run validate