Support for YAML ref array in merge key

[aebaugh]

This might be a way to achieve similar to: https://github.com/APIDevTools/json-schema-ref-parser/issues/1

We've been using json-schema-ref-parser with OpenAPI specs in YAML format. It would be very useful to be able to have several schemas defined in separate/referenced files, and combine them into a single schema. This would allow, for example, maintaining a master schema file that "includes" various versions of subordinate schemas. Such as:

# master schema definition
components:
  schemas:
    # include $ref: 'bounded-context-A-1.3.yml#/components/schemas'
    # include $ref: 'bounded-context-B-2.1.yml#/components/schemas'
    # include $ref: 'bounded-context-C-1.0.yml#/components/schemas'

Below approach using merge key almost works processed by json-schema-ref-parser using !!merge syntax described at: https://yaml.org/type/merge.html

components:
  schemas:
    <<: [ $ref: 'bounded-context-A-1.3.yml#/components/schemas', $ref: 'bounded-context-B-2.1.yml#/components/schemas', $ref: 'bounded-context-C-1.0.yml#/components/schemas'
]

With this (or similar attempts at sequence definition), after bundle only the keys from the map at the first element in the sequence are included. The ideal/expected result is "that all the keys of one or more specified maps should be inserted into the current map".

Possibly this is the realm of an underlying library, but if it could be supported it may bridge the gap between requested allOf semantics and otherwise useful functionality for managing complex schemas. Other suggestions welcome!

[JamesMessinger]

I can definitely see this being useful, but probably not something that should be built-in. We plan to add full-featured plugin support at some point, and this kind of functionality would be a perfect plugin.

In the meantime though, you might be able to add this functionality via a custom parser or custom resolver.

[aebaugh]

Thanks for the input. Additional observation, since js-yaml does properly support handling merge keys, I believe the existing behavior resulting in only the first $ref being in the ultimate merged mapping is probably just because the $refs aren't resolved until after the merge is processed. Thus only the first $ref: key mapping in the sequence is retained, consistent with the merge type definition: "Keys in mapping nodes earlier in the sequence override keys specified in later mapping nodes." So agreed, probably not something that should be built-in, doesn't seem you'd want to change that order of operations. A plugin-in might be a nice solution.

As an alternative, looking at two-stage processing using something like yaml-import to first process a non-standard include type to merge in files, then json-schema-ref-parser to sort out the $refs in the resulting schemas.

components:
  schemas:
    !!import/merge [
      'bounded-context-A-1.3.yml',
      'bounded-context-B-2.1.yml',
      'bounded-context-C-1.0.yml'
]