Documentation is incomplete

[pentzzsolt]

We're trying to set this plugin up, and there is something in the configuration that we don't understand how it works. The SchemasSettings interface expects a fileMatch field, which is documented as:

A Uri file match which will trigger the schema validation. This may be a glob or an exact path.

We're not sure what that means exactly. 🤔 Can you please elaborate?

[remcohaszing]

Sorry, but I don’t understand what’s unclear about it. I would love to improve it though, especially considering the number of 👍s on this issue. Would something like this clear things up?

An array of glob patterns to match the model uris to validate.

[pentzzsolt]

This may just be my shortcoming, but I don't understand what this means. I found the following example in the README:

import { editor, Uri } from 'monaco-editor';
…

const modelUri = Uri.parse('a://b/foo.yaml');

setDiagnosticsOptions({
  …
  schemas: [
    {
      // Id of the first schema
      uri: 'http://myserver/foo-schema.json',
      // Associate with our model
      fileMatch: [String(modelUri)],
      schema: {
        …
      },
    },
    …
  ],
});

What does Uri.parse do? What do I pass to it? In schemas, there is a uri field, does that point to the schema JSON I want my input to be validated by? And how does fileMatch change the behavior?

I think some more detailed, real-world examples would help!

[remcohaszing]

Uri is an integral part when dealing with Monaco editor, regardless of whether you use monaco-yaml or not. I think it should be safe to assume people know this when they integrate monaco-yaml.

I definitely see the value of a more real-world example! I’m thinking of 2 schemas: A GitHub actions schema to show how to use remote schemas and globs, and a custom person schema to match a more realistic resource using a custom schema. Would that help?

[pentzzsolt]

Uri is an integral part when dealing with Monaco editor, regardless of whether you use monaco-yaml or not. I think it should be safe to assume people know this when they integrate monaco-yaml.

Well, I had no idea how this would work. I inherited a codebase in which Monaco was already integrated. I don't think something like this is rare. I'd suggest maybe linking to the corresponding documentation of Monaco wherever appropriate in your implementation, what do you think?

I definitely see the value of a more real-world example! I’m thinking of 2 schemas: A GitHub actions schema to show how to use remote schemas and globs, and a custom person schema to match a more realistic resource using a custom schema. Would that help?

Yea, that sounds like a good start!