Polymorphism/discriminator/oneOf in combination with transformers

[AnderssonPeter]

Description

We are trying to combine oneOf + discriminator with transformers, but it seems the transformer code doesn't support it?

Are there any plans to support this combination?

Reproducible example or configuration

openapi-ts --file openapi-ts.config.ts --input openapi.json

openapi-ts.config.ts:

import { defineConfig } from "@hey-api/openapi-ts";
export default defineConfig({
    input: "openapi.json",
    output: "src/openapi",
    plugins: [
        "@tanstack/react-query",
        {
            name: "@hey-api/typescript",
            enums: "typescript"
        },
        {
            name: "@hey-api/sdk",
            transformer: true
        },
        {
            bigInt: true,
            dates: true,
            name: "@hey-api/transformers"
        }
    ]
});

OpenAPI specification

Without AllOf

{
    "openapi": "3.0.4",
    "info": {
        "title": "pets",
        "version": "1.0.0"
    },
    "paths": {
        "/api/pets/{id}": {
            "get": {
                "operationId": "getPetById",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Animal"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Animal": {
                "type": "object",
                "oneOf": [{
                        "$ref": "#/components/schemas/Dog"
                    }, {
                        "$ref": "#/components/schemas/Cat"
                    }
                ],
                "properties": {
                    "type": {
                        "type": "string"
                    }
                },
                "discriminator": {
                    "propertyName": "type",
                    "mapping": {
                        "dog": "#/components/schemas/Dog",
                        "cat": "#/components/schemas/Cat"
                    }
                }
            },
            "Dog": {
                "type": "object",
                "required": ["type"],
                "properties": {
                    "type": {
                        "type": "string"
                    },
                    "barkVolume": {
                        "type": "integer"
                    },
                    "firstBark": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "Cat": {
                "type": "object",
                "required": ["type"],
                "properties": {
                    "type": {
                        "type": "string"
                    },
                    "whiskerLength": {
                        "type": "integer"
                    },
                    "firstMeow": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            }
        }
    }
}

With AllOf

{
    "openapi": "3.0.4",
    "info": {
        "title": "pets",
        "version": "1.0.0"
    },
    "paths": {
        "/api/pets/{id}": {
            "get": {
                "operationId": "getPetById",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Animal"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Animal": {
                "type": "object",
                "required": ["type"],
                "discriminator": {
                    "propertyName": "type",
                    "mapping": {
                        "dog": "#/components/schemas/Dog",
                        "cat": "#/components/schemas/Cat"
                    }
                }
            },
            "Dog": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/Animal"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "type": {
                                "type": "string"
                            },
                            "barkVolume": {
                                "type": "integer"
                            },
                            "firstBark": {
                                "type": "string",
                                "format": "date-time"
                            }
                        }
                    }
                ]
            },
            "Cat": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/Animal"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "type": {
                                "type": "string"
                            },
                            "whiskerLength": {
                                "type": "integer"
                            },
                            "firstMeow": {
                                "type": "string",
                                "format": "date-time"
                            }
                        }
                    }
                ]
            }
        }
    }
}

System information (optional)

@hey-api/openapi-ts: 0.86.0
node: 24.10.0

[AnderssonPeter]

@mrlubos It would be nice if openapi-ts generated typescript guards that could be used to decern what discriminator value was used. this could then both be used by the end consumer and also the generated code?

export function isCat(value: any): value is Cat {
    return value.type === "Cat";
}

then it could generate

export function transformAnimal(value: Animal) {
  if (isCat(value)) {
    return transformCat(value);
  }
  else if (isDog(value)) {
    return transformDog(value);
  }
  throw new Error("Invalid animal");
}

[jeremyfiel]

This schema has undefined behavior in OpenAPI.
https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-21

You defined propertyName: type but the oneOf schemas don't contain this attribute.

What do you expect the discriminator to use to figure out the condition?

[AnderssonPeter]

@jeremyfiel i have added

"type": {
  "type": "string"
},

To both Cat and Dog does that solve the issue?

I have also added a example that uses allOf

[jeremyfiel]

I'm not sure it fixes your issue, but that's the correct way to define the schemas with discriminator>propertyName.

the discriminating property should also be required in the schema to guarantee it's always available to the discriminator.

in your allOf example, having required: [type] at the root schema is fine, but without declaring a type, it can be any json primitive, which could potentially break your discriminator.

{
  "components": {
    "schemas": {
      "Animal": {
        "required": [
          "type"
        ],
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          }
        },
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "dog": "#/components/schemas/Dog",
            "cat": "#/components/schemas/Cat"
          }
        },
        "oneOf": [
          {
            "$ref": "#/components/schemas/Dog"
          },
          {
            "$ref": "#/components/schemas/Cat"
          }
        ]
      },
      "Dog": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Animal"
          }
        ],
        "type": "object",
        "properties": {
          "barkVolume": {
            "type": "integer"
          },
          "firstBark": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Cat": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Animal"
          }
        ],
        "type": "object",
        "properties": {
          "whiskerLength": {
            "type": "integer"
          },
          "firstMeow": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}

[AnderssonPeter]

@jeremyfiel That was what I meant to do, but i failed somehow, it should be corrected now