Path Templating with multiple parameters allows for ambiguous parsing

[richardwhiuk]

Currently the support for path segments is ambiguous even in simple cases:

Consider:

paths:
  /{foo}:{bar}/update:
    post:
      summary: Example API with multiple parameters
      parameters:
        - name: foo
          in: path
          description: Foo
          required: true
          schema:
            type: string
        - name: bar
          in: path
          description: Bar
          required: true
          schema:
            type: string

If the URL /a:b:c/update is received, there are two possible parses which, as far as I can tell, the spec doesn't state which is correct.

• foo = a, bar = b:c
• foo = a:b, bar = c

This means that two different implementations may have different interpretations of how parameters map through.

Note, from an implementation perspective, this gets more challenging, as in order to parse the URL to work out which operation it is, you need to know the full structure of the path parameter, as that may break the ambiguity (e.g. if bar is an enum which can only take values c, or d, then the parse collapses into the second option).

[richardwhiuk]

Note, I worry that https://github.com/OAI/OpenAPI-Specification/issues/1459 will make this situation worse.

[karenetheridge]

Isn't it required that path parameters occupy the entire substring between slashes? so /{foo}:{bar}/update would be illegal -- you need to change that to /{foo}/update and then do the splitting of a:b:c in your implementation to decompose it into its individual parts.

[hkosova]

@karenetheridge

Isn't it required that path parameters occupy the entire substring between slashes? so /{foo}:{bar}/update would be illegal -- you need to change that to /{foo}/update and then do the splitting of a:b:c in your implementation to decompose it into its individual parts.

There's no such requirement in the OpenAPI Spec, and earlier comments from maintainers confirm that partial path templating is valid.

However, some tools explicitly do not support this.

[handrews]

I think this is a "yup, it's dangerous, but it's an advance feature and you're expected to know what you're doing, and if you do something ambiguous, the results are implementation-defined" thing. Although perhaps we should mention it at least briefly.