Add description of saladVersion

[tom-tan]

This request clarifies the existence of saladVersion, that is currently undocumented.

I'm afraid that added description may conflict with the existing description:

• Added:

  Each document must declare the saladVersion of that document

• Existing description that may conflict with added one:

  A Salad document must consist only of either a single root object or an array of objects.

Please let me know if there are better descriptions for it.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 83.05%. Comparing base (19ac14b) to head (50107f0).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #861   +/-   ##
=======================================
  Coverage   83.05%   83.05%           
=======================================
  Files          22       22           
  Lines        4886     4886           
  Branches     1326     1326           
=======================================
  Hits         4058     4058           
  Misses        548      548           
  Partials      280      280           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[GlassOfWhiskey]

What happens to saladVersion in case of an array of objects? Each object must provide its own saladVersion? @mr-c @tetron

[tom-tan]

At least, it is necessary to declare saladVersion at the root level.
Otherwise, we cannot decide whether to allow the newly introduced features such as nested typeDSL and map/union types.

I guess there are two options to declare saladVersion for the array of objects.

1. As @GlassOfWhiskey mentioned, each object in the array must declare saladVersion
2. I assume that the most root level documents use the explicit context. If my assumption is correct, it is reasonable to enforce saladVersion at the root level and to allow the imported documents inherit the saladVersion in the parent level.

[GlassOfWhiskey]

This must here collides with the may clause at row 212.

Option 1: substitute this clause with

Each document may declare the saladVersion of that document. Implementations may validate against the document's declared version.

Option 2: substitute row 212 with

If a document consists of a root object, this object must contain the
field saladVersion and may contain the fields $base, $namespaces,
$schemas, and $graph:

[tom-tan]

I prefer the option 2.
The option 1 makes difficult to solve #863 in the specification level.