Improve discriminator handling: inject const/enum from mapping before stripping

[argos83]

Discriminator keyword causes false validation failures even after mapping is stripped

Hello folks! I'd like to start a discussion on a gap I recently ran into with discriminator handling — building on previous work in this repo and its predecessor.

Background

OpenAPI's discriminator keyword is incompatible with JSON Schema validators like AJV in two ways:

1. discriminator.mapping is not supported by AJV (ajv-validator/ajv#2262).
2. A discriminator without an accompanying oneOf causes AJV to throw.

Both of these have been addressed in this repository through the cleanupDiscriminators transform (PRs #302, #320, #374), and in the predecessor repo swagger-mock-validator the problem was discussed in issues #51 and #56 (both closed as "not planned" at archival).

---

The problem I recently ran into

I recently bumped into a case where stripping the discriminator is not enough to make validation pass.

When a provider's OpenAPI spec uses discriminator.mapping alongside oneOf, the mapping encodes which concrete schema corresponds to each discriminator value — e.g.:

components:
  schemas:
    Animal:
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
      discriminator:
        propertyName: type
        mapping:
          cat: '#/components/schemas/Cat'
          dog: '#/components/schemas/Dog'

    Cat:
      type: object
      properties:
        type:
          type: string
        # ... cat-specific fields

    Dog:
      type: object
      properties:
        type:
          type: string
        # ... dog-specific fields

After cleanupDiscriminators strips discriminator.mapping (and potentially the entire discriminator object), AJV validates the response body against all oneOf branches simultaneously. If the concrete schemas are sufficiently similar — which is common in practice — more than one branch matches, causing AJV to fail the oneOf constraint ("must match exactly one schema").

The mapping that was stripped contained exactly the information needed to narrow validation to a single branch. By deleting it, we lose the ability to correctly route the instance to its branch.

---

Real-world context

This pattern is common in services that generate OpenAPI specs from code annotations — for example, JVM services using Swagger Core v3 (io.swagger.core.v3) with @Schema(discriminatorProperty = "type", discriminatorMapping = [...]) on sealed class hierarchies. The generated spec faithfully includes discriminator.mapping as part of the oneOf polymorphic schemas.

When such a spec is used in contract testing via openapi-pact-comparator, the current cleanupDiscriminators pass strips the mapping and leaves behind structurally near-identical oneOf branches with no way to differentiate them — resulting in false validation failures.

---

Possible enhancement: inject const/enum into sub-schemas from the mapping

One approach to fix this would be to use the discriminator.mapping information before discarding it, by injecting a const (or enum) constraint into each oneOf sub-schema for the discriminator property:

// Before stripping, transform:
//   Cat schema: { type: object, properties: { type: { type: string }, ... } }
// Into:
//   Cat schema: { type: object, properties: { type: { type: string, const: "cat" }, ... } }

This would allow AJV to correctly match exactly one oneOf branch for any given instance, without requiring AJV to understand discriminator.mapping itself. The transform would:

1. Read discriminator.propertyName and discriminator.mapping before cleanup.
2. For each mapping entry { value → $ref }, resolve the referenced sub-schema.
3. If the sub-schema's properties[propertyName] does not already have a const or enum, inject const: <value> (or enum: [<value>]).
4. Then proceed with the existing cleanupDiscriminators pass.

---

What I'm unsure about and need input on

I don't have deep context on all the edge cases here, so I'd really value the maintainers' perspective before going further:

• Are there cases where this transform would produce incorrect results (e.g., specs where a discriminator value maps to multiple schemas, or where const/enum injection would conflict with existing constraints)?
• Is the allOf-flattening in flattenAllOf.ts expected to already address some of these cases? Does the interaction between the two transforms matter?
• Is there a reason the current approach chose to be purely subtractive (strip only) rather than additive (transform before stripping)?
• Are there other patterns (e.g., anyOf instead of oneOf, inline schemas instead of $refs) that would need to be handled?

I may be able to contribute an implementation, but I can't commit to that timeline at this point — I'm raising this primarily to document the gap and get input on the right direction.

---

References

• swagger-mock-validator fix: don't raise errors on optional request bodies #51 — Support mapping keyword when discriminator is used
• swagger-mock-validator fix(deps): update dependency @sinclair/typebox to v0.34.28 #56 — Support discriminator in oneOf with nested allOf
• openapi-pact-comparator feat: ignore discriminator mapping to avoid crashing AJV #302 — feat: ignore discriminator mapping to avoid crashing AJV
• openapi-pact-comparator feat: tolerate schemas with discriminators but missing oneOf #320 — feat: tolerate schemas with discriminators but missing oneOf
• openapi-pact-comparator fix: fix typo preventing removal of discriminator.mapping #374 — fix: fix typo preventing removal of discriminator.mapping
• openapi-pact-comparator PR feat: support OAS discriminator.mapping #293 — feat: support OAS discriminator.mapping (abandoned attempt at full mapping support)
• ajv-validator/ajv#2262 — upstream AJV issue for discriminator.mapping support

[pact-bot]

🤖 Great news! We've labeled this issue as SmartBear Supported and created a tracking ticket in PactFlow's Jira (PACT-6751). We'll keep work public and post updates here. Meanwhile, feel free to check out our docs. Thanks for your patience!

[vwong]

@argos83 Are you able to provide a working oas.yaml + pact.json that reproduces this issue? I've tried various permutations, and in all of them, I've at least got ajv to complain about Error: discriminator: "properties/type" must have "const" or "enum", which should then be "solvable" by modifying the OAS itself.

In saying that, if need be, we can apply a patched version of ajv to meet the desired outcome.

[sebastian-tello]

@vwong thanks for taking a look. Reproducing now, I get the same discriminator: "properties/<propertyName>" must have "const" or "enum" error you describe — AJV bails at schema-compile time before any pact body is validated. The "matches more than one branch in oneOf" framing in my issue body isn't what I see with current opc (I'm not sure what changed on my side), but I believe the underlying issue is still real and worth fixing: contract testing against any OAS that uses oneOf + discriminator + mapping (with the discriminator property typed as a shared enum, or plain string) is currently broken end-to-end, regardless of pact content.

Minimal reproducer

Attached: oas.yaml, pact.json.

Run: npx -p @pactflow/openapi-pact-comparator opc oas.yaml pact.json →
Error: discriminator: "properties/type" must have "const" or "enum" (thrown from AJV's addMappings/validateMapping).

On "solvable by modifying the OAS"

I understand the suggestion, but I think it's worth being explicit that the OAS as written is valid OpenAPI 3.0/3.1. The OAS spec for discriminator + mapping does not require each oneOf sub-schema to constrain its discriminator property — the mapping is itself the routing mechanism. AJV's discriminator keyword (introduced in AJV 8 specifically for OpenAPI users, as I understand it) made a different representational choice: per-branch const/enum, no support for mapping. So you have a situation where the same logical contract is valid OAS but not valid input for AJV's discriminator extension.

Arguably the cleanest place for this fix is AJV itself, since its discriminator keyword was added specifically for OpenAPI users and a request to support mapping has been open for years. Reviving that thread (or filing a fresh one with a concrete proposal) seems worth doing in parallel. That said, opc is the next-most-natural place to bridge the gap — it sits between OAS authors and AJV, and a preprocessing pass on the schema before AJV sees it avoids the cost of opc maintaining a forked AJV in the meantime.

On the proposed fix — edge cases I'd want input on

The shape I had in mind: before cleanupDiscriminators strips mapping, walk each value → $ref entry, resolve the target sub-schema, and inject a constraint on the discriminator property. Conceptually simple, but I think there are real edge cases that should shape the design:

1. Sub-schema already has a const/enum on the discriminator property.
   • If it covers the mapping value (exact const, or an enum containing the value): no-op (idempotent).
   • If it doesn't cover the mapping value: leaving it untouched seems safer — the author specified something deliberately, and silently overriding feels wrong. Validation would then likely fail in a way that surfaces the inconsistency, which seems preferable to a silent correction.
2. Sub-schema is itself a $ref to another schema.
   • The chained-$ref pattern seems uncommon, so skipping injection for this case may be a reasonable default.
3. Sub-schema is itself an allOf / anyOf / oneOf (possibly nested).
   • Where do you inject the constraint? If it's allOf, adding a new branch with just the discriminator-property const is well-defined. For anyOf/oneOf it's not obvious — injecting into every branch may or may not be correct depending on the author's intent.
   • I think the safest default is to skip injection for these cases and let AJV's existing error surface, so users get a clear signal that this particular combination needs manual help, rather than opc silently producing a schema that validates differently than they expect.
4. Mapped sub-schemas that are also referenced elsewhere in the OAS.
   • If Cat is in Animal.oneOf's mapping AND used as a standalone response body on some other endpoint, injecting const: cat into the canonical Cat definition would constrain it everywhere, not just in the Animal context. The constraint should be scoped to the oneOf occurrence we're processing, not applied globally. I haven't dug into how minimumSchema's existing cloning behaves here; flagging it as something to verify before mutating in place.
5. const vs enum for the injected constraint.
   • As I understand it, const was added in JSON Schema draft-06; OpenAPI 3.0 nominally targets draft-04 wire format (though most tooling tolerates draft-06+ keywords). OpenAPI 3.1 aligns with 2020-12, so const is fully supported there.
   • Since the injected constraint only lives inside opc's preprocessed schema (it's not written back to disk), either should work with AJV. But enum: [<value>] is functionally equivalent to const: <value> and works in every JSON Schema draft, so enum may be the more portable choice.
6. flattenAllOf interaction.
   • I noticed flattenAllOf runs in the same minimumSchema pass as cleanupDiscriminators. If any of the above paths end up wrapping a sub-schema in allOf, there could be a subtle ordering question (inject first, then flatten, vs. flatten first). I haven't dug into this; flagging it in case it's already known.

Flagging these for the team's consideration in case any are non-obvious or need scoping decisions before implementation.

oas.yaml
pact.json

[vwong]

Thanks for the example oas.yaml + pact.json that highlights the problem. I'll need to speak with the wider team on this specific case. Hang tight.

[mefellows]

Thanks for the thoughtful issue @argos83, and the proposals.

I understand the issue, and have tried several times to engage on this issue, but I think it's not something on the priority list. I think we'll need to address it here.

Another possible solution to discuss - changing oneOf → anyOf. Reasons this might work:

• Consumer-driven philosophy: The consumer doesn't care about the provider's internal type exclusivity guarantee. There is no semantic linkage between a consumer test and the OAD, there is just a check to ensure the consumer expectations are a subset of the provider's schema.
• Validation semantics: anyOf correctly expresses "matches at least one valid response type," which is really what consumer validation should check.
• No false negatives: The current oneOf approach creates false failures when consumer expectations are perfectly valid.
• Discriminator irrelevance to consumers: The provider uses oneOf + discriminator to express "I guarantee exactly one type.". onsumers don't need to verify that guarantee - they just need their specific expectation to be valid.

Tradeoffs

• Inject const/enum: Preserves provider's exact contract, more complex implementation. Would also fail under the condition that the const/enum is not present in the consumer, despite being a valid expectation.
• Use anyOf: Simpler, more aligned with consumer-driven testing philosophy, loses provider's exclusivity signal. Makes me feel dirty.

[sebastian-tello]

I think the oneOf → anyOf transformation may work well for response schemas, however for request schemas I think we'd be losing some validation, the consume needs to provide a full valid request matching exactly one of the subschemas. Maybe we need both, the const/enum approach for requests and oneOf → anyOf for responses

[mefellows]

I think the oneOf → anyOf transformation may work well for response schemas, however for request schemas I think we'd be losing some validation, the consume needs to provide a full valid request matching exactly one of the subschemas. Maybe we need both, the const/enum approach for requests and oneOf → anyOf for responses

Aaaand this is the obvious problem I hadn't considered 🤦 - this is why you don't tackle hard problems at the end of a day :P

I think the const/enum is really the better option here. I think we could start with the simpler implementation (i.e. take the current defaults you suggest - no chained $refs, sub-schema) and see how far that gets us.