Properly using oneOf in a Kubernetes CRD OpenAPI schema

Question

I am trying to describe mutually exclusive properties in an OpenAPI v3 schema.

I have a custom resource that can take a property widgetName, a name of a Widget resource, or widgetDefinition, an inline Widget definition. That is, this is valid:

widget:
  widgetName: Foo

And this is valid:

widget:
  widgetDefinition:
    name: Foo
    size: large
    color: red

But you can't have both widget.widgetName and widget.widgetDefinition (it is allowed to have neither). I tried this:

versions:
  - name: v1beta1
    schema:
      openAPIV3Schema:
        type: object
        properties:
        spec:
          type: object
          properties:
            widget:
              type: object
              oneOf:
                - properties:
                    widgetName:
                      type: string
                - properties:
                    widgetDefinition:
                      type: object
                      properties:
                        name:
                          type: string
                        size:
                          type: string
                        color:
                          type: string

But this doesn't work, because:

The CustomResourceDefinition "widgetcontainers.factory.example.com" is invalid: 
* spec.validation.openAPIV3Schema.properties[spec].properties[widget].oneOf[0].properties[widgetName].type: Forbidden: must be empty to be structural
* spec.validation.openAPIV3Schema.properties[spec].properties[widget].oneOf[1].properties[widgetDefinition].properties[color].type: Forbidden: must be empty to be structural
* spec.validation.openAPIV3Schema.properties[spec].properties[widget].oneOf[1].properties[widgetDefinition].properties[name].type: Forbidden: must be empty to be structural
* spec.validation.openAPIV3Schema.properties[spec].properties[widget].oneOf[1].properties[widgetDefinition].properties[size].type: Forbidden: must be empty to be structural
* spec.validation.openAPIV3Schema.properties[spec].properties[widget].oneOf[1].properties[widgetDefinition].type: Forbidden: must be empty to be structural

What's the correct way to say "the cr may contain one of these two properties but not both"?

Did you find an answer ? I came across the same issue and couldn't get it to work. — Lahiru Udayanga, Sep 08 '22 at 12:33

score 0 · Answer 1 · answered Jul 06 '22 at 22:01

larsks, I've defined similar CRD schema in the past, using a syntax like this:

versions:
  - name: v1beta1
    schema:
      openAPIV3Schema:
        type: object
        properties:
        spec:
          type: object
          properties:
            widget:
              type: object
              properties:
                 widgetName:
                   type: string
                 widgetDefinition:
                   type: object
                   properties:
                     name:
                       type: string
                     size:
                       type: string
                     color:
                       type: string
              oneOf:
                - properties:
                  required: [ "widgetName" ]
                - properties:
                  required: [ "widgetDefinition" ]

Unfortunately, this does not describe an exclusive requirement: this will accept an object that provides *both* `widgetName` and `widgetDefinition`. — larsks, Jul 06 '22 at 22:12

Properly using oneOf in a Kubernetes CRD OpenAPI schema

1 Answers1

Linked