0

I am trying to understand in which case the forward slash needs to be escaped when writing OpenApi specification document. Here (https://swagger.io/docs/specification/using-ref/) is written:

/ and ~ are special characters in JSON Pointers, and need to be escaped when used literally 
(for example, in path names).
For example, to refer to the path /blogs/{blog_id}/new~posts, you would use:
$ref: '#/paths/~1blogs~1{blog_id}~1new~0posts'

In this example the first two forward slashes are not escaped?

Then later the following example is given:

$ref: '../resources/users.yaml'

$ref: '../resources/users-by-id.yaml'

And these paths are not escaped?

In which case all (or part of the) forward slashes need to be escaped with ~1 ?

Jaxx
  • 1,355
  • 2
  • 11
  • 19

1 Answers1

1

The JSON Pointer part of a $ref is the part after the # fragment delimiter. Before that is the relative or absolute URI, where forward slashes do not need to be escaped.

In the section following the #, the values of things like pathItem keys which contain forward slashes do need to be escaped.

MikeRalphson
  • 2,247
  • 2
  • 15
  • 16
  • in the URI "#/paths/~1blogs~1{blog_id}~1new~0posts" the # symbol is at the beginning. However 2 of the slashes after it are not escaped and the other 2 need to be escaped? Why /paths/ being after the # symbol is not escaped? – Jaxx Jun 15 '21 at 19:49
  • 1
    The unescaped slashes are **between** the elements of the JSON Pointer, `#/` is the pointer to the root of the document, then you have an element which takes you to the `paths` object, then you need an element that takes you to the `/blogs/{blog_id}/new~posts` key, **but** those slashes would look like JSON Pointer element separators if you just did `#/paths/blogs/{blog_id}/new~posts`, so this is where the escaping comes in. So - where you have a transition between elements of the source document, you need an unescaped slash, and where you are encoding one **string**, escape them. – MikeRalphson Jun 16 '21 at 04:33