Path Templating Clarification - proposed fix for #1830.

[tedepstein]

Proposed fix for #1830. Each variable expression in a path must have a corresponding path parameter.

See the associated issue for further details and questions.

Notes:

• The proposed spec change uses the term variable expression to refer to a curly brace-delimited parameter name used within the path. Borrowed this terminology from RFC 6570.
• For consistency, I changed the language in the Parameter Object name field.
  • The previous text referred to an "associated path segment from the path field in the Paths Object."
  • I changed this to refer instead to refer to a "variable expression occurring at least once within the path field in the Paths Object."
  • I wanted to flag this here because I see that there are still open issues about variable expressions and path segments, asking for clarification or additional flexibility in the use of variable expressions as partial path segments and/or spanning path segments. Maybe the "associated path segment" language is meaningful, in which case we should discuss further.
• This is branched from v3.0.3-dev, optimistically hoping it will be deemed a clarification, not a breaking change. The issue asks that question, and proposes SHOULD instead of MUST if we need to make it non-breaking. Also, if it matters, we can target this change to 3.1 instead of 3.0.3.

[MikeRalphson]

@tedepstein generally LGTM. Your language "occurring at least once", is that meant to cater for the ambiguous case here https://github.com/microsoftgraph/microsoft-graph-openapi/issues/9#issuecomment-439895379 and can we instead look at outlawing it (i.e. each variable-expression / parameter MUST be named differently)?

[tedepstein]

@MikeRalphson , it's not intended to allow duplicate parameter definitions, but rather >1 occurrence of a single parameter within a path, like this:

paths:
  /events/{eventID}/comments/{eventID}/{commentID}: 

the {eventID} path parameter occurs in two different segments. Offhand, I can't think of a good reason to include a path parameter more than once in a path. But I imagine there must be some APIs in the wild that do this. And AFAICT, there's nothing in the OpenAPI spec that disallows it.

If this is surfacing a new question that we'd rather not address right now, I can remove "at least once."

[MikeRalphson]

But is eventID here meant to be defined identically, or is there an unintended ambiguity?

[tedepstein]

@MikeRalphson , looking at your linked example, those duplicated parameters are clearly disallowed by the current OpenAPI v3 spec. Each Parameter Object has to have a unique combination of name and in within its scope.

  '/groups/{group-id}/calendar/calendarView/{event-id}/instances/{event-id}':
    get:
      operationId: groups.calendar.calendarView.GetInstances
      parameters:
        - description: 'key: group-id'
          in: path
          name: group-id
          required: true
          schema:
            type: string
          x-ms-docs-key-type: group
        - description: 'key: event-id'
          in: path
          name: event-id
          required: true
          schema:
            type: string
          x-ms-docs-key-type: event
        - description: 'key: event-id'
          in: path
          name: event-id
          required: true
          schema:
            type: string
          x-ms-docs-key-type: event

The "occurring at least once" language would not allow the duplicate parameter definitions, but would allow repeated variable expressions referring to the same parameter, like this:

  '/groups/{group-id}/calendar/calendarView/{event-id}/instances/{event-id}':
    get:
      operationId: groups.calendar.calendarView.GetInstances
      parameters:
        - description: 'key: group-id'
          in: path
          name: group-id
          required: true
          schema:
            type: string
          x-ms-docs-key-type: group
        - description: 'key: event-id'
          in: path
          name: event-id
          required: true
          schema:
            type: string
          x-ms-docs-key-type: event

[tedepstein]

But is eventID here meant to be defined identically, or is there an unintended ambiguity?

The eventID parameter can only be defined once, so repeated references to that parameter should always resolve to identical values. I don't think that's ambiguous.

For reference, the specification addresses parameter uniqueness here, here, and here.

[MikeRalphson]

Yes. I'm concerned with variable-expression uniqueness as they relate to parameters.

[tedepstein]

@MikeRalphson,

Yes. I'm concerned with variable-expression uniqueness as they relate to parameters.

OK, I'm pretty sure we don't need to address that concern in the scope of this PR, so I'll remove "at least once."

[darrelmiller]

It would be good if we could align with the RFC6570 terminology and call these things template expressions.

Suggested change

	Path templating refers to the usage of variable expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.
	Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.

[darrelmiller]

Suggested change

<a name="parameterName"></a>name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*. <ul><li>If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to a variable expression occurring within the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.<li>If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.<li>For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.</ul>

<a name="parameterName"></a>name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*. <ul><li>If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.<li>If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.<li>For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.</ul>

[tedepstein]

@darrelmiller, thanks, that's fine with me. Your suggestions missed one occurrence of "template variable," so I just made the change in a new commit 6929fee.

Diffs on this PR should now show "template expression."