OAI / OAI/OpenAPI-Specification

v3.2: issues with the path-item and server url templates

Open
#5,062 20 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

clarification
Dominant language
Markdown
Stars
31.2k
Forks
9.2k
Avg merge
6h 37m
Merged PRs (30d)
27

Description

Thank you for the expanded sections on path and server url templating in the 3.2 spec (https://spec.openapis.org/oas/latest#path-templating and https://spec.openapis.org/oas/latest#server-variable-object respectively) -- this is quite helpful in ensuring closer specification compliance in implementations that perform matching of live HTTP requests against elements of the OpenAPI description (OAD).

However I have some questions and concerns that might suggest there are errors with the specification, or perhaps areas where further clarifications could be added:

  • In both path templates and server urls, we do not explicitly disallow two adjacent template components - e.g. /{foo}{bar}. In the absence of specifying which one of these matches is greedy, there is no deterministic way of matching this, and should be prohibited. (I filter these out in regexes (see below) using a negative look-ahead assertion.)

  • https://spec.openapis.org/oas/latest#path-templating says that the path template ABNF is derived from RFC3986 s3.3 (via commit e4caedca690, by @baywet). But that section describes URI paths, not templates. Was this intended to refer to the uri template RFC instead?

The regular expressions that I am using in my implementation are below; I would appreciate a sanity check:

  • for path templates: each segment (split on /, after omitting the leading /) must match: ^(?:\{[^{}]+\}(?!\{)|%[0-9A-F]{2}|[:@!\$&'()*+,;=A-Za-z0-9._~-]+)+$

  • for server url, the entire string must match: ^(?:\{[^{}]+\}(?!\{)|%[0-9A-F]{2}|[\x21\x23\x24\x26-\x3B\x3D\x3F-\x5B\x5D\x5F\x61-\x7A\x7E\xA0-\x{D7FF}\x{F900}-\x{FDCF}\x{FDF0}-\x{FFEF}\x{10000}-\x{1FFFD}\x{20000}-\x{2FFFD}\x{30000}-\x{3FFFD}\x{40000}-\x{4FFFD}\x{50000}-\x{5FFFD}\x{60000}-\x{6FFFD}\x{70000}-\x{7FFFD}\x{80000}-\x{8FFFD}\x{90000}-\x{9FFFD}\x{A0000}-\x{AFFFD}\x{B0000}-\x{BFFFD}\x{C0000}-\x{CFFFD}\x{D0000}-\x{DFFFD}\x{E1000}-\x{EFFFD}\x{E000}-\x{F8FF}\x{F0000}-\x{FFFFD}\x{100000}-\x{10FFFD}])+$

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked Path Templating and Server Variable Object sections, then compare their ABNF references with RFC3986 section 3.3. Review the proposed regular expressions and the 20-comment discussion; the work is done when the specification's handling of adjacent template components and its cited reference are resolved in clear wording.

Written by the indexing model from the issue text.

Assessment

Domain
api, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.