RFC-5: Type inconsistency on nested transform input/output

[btbest]

Problematic section:

Omitting input/output: Coordinate transformations MUST specify their input and output coordinate systems using the input and output fields. These fields MUST correspond to the name of a coordinate system or the path to a multiscales group. Exceptions are if the coordinate transformation is wrapped in another transformation, e.g. as part of a sequence, byDimension or bijection. In these cases, the input and output fields MAY be omitted or null.

The rest of the spec is now consistent about transform input/outputs always being objects and never plain strings. This paragraph still requires input/output on nested transforms being plain strings, if not omitted.

I've mentioned before that my opinion is that they SHOULD/MUST be omitted when nested, and that would make this paragraph simple too :)

I'd otherwise recommend to require the input/output of nested transforms to follow the same constraints as their parent (i.e. depending on the multiscale/dataset/scene context).

Also, not sure anymore what to do with this issue. I thought it was a minor phrasing issue, and only realised it's a bit more substantially about actual requirements while trying to phrase out the "simple" fix.

I guess the issue remains as the inconsistency in definitions. The first rule we encounter when reading from the top is:

MUST contain the field output, which is an object with fields name and path. The output field MAY be omitted if the transformation is part of a wrapper transform (i.e., sequence, bijection, byDimension, see details).
MUST contain the field input, which is an object with fields name and path. The input field MAY be omitted if the transformation is part of a wrapper transform (i.e., sequence, bijection, byDimension, see details).

But then as we get down to the "Additional details", the input/output are specified as "MUST be a name/path".

[thewtex]

CC @bogovicj @jo-mueller

[jo-mueller]

@btbest sorry big time for the comms blackout on this issue. To be clear, the problem here is inconsistency on the wording, right? I.e., the terminology used in the spec should go from permissive where general terms are concerned and then increasingly restrictive when we refer to the contextual usages of the input/output fields.

Suggestion:

Omitting input/output: Coordinate transformations MUST specify their input and output coordinate systems using the input and output fields. These fields, if provided, MUST contain an object consisting of name (a coordinate system name) and the path to a multiscales group. If the coordinate transformation is wrapped in another transformation, e.g. as part of a sequence, byDimension or bijection. In these cases, the input and output fields MAYSHOULD be omitted or null.

[btbest]

Yup, what tripped me was really just the wording inconsistency. Your suggestion would basically be fine I think, although blanket-requiring both name and path would make it almost never valid to actually have input/output on nested transforms. Not a problem from my perspective, since I don't think this is ever useful anyway :)

Maybe it would be best to leave the specifics up to the respective other sections:

Omitting input/output: Coordinate transformations generally specify their input and output coordinate systems using the input and output fields. If the coordinate transformation is wrapped in another transformation, e.g. as part of a sequence, byDimension or bijection, the input and output fields SHOULD be omitted or null.

I also noticed that two other place reiterate the "MAY" and would need to be changed to "SHOULD":

top-level coordinateTransforms spec:

MUST contain the field output, which is an object with fields name and path. The output field MAYSHOULD be omitted if the transformation is part of a wrapper transform (i.e., sequence, bijection, byDimension, see details).
(same for the input bullet point)

bijection details:

input and output fields MAYSHOULD be omitted for the forward and inverse transformations. in which case The forward transformation’s input and output are understood to match the bijection’s, and the inverse transformation’s input (output) matches the bijection’s output (input), see the example below.

Considering these notes already exist there - maybe this "Omitting input/output" section is just not really necessary at all..?

[jo-mueller]

Omitting input/output: Coordinate transformations generally specify their input and output coordinate systems using the input and output fields. If the coordinate transformation is wrapped in another transformation, e.g. as part of a sequence, byDimension or bijection, the input and output fields SHOULD be omitted or null.

Sounds good to me 👍

I don't have a strong opinion around the wording of omitting (SHOULD/MAY?). It's not required, and whether it's not required or very much not wanted is secondary to me.

[jo-mueller]

I just realized that the input/output constraints are already well-spelled out above, so we can actually remove this entire section. Above, it says:

• MUST contain the field output, which is an object with fields name and path.
  The output field MAY be omitted if the transformation is part of a wrapper transform
  (i.e., sequence, bijection, byDimension, see details).
• MUST contain the field input, which is an object with fields name and path.
  The input field MAY be omitted if the transformation is part of a wrapper transform
  (i.e., sequence, bijection, byDimension, see details).

I'll do that in a PR and polish the respective section a bit for better readability.