Summary
When generating OpenAPI 3.0 documents using OpenAPI.NET, schemas that define
PatternProperties lose their semantic meaning during serialization.
Currently, the serializer either:
- drops the information entirely, or
- emits
additionalProperties: false, which is semantically incorrect for
dictionary-like schemas with patterned keys.
This issue proposes preserving PatternProperties in a spec-compliant way
for OpenAPI 3.0 by emitting a vendor extension, while keeping a reasonable
fallback for standard tooling.
Background
patternProperties is a core JSON Schema feature that has existed since early
drafts and is fully supported in:
- JSON Schema (all modern drafts)
- OpenAPI 3.1+ (which aligns with JSON Schema 2020-12)
However, OpenAPI 3.0 uses a restricted schema dialect and does not
support patternProperties.
OpenAPI.NET already exposes:
OpenApiSchema.PatternProperties
but this information is effectively lost when serializing to OpenAPI 3.0.
Current Behavior
Given a schema intent like:
{
"type": "object",
"patternProperties": {
"^[a-z][a-z0-9_]*$": {
"type": "integer",
"format": "int32"
}
}
}OpenAPI 3.0 serialization may produce:
{
"type": "object",
"additionalProperties": false
}This output is:
- syntactically valid OpenAPI 3.0
- semantically incorrect, because it forbids all dynamic keys
Expected / Proposed Behavior
When serializing OpenAPI 3.0 and OpenApiSchema.PatternProperties is present:
1. Preserve semantic intent using a vendor extension
Emit a vendor extension such as:
"x-jsonSchema-patternProperties": {
"^[a-z][a-z0-9_]*$": {
"type": "integer",
"format": "int32"
}
}Vendor extensions are explicitly allowed in OpenAPI 3.0 and are the only
spec-compliant mechanism to preserve this information.
2. Provide a best-effort OpenAPI 3.0 fallback
Additionally emit one of the following (depending on feasibility):
This ensures existing OpenAPI 3.0 tooling continues to function predictably,
while advanced consumers can still read the extension.
Non-Goals
- This proposal does not attempt to make
patternProperties a first-class
OpenAPI 3.0 keyword (that would be non-spec).
- This proposal does not change OpenAPI 3.1+ behavior.
Scope of Change
- Affects serialization only
- Only for
OpenApiSpecVersion.OpenApi3_0
- No changes to the public object model
- No breaking changes
Benefits
- Prevents silent loss of schema semantics
- Produces valid OpenAPI 3.0 output
- Allows downstream tools to recover JSON Schema intent
- Aligns with OpenAPI’s intended use of vendor extensions
Suggested Extension Name
x-jsonSchema-patternProperties
Rationale:
- Explicitly indicates JSON Schema keyword preservation
- Avoids ambiguity with standard OpenAPI fields
- Minimizes risk of collision with other extensions
References
Closing Notes
This change would allow OpenAPI.NET to preserve important schema semantics
without violating the OpenAPI 3.0 specification, and without requiring users
to fork or post-process the library output.
Thank you for considering this enhancement.
Summary
When generating OpenAPI 3.0 documents using OpenAPI.NET, schemas that define
PatternPropertieslose their semantic meaning during serialization.Currently, the serializer either:
additionalProperties: false, which is semantically incorrect fordictionary-like schemas with patterned keys.
This issue proposes preserving
PatternPropertiesin a spec-compliant wayfor OpenAPI 3.0 by emitting a vendor extension, while keeping a reasonable
fallback for standard tooling.
Background
patternPropertiesis a core JSON Schema feature that has existed since earlydrafts and is fully supported in:
However, OpenAPI 3.0 uses a restricted schema dialect and does not
support
patternProperties.OpenAPI.NET already exposes:
but this information is effectively lost when serializing to OpenAPI 3.0.
Current Behavior
Given a schema intent like:
{ "type": "object", "patternProperties": { "^[a-z][a-z0-9_]*$": { "type": "integer", "format": "int32" } } }OpenAPI 3.0 serialization may produce:
{ "type": "object", "additionalProperties": false }This output is:
Expected / Proposed Behavior
When serializing OpenAPI 3.0 and
OpenApiSchema.PatternPropertiesis present:1. Preserve semantic intent using a vendor extension
Emit a vendor extension such as:
Vendor extensions are explicitly allowed in OpenAPI 3.0 and are the only
spec-compliant mechanism to preserve this information.
2. Provide a best-effort OpenAPI 3.0 fallback
Additionally emit one of the following (depending on feasibility):
If all pattern properties share the same schema:
Otherwise:
This ensures existing OpenAPI 3.0 tooling continues to function predictably,
while advanced consumers can still read the extension.
Non-Goals
patternPropertiesa first-classOpenAPI 3.0 keyword (that would be non-spec).
Scope of Change
OpenApiSpecVersion.OpenApi3_0Benefits
Suggested Extension Name
Rationale:
References
OpenAPI 3.0 Vendor Extensions
https://swagger.io/docs/specification/v3_0/openapi-extensions/
OpenAPI 3.1 JSON Schema Alignment
https://spec.openapis.org/oas/v3.1.0.html
JSON Schema
patternPropertieshttps://json-schema.org/understanding-json-schema/reference/object.html#pattern-properties
Closing Notes
This change would allow OpenAPI.NET to preserve important schema semantics
without violating the OpenAPI 3.0 specification, and without requiring users
to fork or post-process the library output.
Thank you for considering this enhancement.