Search code examples
parametersopenapi

Does OpenAPI allow using RFC 6570 template syntax in path templates?

I'm a little bit confused, as swagger.io mentions the connection between OpenAPI parameter serialization and RFC 6570 path/query template syntax. It's also mentioned in the openapis.com docs.

What I'm interested in is the exact syntax used to express OpenAPI parameters in the path template string.

A) Is it allowed (by OA spec) to use the relevant parts of RFC 6570 to substitute parameter objects?

I know that this is allowed.

paths:
  "/test/{foo}":
    get:
      operationId: getFoo
      parameters:
      - in: path
        name: foo
        required: true
        style: label
        schema:
          type: string

But is this? Is it equivalent to the first one?

paths:
  # Parameters array omitted, as "." marks "foo" a "label" style parameter
  "/test/{.foo}":
    get:
      operationId: getFoo

B) In case the second example is not allowed, what's the path parameter syntax?

From the examples it looks like {<identifier>}, but is there anything more to this?

C) If it's B) (no RFC syntax in the path templates), is it always required to have a matching parameter object for {<identifier>}?

Meaning do I have to have as many parameter objects, as I have {<identifier>} in my path templates? I'm not 100% sure about the wording, but openapis.com seems to suggest this. It also mentions:

An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required.

What does this mean?

My sources:

Solution

  • A) Is it allowed (by OA spec) to use the relevant parts of RFC 6570 to substitute parameter objects?
    B) In case the second example is not allowed, what's the path parameter syntax?
    From the examples it looks like {<identifier>}, but is there anything more to this?

    OpenAPI supports RFC 6570 level 1 syntax in the path template strings, that is, just {identifier}. OpenAPI does not support RFC 6570 operators and value modifiers (+, *, etc.) in its path templates. So your second example /test/{.foo} means the parameter name is .foo not foo.

    OpenAPI analog of RFC 6570 operators and modifiers (., +, *, etc.) are the style and explode keywords in parameter objects. These keywords mimic some types of RFC 6570 expression expansions (specifically, the simple, label, form-style, and path-style expansions). The Serialization doc on swagger.io mentions RFC 6570 modifiers to give an idea how various style and explode combinations correspond to RFC 6570-style URI templates.


    C) If it's B) (no RFC syntax in the path templates), is it always required to have a matching parameter object for {<identifier>}?

    Not always. According to the Path Templating section of the OpenAPI Specification, the only case when it's NOT required is if the path item object is empty, like so:

    paths:
  # Valid
  /test/{foo}: {}
  /test/{foo}/{bar}: {}

    In all other cases (i.e. when your path items have content), you need matching {<identifiers>} and parameter objects. For example, the following are errors:

    paths:
  /test/{foo}:
    get:
      parameters: []  # Error - missing path parameter definition
      ...

  /test:
    get:
      parameters:
        - in: path    # Error - a path parameter is defined, but is not included in the endpoint path
          name: foo
          ...