OpenAPI V3 references parsed as *proto.Arbitrary instead of *proto.Ref

[tomleb]

The issue

I'm using proto.NewOpenAPIV3Data() to parse an OpenAPI V3 spec coming from the /openapi/v3 endpoints of the apiserver.

I'd expect fields such as .metadata.ownerReferences to be a *proto.Ref that refers to the io.k8s.apimachinery.pkg.apis.meta.v1.OwnerReference schema, however they are instead returned as *proto.Arbitrary.

I'm not sure if this is the intended behavior, but I believe it should return a *proto.Ref.

Investigation

I observed a difference between the testdata for pkg/util/proto and the actual spec returned by /openapi/v3.

ownerReferences field from testdata

The $ref is directly under items.

          ...
          "ownerReferences": {
            "description": "List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true. There cannot be more than one managing controller.",
            "type": "array",
            "items": {
              "default": {},
              "$ref": "#/components/schemas/io.k8s.apimachinery.pkg.apis.meta.v1.OwnerReference"
            },
            "x-kubernetes-patch-merge-key": "uid",
            "x-kubernetes-patch-strategy": "merge"
          },
          ...

ownerReferences field from k3s 1.30.0 (and 1.28.6)

The $ref is under an allOf, under items.

          ...
          "ownerReferences": {
            "description": "List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true. There cannot be more than one managing controller.",
            "type": "array",
            "items": {
              "default": {},
              "allOf": [
                {
                  "$ref": "#/components/schemas/io.k8s.apimachinery.pkg.apis.meta.v1.OwnerReference"
                }
              ]
            },
            "x-kubernetes-list-map-keys": [
              "uid"
            ],
            "x-kubernetes-list-type": "map",
            "x-kubernetes-patch-merge-key": "uid",
            "x-kubernetes-patch-strategy": "merge"
          },
          ...

Going further, this document is being parsed by gnostic's openapi_v3.ParseDocument. This results in the following different result (marshaled to JSON):

from testdata

items -> schema_or_reference -> oneof -> reference -> the ref

                     ...
                      "name": "ownerReferences",
                      "value": {
                        "Oneof": {
                          "Schema": {
                            "type": "array",
                            "items": {
                              "schema_or_reference": [
                                {
                                  "Oneof": {
                                    "Reference": {
                                      "_ref": "#/components/schemas/io.k8s.apimachinery.pkg.apis.meta.v1.OwnerReference"
                                    }
                                  }
                                }
                              ]
                            }
                          }
                        }
                      }
                     ...

from k3s 1.30.0

items -> schema_or_reference -> oneof -> allof ->oneof -> reference -> the ref

                     ...
                      "name": "ownerReferences",
                      "value": {
                        "Oneof": {
                          "Schema": {
                            "type": "array",
                            "items": {
                              "schema_or_reference": [
                                {
                                  "Oneof": {
                                    "Schema": {
                                      "all_of": [
                                        {
                                          "Oneof": {
                                            "Reference": {
                                              "_ref": "#/components/schemas/io.k8s.apimachinery.pkg.apis.meta.v1.OwnerReference"
                                            }
                                          }
                                        }
                                      ],
                                      "default": {
                                        "Oneof": null
                                      }
                                    }
                                  }
                                }
                              ]
                            }
                          }
                        }
                      }
                     ...

Looking at the code, the first case is handled correctly. The calls are: proto.ParseSchemaV3 -> proto.parseV3Array -> proto.ParseV3SchemaOrReference -> proto.ParseV3SchemaReference -> returns a Ref.

The second case fails to parse as a ref properly because once it finds the Oneof which has type schema, so proto.ParseSchemaV3 is called. That function expects a type field to be defined, but since there isn't one, it defaults to returning an arbitrary.

Solution

From the looks of it, it seems like proto.ParseSchemaV3 should first check if there's an AllOf, before checking if there's a type. I have a small proof of concept that makes it work for my use case, though I'm not knowledgeable enough on the OpenAPI spec side to know whether that's a bullet proof fix.

Reproducing

I created a repo for easily reproducing this issue: https://github.com/tomleb/kube-openapi-issue/blob/master/main_test.go. Simply run go test -v ./.... I included a OpenAPI V3 spec from v1.30.0, v1.28.6 and from this repo's testdata.

---

I'd appreciate some guidance on whether this is a truly a bug (as opposed to say, misuse of the library?) and thoughts on the fix proposed above. I'd be willing to work on the fix and contribute to the repo once that's confirmed.

[tomleb]

A quick glance at the closed PRs, it looks like this PR introduced the wrapped refs: #298. The reason for wrapping the refs is explained here: kubernetes/kubernetes#106387 (comment).

Any members other than "$ref" in a JSON Reference object SHALL be ignored.

Aka we wouldn't be able to have description with a $ref, so instead we wrap it in an allOf.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue, marking it as "Not Planned".

In response to this:

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.