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]

Option 1 is easier to be documented but it is less practical for users.
Option 2 requires to distinguish between root Salad documents and imported Salad documents (those that are included through the $import statement), clearly define the two concepts, and state that a Salad document can be used as a root Salad document only if it specifies a saladVersion field. Conversely, if imported documents do not specify a saladVersion they inherit the one from their root Salad doument.

Another problem here is dealing with mixed versions, as in CWL. What if a Salad 2.0 document imports a Salad 3.0 document, and viceversa? Is this something that Salad allows?

[tom-tan]

Another problem here is dealing with mixed versions, as in CWL. What if a Salad 2.0 document imports a Salad 3.0 document, and viceversa? Is this something that Salad allows?

I prefer to take a similar approach as CWL.
That is,

• Implementation allows a root document to import documents with newer and older saladVersion, and
• Each imported document is validated and processed as its declared saladVersion rather than its parent saladVersion.

---

Here is the corresponding description in CWL v1.2.

Implementations should allow workflows to reference documents of both newer and older CWL versions (up to the highest version of CWL supported by that implementation). Where the runtime environment or runtime behavior has changed between versions, for that portion of the execution an implementation must provide runtime environment and behavior consistent with the document's declared version. An implementation must not expose a newer feature when executing a document that specifies an older version that does not include that feature.

[tom-tan]

There is a technical issue for it.
The current code generator seems to hold saladVersion only at the root level rather than schema object level.

To fix this issue, we may need to introduce saladVersion for each schema object in addition to the root explicit context.

[mr-c]

@tom-tan Is this fixed?

[tom-tan]

Not yet fixed because there is a corner case to be discussed as shown below:

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 and I prefer the option 2 but it needs changes that may affect all the code generators.
There are several ways for option 2.

• Introduce saladVersion for each schema object as mentioned above, or
• Implement schemaSaladUpgrader such as cwl-normalizer
  • The behavior of typeDSL blocks this option. Related: Backported schemas to codegen branch may break portability between platforms due to handling typeDSL #863

I prefer to introduce a upgrader for schema salad after fixing the typeDSL issue.
What do you think?

[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.

[GlassOfWhiskey]

I totally agree to go with option 2 here.

[tom-tan]

I fixed the row 212 to take the option 2.