# OpenAPI.NET emits `x-jsonschema-unevaluatedProperties` for OpenAPI 2.0 / 3.0 documents

[mdaneri]

Describe the issue

When generating OpenAPI 2.0 or 3.0 documents, OpenAPI.NET emits the vendor extension:

"x-jsonschema-unevaluatedProperties": false

This appears to be used as a fallback representation for the JSON Schema keyword unevaluatedProperties, which is supported in OpenAPI 3.1 but not in OpenAPI 2.0 or OpenAPI 3.0.

Example output:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    }
  },
  "x-jsonschema-unevaluatedProperties": false
}

Why this is problematic

OpenAPI 2.0 and 3.0 do not support the unevaluatedProperties keyword.

The x- prefix makes this a vendor extension, which means:

• Most OpenAPI tools will ignore it
• Validators will not enforce strict property validation
• The schema may appear stricter than it actually is

This can create confusion because the generated document appears to prohibit unknown properties even though most tooling will still allow them.

Interaction with allOf

The likely reason this extension exists is related to schema composition.

In modern JSON Schema (2019‑09 / 2020‑12) and OpenAPI 3.1, the keyword unevaluatedProperties was introduced to correctly support strict validation when using schema composition such as:

• allOf
• $ref
• anyOf
• oneOf

For example, when a schema is composed using allOf, unevaluatedProperties: false allows properties defined across multiple subschemas to be recognized correctly while still preventing unknown fields.

However, OpenAPI 2.0 and 3.0 do not have an equivalent keyword. The closest available keyword is:

"additionalProperties": false

Unfortunately, additionalProperties does not behave the same way when schemas are composed with allOf. Because of this limitation, there is no perfect standards‑compliant way to represent unevaluatedProperties semantics in OpenAPI 2.0 / 3.0.

Expected behavior

If the goal is to generate OpenAPI documents intended for general tooling:

• The generator should avoid emitting x-jsonschema-unevaluatedProperties
• If strict object validation is desired, the standard keyword should be used:

"additionalProperties": false

Alternatively, schemas may need to be flattened or structured differently to achieve strict validation in OpenAPI 2.0 / 3.0.

Actual behavior

The generator emits:

"x-jsonschema-unevaluatedProperties": false

This extension is ignored by most OpenAPI tools and does not enforce validation semantics.

Impact

This behavior can cause:

• confusion for users inspecting generated schemas
• misleading schema strictness
• inconsistent validation behavior across tooling
• OpenAPI documents containing extensions that most tooling does not understand

Suggested fix

Possible improvements:

1. Do not emit x-jsonschema-unevaluatedProperties when targeting OpenAPI 2.0 / 3.0.
2. Prefer additionalProperties: false if strict object validation is required.
3. If the extension is intended only for round‑trip JSON Schema compatibility, document this clearly and make it optional.

Version info

• OpenAPI.NET: 3.4.0
• OpenAPI document version: 2.0 / 3.0

[baywet]

Hi @mdaneri,
Thank you for using the SDK and for reaching out.

I'm a bit confused by this request:

• from a strict "is the document valid" perspective, extensions are allowed on schemas for every version as far as I can remember.
• from a "tools don't do anything with it" perspective, this is a tool specific decision, some tools might decide to do something with it.
• from a "it creates confusion" perspective, it's a hint the intended document was downconverted and some loss of fidelity has occurred. And potentially a nudge to use a newer version of the OpenAPI specification to get better fidelity.

As for the suggestion to "convert it" to an additionalProperties false, I disagree, that conversion would lead to some corner cases not passing schema validation anymore when they should.

Let me know if you have any additional comments or questions.