Validation of external $ref property values should show error on unexpected object type

[tfesenko]

Extracted from #323 Validation of $ref property values should show error on unexpected object type

It covers validation of property values which are defined in an external file, but which resides in the same workspace/project, e.g. $ref: "./uber_schemas.yaml#/components/schemas/Product"

[Local] Validation checks that the referenced element is actually what we expect: good for correctness, bad for performance

We check the local references by getting their actual JSON schema type and comparing it to the expected value. It's done by loading the referenced definition and matching it against the JSON schema. It's OK for local references because all elements are already loaded and schema-matched, but it can really slow down editing experience as validation is live and loading/schema-matching is executed on every change.

Solution: "Batch Validate" action

We can add a "Validate References" action. It's OK for it to be slow - it will now influence editing experience as the users will be invoking it explicitly, and it will still allow us to validate references.

Complimentary step: Check the JSON pointer first

We know that the referenced elements must live at a certain location, e.g. schema definitions must have a <optional file url>#/components/schemas/{componentName} pointer, headers must be in <...>#/components/headers/{componentName}, etc.
So, while not all invalid referenced elements have invalid (wrong format) pointers, but all elements with invalid (wrong format) JSON Pointer are invalid values for references.
We can run validation in two steps:

1. Check the JSON Pointer. It will not guarantee that the referenced element actually has the needed fast, or even that the file is a valid OAS 3 file, but it's fast.
2. For those elements whose JSON pointers are fine, check their actual type

[ghillairet]

See PR #358

I moved the code that does validation of references into the reference validator that was previously only checking that the URI or pointer actually points to something. By adding a few methods I am able to load the referenced document and parse it as a Model. From that I can check the type of the referenced object.

Only missing in this PR is a few tests that I'll add next week.

Also worth to check that this way of validating references does not impact too much the performance of the editor, as multiple documents have to be parsed during validation.

[tedepstein]

I ran into this when testing multi-file BeamUp, which has an invalid reference to a parameter object, where reference to a callback object would be expected. Looks like implementation of the fix is already underway in #358.

I have a couple of comments:

1. Requiring an explicit, specialized user action to validate references seems like a pretty significant usability compromise. Could we have an option, enabled by default, to validate references on save?
2. As of the last time I looked at the spec, or discussed on a spec call, it's still legal to have references to objects that don't reside in their designated /components/... object map.

• References can be to a definition that is used somewhere else in context.
• They can be to an entire file that is a fragment of an OpenAPI document, containing only a single object that conforms to the expected schema.
• Or they can reside somewhere inside a non-OpenAPI file, as long as it is valid JSON or YAML, and as long as the specified JSON Reference resolves to an object that conforms to the expected schema.

So I don't think we can rely on the path as an indicator that a reference is invalid.