Incorrect generation of RFC 6570 `{+param}` in OpenAPI versions ≤ 3.1

[mdaneri]

Summary

When generating OpenAPI documents with OpenApiSpecVersion ≤ 3.1, the library emits RFC 6570 URI template syntax such as:

"/files/{+path}": {
  "get": {
    "tags": ["Files"]
  }
}

This syntax is only valid in OpenAPI 3.2, which formally adopts RFC 6570 URI Templates.
In OpenAPI 3.0 and 3.1, {+path} is out of spec and has no defined meaning.

---

Expected behavior

When targeting OpenAPI 3.0 or 3.1, path templates should be restricted to:

/files/{path}

Specifically:

• No RFC 6570 operators (+, *, ?, #, &)
• No multi-segment semantics
• No reserved expansion

---

Actual behavior

For OpenApiSpecVersion <= 3.1, the generated document contains:

/files/{+path}

This results in:

• ❌ Invalid OpenAPI 3.0 / 3.1 documents
• ❌ Rejection by strict validators
• ❌ Undefined behavior in tooling and code generators

---

Specification references

• OpenAPI 3.0 / 3.1

  • Path templating supports simple parameters only ({param})
  • RFC 6570 is not referenced or adopted

• OpenAPI 3.2

  • Formally adopts RFC 6570 URI Templates
  • {+path} becomes valid and meaningful

---

Suggested resolution

One of the following (or similar):

1. Version-aware generation

   • Emit {+param} only when OpenApiSpecVersion >= 3.2
   • Downgrade to {param} for earlier versions

2. Validation / guardrail

   • Throw or warn when RFC 6570 operators are used with OpenAPI ≤ 3.1

3. Explicit opt-in

   • Require a flag or setting to enable RFC 6570 features

---

Why this matters

Many frameworks (e.g., ASP.NET Core) support multi-segment routing internally (e.g., {**path}), but OpenAPI ≤ 3.1 cannot represent this legally.
Emitting {+path} for those versions produces specs that appear valid but are not.

---

Additional context

OpenAPI 3.2 resolves this cleanly by aligning with RFC 6570.
This issue is about ensuring correct version targeting and spec compliance for earlier versions.

References

RFC 6570 – URI Template (IETF)

https://www.rfc-editor.org/rfc/rfc6570.html

https://spec.openapis.org/oas/v3.2.0.html#path-templating

[baywet]

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

The paths MAY be used for templating, not MUST. This ABNF clearly defines + as a valid character in an expression parameter.

What that effectively means:

• A specification paths are "valid according to RFC 6570". Great, that means you can use additional tooling/have achieve better interoperability.
• A specification paths are "invalid according to RFC 6570". It looses a bit of value/functionality, but it's perfectly valid from an OpenAPI perspective. And some people might not care about the ability to do URI templating according to RFC 5670.

Since the OpenAPI specification does not forbid those characters, we cannot have the library enforce such rules.
We might be able to add a new Validation rule that would log warnings for such things in the optional set, so people are pushed towards better practices, but we can't force things here.

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

[mdaneri]

Technically you are right you can have a path with /{+var} and it's valid.
I was confused by
All the fixed fields declared above are objects that MUST use keys that match the regular expression: ^[a-zA-Z0-9.-_]+$.
in the Component Object section. But the component.pathItems is not the fields items

I think we can close the PR

[baywet]

Do you think a warning validation rule would be beneficial?

[mdaneri]

Do you think a warning validation rule would be beneficial?

No