some constraints seem to be unintentional no-ops

[rogpeppe]

According to the OpenAPI 3.0 specification any keywords alongside a $ref keyword should be ignored:

This object cannot be extended with additional properties and any properties added SHALL be ignored. (emphasis in the original).

The API spec here seems to have a number of occurrences of this pattern, as flagged by the tool I was using to interpret the schema:

• "nullable" alongside $ref: openapi.yaml:14725
• "title" alongside $ref: openapi.yaml:17239
• "title" alongside $ref: openapi.yaml:17242
• "nullable" alongside $ref: openapi.yaml:17509
• "description" alongside $ref: openapi.yaml:17682
• "description" alongside $ref: openapi.yaml:17837
• "nullable" alongside $ref: openapi.yaml:18316
• "description" alongside $ref: openapi.yaml:18317
• "nullable" alongside $ref: openapi.yaml:20120
• "description" alongside $ref: openapi.yaml:20151
• "nullable" alongside $ref: openapi.yaml:20354
• "title" alongside $ref: openapi.yaml:21094
• "description" alongside $ref: openapi.yaml:21096
• "type" alongside $ref: openapi.yaml:22567
• "title" alongside $ref: openapi.yaml:22568
• "description" alongside $ref: openapi.yaml:22569
• "nullable" alongside $ref: openapi.yaml:24316
• "description" alongside $ref: openapi.yaml:26244
• "description" alongside $ref: openapi.yaml:26339
• "description" alongside $ref: openapi.yaml:28204
• "description" alongside $ref: openapi.yaml:28484
• "description" alongside $ref: openapi.yaml:28797
• "description" alongside $ref: openapi.yaml:29864
• "description" alongside $ref: openapi.yaml:29951
• "description" alongside $ref: openapi.yaml:30000
• "description" alongside $ref: openapi.yaml:30037
• "description" alongside $ref: openapi.yaml:30173
• "description" alongside $ref: openapi.yaml:30501
• "description" alongside $ref: openapi.yaml:30559
• "description" alongside $ref: openapi.yaml:30717
• "description" alongside $ref: openapi.yaml:30756
• "description" alongside $ref: openapi.yaml:30794
• "nullable" alongside $ref: openapi.yaml:30808
• "nullable" alongside $ref: openapi.yaml:31514

This seems like it would be worth fixing. Even if some tools do in fact interpret keywords alongside $ref, following likely intent despite being technically incorrect, it's straightforward to fix things so the openAPI schema follows the letter of the law.

The fix is this: any time we see $ref alongside another keyword, replace the $ref field with "allOf": {"$ref": originalRefContents}. As an allOf is allowed to coexist with other properties, this fixes the issue.

Note that if a later OpenAPI schema version (v3.1 or later) was used, this would not be an issue because subsequent versions use JSON Schema 2020-12 which does allow $ref alongside other properties.

I see this repo doesn't accept PRs but I'd be happy to provide a patch on request.