Create a JSON Schema for webhook events

[heuels]

Following the discussion in octokit/webhooks.js#171 the plan is to manually create a JSON Schema of webhook events.

As a first step I will bootstrap the schema by feeding the examples through some generator tool (I have my eyes on https://jsonschema.net/ now, but I haven't tried it yet). The second step would take manually correcting the definitions and converting them to enums as needed.

And finally, it would be nice to use the freshly-available schema to generate TypeScript definitions in octokit/webhooks.js using bcherny/json-schema-to-typescript.

[gr2m]

Sounds like a great plan! Thanks Egor for taking this on!

For future reference, we might consider changing the format of the published assets to follow the OpenAPI 3.1 specification for webhooks. See the webhooks field in https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#fixed-fields (current a release candidate). Here is an example (see the webhooks key): https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.1/webhook-example.yaml

[gr2m]

Another way to improve the initial JSON Schemas would be to not only parse the examples but also the "Webhook payload object" tables from the docs, e.g. https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#webhook-payload-object

[gwestersf]

Events and Webhooks team has discussed publishing a schema, but we do not have a committed roadmap date. Thanks for raising this. @bswinnerton

[gr2m]

Hey @heuels, just checking in, are you still working on this? No rush, just want to free up the issue for others to work on in case you can't yourself

[heuels]

Hey! Sorry for the lack of updates for a while. I'm still working on this, although rather slowly. I hope to open a PR in a couple of weeks.

[gr2m]

Great, thanks for the update. Let us know if you run into any questions or blockers

[heuels]

Hey @gr2m, sorry it took me so long, but I've opened a pull request #186 with JSON schemas for every payload type and made sure that all payloads pass validation. Could you please take a look at that and maybe we could figure out next steps there?

[gr2m]

Thanks Egor, that's great! I'll have a look on Monday

[octokitbot]

🎉 This issue has been resolved in version 3.27.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀