OpenAPI 3.0: Preserve PatternProperties via Vendor Extension during Serialization

[mdaneri]

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):

• If all pattern properties share the same schema:

  "additionalProperties": {
    "type": "integer",
    "format": "int32"
  }

• Otherwise:

  "additionalProperties": true

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

• 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 patternProperties
  https://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.