google / google/gnostic

OpenAPI v2 $ref with sibling elements not removed

Open
#269 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
2.3k
Forks
279
PR merge metrics
No merged PRs in 30d

Description

Per [JSON Schema 2019-09](https://json-schema.org/draft/2019-09/release-notes.html#keyword-changes), $ref is not allowed to have other keywords alongside it until this version.

Both OpenAPI v2 and v3.0 follow a version of JSON Schema below this version and in the [OpenAPI documentation for $ref](https://swagger.io/docs/specification/using-ref/) it mentions that sibling elements alongside $ref will be ignored.

I tried serializing an object containing a $ref and a sibling element to proto with both the openapiv2 and openapiv3 library and noticed that the sibling elements were only ignored in openapiv3.

In the below example, the description is kept in the message in OpenAPI v2 but removed from the message in OpenAPI v3. The correct behavior should be to drop that field for both OpenAPI v2 and v3.

```
"foo" : {
"$ref" : "#/definitions/someRef",
"description" : "description"
},
```

I believe this is due to openapiv3 using [SchemaOrReference](https://github.com/google/gnostic/blob/master/openapiv3/OpenAPIv3.proto#L576) to enforce mutual exclusivity and openapiv2 [directly embedding the ref](https://github.com/google/gnostic/blob/master/openapiv2/OpenAPIv2.proto#L579). Is this something that can be fixed?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.