URL-encoding for operationRef

[Alan-Cha]

I was under the impression that operationRef does not need URL-encoding.

For example, in the following snippit taken directly from the link object documentation...

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

... { and } are not encoded, i.e. replaced with %7B and %7D, like in the following:

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1%7Busername%7D/get'
    parameters:
      username: $response.body#/username

---

However, after talking to a developer of an OAS validator, I am doubtful... I was told that because operationRef is defined as a reference in the OAS, it needs URL-encoding.

Here is the link to the discussion. The last two exchanges are most important to this topic.

Could you clarify if operationRef needs URL-encoding?

[darrelmiller]

The operationRef is a fragment identifier and we need to investigate if curly braces require escaping in that portion of a URL. Some of us think they don't but we will confirm.

Change initial description of OperationRef to "A relative or absolute URI reference to an OAS operation. "

It would be useful to add comments as to how this is different than a regular JSON Reference.

[darrelmiller]

According to RFC 3986,

fragment    = *( pchar / "/" / "?" )
pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"
unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
sub-delims  = "!" / "$" / "&" / "'" / "(" / ")"/ "*" / "+" / "," / ";" / "="

This means the only way a curly brace can exist in a fragment is if it is percent-encoded. That makes me sad.

[MikeRalphson]

@darrelmiller Thanks for clarifying. Do we also need to update the examples?

[jeffory-orrok]

Hi, I just went to https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operationref-examples and there are still literal curly braces in the first two code blocks, so I was wondering whether a decision was made to relax the JSON Reference syntax requirement?

[handrews]

@jeffory-orrok oof. Thanks, this needs fixing in 3.0.4 and 3.1.1.

[lornajane]

Fixed by @handrews in #3731, #3747 and #3748 so I'll resolve.