Consider how to handle valid `allOf` constraints - schema composition

[austinvalle]

References:

• OpenAPI 3.1 is JSON schema compatible: https://json-schema.org/understanding-json-schema/reference/combining.html
• OpenAPI 3.0: https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/

Background

Usage of the allOf constraint describes a JSON schema that must match all subschemas defined, which I've seen used as a way to compose multiple schemas or share a common base model.

Note from JSON schema docs:

Instances must independently be valid against “all of” the schemas in the allOf.

The PetStore Expanded 3.0 spec has an example of this:

# .. rest of OAS
components:
  schemas:
    Pet:
      allOf:
        - $ref: '#/components/schemas/NewPet'
        - type: object
          required:
          - id
          properties:
            id:
              type: integer
              format: int64

    NewPet:
      type: object
      required:
        - name  
      properties:
        name:
          type: string
        tag:
          type: string 

Proposal

I'm wondering for something like above if we can consider the schema as both of them combined, for the example above:

Original

Pet:
  allOf:
    - $ref: "#/components/schemas/NewPet"
    - type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: int64

NewPet:
  type: object
  required:
    - name
  properties:
    name:
      type: string
    tag:
      type: string

Combined

Pet:
  type: object
  required:
    - id
    - name
  properties:
    id:
      type: integer
      format: int64
    name:
      type: string
    tag:
      type: string

Possible IR output

{
	"name": "pet",
	"schema": {
		"attributes": [
			{
				"name": "id",
				"int64": {
					"computed_optional_required": "required"
				}
			},
			{
				"name": "name",
				"string": {
					"computed_optional_required": "required"
				}
			},
			{
				"name": "tag",
				"string": {
					"computed_optional_required": "computed_optional"
				}
			}
		]
	}
}

Notes

• We'd need to combine the schemas together somehow, duplicate properties with mismatched types/nested children would need to be considered
• There are potential invalid allOf use-cases we'd need to determine how to handle
• The allOf keyword can appear anywhere, not just in the root of the schema like shown above 😄 , will need to consider that

[austinvalle]

Other use-cases of allOf from the kubernetes API where there is only one entry (possibly for overriding description?):

https://github.com/kubernetes/kubernetes/blob/3ac83f528dde9d6f37f0ca164d5642226f2380a7/api/openapi-spec/v3/apis__apps__v1_openapi.json#L5637-L5644

"fieldsV1": {
  "allOf": [
    {
      "$ref": "#/components/schemas/io.k8s.apimachinery.pkg.apis.meta.v1.FieldsV1"
    }
  ],
  "description": "FieldsV1 holds the first JSON version format as described in the \"FieldsV1\" type."
},

[raphaelfff]

I started some work here: raphaelfff#1

[HenriBlacksmith]

Any progress on this? The tool looked super interesting until I reached that limitation :-/