From dcd121eb30ab4a2079a1e92564d40e6099fd723a Mon Sep 17 00:00:00 2001
From: wolfy1339 <4595477+wolfy1339@users.noreply.github.com>
Date: Tue, 21 Jun 2022 19:37:29 -0400
Subject: [PATCH] docs(CONTRIBUTING): add section on how to create schemas
 (#645)

---
 CONTRIBUTING.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4412d4a1c..fccdb5a52 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -39,6 +39,89 @@ When you send a pull request, make sure that the `index.json` file is up-to-date
 with the changes in the `payload-examples/api.github.com/` folder, otherwise the
 tests will fail.
 
+## Creating a new schema
+
+The webhook schemas are [JSON schemas](https://json-schema.org/) that are manually created using example payloads for webhook events.
+
+- Create a new folder for the event in `payload-schemas/api.github.com/`, if it doesn't already exist
+- Create a new JSON file in that folder named `<action>.schema.json` if the event has an `action` property, otherwise name it `event.schema.json`
+- The `$id` property should start with the event name, followed by the `action` name separated with `$` if the event has an `action` property, e.g. `pull_request$created`. If the event doesn't have an `action` property then simply use `event` instead of the `action` name.
+- the `title` property's value should be in the format `<eventName> <action> event`, where `<eventName>` is the name of the event, and `<action>` is the value of the `action` property of the webhook payload. If there is no action, the it should simply be `<eventName> event`
+- `type` should be `object`
+- Add any required properties in an array in the [`required` property](https://json-schema.org/understanding-json-schema/reference/object.html#required-properties)
+- Define properties of the payload in the [`properties` property](https://json-schema.org/understanding-json-schema/reference/object.html#properties) as an object in that property, like so:
+
+```json
+{
+  "properties": {
+    "myproperty": {
+      "type": "int",
+      "description": "My Property's description"
+    }
+  }
+}
+```
+
+- When a property is a `string`, or `number` and has a defined set of values it can be, add the values in an array in the [`enum`](https://json-schema.org/understanding-json-schema/reference/generic.html#enumerated-values) property of the `property`'s object
+  - If the property may have `null` as a value, add `null` to the `enum` array
+  ```json
+  {
+    "type": ["string", "null"],
+    "enum": ["foo", "bar", null]
+  }
+  ```
+- When a property can be of multiple types, use a [`oneOf`](https://json-schema.org/understanding-json-schema/reference/combining.html#oneof) for the decleration of that property, and declare each type in the `oneOf`
+- When it is possible that a property may have a value of `null`:
+
+  - if there is only one other type the property can be, change the `type` property to an array including the type, and the string `null`
+
+  ```json
+  {
+    "type": ["string", "null"]
+  }
+  ```
+
+  - if there are more than one other type, that the property can be, simply add it to the `oneOf`:
+
+  ```json
+  {
+    "oneof": [{ "type": "string" }, { "type": "integer" }, { "type": "null" }]
+  }
+  ```
+
+- Set `additionalProperties` to `false` to prevent the use of other keys without erroring.
+- Repeat until you reach the lowest level of the payload
+
+In the end, you should have a document that resembles the following
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "event_name$action",
+  "type": "object",
+  "required": ["myProp"],
+  "properties": {
+    "myProp": {
+      "type": "string",
+      "enum": ["some", "values"]
+    },
+    "anoptionalProp": {
+      "oneOf": [{ "type": "string" }, { "type": "number" }]
+    },
+    "anObjectProp": {
+      "type": "object",
+      "required": ["nestedProp"],
+      "properties": {
+        "nestedProp": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "title": "event name action"
+}
+```
+
 ## Updating types
 
 The