fix(schemas): remove 'email' format for 'email' property in committer…

….schema.json (#678) * fix(schemas): remove 'email' format for 'email' property in committer.schema.json * docs(readme): add 'JSON schema conventions' section
octokit · Jul 21, 2022 · e410fa0 · e410fa0
1 parent f2f7ffb
commit e410fa0
Show file tree

Hide file tree

Showing 4 changed files with 443 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -327,6 +327,30 @@ the [`cache/`](cache/) folder.
 - [octokit/app-permissions](https://github.com/octokit/app-permissions) – GitHub
   App permission specifications
 
+## JSON Schema conventions
+
+What conventions are the schemas of this repository following?
+
+This section offers the origin of these conventions and the reasoning behind them.
+
+### `"email"` for `committer.schema.json` treated as a regular `string`
+
+The JSON schema for a committer (`committer.schema.json`) has a property `"email"`, which [originally was using](https://github.com/octokit/webhooks/blob/f2f7ffb6ed4179fe22b1b82b670d536a833d83f6/payload-schemas/api.github.com/common/committer.schema.json#L11) the default `email` format offered by [`ajv-format`](https://github.com/ajv-validator/ajv-formats/blob/4dd65447575b35d0187c6b125383366969e6267e/src/formats.ts#L65).
+
+What we noticed is [the Regular Expression used by ajv-format for `emails`](https://github.com/ajv-validator/ajv-formats/blob/4dd65447575b35d0187c6b125383366969e6267e/src/formats.ts#L65) is not accepting emails containing `[` or `]` characters (i.e. `41898282+github-actions`**[**`bot`**]**`@users.noreply.github.com`).
+
+After [considering the option](https://github.com/octokit/webhooks/pull/677) of applying our pattern by extending [`ajv-format` Regular Expression for emails](https://github.com/ajv-validator/ajv-formats/blob/4dd65447575b35d0187c6b125383366969e6267e/src/formats.ts#L65), we considered not to do that because:
+
+- It is an excellent way to cause more trouble (the size of this Regular Expression alone is enormous even before you think about all the sub-patterns).
+- The moment we decide to use our Regular Expression, we are committing to maintaining it, so if someone else comes along and presents another email that is considered invalid by this pattern but works with git, we will need to safely modify the pattern again to cover that in addition to what we currently consider valid.
+- If we want to be accurate, we should follow a spec to decide what is valid and what is not. [Since GitHub is not following a spec for emails (and it will not change any time soon)](https://github.com/octokit/webhooks/issues/453#issuecomment-1189113327), to be validating emails with our RegEx would not be correct either.
+
+You can read more details and the discussion behind in this resources:
+
+- https://github.com/octokit/webhooks/issues/453
+- https://github.com/octokit/webhooks/pull/677
+- https://github.com/octokit/webhooks/pull/678
+
 ## LICENSE
 
 [MIT](LICENSE.md)
diff --git a/...ples/api.github.com/check_suite/requested.payload.with-email-with-special-characters.json b/...ples/api.github.com/check_suite/requested.payload.with-email-with-special-characters.json
@@ -0,0 +1,209 @@
+{
+  "action": "requested",
+  "check_suite": {
+    "id": 118578174,
+    "node_id": "MDEwOkNoZWNrU3VpdGUxMTg1NzgxNzQ=",
+    "head_branch": "master",
+    "head_sha": "f95f852bd8fca8fcc58a9a2d6c842781e32a215e",
+    "status": "queued",
+    "conclusion": null,
+    "url": "https://api.github.com/repos/Codertocat/Hello-World/check-suites/118578174",
+    "before": "6113728f27ae82c7b1a177c8d03f9e96e0adf246",
+    "after": "f95f852bd8fca8fcc58a9a2d6c842781e32a215e",
+    "pull_requests": [],
+    "app": {
+      "id": 29310,
+      "node_id": "MDM6QXBwMjkzMTA=",
+      "owner": {
+        "login": "Octocoders",
+        "id": 38302899,
+        "node_id": "MDEyOk9yZ2FuaXphdGlvbjM4MzAyODk5",
+        "avatar_url": "https://avatars1.githubusercontent.com/u/38302899?v=4",
+        "gravatar_id": "",
+        "url": "https://api.github.com/users/Octocoders",
+        "html_url": "https://github.com/Octocoders",
+        "followers_url": "https://api.github.com/users/Octocoders/followers",
+        "following_url": "https://api.github.com/users/Octocoders/following{/other_user}",
+        "gists_url": "https://api.github.com/users/Octocoders/gists{/gist_id}",
+        "starred_url": "https://api.github.com/users/Octocoders/starred{/owner}{/repo}",
+        "subscriptions_url": "https://api.github.com/users/Octocoders/subscriptions",
+        "organizations_url": "https://api.github.com/users/Octocoders/orgs",
+        "repos_url": "https://api.github.com/users/Octocoders/repos",
+        "events_url": "https://api.github.com/users/Octocoders/events{/privacy}",
+        "received_events_url": "https://api.github.com/users/Octocoders/received_events",
+        "type": "Organization",
+        "site_admin": false
+      },
+      "name": "octocoders-linter",
+      "description": "",
+      "external_url": "https://octocoders.io",
+      "html_url": "https://github.com/apps/octocoders-linter",
+      "created_at": "2019-04-19T19:36:24Z",
+      "updated_at": "2019-04-19T19:36:56Z",
+      "permissions": {
+        "administration": "write",
+        "checks": "write",
+        "contents": "write",
+        "deployments": "write",
+        "issues": "write",
+        "members": "write",
+        "metadata": "read",
+        "organization_administration": "write",
+        "organization_hooks": "write",
+        "organization_plan": "read",
+        "organization_projects": "write",
+        "organization_user_blocking": "write",
+        "pages": "write",
+        "pull_requests": "write",
+        "repository_hooks": "write",
+        "repository_projects": "write",
+        "statuses": "write",
+        "team_discussions": "write",
+        "vulnerability_alerts": "read"
+      },
+      "events": []
+    },
+    "created_at": "2019-05-15T15:20:33Z",
+    "updated_at": "2019-05-15T15:20:33Z",
+    "latest_check_runs_count": 0,
+    "check_runs_url": "https://api.github.com/repos/Codertocat/Hello-World/check-suites/118578174/check-runs",
+    "head_commit": {
+      "id": "f95f852bd8fca8fcc58a9a2d6c842781e32a215e",
+      "tree_id": "c3e6e174b68ce629340ca817d52393dcf0aed707",
+      "message": "Add new gemfile",
+      "timestamp": "2019-05-15T15:20:31Z",
+      "author": {
+        "name": "github-actions[bot]",
+        "email": "41898282+github-actions[bot]@users.noreply.github.com",
+        "username": "github-actions[bot]"
+      },
+      "committer": {
+        "name": "GitHub",
+        "email": "noreply@github.com",
+        "username": "web-flow"
+      }
+    }
+  },
+  "repository": {
+    "id": 186853002,
+    "node_id": "MDEwOlJlcG9zaXRvcnkxODY4NTMwMDI=",
+    "name": "Hello-World",
+    "full_name": "Codertocat/Hello-World",
+    "private": false,
+    "owner": {
+      "login": "Codertocat",
+      "id": 21031067,
+      "node_id": "MDQ6VXNlcjIxMDMxMDY3",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/21031067?v=4",
+      "gravatar_id": "",
+      "url": "https://api.github.com/users/Codertocat",
+      "html_url": "https://github.com/Codertocat",
+      "followers_url": "https://api.github.com/users/Codertocat/followers",
+      "following_url": "https://api.github.com/users/Codertocat/following{/other_user}",
+      "gists_url": "https://api.github.com/users/Codertocat/gists{/gist_id}",
+      "starred_url": "https://api.github.com/users/Codertocat/starred{/owner}{/repo}",
+      "subscriptions_url": "https://api.github.com/users/Codertocat/subscriptions",
+      "organizations_url": "https://api.github.com/users/Codertocat/orgs",
+      "repos_url": "https://api.github.com/users/Codertocat/repos",
+      "events_url": "https://api.github.com/users/Codertocat/events{/privacy}",
+      "received_events_url": "https://api.github.com/users/Codertocat/received_events",
+      "type": "User",
+      "site_admin": false
+    },
+    "html_url": "https://github.com/Codertocat/Hello-World",
+    "description": null,
+    "fork": false,
+    "url": "https://api.github.com/repos/Codertocat/Hello-World",
+    "forks_url": "https://api.github.com/repos/Codertocat/Hello-World/forks",
+    "keys_url": "https://api.github.com/repos/Codertocat/Hello-World/keys{/key_id}",
+    "collaborators_url": "https://api.github.com/repos/Codertocat/Hello-World/collaborators{/collaborator}",
+    "teams_url": "https://api.github.com/repos/Codertocat/Hello-World/teams",
+    "hooks_url": "https://api.github.com/repos/Codertocat/Hello-World/hooks",
+    "issue_events_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/events{/number}",
+    "events_url": "https://api.github.com/repos/Codertocat/Hello-World/events",
+    "assignees_url": "https://api.github.com/repos/Codertocat/Hello-World/assignees{/user}",
+    "branches_url": "https://api.github.com/repos/Codertocat/Hello-World/branches{/branch}",
+    "tags_url": "https://api.github.com/repos/Codertocat/Hello-World/tags",
+    "blobs_url": "https://api.github.com/repos/Codertocat/Hello-World/git/blobs{/sha}",
+    "git_tags_url": "https://api.github.com/repos/Codertocat/Hello-World/git/tags{/sha}",
+    "git_refs_url": "https://api.github.com/repos/Codertocat/Hello-World/git/refs{/sha}",
+    "trees_url": "https://api.github.com/repos/Codertocat/Hello-World/git/trees{/sha}",
+    "statuses_url": "https://api.github.com/repos/Codertocat/Hello-World/statuses/{sha}",
+    "languages_url": "https://api.github.com/repos/Codertocat/Hello-World/languages",
+    "stargazers_url": "https://api.github.com/repos/Codertocat/Hello-World/stargazers",
+    "contributors_url": "https://api.github.com/repos/Codertocat/Hello-World/contributors",
+    "subscribers_url": "https://api.github.com/repos/Codertocat/Hello-World/subscribers",
+    "subscription_url": "https://api.github.com/repos/Codertocat/Hello-World/subscription",
+    "commits_url": "https://api.github.com/repos/Codertocat/Hello-World/commits{/sha}",
+    "git_commits_url": "https://api.github.com/repos/Codertocat/Hello-World/git/commits{/sha}",
+    "comments_url": "https://api.github.com/repos/Codertocat/Hello-World/comments{/number}",
+    "issue_comment_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/comments{/number}",
+    "contents_url": "https://api.github.com/repos/Codertocat/Hello-World/contents/{+path}",
+    "compare_url": "https://api.github.com/repos/Codertocat/Hello-World/compare/{base}...{head}",
+    "merges_url": "https://api.github.com/repos/Codertocat/Hello-World/merges",
+    "archive_url": "https://api.github.com/repos/Codertocat/Hello-World/{archive_format}{/ref}",
+    "downloads_url": "https://api.github.com/repos/Codertocat/Hello-World/downloads",
+    "issues_url": "https://api.github.com/repos/Codertocat/Hello-World/issues{/number}",
+    "pulls_url": "https://api.github.com/repos/Codertocat/Hello-World/pulls{/number}",
+    "milestones_url": "https://api.github.com/repos/Codertocat/Hello-World/milestones{/number}",
+    "notifications_url": "https://api.github.com/repos/Codertocat/Hello-World/notifications{?since,all,participating}",
+    "labels_url": "https://api.github.com/repos/Codertocat/Hello-World/labels{/name}",
+    "releases_url": "https://api.github.com/repos/Codertocat/Hello-World/releases{/id}",
+    "deployments_url": "https://api.github.com/repos/Codertocat/Hello-World/deployments",
+    "created_at": "2019-05-15T15:19:25Z",
+    "updated_at": "2019-05-15T15:19:27Z",
+    "pushed_at": "2019-05-15T15:20:32Z",
+    "git_url": "git://github.com/Codertocat/Hello-World.git",
+    "ssh_url": "git@github.com:Codertocat/Hello-World.git",
+    "clone_url": "https://github.com/Codertocat/Hello-World.git",
+    "svn_url": "https://github.com/Codertocat/Hello-World",
+    "homepage": null,
+    "size": 0,
+    "stargazers_count": 0,
+    "watchers_count": 0,
+    "language": null,
+    "has_issues": true,
+    "has_projects": true,
+    "has_downloads": true,
+    "has_wiki": true,
+    "has_pages": true,
+    "forks_count": 0,
+    "mirror_url": null,
+    "archived": false,
+    "disabled": false,
+    "open_issues_count": 1,
+    "license": null,
+    "forks": 0,
+    "open_issues": 1,
+    "watchers": 0,
+    "default_branch": "master",
+    "is_template": false,
+    "topics": [],
+    "visibility": "public",
+    "web_commit_signoff_required": false
+  },
+  "sender": {
+    "login": "Codertocat",
+    "id": 21031067,
+    "node_id": "MDQ6VXNlcjIxMDMxMDY3",
+    "avatar_url": "https://avatars1.githubusercontent.com/u/21031067?v=4",
+    "gravatar_id": "",
+    "url": "https://api.github.com/users/Codertocat",
+    "html_url": "https://github.com/Codertocat",
+    "followers_url": "https://api.github.com/users/Codertocat/followers",
+    "following_url": "https://api.github.com/users/Codertocat/following{/other_user}",
+    "gists_url": "https://api.github.com/users/Codertocat/gists{/gist_id}",
+    "starred_url": "https://api.github.com/users/Codertocat/starred{/owner}{/repo}",
+    "subscriptions_url": "https://api.github.com/users/Codertocat/subscriptions",
+    "organizations_url": "https://api.github.com/users/Codertocat/orgs",
+    "repos_url": "https://api.github.com/users/Codertocat/repos",
+    "events_url": "https://api.github.com/users/Codertocat/events{/privacy}",
+    "received_events_url": "https://api.github.com/users/Codertocat/received_events",
+    "type": "User",
+    "site_admin": false
+  },
+  "installation": {
+    "id": 957387,
+    "node_id": "MDIzOkludGVncmF0aW9uSW5zdGFsbGF0aW9uOTU3Mzg3"
+  }
+}