Openapi discriminator. 0 and trying to use a discriminator.
Openapi discriminator e. May 20, 2022 · Discussion on using oneOf discriminator type string with enum in OpenAPI Generator, generating POJOs and implementing classes effectively. The discriminator object in OpenAPI tells a client or server which field can be used to discriminate between different schemas. Mar 18, 2022 · Not sure if you're still looking for an answer, considering you asked this so long ago. To help API consumers detect the object type, you can add the discriminator/propertyName keyword to model definitions. point to one schema), why sho # Discriminator Object details summary Excerpt from the OpenAPI 3. Discriminator object. Learn how to use the discriminator to describe polymorphic schemas in OpenAPI specifications. 2 to implement polymorphism. Let's say Animal is "oneOf" Cat or Dog. For that purpose, you should include the discriminator. Is something magically encoded into the name since it ends with Base? What if you have deeper inheritance hierarchies? Feb 9, 2024 · The discriminator concept exists to help processing software which needs to parse instance data conforming to an OpenAPI specification, such as validators, serializers, and to a lesser extent, code generators, work with the schema constructs oneOf, and anyOf. Sep 25, 2016 · Referencing OpenAPI 2. When properly defined via OpenAPI, a consumer Standard library reference to describing discriminated typesTypeSpec allows for the expression of unions and inheritance. Jul 31, 2025 · The OpenAPI discriminator simplifies managing polymorphic data in your API by distinguishing between different types within a single schema. Appreciate any help. Apr 27, 2023 · And that’s why discriminator support is different for OpenAPI 3. So let's say you have a schema for Animal but you use OpenAPI's polymorphism capabilities to also define a Cat and Dog. May 29, 2025 · OpenAPI の discriminator のつらみ Union を直接的に表現する構文を持たないプログラミング言語向けの自動生成が 難しい それはそう。例えば Go や Java。 openapi-generator の go-server で GO バックエンド向けスタブ生成を試み たが、適切な定義にならないことがある（後述） openapi-generator の java-microprofile Jul 11, 2024 · To better understand the background and possible motivations for the allOf/discriminator use case, I reviewed the different versions of the OpenAPI specification (including the former Swagger specifications). Put another way, the discriminator has to discriminate based only on the value of the propertyName, so that is what the Unions Unions are fundamentally different to all other types Pydantic validates - instead of requiring all fields/items/values to be valid, unions require only one member to be valid. The discriminator is a specific object in a schema which is used to inform the . Dec 21, 2018 · Trying to use OpenApi 3. OpenApi Generator The openapi-generator follows the OAS specification Sep 16, 2025 · When using oneOf to indicate that a request body or response contains exactly one of multiple Schema Objects, a discriminator object can help the client or server figure out which schema is included in the request or response. To support polymorphism, the OpenAPI Specification adds the discriminator field. However, when transmitting types over the network, many languages require a mechanism to distinguish between different union variants or models within an inheritance hierarchy. You can provide a value in a field to allOf OpenAPI lets you combine and extend model definitions using the allOf keyword. You know and I know that a dog has four legs and a chicken has two legs, but the schema doesn't. Jan 1, 2024 · In OpenAPI 3 how do I use the discriminator column to map to a list of objects? Asked 1 year, 8 months ago Modified 1 year ago Viewed 749 times Feb 16, 2020 · Are there any simple examples of how "discriminator" in OpenAPI would compare to the analogous schema as described using JSON Schema? If you take my example schema from #2141 and remove the discriminator, that's how you'd do it in JSON Schema. In my own project, I have a schema that is dependent on the values of two Adds support for polymorphism. Sep 20, 2024 · In the generated schema, it's anyOf. This approach helps maintain data consistency and reduces errors during JSON deserialization. Feb 26, 2025 · Master OpenAPI's oneOf, allOf, and anyOf constructs to create flexible and robust API schemas. OpenAPI-generated documentation tool with 24k+ stars on Github - make APIs your company's superpower. Learn when to use each for better API design and data validation. When used, the discriminator will be the name of the property that decides which schema definition validates the structure of the model. It supports the growth of digital services by ensuring APIs cater to a wide range of potential use cases. Still, it does not imply a hierarchy between the models. This keyword points to the property that specifies the data type name: In our example, the discriminator points to the objectType property that contains the data type name. Note: in that case type will be a required property within each schema. Sep 16, 2020 · In other words: The API designer decides whether the API server requires the discriminator; and this is particularly advisable for complex schemas. What is the OpenAPI Specification? The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. This guide explains how to implement it effectively, enhancing API clarity, maintainability, and developer experience while handling complex data models. When the receiver gets a response, how can it determine which one it is? This is where the discriminator is useful. Feb 24, 2024 · In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. Feb 28, 2020 · Do Reptile and Lizard contain the discriminator defined in Pet? If discriminators are inheritable, then what is the correct interpretation of receiving payloads of type Reptile from the below specs? SpecB (discriminator missing from Snake + Lizard) To support polymorphism, the OpenAPI Specification adds the discriminator field. Thanks ` CustomerReq: type: object Sep 6, 2021 · So your OpenAPI spec your discriminator will use type property to determine which schema to use. Aug 13, 2025 · What is the impact of OpenAPI Discriminator on API development? Incorporating the OpenAPI Discriminator into your API specification can streamline API development, making APIs more efficient, adaptable, and user-centric. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. OpenApi Specification The OAS Specification doesn't natively support a default discriminator. 0, Schema Object, or Swagger 2. Aug 22, 2024 · I am using OpenAPI 3. OpenAPI oneOf vs AnyOf with discriminator examples: Compare exclusive vs overlapping schemas and show discriminators resolving ambiguity using YAML/JSON. In our example: Oct 10, 2023 · I try to understand in which cases one might use anyOf in conjunction with a discriminator in an openapi specification. Apr 17, 2024 · I am playing around with formatting of the schema but not able to generate proper OpenAPI spec with discriminator. 0, Schema Object, and the definition of discriminator field as: Adds support for polymorphism. Nov 4, 2024 · The discriminator is saying “look at the type field in the payload to figure out whether this is a Dog or a Cat. ” If the type field says dog, then OpenAPI knows to check against the Dog schema, and if it says cat, it’ll check against the Cat schema. The name of the property in the payload that will hold the discriminator value. Aug 4, 2021 · To support polymorphism, the OpenAPI Specification adds the discriminator field. The OAS specification expected every field to contain a value to specify which child model to use (discriminator). Type1: type: object required: - dn - typeOfType properties: dn: description: Description type: string typeOfTyp To support polymorphism, the OpenAPI Specification adds the discriminator field. 1: In this case, discriminator is an object, with two fields: propertyName, string value of the property used as discriminator mapping, a hash to give explicit values And in this case, it has to be defined at the same level as the combinator. Apr 7, 2022 · The discriminator is a way to distinguish or "discriminate" different schemas. The discriminator is the schema property name t Jan 31, 2021 · Here the documentation explains how to define discriminators when an OpenAPI schema is dependent on the value of a property. At most, all you can hope to do is define an alternate field key to simplify the discriminator (called a mapping). Without that the generated clients have issues when unmarshalling the json because the client cannot match the object with proper schema. When used, the discriminator indicates the name of the property that hints which schema definition is expected to validate the structure of the model. I am seeing error in my code generation. 0 and trying to use a discriminator. 0. The discriminator property mappings are legal to use with any of the composite keywords: The discriminator object is legal only when using one of the composite keywords oneOf, anyOf, allOf. The problem here is that you haven't explicitly declared the available values for legs. As a discriminator can only have one type (i. Nov 26, 2024 · Handling unknown subtypes with OpenAPI discriminator property In our API, we return different subclasses of a base class (SearchEntity) using the discriminator property (searchType) to differentiate between various types. See examples, best practices, common mistakes and alternatives to the discriminator. 1 specification about the Discriminator Object ## Discriminator Object When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. allOf takes an array of object definitions that are used for independent validation but together compose a single object. This leads to some nuance around how to validate unions: which member (s) of the union should you validate data against, and in which order? which errors to raise when validation fails? Validating unions feels Dec 9, 2020 · In the OpenAPI documentation there is example of using discriminator components: responses: sampleObjectResponse: content: application/json: schema: oneOf: Apr 5, 2018 · As of today, a Google search of "openapi discriminator example" yields a smattering of partial examples, plus one attempt at an example, last commented on 10 weeks ago which, alas, ends up just showing a frustrated user "struggling" (unsuccessfully) to get that example to work. zpsluuetfjfpkxg97lkuxqcu2gqnajb7u8wt3gajrqhsp