Add 'isLatestVersion' to VersionableEntity

Description

May have missed something in the REST docs, but as far as I can tell, there's no documented way to determine if a table version is 'living' and has not been manually created, or if it is a manually created version with frozen data.

'Living' versions always have the (unique) label "in progress", but I don't want to rely on undocumented behavior to verify that a table version is current/most recent.

Environment

None

Activity

Show:
Xavier Schildwachter
March 15, 2021, 4:51 AM

Verified fixed 348.0-x.

Nick Grosenbacher
March 10, 2021, 8:37 PM

Summary of meeting on 3/10

I’ll create Jira tickets for each issue and link them in this comment.

There are 3 main questions at play here, and I think these are the answers that we settled on

  1. Should we return the latest, mutable version for tables and views in GET /entity/{id}/version? Yes, for consistency’s sake, because we do this for Files and other versioned entities.

  2. How do we communicate the nuances of versions to users, especially that the latest version is mutable? This is something we currently do inadequately for Files, and don’t attempt to do for Tables and Views. This needs further work.

  3. Should we allow users to create references designed to be immutable (e.g. DOIs, Provenance) on mutable entities? Users should not be able to explicitly reference a version that is mutable

Showing/Communicating Versions

GET /entity/{id}/version returns the current version for Files, but does not do so for Tables and Views. We suspect that the original reasoning for hiding the mutable, current version from the version API for tables and not files seems to be for UI/UX reasons in the browser. With the isLatestVersion flag, there is no reason to omit them. The browser client can choose to hide them if appropriate.

Ultimately, the web client must improve how we communicate the difference in mutability between current and previous versions. Since we need to do this for files, we should do it for tables as well, just to be consistent.

References to Mutable Entities

DOIs, Provenance, and possibly other tools in Synapse are designed to handle use cases where data/metadata should be immutable. We have generally given users the flexibility to use these tools on mutable entities, but we should restrict them in such a way to prevent confusing behavior. We can maintain the ability to create unversioned references to entities (e.g. syn123). Versioned references to entities in DOIs and Provenance should only work on immutable versions (e.g. the current version of syn123 is version 3).

As an example, consider a versioned entity, syn123. Suppose the entity has two immutable versions, syn123.1 and syn123.2, and one current, mutable version, syn123.3.

If a user wishes to make a DOI that refers to the mutable entity, they can simply mint a DOI for syn123. At this time, they should not be able to create a DOI for syn123.3, because it appears immutable, but is actually not. To create an immutable reference, they can mint DOIs for syn123.1 and syn123.2.

If the user wishes to create an immutable reference to syn123.3, they should have to create a new version (syn123.4), which locks syn123.3, and then mint the DOI for syn123.3.

The web interface and documentation should inform the user, then, that ‘dot-references' that don’t refer to the current version are immutable, and ‘non-dot’ references are mutable.

Marco Marasca
March 10, 2021, 6:05 PM

Views and table versions are fundamentally different from files, but I’m not sure what was the rationale to exclude the current “living” version from the list of versions in the /version API (we specifically skip the latest revision for tables and views) when we can actually access it using its revision number. any thoughts?

Xavier Schildwachter
March 9, 2021, 9:20 PM

Agree, I think we just have to decide what we’re allowed to do on the latest version, given that it’s not locked on views. In this case, I would say you cannot create a DOI explicitly on the latest version of a view (but you can always create a non-versioned DOI).

My issue with versionInfo() is that I think it should include the current (unlocked if view) latest version.

Nick Grosenbacher
March 9, 2021, 9:08 PM

cc for visibility/any thoughts about this behavior ?

Done

Assignee

Nick Grosenbacher

Reporter

Nick Grosenbacher

Validator

Xavier Schildwachter

Priority

Major

Labels

None

Development Area

None

Sprint

None

Fix versions

Release Version History

None

Story Points

None

Epic Link

None

Slack Channel

None