16

Here it says I could refer to the definition in another file for an individual path, but the example seems to refer to a whole file, instead of a single path definition under the paths object. How to assign an individual path in another file's paths object?

For example, I have Anotherfile.yaml that contains the /a/b path:

paths:
  /a/b:
    post:

In another file, I use $ref to reference the /a/b path as follows:

paths:
  /c/d:
    $ref: 'Anotherfile.yaml#/paths/a/b'

but this gives an error:

Could not find paths/a/b in contents of ./Anotherfile.yaml

Helen
  • 87,344
  • 17
  • 243
  • 314
Tiina
  • 4,285
  • 7
  • 44
  • 73

1 Answers1

24

When referencing paths, you need to escape the path name by replacing / with ~1, so that /a/b becomes ~1a~1b. Note that you escape just the path name and not the #/paths/ prefix.

$ref: 'Anotherfile.yaml#/paths/~1a~1b'
Helen
  • 87,344
  • 17
  • 243
  • 314
  • BTW, why "to reference sth" not "to refer sth" >. – Tiina Nov 20 '19 at 01:27
  • 3
    @Tiina I'm not a native speaker. Is "to refer smth" more correct grammatically? [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md) uses the term "referencing", e.g. "if referencing a schema, ..." – Helen Nov 20 '19 at 08:14
  • Another use case I've come along is referencing an `Object Schema`'s `property` (part of `properties`) in another `Object Schema`. One can achieve this via a more specific JSON pointer -- `$ref: './my-other-schema#/properties/propToImport` – Dr1Ku Mar 09 '22 at 09:07