What is a Discriminator in API Design? A Beginner’s Guide

If you’re new to API design, you might have come across the term “discriminator” and wondered what it means. Don’t worry — it’s simpler than it sounds.

A discriminator is a feature in API specifications that helps you handle situations where your API can accept or return different types of data. Think of it as a label that tells your API: “Hey, this is the type of data I’m sending you, so treat it accordingly.”

Understanding Discriminators: The Basics

Imagine you’re building an API for a pet store. Your API needs to handle information about different types of pets — dogs, cats, birds, etc. Each pet type has some common information (like name and age) but also unique details:

• Dogs have breed, walking schedule, and training level
• Cats have litter box type, scratching post height, and favorite sleeping spot

Without a discriminator, your API documentation would be confusing. Users would have to guess which fields apply to which pet type. A discriminator solves this by using a special field (like petType) to clearly identify what kind of data you're working with.

A Real-World Example

Let’s look at two different data structures for our pet store API.

Here’s what dog data looks like:

  { "name": "Hotdog",

    "age": 3,

    "weight": 25.5,

    "petType": "dog",

    "breed": "Golden Retriever",

    "isVaccinated": true,

    "walkingSchedule": "Morning and Evening",

    "favoriteToys": ["Frisbee", "Tennis Ball"],

    "trainingLevel": "Intermediate"

}

And here’s cat data:

   { "name": "Meow",

    "age": 2,

    "weight": 4.2,

    "petType": "cat",

    "isVaccinated": true,

    "isIndoor": true,

    "litterBoxType": "Enclosed",

    "scratchingPostHeight": 120,

    "favoriteSleepingSpot": "Balcony"

}

Notice how both have name, age, and petType, but each has unique fields? The petType field is the key—it tells us whether we're dealing with a dog or a cat. This is exactly what a discriminator uses.

Why Do You Need a Discriminator?

When designing APIs, you might use something called oneOf to say "this data could be one of several types." But oneOf alone doesn't make it clear which type you're actually using.

Without a discriminator, your API documentation looks like this — users have to flip between tabs to figure out what fields belong to what type:

With a discriminator, your documentation becomes much clearer. Users can select the type from a dropdown (like “dog” or “cat”), and the documentation automatically shows only the relevant fields:

This makes your API documentation easier to read and helps developers understand exactly what data they need to send or expect to receive.

How Does a Discriminator Work?

A discriminator has two main parts:

1. propertyName : This is the field name that identifies the type (like petType in our example)
2. mapping : This connects each value to its corresponding data structure (like "dog" → Dog schema, "cat" → Cat schema)

Here’s what it looks like in OpenAPI format:

discriminator:

propertyName: petType

mapping:
    dog: '#/components/schemas/Dog'
    cat: '#/components/schemas/Cat'

This tells the API: “Look at the petType field. If it says 'dog', use the Dog schema. If it says 'cat', use the Cat schema."

Setting Up a Discriminator in Apidog

Apidog makes it easy to add discriminators to your API documentation. There are two ways to do it:

Method 1: Using Apidog’s Visual Interface

This method is great if you prefer working with a graphical interface.

Step 1: Create your schemas (like Dog and Cat) in Apidog:

Step 2: In your API endpoint, go to the request or response body editor and set up oneOf to reference your schemas:

Step 3: Add references to your Dog and Cat schemas:

Step 4: Switch to JSON Schema mode to add the discriminator:

Step 5: Add the discriminator configuration at the same level as oneOf:

"discriminator": {

 "propertyName": "petType",

"mapping": {
        "dog": "#/definitions/190704823",
        "cat": "#/definitions/190704706"
    }
}

The numbers in the mapping (like 190704823) are unique IDs that Apidog generates for each schema. You can find these in the JSON Schema panel:

Once you save, your API documentation will have an intelligent dropdown that switches between schemas:

Method 2: Importing OpenAPI Specifications

If you’re comfortable writing OpenAPI specs directly, you can include the discriminator in your specification file and import it into Apidog.

Here’s how you define it in OpenAPI:

Pet:  

  oneOf:

    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Cat'

  discriminator:

    propertyName: petType

    mapping:
      dog: '#/components/schemas/Dog'
      cat: '#/components/schemas/Cat'

This tells Apidog:

• The Pet object can be either a Dog or Cat (oneOf)
• Use the petType field to determine which one (propertyName)
• Map “dog” to the Dog schema and “cat” to the Cat schema (mapping)

Here’s a complete example:

openapi: 3.0.3

info:

  title: Pet Shop API

  version: 1.0.0

components:

  schemas:

    Dog:

      type: object

      properties:

        petType:

          type: string

          enum: [dog]

        name:

          type: string

        age:

          type: integer

        weight:

          type: number

        breed:

          type: string

        isVaccinated:

          type: boolean

        walkingSchedule:

          type: string

        favoriteToys:

          type: array

          items:

            type: string

        trainingLevel:

          type: string

      required:

        - petType

        - name

        - age

    Cat:

      type: object

      properties:

        petType:

          type: string

          enum: [cat]

        name:

          type: string

        age:

          type: integer

        weight:

          type: number

        isVaccinated:

          type: boolean

        isIndoor:

          type: boolean

        litterBoxType:

          type: string

        scratchingPostHeight:

          type: integer

        favoriteSleepingSpot:

          type: string

      required:

        - petType

        - name

        - age

    Pet:

      oneOf:

        - $ref: '#/components/schemas/Dog'

        - $ref: '#/components/schemas/Cat'

      discriminator:

        propertyName: petType

        mapping:

          dog: '#/components/schemas/Dog'

          cat: '#/components/schemas/Cat'

paths:

  /pets:

    get:

      summary: Get pet information

      responses:

        '200':

          description: Successful response

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/Pet'

Import this into Apidog, and it will automatically recognize the discriminator configuration:

Common Questions About Discriminators

When should I use a discriminator?

Use a discriminator when:

• Your API can handle multiple types of data
• You have a field that identifies which type you’re using (like petType, type, or kind)
• You want to make your API documentation clearer for users

Don’t use a discriminator if:

• Your data structure is simple with no variations
• You don’t have a field that identifies the type
• You’re only using oneOf without needing to distinguish types explicitly

Does a discriminator work on its own?

No. A discriminator always works together with oneOf, anyOf, or allOf. These keywords define the possible data structures, and the discriminator tells the system how to choose between them.

Think of it this way:

• oneOf says: "The data could be one of these types"
• discriminator says: "Here's how to figure out which type it is"

What if I don’t have a type field in my data?

If your data doesn’t naturally include a field that identifies its type, you have two options:

1. Add a type field to your data structure (recommended if you control the API design)
2. Skip the discriminator and just use oneOf alone (the documentation won't be as clear, but it will still work)

Key Takeaways

A discriminator is a simple but powerful tool for making your API documentation clearer:

• It uses a specific field (like petType) to identify which data structure you're using
• It works together with oneOf, anyOf, or allOf to handle multiple data types
• It makes your API documentation easier to read by showing only relevant fields
• In Apidog, you can set it up visually or by importing OpenAPI specifications

You don’t always need a discriminator — it’s most useful when you have multiple data types with a clear identifier field. For simple APIs, oneOf alone might be enough.