Impose an order on qualifiers?

[zvr]

In the current state of specification all qualifiers are appended in an arbitrary order.

I propose we consider having a fixed order in which they could appear, if present.

Otherwise, checking two SWHIDs for identity always needs to have the complete parsing.

For example, are those two the same? (copied from the SWHID documentation)

swh:1:cnt:4d99d2d18326621ccdd70f5ea66c2e2ac236ad8b;origin=https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git;visit=swh:1:snp:d7f1b9eb7ccb596c2622c4780febaa02549830f9;anchor=swh:1:rev:2db189928c94d62a3b4757b3eec68f0a4d4113f0;path=/Examples/SimpleFarm/simplefarm.ml;lines=9-15

and

swh:1:cnt:4d99d2d18326621ccdd70f5ea66c2e2ac236ad8b;anchor=swh:1:rev:2db189928c94d62a3b4757b3eec68f0a4d4113f0;lines=9-15;origin=https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git;path=/Examples/SimpleFarm/simplefarm.ml;visit=swh:1:snp:d7f1b9eb7ccb596c2622c4780febaa02549830f9

[zacchiro]

The argument in favor of mandating an order is clear and compelling (= it's easier to compare SWHIDs with a fixed order).

The converse argument is that if we mandate an order it is harder to produce correct SWHIDs, i.e., you cannot simply append key=value pairs as you figure out you need them; you need to sort them in the right order.

So, ultimately, it boils down to whether we want to favor ease of production vs ease of consumption or vice-versa.
Arguably, there will be many more use cases (and hence more code) out there that consume SWHIDs than use cases (hence code) that produce them.

Based on this, I'm (mildly) in favor of mandating, with a MUST in the spec, a strict ordering on qualifiers.

(To mitigate the impact of this, we might add a MAY provision that consumers of SWHIDs can try to reorder qualifiers upon parsing, if they want to, with no obligation of doing so.)

[rdicosmo]

I see the interest of having a canonical form, with a strict order on qualifiers. But if the canonical form is mandated, any conformant implementation will need to parse the full SWHID to check the order, and decide what to do with a SWHID with out of order qualifiers.

The usual approach, hinted at by @zacchiro above, is "be liberal in what you consume and strict in what you produce", so the implementations should just reorder the qualifiers before internal consumption, instead of rejecting non conformant SWHIDs.

In practice all this will not make much of a difference in terms of implementation: no matter what we recommend, there will be non canonical SWHIDs around, so one will not be able to compare them without a previous validation phase, and that phase can or need in any case canonicalize the input before processing.

Any more thoughts on what the best path forward could be?

[zvr]

My initial proposal for a strict order in qualifiers was triggered by the real-use case of comparing two SWHIDs to determine whether they are "equal" ("equivalent" or whatever term we might choose to use). If there is an order, then it's easy to compare the strings and determine whether they are the same.

I'm not sure I agree with @rdicosmo's statement

no matter what we recommend, there will be non canonical SWHIDs around

If we specify an order, why would there be SWHIDs not adhering to the standard? They might as well have other changes.

But anyway, if we don't specify an order, we have to write something about how to determine whether two SWHIDs are the same.

Again, @rdicosmo writes:

the implementations should just reorder the qualifiers before internal consumption

Where do we specify that reordering qualifiers does not "change" a SWHID? That it's a valid transformation and results in an "equal"/"equivalent" representation of the same SWHID?

[rdicosmo]

My initial proposal for a strict order in qualifiers was triggered by the real-use case of comparing two SWHIDs to determine whether they are "equal" ("equivalent" or whatever term we might choose to use). If there is an order, then it's easy to compare the strings and determine whether they are the same.
anyway, if we don't specify an order, we have to write something about how to determine whether two SWHIDs are the same. Where do we specify that reordering qualifiers does not "change" a SWHID? That it's a valid transformation and results in an "equal"/"equivalent" representation of the same SWHID?

Let's get back briefly to the motivation of comparing two SWHIDs.

If we want to know whether the software artifact denoted by a SWHID is the same object (bit by bit), it's enough to compare the code SWHIDs, which is trivial (qualifiers do not play any role here).

If we want to know if two SWHIDs denote the same software artifact (or fragment thereof) in the same context, than we need to also compare the qualifiers: two SWHIDs will be equivalent if they have the same qualifiers (qualifiers are optional), with the same values. For example, they both have an anchor qualifier, with the same core SWHID as value, and they both have a lines qualifier with the same value. The order in which the qualifiers appear in the textual representation of the SWHIDs plays no role in determining their equivalence, so I am not super attracted to the idea of imposing a specific order, but I can live with that if we specify that implementations should be liberal in what they accept and strict in what they produce.

To sum up, we have two options:

• recommend (but do not impose) a canonical order of qualifiers (I would go for origin->visit->anchor->path->lines/bytes), and indicate the process to compare two SWHIDs: reorder the qualifiers, if needed, into the canonical order, and then compare the resulting string.

• impose the canonical order, and indicate that conformant implementations may accept non conformant SWHIDs by converting them into conformant ones by reordering the qualifiers

Any more thoughts?

[zacchiro]

To sum up, we have two options: - recommend (but do not impose) a canonical order of qualifiers (I would go for origin->visit->anchor->path->lines/bytes), and indicate the process to compare two SWHIDs: reorder the qualifiers, if needed, into the canonical order, and then compare the resulting string. - impose the canonical order, and indicate that conformant implementations may accept non conformant SWHIDs by converting them into conformant ones by reordering the qualifiers

I think that in practical terms for implementers these two options will be equivalent. Because any implementation that aims to be "good", even in the stricter case (2), will want to implement the reordering to be nice to its users. So I'm now erring in favor of (1): not impose an order, but document precisely how to reorder qualifiers in case you need to syntactically compare SWHIDs.

[zvr]

After going back-and-forth between the two alternatives, I am now also in favor of the first one (no specific order, but we explain in prose).

We essentially need to add (in a different wording, perhaps), the two paragraphs that @rdicosmo wrote in the comment above, starting with "If we want to know..."

[rdicosmo]

Thanks @zacchiro and @zvr for the extensive discussion, I will draft a PR to implement (1) as suggested.

[rdicosmo]

Done in #29

[zvr]

Closing this, as #29 has been merged