@ethanresnick, this is in conflict with the base spec. Not sure what to do or how to accommodate this in any other way. Perhaps you have some ideas?

@gabesullice I'd be happy to just define these links in the base spec as a temporary workaround. Note also that the base spec's current approach is that, if an array of links is allowed, an array should be required (like we did for profile) to not further proliferate the number of links cases that clients have to handle.

So, the base spec language would go under the resource links section, and could say something like:

If present, this object MAY also contain an array of links as the value for any of the following keys: latest-version, working-copy, predecessor-version, successor-version, [etc]. Links at any of these keys point to resources that are related to the resource object according to the IANA link relation corresponding to their key name.

That'd be great :)

bump.

@ethanresnick Rather than calling out those 4 specific link relations, perhaps it'd be better to generalize that to something like:

Links with a key that matches a registered link relation type which allows multiple values are allowed to have a value that is not a link, but an array of links.

While I agree that calling out specific link relations "smells" a bit, I would not like to see the concept of links object keys as link relations furthered in the spec. Links can have more than one link relation and this pattern makes that more challenging to fix in later iterations of the spec.

[Spec compliance] Having multiple resource objects in data with the same type/id is sort of a spec violation. I say "sort of" because the spec technically says only that:

A compound document MUST NOT include more than one resource object for each type and id pair.

So, if this version history response isn't a compound document, you're technically in the clear. But the intent has always been that this restriction should apply to all responses. (I can't find the link for that now, but it's come up in conversations with @dgeb over the years.)

Note: I've also proposed removing the restriction altogether.

It is not intended to be a compound document.

I don't think this profile can impose a requirement that ids contain version information. I think most systems store revision IDs separately from the entity ID. In our case, we use UUIDs for id and revision IDs are auto-incrementing integers. We'd have to make some wonky concatenation of these to put revision IDs into our resource object IDs and I don't think this profile should define how to do that.

I've been considering adding a recommendation that implementations add information to resource object's meta object that matches their most-specific version negotiator. For example, in our case (since we implement the id negotiator) we'd have:

{
  "type": "article",
  "id": "some-long-uuid",
  "meta": {
    "resourceVersionId": 42
  },
  "links": {
    "self": "/articles/some-long-uuid?resourceVersion=id:42"
  }
}

The rule would be something like:

It is RECOMMENDED that resource object's meta object contains a member whose name is resourceVersion appended by the upper-camel-cased name of the version negotiator used in the resource object's self link. The value of this member should be the the version identifier used in the resource object's self link, excluding its first segment, and it MUST NOT begin with a colon.

I just read the #824 PR. I like the idea of a revision key. This profile could adopt revision as a meta object member and require that it must be equal to the complete version identifier in a resource object's self link (or a valid one if a self link is not provided).

@e0ipso @wimleers thoughts? ^

I also like a revision key (or version). This would also address @ethanresnick's "sort of" spec violation concern: if present, then it would be a higher specificity resource identifier (or perhaps even an intra resource identifier?): just like [type, id] uniquely identify a resource, [type, id, version] uniquely identifies a version of that resource.

Taking this further, there are multiple potential axes along which a variant of a resource can exist: version (or revision) is one, lang (or translation) is another. I think those are the two clearest, strongest use cases. It's possible to think of others though, such as localization.

I'd say versioning and translations are the two most common needs. I think we should keep both in mind if we're going to go this direction.

But for the sake for consistency and optionality (to ensure backwards compatibility & evolvability), I think we should consider not adding a version key, but a variant key. Under variant, this profile could then reserve the version key. A translation profile could reserve the translation key. This also opens the door for multiple versioning profiles if there is the need.

After having written this, I continued reading #824, to make sure I didn't miss anything. I think my variant proposal would actually address the "identity" concerns that @ethanresnick raised in
#824 (comment)? :)

Crazy thought... maybe we could we extract a variant profile out of this profile? Re-minting resource_version as resource_variant. The "negotiation mechanism" would become the variant negotiation mechanism. Then you could have something like ?resource_variant=lang:en-US or resource_variant=revision:id:42 or ?resource_variant=revision:rel:working-copy.

In fact, if this variation scheme were part of the base spec, then revisions, translations, etc could just enhance that mechanism for its needs.

@wimleers noted very important thing. It's not enough to add version of the resource because each resource could have many translations and each translation could have it's own versions.

Word locale could be considered for translation purposes instead of lang abbreviation.

[Design feedback/interoperable implementations review requirement] If I'm understanding correctly, each server implementation can define its own version negotiators, with multiple servers using the same negotiator name in different ways (and no central registry). That seems not great for interoperability. It would also seem to mean that no other version negotiators can ever be standardized as part of this profile, because they could conflict with existing implementations. Is that really what you want?

My gut instinct would be to make this profile's spec the canonical list of all legal version negotiators. Then, you can add more over time to this spec as they're requested. To support people who really need to use a version negotiator that isn't part of your profile, you could have some set of negotiator names/schemes/namespaces that are allowed to have implementation-specific meanings.

What I've done is applied the implementation-specific query parameter name constraints as a version negotiator constraint and added a mechanism for adding new negotiators to the profile.

Changes here: f0d73db

Elsewhere, @e0ipso suggest that we use URIs but I think this is sufficient. @e0ipso, WDYT?

cc: @wimleers cause it's his inbox that I suggested too 😛

I'm OK with that. However I still think that doc curies offer a lower barrier of entry. One could document the new crazy negotiator in their blog and have the server implementation point to that, instead of adding it here.

Many will just not go through the trouble to send their idea to some email addresses and be potentially blocked by them.

I guess I wanted to discourage non-standard negotiators being used as a standard and keep them isolated. My feeling was that sending an email saying "hey, I'd like to add a negotiator like this..." doesn't seem like a super high barrier. In some ways, it's even less difficult than opening a PR.

What if we add this:

Note: Don't be shy! New version negotiators are more than welcome, the editors want to see this profile proliferate and that means accepting versioning strategies like yours!

@e0ipso, would that work?