Deprecate schema-less specs in Vega

[alexwizp]

Closes #30951

Release Notes:

We decided to don't support Vega visualizations without a $schema specification property.

Before that PR in case if user did not provide the $schema property, we set the default value which was hardcoded in Vega code (

for Kibana < 7.9 it was https://vega.github.io/schema/vega/v3.json
for Kibana 7.9 it was https://vega.github.io/schema/vega/v5.json

) and then rendered visualization with a warning message.

This introduced certain difficulties when updating the version of the Vega library as a result we decided to change this approach.

Now all Vega Specs should contain $schema param. In case of no $schema param user should see an error message

Please see Vega Doc get more information about this property.

Checklist

Delete any items that are not applicable to this PR.

• Any text added follows EUI's writing guidelines, uses sentence case text and includes i18n support
• Documentation was added for features that require explanation or tutorials
• Unit or functional tests were updated or added to match the most common scenarios
• This was checked for keyboard-only and screenreader accessibility
• This renders correctly on smaller devices using a responsive layout. (You can test this in your browser
• This was checked for cross-browser compatibility

For maintainers

• This was checked for breaking API changes and was labeled appropriately

[nyurik]

I think this is a good change. One note -- make sure the error offers "copy/pastable" schema strings, e.g. say "for Vega, use "$schema": "...", and for Vega-Lite use ... . Could also add some text saying that this link does not need to be accessible, and will only be used for describing Vega code (i kept getting this question, esp for the air-gaped customers)

[alexwizp]

@nyurik np, message was updated

[elasticmachine]

Pinging @elastic/kibana-app (Team:KibanaApp)

[nyurik]

@nyurik np, message was updated

@alexwizp thanks, but I think we should iterate on it a bit more -- something like this would probably be better, as it would require less thinking (always a good thing™). We could try to get someone from the docs team involved - they are very good at this sorts of things :)

The "$schema" field is missing.
Add one of these lines to your code, depending if you use Vega or Vega-Lite:

   "$schema": "https://vega.github.io/schema/vega/v5.json"
   "$schema": "https://vega.github.io/schema/vega-lite/v4.json"

Note that the URL does not need to be accessible from your environment,
and will only be used to identify the required Vega or Vega-Lite engine.

[timroes]

I think we should not try to put specific versions in there. It just have shown in the past those get outdated. Also if you're up to writing a Vega specification, finding that $schema URL should be the least of your problems, or put otherwise: If you're not able to get the schema URL, you'll most likely not have much success with the rest of your spec.

I'd suggest we might instead just add some links to the vega documentation that talks about the spec instead, and make the message something like the following:

Your specification is missing a "$schema" field. You need to add a valid [vega](https://vega.github.io/vega/docs/specification/#top-level-specification-properties) or [vega-lite](https://vega.github.io/vega-lite/docs/spec.html#top-level) schema. The schema URL is an identifier and does not need to be accessible from your browser.

I think the current text is a bit too verbose, and we should stick to our writing principles or being clear and concise.

I am still not happy with the last sentence "The schema URL is an identifier and does not need to be accessible from your browser.", since "browser" sounds like the server could access it, "environment" is imho not a clear enough term.
cc @gchaps Could you help out with phrasing this, that the "URL" will never be "loaded" or tried to access by Kibana or your browser, but is really just an ID in the form of a URL?

[gchaps]

Does this work?

Your specification requires a $schema field with a valid URL for Vega or Vega-Lite. The URL is an identifier only. Kibana and your browser will never access this URL.

Also, we have specific wording for what experimental means. Do you want to add some wording around that in the message?

This functionality is experimental and is not subject to the support SLA of official GA features. For feedback, please create an issue in Github.

[nyurik]

I'm not sure we should include the language about the experimental nature of the Vega vis into this (or other) error or warning messages about specific problems.

[alexwizp]

@elasticmachine merge upstream

[alexwizp]

thank you @gchaps. An error message was updated

[alexwizp]

@elasticmachine merge upstream

[timroes]

@gchaps the experimental banner is the same for all vis, we can change it to that text, but should do that in a separate PR unrelated to Vega (especially since Vega will anyway be made GA in this release :D)

I've created #74354 for it.

[alexwizp]

@timroes @stratoula could you please review it?

[alexwizp]

@elasticmachine merge upstream

[alexwizp]

@elasticmachine merge upstream

[timroes]

Markdown does not seem to be parsed here, so there is no use in using markdown here, we instead should just make this a regular text:

Your specification requires a {schemaParam} field with a valid URL for Vega (see {vegaSchemaUrl}) or Vega-Lite (see {vegaLiteSchemaUrl}). The URL is an identifier only. Kibana and your browser will never access this URL.

[timroes]

Left one last comment about getting rid of the Markdown. Otherwise looks good to me.

[kibanamachine]

💚 Build Succeeded

• continuous-integration/kibana-ci/pull-request
• Commit: d8b2ac9

Build metrics

async chunks size

id	value	diff	baseline
visTypeVega	1.4MB	+278.0B	1.4MB

History

• 💚 Build #67181 succeeded 07680a7
• 💚 Build #67105 succeeded 9ca2473
• 💛 Build #66565 was flaky e1e3eb6
• 💚 Build #66400 succeeded 570cab1
• 💔 Build #66370 failed c9e8e1c4bdba3dff3a0d199e610028ba349cbe7b

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream