Microcks Schema Validation Failure: Polymorphic oneOf + Discriminator Not Resolving Correctly

[themalatha888]

We are encountering persistent schema validation failures in Microcks for an API response that contains polymorphic data structures. Despite correctly defining oneOf and a discriminator based on a type-identifying property in our OpenAPI specification, Microcks validation flags subtype-specific properties as undefined and reports that the object "must be valid to one and only one schema, but 2 are valid."
📋 Details:

API Endpoint Affected:
GET /api/v1/resource/{resourceId}/settings (Generic example of the type of endpoint)

Symptoms Observed in Microcks Validation Report:

property 'additionalFieldA' is not defined in the schema and the schema does not allow additional properties (for objects of TypeB or TypeC when additionalFieldA is specific to TypeA)
property 'additionalFieldB' is not defined in the schema and the schema does not allow additional properties (for objects of TypeA or TypeC when additionalFieldB is specific to TypeB)
must be valid to one and only one schema, but 2 are valid with indexes '1, 2'
The API response is logically correct and contains the expected properties for each specific type, but it fails Microcks contract validation.
Expected Behavior:
The API response should validate successfully against the OpenAPI schema. The discriminator on the type-identifying property should correctly resolve the appropriate subtype schema (SubtypeADto, SubtypeBDto, SubtypeCDto, SubtypeDDto), allowing validation of their specific properties.

Relevant OpenAPI Schema:
Please refer to openapi-spec.json (or .yaml) attached to this ticket for the complete and exact OpenAPI specification. The relevant sections are:

BasePolymorphicDto (the base type with oneOf and discriminator)
SubtypeADto, SubtypeBDto, SubtypeCDto, SubtypeDDto (the derived types)
The response wrapper (ResponseCollectionWrapper or similar) that contains the array of BasePolymorphicDto.
Example Failing Response Payload:
Please refer to failing-response-payload.json attached to this ticket for the exact JSON response payload that is failing validation in Microcks.

failing-response-payload.json

OpenAPI Schema Verification: Confirmed oneOf and discriminator are correctly defined in the OpenAPI spec, using typeIdentifierProp as the discriminator property and simple schema names (e.g., SubtypeADto) in the mapping. additionalProperties: false is present on all relevant schemas.
Schema Generation Control: Ensured the build process generates the OpenAPI specification with the proper discriminator mapping and a clean oneOf structure (no allOf extending references).
Response Payload Accuracy: Verified that the API's JSON responses precisely match the structure and properties expected by each specific subtype schema (e.g., TypeA objects only include additionalFieldA, TypeB objects only include additionalFieldB and additionalFieldC, etc.).
Microcks Contract Update: Confirmed that the exact OpenAPI JSON file containing the corrected discriminator mapping is the one being pushed to the Microcks contract repository and used by the pipeline for validation. (This was a key area of investigation).
Custom JSON Handling: Verified any custom JSON serialization/deserialization logic correctly handles the typeIdentifierProp for both input and output of derived types.
openapi-spec.json

[lbroudoux]

Hi @themalatha888
Thanks for raising this issue. Could you provide a small OpenAPI spec file as a reproducer? It appears that the openapi-spec.json file you attached is not complete and is actually pseudo YAML... Once received, I can compare to the unit tests we already have on that topic and see the results.

[themalatha888]

"Thanks for the quick response! My apologies for the previous attachment. I've created a minimal OpenAPI spec file (reproducer-openapi.json) focusing on the polymorphic definitions, and ensured it's valid JSON. I've also re-attached the failing-response-payload.json for validation against this spec. Please let me know if you need anything else."
failing-response-payload.json
reproducer-openapi.json

[lbroudoux]

Thanks. Will have a look at it asap.

[lbroudoux]

So here are my findings.

First, I had to modify the failing response a bit to adapt to the data array required by the ResponseCollectionWrapper type. Also, I removed the unknown commonProp2 property that was defined nowhere. Here is the JSON I have used:

{
   "data": [
     {
       "commonProp1": "Value1A",
       "typeIdentifierProp": "TypeA",
       "commonProp3": false,
       "additionalFieldA": "Specific data for TypeA",
       "nestedCommon": { "label": "Category Alpha", "description": null }
     },
     {
       "commonProp1": "Value1B",
       "typeIdentifierProp": "TypeB",
       "commonProp3": true,
       "additionalFieldB": 123,
       "additionalFieldC": "Another B field",
       "nestedCommon": { "label": "Category Beta", "description": "Details for Beta" }
     },
     {
       "commonProp1": "Value1C",
       "typeIdentifierProp": "TypeC",
       "commonProp3": false,
       "additionalFieldD": ["item1", "item2"],
       "nestedCommon": { "label": "Category Gamma", "description": null }
     }
   ]
}

I faced validation failures and here are the full results I have:

Error: property 'additionalFieldA' is not defined in the schema and the schema does not allow additional properties
Error: property 'additionalFieldB' is not defined in the schema and the schema does not allow additional properties
Error: property 'additionalFieldC' is not defined in the schema and the schema does not allow additional properties
Error: must be valid to one and only one schema, but 0 are valid
Error: property 'additionalFieldD' is not defined in the schema and the schema does not allow additional properties
Error: property 'additionalFieldD' is not defined in the schema and the schema does not allow additional properties
Error: property 'additionalFieldD' is not defined in the schema and the schema does not allow additional properties

Given the fact that TypeC is not defined as a discriminator value and additionalFieldD is nowhere defined, I removed the 3rd element of the data array to focus on real problems. Now I have those results:

Error: property 'additionalFieldA' is not defined in the schema and the schema does not allow additional properties
Error: property 'additionalFieldB' is not defined in the schema and the schema does not allow additional properties
Error: property 'additionalFieldC' is not defined in the schema and the schema does not allow additional properties

Now, looking in detail, something that is a bit strange to me in the BasePolymorphicDto definition is the additionalProperties=false. I tend to think that is one is orthogonal with the oneOf usage because you put a restriction on sub-types here. Chaning this to additionalProperties=true (or removing it) makes the validation a success!

So to sum up, I would say that there's 3 issues with the response + schema you are trying to validate:

• commonProp2 is undefined and must be removed from the response
• TypeC is unknown and shouldn't appear in the response
• additionalProperties should be set to true or removed from the basic polymorphic type.

As a side note, I'm definitely not a JSON Schema expert, but the validator implementation we use in Microcks (https://github.com/networknt/json-schema-validator/) is itself validated by the JSON Schema community using the Bowtie tool. See the report for the lib we use here: https://bowtie.report/#/implementations/java-networknt-json-schema-validator

[themalatha888]

Dear Microcks Team, especially @lbroudoux

Following up on our previous discussions regarding schema validation failures for polymorphic DTOs in Microcks, we have prepared a minimal, generic reproducer that highlights the specific configuration causing persistent validation errors.

We are encountering the following errors:

must be valid to one and only one schema, but 0 are valid
property 'additionalFieldX' is not defined in the schema and the schema does not allow additional properties (where 'X' is A, B, C, or D)
The core of our inquiry focuses on two specific aspects of our OpenAPI schema configuration:

additionalProperties: false on the Base Polymorphic Type:
As lbroudoux previously pointed out, setting additionalProperties: false on the BasePolymorphicDto (our base type) can cause issues, even when the discriminator correctly resolves to a subtype where these "additional" properties are explicitly defined. We have included additionalProperties: false on BasePolymorphicDto in the attached reproducer-openapi.json to confirm if this is indeed the cause of the "property 'additionalFieldX' is not defined" errors.
Discriminator Mapping to the Base Schema Itself:
This is the primary area where we need clarification. In our reproducer-openapi.json, we have configured the discriminator for BasePolymorphicDto to map a specific typeIdentifierProp value ("TypeC") directly back to the BasePolymorphicDto schema itself.
"TypeC": "BasePolymorphicDto" in the discriminator mapping.
BasePolymorphicDto included in the oneOf list.
Our understanding is that, according to strict OpenAPI Specification rules, a discriminator should always map to a distinct subtype schema, not the base schema that defines the discriminator. However, we are testing this configuration as per an internal requirement.
When Microcks encounters an object with typeIdentifierProp: "TypeC", it produces the must be valid to one and only one schema, but 0 are valid error.
Questions for the Microcks Team:

Can you confirm that additionalProperties: false on a base polymorphic type (like BasePolymorphicDto in our example) is indeed problematic and should be set to true (or removed) when using oneOf and discriminator?
More critically, how does Microcks's validator handle a discriminator mapping a value (e.g., "TypeC") directly back to the base schema (BasePolymorphicDto) that defines the discriminator? Is this specific pattern supported by the Microcks validator, or does it strictly adhere to the OpenAPI rule requiring a distinct subtype schema for each discriminator mapping?
We have attached two files to reproduce this scenario:

reproducer-openapi.json: The OpenAPI specification demonstrating the additionalProperties: false on the base type and the discriminator mapping TypeC back to BasePolymorphicDto.
failing-response-payload.json: An example JSON payload that triggers the validation errors with the provided OpenAPI spec.
Your insights into these specific configurations will be invaluable for our schema design and ensuring successful validation with Microcks.

Thank you for your continued support.
failing-response-payload.json
reproducer-openapi.json

[lbroudoux]

Thanks for the follow-up. Here's my take on your questions:

Can you confirm that additionalProperties: false on a base polymorphic type (like BasePolymorphicDto in our example) is indeed problematic and should be set to true (or removed) when using oneOf and discriminator?

According to the NetworkNT JSON validator, additionalProperties: false is actually problematic. Whether it is a validator lib restriction or a correct implementation should be asked to the JSON Schema community. However, as said before, as NetworkNT JSON validator is ranked as 100% compliant by this Bowtie report, I suspect the answer will be that it's the correct implementation.

More critically, how does Microcks's validator handle a discriminator mapping a value (e.g., "TypeC") directly back to the base schema (BasePolymorphicDto) that defines the discriminator? Is this specific pattern supported by the Microcks validator, or does it strictly adhere to the OpenAPI rule requiring a distinct subtype schema for each discriminator mapping?

Again, I would say that the JSON Schema community is the Subject Matter Expert here. As I understand it, the NetworkNT JSON validator only considers distinct subtypes. Considering the base type would also probably lead to an infinite recursion issue when validating. It's IMHO a best practice to have with safety guard imposed by the spec.

I don't know if this is the case here, but generating the OpenAPI spec from the code usually leads to this kind of error: programming languages are more flexible, and the OpenAPI spec has its own additional constraints.

Hope it helps in your thoughts and process.

[themalatha888]

Hi @lbroudoux ,

Thank you very much for your detailed and insightful response. Your clarifications are extremely helpful and confirm our understanding of these OpenAPI/JSON Schema patterns.

We appreciate you confirming that additionalProperties: false on the base polymorphic type is indeed problematic for the NetworkNT JSON validator, and more critically, that mapping a discriminator value directly back to the base schema is not supported and strictly adheres to the OpenAPI rule requiring distinct subtype schemas.

This provides us with the clear guidance we needed. We will proceed with adjusting our OpenAPI generation to align with these requirements.

Thanks again for your excellent support!

[lbroudoux]

You're welcome! Please keep us informed about what you're cooking with Microcks. We love user feedback!

[yada]

Thank you, @themalatha888, for raising the issue and for the great technical discussion.
Since you appear to be already using Microcks within your organization, we’d be very grateful if you could:

⭐ Star our main repo

• Stars are a key metric for open source projects like ours.

🏢 Add your company and use case to our adopter list

• This is critical as we work towards moving from CNCF Sandbox to Incubation, to showcase community adoption and usage.

Thanks a lot for your support, we really count on you! 🙌