Ambiguity in Validation Due to Same `discriminator.propertyName` Across Multiple Schemas

[kapil5harma]

Note: We noticed this when we tried to upgrade from version 4.13.8 to 5.5.7

Describe the bug

The OpenAPI document defines multiple schemas (Animal, Vehicle, and Building) that all use the same discriminator configuration:

discriminator: {
    propertyName: 'type'
}

This creates ambiguity during validation because the type property is shared across these schemas. When the validator encounters a request body containing the type property, it cannot determine which schema the type belongs to. This leads to conflicts and unclear error messages.

Example to Illustrate the Problem

// Schema Definitions
.addSchema('Animal', {
  oneOf: [
    { $ref: '#/components/schemas/Dog' },
    { $ref: '#/components/schemas/Cat' }
  ],
  discriminator: {
    propertyName: 'type',
    mapping: {
      dog: '#/components/schemas/Dog',
      cat: '#/components/schemas/Cat'
    }
  }
})

.addSchema('Vehicle', {
  oneOf: [
    { $ref: '#/components/schemas/Car' },
    { $ref: '#/components/schemas/Bike' }
  ],
  discriminator: {
    propertyName: 'type',
    mapping: {
      car: '#/components/schemas/Car',
      bike: '#/components/schemas/Bike'
    }
  }
})

.addSchema('Building', {
  oneOf: [
    { $ref: '#/components/schemas/House' },
    { $ref: '#/components/schemas/Apartment' }
  ],
  discriminator: {
    propertyName: 'type',
    mapping: {
      house: '#/components/schemas/House',
      apartment: '#/components/schemas/Apartment'
    }
  }
})

Problematic Scenario

When a request body contains the type property, the validator cannot determine which schema (Animal, Vehicle, or Building) the type belongs to.
For example:

{
  "type": "dog",
  "name": "Buddy",
  "breed": "Golden Retriever"
}

The type value (dog) matches the Animal schema.
However, the validator also attempts to match it against the Vehicle or Building schemas, leading to conflicts or unclear error messages.

Validation Error Example

The validator might produce an error like:

Error: 'type' property is ambiguous. Expected one of [dog, cat, car, bike, house, apartment].

This happens because the type property is shared across multiple schemas, and the discriminator configuration does not provide enough context to resolve the ambiguity.

Why This Matters
This ambiguity makes it difficult to:

1. Validate request bodies accurately.
2. Provide clear error messages to users.
3. Extend the API with new schemas using the type property.

While changing the discriminator property name for each schema (e.g., animalType, vehicleType, buildingType) would resolve the issue, this approach is not feasible without breaking existing APIs.