bundle a schema together with all of its references

[karenetheridge]

If one schema has $refs to another in another document, it might be desirable to package all the referenced schemas up as definitions in the first schema as a single point of reference.

• conflicting reference names need to be resolved. In the simplest case, if collisions occur we can just die. But easiest is if the base uri of each schema resource can be identified, and then these are written into the $id for each definition (so the $refs don't even need to change).
• if referenced resources have different $schema declarations, then allow changing $schema in resource subschemas #12 is required first. (In the simplest case, we can just die if $schema declarations are different.) This also requires that the referenced resources have $ids as $schema cannot occur in a subschema without $id.

see https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.appendix.B.1

[karenetheridge]

Injecting $id keywords into each referenced subschema in the bundle won't work if the $ref contains a json pointer fragment. In that case we would have to rewrite the $ref to refer to a local definition instead.

[karenetheridge]

This requires a more sophisticated traversal mechanism, as we need to walk a schema in order to identify all its $ref keywords, without any false positives that might be embedded under default, examples, const or enum.

[karenetheridge]

This is now possible, using the callback hooks in 'traverse'. We can use a hook on $ref to compile a list of json pointer locations where $refs live. Then, if one wants a document containing path /x/y/z and all of the locations referenced (recursively) by anything under /x/y/z, we can walk this location list recursively to find everything that can possibly be referenced by /x/y/z and its subschemas.

This code would belong in JSON::Schema::Modern::Document, and be heavily used by JSON::Schema::Modern::Document::OpenAPI for things like "give me the openapi document, but only things suitable to show to users with authentication role foo" or "...only paths with tag bar".