[Schema Inaccuracy] "#/components/schemas/email" should not be a `oneOf`, it cannot be a string

[gr2m]

Schema Inaccuracy

#/components/schemas/email is currently only referenced in response types for

• https://docs.github.com/en/rest/reference/users#set-primary-email-visibility-for-the-authenticated-user
• https://docs.github.com/en/rest/reference/users#list-email-addresses-for-the-authenticated-user
• https://docs.github.com/en/rest/reference/users#add-an-email-address-for-the-authenticated-user
• https://docs.github.com/en/rest/reference/users#list-public-email-addresses-for-the-authenticated-user

I don't think that any of these responses permit an item of the returned array to be a string, they are all objects

The current schema is

{
  "title": "Email",
  "description": "Email",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "example": "octocat@github.com"
        },
        "primary": { "type": "boolean", "example": true },
        "verified": { "type": "boolean", "example": true },
        "visibility": {
          "type": "string",
          "example": "public",
          "nullable": true
        }
      },
      "required": ["email", "primary", "verified", "visibility"]
    },
    { "type": "string" }
  ]
}

Expected

{
  "title": "Email",
  "description": "Email",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "example": "octocat@github.com"
    },
    "primary": { "type": "boolean", "example": true },
    "verified": { "type": "boolean", "example": true },
    "visibility": {
      "type": "string",
      "example": "public",
      "nullable": true
    }
  },
  "required": ["email", "primary", "verified", "visibility"]
}

Reproduction Steps

See octokit/openapi-types.ts#37 /cc @filipstefansson

[ahoglund]

@gr2m - All 4 of these operations will response with an string for the email if you pass in the beta media type:

curl -H "Accept: application/vnd.github.beta+json" https://api.github.com/user/email

So it looks like the real fix for this operation is to modify it from a oneOf in the response to instead reflect that this beta media type will contain the array of strings.

[gr2m]

I've never seen the beta version before. It seems to be deprecated since 2014?
https://docs.github.com/en/developers/overview/about-githubs-apis

[ahoglund]

Looks like it's still in use pretty heavily though so we can't easily remove it functionally. That being said, we probably don't need it documented since its officially unsupported.

[gr2m]

Looks like it's still in use pretty heavily though so we can't easily remove it functionally. That being said, we probably don't need it documented since its officially unsupported.

Yes, I wouldn't remove the functionality. But I wouldn't add it to the API specification either, the same is the case for several deprecated API endpoints that have been replaced by new ones

[ahoglund]

Closed by #199