fix: add descriptions from GitHub REST API description, source_url …

…property on `package` events is not a full URI (#659)

payload-schemas/api.github.com/code_scanning_alert/appeared_in_branch.schema.json

@@ -31,7 +31,11 @@
           "format": "date-time",
           "description": "The time that the alert was created in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ.`"
         },
-        "url": { "type": "string", "format": "uri" },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The REST API URL of the alert resource."
+        },
         "html_url": {
           "type": "string",
           "format": "uri",

payload-schemas/api.github.com/code_scanning_alert/closed_by_user.schema.json

@@ -31,7 +31,11 @@
           "format": "date-time",
           "description": "The time that the alert was created in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ.`"
         },
-        "url": { "type": "string", "format": "uri" },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The REST API URL of the alert resource."
+        },
         "html_url": {
           "type": "string",
           "format": "uri",

payload-schemas/api.github.com/code_scanning_alert/created.schema.json

@@ -31,7 +31,11 @@
           "format": "date-time",
           "description": "The time that the alert was created in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ.`"
         },
-        "url": { "type": "string", "format": "uri" },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The REST API URL of the alert resource."
+        },
         "html_url": {
           "type": "string",
           "format": "uri",

payload-schemas/api.github.com/code_scanning_alert/fixed.schema.json

@@ -31,7 +31,11 @@
           "format": "date-time",
           "description": "The time that the alert was created in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ.`"
         },
-        "url": { "type": "string", "format": "uri" },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The REST API URL of the alert resource."
+        },
         "html_url": {
           "type": "string",
           "format": "uri",

payload-schemas/api.github.com/code_scanning_alert/reopened.schema.json

@@ -31,7 +31,11 @@
           "format": "date-time",
           "description": "The time that the alert was created in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ.`"
         },
-        "url": { "type": "string", "format": "uri" },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The REST API URL of the alert resource."
+        },
         "html_url": {
           "type": "string",
           "format": "uri",

payload-schemas/api.github.com/code_scanning_alert/reopened_by_user.schema.json

@@ -31,7 +31,11 @@
           "format": "date-time",
           "description": "The time that the alert was created in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ.`"
         },
-        "url": { "type": "string", "format": "uri" },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The REST API URL of the alert resource."
+        },
         "html_url": {
           "type": "string",
           "format": "uri",

payload-schemas/api.github.com/common/deployment.schema.json

@@ -21,20 +21,38 @@
   "type": "object",
   "properties": {
     "url": { "type": "string", "format": "uri" },
-    "id": { "type": "integer" },
+    "id": {
+      "type": "integer",
+      "description": "Unique identifier of the deployment"
+    },
     "node_id": { "type": "string" },
     "sha": { "type": "string" },
-    "ref": { "type": "string" },
-    "task": { "type": "string" },
+    "ref": {
+      "type": "string",
+      "description": "The ref to deploy. This can be a branch, tag, or sha."
+    },
+    "task": {
+      "type": "string",
+      "description": "Parameter to specify a task to execute"
+    },
     "payload": {
       "type": "object",
       "required": [],
       "additionalProperties": true
     },
     "original_environment": { "type": "string" },
-    "environment": { "type": "string" },
-    "transient_environment": { "type": "boolean" },
-    "production_environment": { "type": "boolean" },
+    "environment": {
+      "type": "string",
+      "description": "Name of the target deployment environment."
+    },
+    "transient_environment": {
+      "type": "boolean",
+      "description": "Specifies if the given environment will no longer exist at some point in the future. Default: false."
+    },
+    "production_environment": {
+      "type": "boolean",
+      "description": "Specifies if the given environment is one that end-users directly interact with. Default: false."
+    },
     "description": { "type": ["string", "null"] },
     "creator": { "$ref": "user.schema.json" },
     "created_at": { "type": "string", "format": "date-time" },

payload-schemas/api.github.com/common/discussion.schema.json

@@ -62,7 +62,10 @@
     "id": { "type": "integer" },
     "node_id": { "type": "string" },
     "number": { "type": "integer" },
-    "title": { "type": "string" },
+    "title": {
+      "type": "string",
+      "description": "The discussion post's title."
+    },
     "user": { "$ref": "user.schema.json" },
     "state": { "type": "string", "enum": ["open", "locked", "converting"] },
     "locked": { "type": "boolean" },
@@ -71,7 +74,10 @@
     "updated_at": { "type": "string", "format": "date-time" },
     "author_association": { "$ref": "author_association.schema.json" },
     "active_lock_reason": { "type": ["string", "null"] },
-    "body": { "type": "string" },
+    "body": {
+      "type": "string",
+      "description": "The discussion post's body text."
+    },
     "reactions": { "$ref": "reactions.schema.json" }
   },
   "additionalProperties": false,

payload-schemas/api.github.com/common/installation.schema.json

@@ -43,62 +43,164 @@
       "type": "object",
       "required": [],
       "properties": {
-        "actions": { "type": "string", "enum": ["read", "write"] },
-        "administration": { "type": "string", "enum": ["read", "write"] },
-        "checks": { "type": "string", "enum": ["read", "write"] },
+        "actions": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token for GitHub Actions workflows, workflow runs, and artifacts."
+        },
+        "administration": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token for repository creation, deletion, settings, teams, and collaborators creation."
+        },
+        "checks": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token for checks on code."
+        },
         "content_references": { "type": "string", "enum": ["read", "write"] },
-        "contents": { "type": "string", "enum": ["read", "write"] },
-        "deployments": { "type": "string", "enum": ["read", "write"] },
+        "contents": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token for repository contents, commits, branches, downloads, releases, and merges."
+        },
+        "deployments": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token for deployments and deployment statuses."
+        },
         "discussions": { "type": "string", "enum": ["read", "write"] },
         "emails": { "type": "string", "enum": ["read", "write"] },
-        "environments": { "type": "string", "enum": ["read", "write"] },
-        "issues": { "type": "string", "enum": ["read", "write"] },
-        "members": { "type": "string", "enum": ["read", "write"] },
-        "metadata": { "type": "string", "enum": ["read", "write"] },
+        "environments": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token for managing repository environments."
+        },
+        "issues": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token for issues and related comments, assignees, labels, and milestones."
+        },
+        "members": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token for organization teams and members."
+        },
+        "metadata": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to search repositories, list collaborators, and access repository metadata."
+        },
         "organization_administration": {
           "type": "string",
-          "enum": ["read", "write"]
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to manage access to an organization."
         },
         "organization_events": { "type": "string", "enum": ["read", "write"] },
-        "organization_hooks": { "type": "string", "enum": ["read", "write"] },
+        "organization_hooks": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to manage the post-receive hooks for an organization."
+        },
         "organization_packages": {
           "type": "string",
-          "enum": ["read", "write"]
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token for organization packages published to GitHub Packages."
+        },
+        "organization_plan": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token for viewing an organization's plan."
         },
-        "organization_plan": { "type": "string", "enum": ["read", "write"] },
         "organization_projects": {
           "type": "string",
-          "enum": ["read", "write"]
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to manage organization projects and projects beta (where available)."
+        },
+        "organization_secrets": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to manage organization secrets."
         },
-        "organization_secrets": { "type": "string", "enum": ["read", "write"] },
         "organization_self_hosted_runners": {
           "type": "string",
-          "enum": ["read", "write"]
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to view and manage GitHub Actions self-hosted runners available to an organization."
         },
         "organization_user_blocking": {
           "type": "string",
-          "enum": ["read", "write"]
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to view and manage users blocked by the organization."
+        },
+        "packages": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token for packages published to GitHub Packages."
+        },
+        "pages": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to retrieve Pages statuses, configuration, and builds, as well as create new builds."
+        },
+        "pull_requests": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token for pull requests and related comments, assignees, labels, milestones, and merges."
+        },
+        "repository_hooks": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to manage the post-receive hooks for a repository."
+        },
+        "repository_projects": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to manage repository projects, columns, and cards."
         },
-        "packages": { "type": "string", "enum": ["read", "write"] },
-        "pages": { "type": "string", "enum": ["read", "write"] },
-        "pull_requests": { "type": "string", "enum": ["read", "write"] },
-        "repository_hooks": { "type": "string", "enum": ["read", "write"] },
-        "repository_projects": { "type": "string", "enum": ["read", "write"] },
         "secret_scanning_alerts": {
           "type": "string",
-          "enum": ["read", "write"]
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to view and manage secret scanning alerts."
+        },
+        "secrets": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to manage repository secrets."
+        },
+        "security_events": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to view and manage security events like code scanning alerts."
         },
-        "secrets": { "type": "string", "enum": ["read", "write"] },
-        "security_events": { "type": "string", "enum": ["read", "write"] },
         "security_scanning_alert": {
           "type": "string",
           "enum": ["read", "write"]
         },
-        "single_file": { "type": "string", "enum": ["read", "write"] },
-        "statuses": { "type": "string", "enum": ["read", "write"] },
-        "team_discussions": { "type": "string", "enum": ["read", "write"] },
-        "vulnerability_alerts": { "type": "string", "enum": ["read", "write"] },
-        "workflows": { "type": "string", "enum": ["read", "write"] }
+        "single_file": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to manage just a single file."
+        },
+        "statuses": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token for commit statuses."
+        },
+        "team_discussions": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to manage team discussions and related comments."
+        },
+        "vulnerability_alerts": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to manage Dependabot alerts."
+        },
+        "workflows": {
+          "type": "string",
+          "enum": ["read", "write"],
+          "description": "The level of permission granted to the access token to update GitHub Actions workflow files."
+        }
       },
       "additionalProperties": false
     },

payload-schemas/api.github.com/common/issue.schema.json

@@ -39,7 +39,10 @@
     "html_url": { "type": "string", "format": "uri" },
     "id": { "type": "integer" },
     "node_id": { "type": "string" },
-    "number": { "type": "integer" },
+    "number": {
+      "type": "integer",
+      "description": "Number uniquely identifying the issue within its repository"
+    },
     "title": { "type": "string", "description": "Title of the issue" },
     "user": { "$ref": "user.schema.json" },
     "labels": { "type": "array", "items": { "$ref": "label.schema.json" } },
@@ -86,7 +89,10 @@
     },
     "reactions": { "$ref": "reactions.schema.json" },
     "timeline_url": { "type": "string", "format": "uri" },
-    "state_reason": { "type": ["string", "null"] }
+    "state_reason": {
+      "type": ["string", "null"],
+      "description": "The reason for the current state"
+    }
   },
   "additionalProperties": false,
   "title": "Issue"

payload-schemas/api.github.com/common/membership.schema.json

@@ -6,8 +6,14 @@
   "description": "The membership between the user and the organization. Not present when the action is `member_invited`.",
   "properties": {
     "url": { "type": "string", "format": "uri" },
-    "state": { "type": "string" },
-    "role": { "type": "string" },
+    "state": {
+      "type": "string",
+      "description": "The state of the user's membership in the team."
+    },
+    "role": {
+      "type": "string",
+      "description": "The role of the user in the team."
+    },
     "organization_url": { "type": "string", "format": "uri" },
     "user": { "$ref": "user.schema.json" }
   },