Remove version number?

[andrewwhitehead]

At the moment each document version has an associated entry hash as well as a numeric version ID. We currently check that each log line contains the next incremented version ID, which is a simple and efficient sanity check on the log file (short of checking the hash chain) and can be easily done by a human.

When it comes to DID resolution, we don't currently have a way to resolve a specific entry hash, as there is no corresponding resolution parameter (although we could add one specific to this DID method). This would provide more security than referencing a version number as it would require producing a hash collision in order to rewrite that reference. While the hl parameter could be used as an integrity check, that parameter would not match the version hash (which covers the metadata, not just the document state).

If we simply use the entry hash as the versionId parameter, then we can operate within the current DID Core spec in terms of the existing resolver parameters. This would simplify the log format, and makes logical sense as it's the first parameter on each line.

A small downside is that the different versions of the document could not be stepped through as easily using a DID resolver interface (ie. with versionId=1, versionId=2). We could populate the nextVersionId resolution metadata in order to allow stepping forward through the versions, though.

[andrewwhitehead]

We could also keep the current scheme, but say that the entry hash is the versionId (when it comes to resolving), and the second field is the versionNumber. We could then add a custom versionNumber resolution parameter to allow lookups by that field, if needed.

[andrewwhitehead]

Third (and favourite) proposal: we can simply combine the version number and entry hash to create the versionId. Each line would then start with something like 1-4fbja27mgf0bumtbg2b4hbzqc2ux9a9crrqx7w6cfnd97k9u7k5g.

A resolver could then support multiple formats for the versionId parameter: ?versionId=1, or ?versionId=1-<entryHash>, or even ?versionId=1-<entryHash prefix>. This format would also make more logical sense when talking about a 'minimum' version ID for resolution. And when encountering a versionId in the wild, it would be more straightforward to find the specific line in the log short of scanning through all of the hashes for a match.

[swcurran]

Assuming this is needed, and it does kinda make sense, I definitely like the third option. I was thinking that the first representation, ?versionId=1 was just the unique prefix, but it isn’t, as then ?versionId=10 could be used for ?versionId=1. So it does have to use up to and excluding the “-“.

But I’m overall good with it.

[andrewwhitehead]

Yes, essentially if the versionId parameter is set to just an integer, then it should append a '-' when matching. And a valid filter value should always start with an integer.

[brianorwhatever]

I actually prefer option 2 where the hash is the versionId and the number is versionNumber. Option 3 seems to be accomplishing the same thing with more parsing of things from the string

[andrewwhitehead]

I mentioned the minimum version ID parameter, here's what it might look like with the 3rd form, which I like since it combines the version number and integrity protection:
did:tdw:domain.example_2fbja27mgf0bumtbg2b44fbja27?minVersionId=22-4fbja27mgf0bumtbg2b4

[brianorwhatever]

Ok sure I see the benefit of this 👍