Inconsistency for successive references in schemas and parsing

[afranke]

The schemas in data/ are parsed by two tools: dump-swagger.py to generate OpenAPI JSON files and hugo to generate https://spec.matrix.org. Each tool has different expectations when it comes to successive relative reference resolution. Consider the following example:

example: {
  "$ref": "examples/foo.json",
  "key": [{"$ref": "bar.json"}]
}

dump-swagger.py will look for bar.json in a path relative to the one of foo.json, i.e. bar.json needs to be in the examples directory for this to work.
hugo on the other hand will look for bar.json in the same directory as examples.

The schemas are not consistent either. Some work one way, some others work the other way. For instance:

• data/api/server-server/invites-v2.yaml line 133, ../../event-schemas/examples/invite_room_state.json is relative to data/api/server-server/ which contains definitions/.
  This is compatible with hugo. It results in the example body for the 200 response for /v2/invite to contain the invite_room_state array. It however breaks dump-swagger.py which gives a FileNotFoundError for /home/afranke/src/matrix/matrix-doc/data/api/server-server/examples/../../event-schemas/examples/invite_room_state.json (the examples/ from examples/minimal_pdu.json a few lines above is creating the problem).
• data/api/server-server/transactions.yaml line 72, edu.json is (as pointed out by the comment there) relative to the examples/ directory, from line 71.
  This works with dump-swagger.py but breaks for hugo, as can be seen by the lack of (required) edus field in the request body example for /v1/send.

I looked it up online and failed to find which way is The Correct One™, but I have to say I find the dump-swagger.py one confusing (“relative to another path that I used somewhere above”⁉️).

We need to decide on one of the two ways (I recommend the hugo one), and then we need to patch both the other tool and the schemas that were aligned with that tool.

[richvdh]

agreed, the search path for $ref should not depend on other things earlier in the document.