Establish guidance for valid/invalid configuration

[radeksimko]

Context

Semantic highlighting comes with a few goals:

1. fill in the gaps created by more limited static highlighting grammars, such as TextMate which cannot account e.g. for nesting
2. tell apart valid and invalid configuration

We are mostly satisfying the 1st goal currently, but the 2nd one is mostly suppressed through us matching the semantic token types with the token types used by the static TextMate grammar.

One reason we suppress it is because we don't yet cover the whole language/schema which would lead to confusions when mis-highlighting unsupported or partially supported language parts.

The other reason (which this issue focuses on) is broad lack of agreement around what makes configuration invalid and where lies the border between diagnostics and semantic highlighting (or how much they overlap).

A few example questions to set the scope:

• (type compliance) If attr is of type string, how should attr = 42 or attr = [1, 2] be highlighted?
• (attribute metadata compliance) If attr is of type list with MaxItems: 3, how should attr = [1, 2, 3, 4] be highlighted?
• (compliance with best practices) Quotes are usually used to enclose map keys and avoided for object attributes. How should mymap = { foo = "bar" } and myobj = { "foo" = "bar" } be highlighted?

Other LSP features, such as completion, hover, go-to-definition faces similar or same questions - the broader question is should they work in various "invalid" contexts?

Proposal

Establish & document guidance on what we consider valid/invalid in semantic highlighting, completion, hover, go-to-* etc., what should only be reported as diagnostic (and of what level) and where there can be overlap.