Various utilities for JSON References (http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03).
$ref
. Simple merging would mean allowing neighboring properties beside the $ref
and merging the properties of the JSON Reference object and the resolved object. That use case seems simple, of course some ruling for conflicts where both have the same property.
$ref
container for merging, as that's how they did it by mistake in the past. I don't disagree with you that it's semantically "replace the container with the referenced document/fragment" but any reasoning behind why this use case isn't ideal?
$ref
with $merge
or $compose
or something else, then you could handle this as well without the ambiguity. Thoughts?
$ref
working. If $ref
was a string, it's a replacement. If it's an object, it's a merge.
$ref
itself doesn't change (replace the container with the resolved value) but you give the author control as to how the resolution happens.
for Example
openapi: "3.0.1"
info:
$ref: ./info/index.yaml
servers:
$ref: ./servers/index.yaml
paths:
$ref: ./paths/index.yaml
components:
$ref: ./servers/index.yaml # has been set as /servers/ just to prove the concept of importing same file twice in same yaml.
running this through resolveRefs results in:
....
servers: &ref_1
- url: 'https://api.example.com/{basePath}'
variables:
basePath:
default: /v1
......
components: *ref_1
Is there anyway to get the following output instead? (Ignoring the fact that of course components does not conform to the the standard, its just an example of the behaviour i'm seeing. with the pointers.
....
servers:
- url: 'https://api.example.com/{basePath}'
variables:
basePath:
default: /v1
......
components:
- url: 'https://api.example.com/{basePath}'
variables:
basePath:
default: /v1
#/components
to be a deep copy of #/servers
, that's your needs but from a resolution perspective, they come from same source and are not copied. On the other, I can see this being a configuration item to do it for you.