[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.