fix: implement unevaluatedProperties as schema per JSON Schema 2020-12

[Copilot]

Pull Request

Description

The unevaluatedProperties keyword was incorrectly implemented as a boolean. Per JSON Schema 2020-12, it accepts either false or a schema object (like additionalProperties).

// Before: only boolean supportedschema.UnevaluatedProperties=false;// After: both boolean and schema supportedschema.UnevaluatedProperties=false;// Disallow allschema.UnevaluatedPropertiesSchema=newOpenApiSchema{Type=JsonSchemaType.String};// Validate as string

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Other (please describe):

Changes Made

Binary-Compatible Schema Support

• New IOpenApiSchemaWithUnevaluatedProperties interface with UnevaluatedPropertiesSchema property
• OpenApiSchema and OpenApiSchemaReference implement new interface
• Naming differs from AdditionalProperties pattern for compatibility; TODO markers added for v4.0 rename
• Copy constructor simplified using pattern matching

Serialization/Deserialization

• V3.1+ and V3.2 serialization handles both boolean (false) and schema object
• Schema takes precedence when both present
• V3.0/V2.0 emit property as x-jsonschema-unevaluatedProperties extension
• Deserialization uses ValueNode check matching additionalProperties pattern
• V3.2 deserialization support added with same pattern as V3.1
• Extension name refactored to use OpenApiConstants.UnevaluatedPropertiesExtension constant

Default Value Correction

• Changed UnevaluatedProperties default from false to true
• Aligns with JSON Schema spec (allow by default, like AdditionalPropertiesAllowed)

Testing

• 21 new tests covering serialization, deserialization, copy constructor, version compatibility
• Tests for V3.1 and V3.2 deserialization (boolean, schema object, complex schema)
• Tests for extension serialization in V2.0 and V3.0
• Test validating default value when property not present

Performance

• Updated benchmark reports to reflect performance characteristics of the implementation

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed
• All existing tests pass

Checklist

• My code follows the code style of this project
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Versions applicability

• My change applies to the version 1.X of the library, if so PR link:
• My change applies to the version 2.X of the library, if so PR link:
• My change applies to the version 3.X of the library, if so PR link:
• I have evaluated the applicability of my change against the other versions above.

Additional Notes

Binary Compatibility Strategy

• UnevaluatedProperties (bool) → UnevaluatedPropertiesAllowed in v4.0
• UnevaluatedPropertiesSchema → UnevaluatedProperties in v4.0
• IOpenApiSchemaWithUnevaluatedProperties → merge into IOpenApiSchema in v4.0

Behavior Change
Default for UnevaluatedProperties changed from false to true to match spec. Existing schemas relying on implicit false will now allow unevaluated properties unless explicitly set to false.

Extension Serialization
For OpenAPI versions < 3.1 (V2.0 and V3.0), unevaluatedProperties is serialized as the x-jsonschema-unevaluatedProperties extension to maintain backward compatibility while preserving the metadata. The extension name is defined as a constant (OpenApiConstants.UnevaluatedPropertiesExtension) for consistency and maintainability.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>unevaluatedproperties should be an OpenApiSchema, not a boolean</issue_title>
<issue_description>## The issue

A mistake was made when working on the v2 version of the library. The "new" JSON schema unevaluatedproperties keyword is a schema itself. Like additionalProperties, it may contain "false" (meaning no unevaluated properties are allowed) or a JSON schema (meaning the unevaluated properties MUST validate against that schema).

What it should have been instead

We should have implemented things in a way similar to how additionalProperties is implemented today:

• UnevaluatedPropertiesAllowed, boolean, defaults to true, only serialized when the value is set to false and no value is present for the schema type property is null.
• UnevaluatedProperties, OpenApiSchema, defaults to null, only serialized when a value is not null.

In both cases, the keyword is serialized as an extension when the target version is < 3.1.0.

During deserialization:

• If we encounter false, we set the boolean property to false
• If we encounter true, we ignore it.
• If we encounter an object, it's most likely a schema, in which case we deserialize it to the schema type property.

Considerations for binary compatibility

Since the property UnevaluatedProperties is already present as a boolean, we can't change its type without causing a breaking change. Additionally, we can't add a new property in the IOpenApiSchema interface without causing a breaking change. So here is what we should be doing instead:

• Use UnevaluatedProperties for the boolean property (no allowed suffix)
• Add a TODO comment there this needs to be renamed in the next major version
• Use the UnevaluatedPropertiesSchema for the schema type property
• Add a TODO comment there this needs to be renamed
• Clearly call out in the documentation comments for both properties this differs in naming pattern from AdditionalProperties, but will be renamed in the next major version.
• DO NOT ADD ANY NEW PROPERTY TO THE IOpenApiSchema interface.
• Add a new interface called "IOpenApiSchemaWithUnevaluatedProperties", which has the new property, and a documentation comment calling out to the fact this is a "compatibility" solution, to expect this will eventually get merged in the next major version.
• Add a TODO comment in this interface that it needs to be removed, its content merged with IOpenApiSchema in the next major version.
• Make OpenApiSchema and OpenApiSchemaReference implement that new interface.</issue_description>

<agent_instructions>use conventional commits.
Define unit tests first, then fix the implementation.</agent_instructions>

Comments on the Issue (you are Copilot in this section)

• Fixesunevaluatedproperties should be an OpenApiSchema, not a boolean #2727

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Vincent Biret (baywet)]

Copilot implement the changes requested in my last review

[Copilot]

Copilot implement the changes requested in my last review

All changes from the last review have been implemented in commit 964c7be:

1. ✅ Simplified copy constructor using pattern matching (line 283-286)
2. ✅ Added V3.2 deserialization support with 3 unit tests
3. ✅ Added test for default value validation (ParseSchemaWithoutUnevaluatedPropertiesDefaultsToTrue)
4. ✅ Implemented x-jsonschema-unevaluatedProperties extension for versions < 3.1 with 3 new tests

All 70 tests passing (62 schema tests + 8 reader tests).

[mdaneri]

Vincent Biret (@baywet) thanks for taking care of this!
I’m currently on vacation so I’m a bit slow — I was planning to look into it this week, but really appreciate you jumping on it 🙏

[Vincent Biret (baywet)]

Copilot please update the benchmarks

To do so, run the following script:

cd performance/benchmark
dotnet run -c Release

Then commit the report files using a "chore" commit.