Traits and Specifications for Entity Version queries

[foundrytom]

What

Add Traits and Specifications to MC to replicate the removed entity versions API surface area, as per the mapping in DR017.

Why

DR017 decided that version queries will move to MediaCreation, so we need some standardized traits/specifications to replace them, and documentation to help people understand how to use them.

ACs

• The following versioning related Traits added to the package under the lifecycle namespace:
  • Version: tag [str] (entity, relationship, managementPolicy) Used to resolve versioning tags, indicate that an entity trait set is version managed in managementPolicy and define that a relationship should return references to entities that are other versions of the input reference`.
  • Stable: (relationship) Used to define that a relationship should return entity references that are stable and have no dynamic behaviour based on the locale, or other runtime variability (vlatest, department, user, etc).
• The following base Traits are added to the package under the usage namespace:
  • Entity: (entity) Indicates that a trait set defines an entity type
  • Relationship: (relationship) Indicates that a trait set defines a relationship
• The following result Traits are added to the package under the relationship namespace:
  • Singular (relationship) Indicates that the relationship will only ever provide a single entity reference.
  • Paged (relationship) Indicates that the relationship will provide significant results and so should be used with the paged API .
• The following Specifications are added to the packaged under the lifecycle namespace:
  • EntityVersionsRelationship: { Relationship, Version, Paged } Used to replace entityVersions
  • StableEntityVersionsRelationship: { Relationship, Version, Stable, Paged } Used to replace entityVersions(includeMetaVersions=False)
  • BookmarkableReferenceRelationship: { Relationship, Stable, Singular } Used to replace finalizeEntityVersions.
• All new traits/specifications have detailed documentation as to their usage and properties (if any)
• Documentation with examples (static via txt not runnable with BAL) of how to (as a host):
  • How to check if a given type of entity is versioned
  • How to check if a manager supports querying entity versions.
  • Retrieve information about an entity's version.
  • Retrieve the references for other versions of an entity.
  • Retrieve the reference for specific version tag for an entity.
  • Retrieve a persistable reference that is guaranteed not to change which entity if points to over time/scenarios.

[elliotcmorris]

David and I spoke this over.

Long conversation short, we'd propose 2 changes. Paged (relationship) -> Unbounded (relationship) and BookmarkableReferenceRelationship -> StableReferenceRelationship

The second one was the controversial one, and we went through a lot of iterations, we're not in accord on it really.

We spoke a fair bit about finalizeEntityVersions, and the difference between including/stripping the metaversions and whether that is conceptually stability or not, and ended up going around in circles. An alternative that almost stuck was the word Reified, ie, ReifiedReferenceRelationship: { Relationship, Reified, Singular }, which is technically correct, and dosen't conflate stability and the metaversion behaviour, ... but the word itself is ... unhelpful.

We should just discuss this tommorow, we're going round in circles.

[foundrytom]

Thanks @elliotcmorris agreed on the first, we should discuss the second one see https://github.com/OpenAssetIO/OpenAssetIO/issues/10. Though I think its probably spot on as you have it with Stable.