[Traits] Add versioning traits/specifications

Adds traits and specifications that can be used to replicate the old
"versioning" API methods from the core API. These were recently removed
in favour of domain specific definitions such as these.

We opted to add base traits for 'usage' to the package. These should be
composed with the other relevant traits when defining a specification to
allow runtime introspection of the trait set. Amongst other uses, this
helps managers in their implementation of methods such as
`managementPolicy` where they need to be able to determine the nature of
the query.

For relationships, this also adds traits that define the expected
cardinality of the result references. This helps inform a host whether
they should be using the paged API methods.

Part of OpenAssetIO#48

Signed-off-by: Tom Cowland <[email protected]>

Author: foundrytom

RELEASE_NOTES.md

@@ -11,6 +11,10 @@ v1.0.0-alpha.x
   Added cmake variables `OPENASSETIO_MEDIACREATION_GENERATE_PYTHON` and
   `OPENASSETIO_MEDIACREATION_PYTHON_SITEDIR` to support this.
 
+- Added traits and specifications to define and query entity versioning
+  information.
+  [#48](https://github.com/OpenAssetIO/OpenAssetIO-MediaCreation/issues/48)
+
 v1.0.0-alpha.6
 --------------
 

traits.yml

@@ -4,6 +4,22 @@ package: openassetio-mediacreation
 description: Well-known Traits and Specifications for use in OpenAssetIO
   hosts and managers.
 traits:
+  usage:
+    description: >
+      Base traits that scope a trait set for use within a specific
+      context, such as resolution or relationship queries. Exactly
+      one of these should be included in any given Specification.
+    members:
+      Entity:
+        description: The trait set defines qualities of an entity.
+        usage:
+          - entity
+      Relationship:
+        description: >
+          The trait set defines a relationship between one or more
+          entities.
+        usage:
+          - relationship
   content:
     description: Traits related to abstract content.
     members:
@@ -24,7 +40,7 @@ traits:
           location:
             type: string
             description: >
-              The location of the entities external content.
+              The location of the entity's external content.
 
 
               This must be a valid URL, so special characters need to
@@ -68,6 +84,98 @@ traits:
                   of an asset in an 'open recent' menu.
               - `"Sequence 003 [ Dive / Episode 1 ]"` for a sequence in
                  a hierarchy as a window title.
+  lifecycle:
+    description: >
+      Traits that are concerned with describing aspects of the lifecycle
+      of an entity, such as versioning.
+    members:
+      Version:
+        description: >
+          Describes a specific version of an entity.
+
+
+          A version is defined as a revision or iteration of what is
+          otherwise the same logical entity. If supported by a manager,
+          versions are created when new data is published to an existing
+          entity. Not all managers may version all types of entity.
+
+
+          There is no requirement for version to be a singular atomic
+          series, managers may wish to support "meta versions", such as
+          'vLatest' or similar, or provide multiple parallel versioning
+          streams.
+
+
+          This trait can be used in several places:
+           - When resolved, the manager should provide information about
+             the version of the referenced entity. This trait should only 
+             be imbued if the target entity is considered versioned by the
+             manager, and it can populate the stableTag property.
+           - When responding to managementPolicy for an entity trait set,
+             the manager should imbue this trait if that type of entity
+             is version managed by the manager (not all managers version
+             all types of entity).
+           - When used within a relationship query, this trait indicates
+             that the returned entities should be constrained to other
+             versions of the logical entity targeted by the reference.
+        usage:
+          - entity
+          - relationship
+          - managementPolicy
+        properties:
+          specifiedTag:
+            type: string
+            description: >
+              An unambiguous identifier (tag) for the specific version of 
+              an entity targeted by a specific reference.
+
+
+              Examples of version tags include "1", "v2", "latest".
+
+
+              If the reference itself does not contain a version
+              specifier and relies on dynamic behaviour, then this should
+              be left empty.
+          stableTag:
+            type: string
+            description: >
+              The tag (see 'specifiedTag') targeted by the reference once
+              meta-versions or other dynamic behaviour is applied.
+
+
+              If, for example, references without an explicit version
+              yield the most recent, then this should be set to
+              the tag of that version. When referencing some other
+              semantic state (eg. approval), this should be set to the
+              tag of the concrete version that matches the specific
+              state.
+
+
+              Examples of stable version tags include "1", "v2".
+
+
+              This property should always be set when the Version trait
+              is imbued as part of a resolve response. If the entity is
+              not versioned, then the trait itself should not be imbued.
+      Stable:
+        description: >
+          Defines that the entity references returned from a
+          relationship query with this trait should be devoid of any
+          dynamic behaviour. This includes concepts such as
+          meta-versioning or context-specific variation that results
+          logically different data being supplied.
+
+
+          This is generally used to snapshot/bookmark specific
+          configurations to avoid temporal instability and/or ensure
+          processes are repeatable.
+
+
+          Note: This does not include variations such as regional
+          adaptation of the LocatableContent trait, where the underlying
+          data remains the same.
+        usage:
+          - relationship
   managementPolicy:
     description: Traits used in a Manager's managementPolicy response.
     members:
@@ -129,6 +237,23 @@ traits:
           determine a suitable output location.
         usage:
           - managementPolicy
+  relationship:
+    description: Traits specific to qualities of a relationship.
+    members:
+      Singular:
+        description: >
+          The relationship should return at most one reference for each
+          input. Unless otherwise qualified, relationships are
+          considered one-to-many.
+        usage:
+          - relationship
+      Unbounded:
+        description: >
+          The relationship may return large numbers of results for each
+          input, and so must be used with the paged API methods, such as
+          Manager.getWithRelationshipPaged.
+        usage:
+          - relationship
   auth:
     description: Traits related to authentication and authorization.
     members:
@@ -143,3 +268,58 @@ traits:
             type: string
             description: >
               Contents of the token.
+specifications:
+  lifecycle:
+    description:
+      Specifications that are concerned with describing aspects of the
+      lifecycle of an entity, such as versioning.
+    members:
+      EntityVersionsRelationship:
+        description: >
+          A relationship between alternate versions of the same logical
+          entity. This may include unstable versions such as "latest".
+        traitSet:
+          - namespace: usage
+            name: Relationship
+          - namespace: relationship
+            name: Unbounded
+          - namespace: lifecycle
+            name: Version
+        usage:
+          - relationship
+      StableEntityVersionsRelationship:
+        description: >
+          Retrieves references to alternate stable versions of the same
+          logical entity. This will not include unstable versions such
+          as "latest".
+        traitSet:
+          - namespace: usage
+            name: Relationship
+          - namespace: relationship
+            name: Unbounded
+          - namespace: lifecycle
+            name: Version
+          - namespace: lifecycle
+            name: Stable
+        usage:
+          - relationship
+      StableReferenceRelationship:
+        description: >
+          Retrieves a stable reference to the supplied entity that is
+          guaranteed to always point to that specific entity and version.
+
+
+          This will apply and remove any dynamic behaviour such as
+          "latest version" or other context-sensitive behaviour. The
+          result may be used as a persistent bookmark (such as in an
+          "open recent" menu), or to snapshot the specific entities used
+          by a process for archival.
+        traitSet:
+          - namespace: usage
+            name: Relationship
+          - namespace: relationship
+            name: Singular
+          - namespace: lifecycle
+            name: Stable
+        usage:
+          - relationship