I think "the most appropriate" is unnecessarily vague. Can't we change the most appropiate version to the requested version?

[Design] My biggest piece of feedback about this profile is that it should probably also consider how to update resources (e.g., how to create a new working copy based of an existing one, or change the default version, or reject a PATCH if the resource's working copy has changed from the working copy that the client is trying to apply its PATCH to, etc). When resource versions have come up in the past, these updating use cases were actually the primary motivation, so not addressing them here would seem like a major missed opportunity that might be hard to remedy once this is published.

I've put this comment on this paragraph, though, because I think the considerations about updating bear directly on what the self link should be. If the self link is URL of a specific revision (as it seems to be here), then a PATCH to that link would be interpreted as updating the revision -- which should probably usually be immutable -- and creating a new revision would become a POST (or a patch to the default version's URL). So that's something to think about.

Also, if each revision is it's own HTTP resource (i.e., has its own URL), then the JSON:API id would usually be different for each revision too (e.g., so a PATCH actually could target the revision), though I suppose it wouldn't have to be. Distinct ids could cause lots of problems, though, because presumably only the default version's type/id would want to be used in relationship objects.

So this is all stuff to think about... I don't have any conclusions at the moment, but I'll mull it over, and hopefully you guys can too. I think, as usual, it goes back to the weird relationship that JSON:API resource objects have with HTTP's concepts of resources + entities.

which should probably usually be immutable

I think it makes sense to treat revisions as immutable.

I agree with all that was said in the comment above, but I want to highlight another implicit way of creating revisions that we may need to be explicit about.

Many frameworks handle revision creation as part of the store update. In Drupal when you save an entity that supports revisioning by PATCHing it (no resourceVersion used here), then a new revision will be created for you. You cannot do much about it in most of the cases. This new revision will be a working-copy or a version depending on some custom business logic (usually a published: true / false flag).

I guess that what I'm saying is that strict regulation of how revisions are created may become hard. However, we can put language on how to create revisions through JSON:API.

Where I'm going is, do we want this profile to include revision creation or it can be a separate profile?

[Not] addressing [PATCH/DELETE] here would seem like a major missed opportunity that might be hard to remedy once this is published.

I think I agree.

Where I'm going is, do we want this profile to include revision creation or it can be a separate profile?

As above, I think I would like this profile to define how update/delete should be handled.

I think the considerations about updating bear directly on what the self link should be. If the self link is URL of a specific revision (as it seems to be here), then a PATCH to that link would be interpreted as updating the revision -- which should probably usually be immutable -- and creating a new revision would become a POST (or a patch to the default version's URL).

I think I may be in a minority about this, but I try to deeply appreciate the difference between a top-level self link and a resource object self link. I feel that once one groks what it means when they're different, the way JSON:API reconciles resource objects with HTTP resources + entities becomes much easier to think about.

Where I'm going with that is pretty simple: the top-level self link should be the URL used to mutate a resource object, not the resource object self link. Once you establish that, things become pretty simple.

GET /article/1?resourceVersion=rel:working-copy

{
  "data": {
    "type": "article",
    "id": 1,
    "links": {
      "self": "/article/1?resourceVersion=id:42"
    }
  },
  "links": {
    "self": "/article/1?resourceVersion=rel:working-copy"
  }
}

That means that a PATCH would update the working copy via the top-level self link, whatever it may be, like so:

PATCH /articles/1?resourceVersion=rel:working-copy

{
  "type": "article",
  "id": 1,
  "attributes": { // some changes }
}

The server response would then be:

200 OK

{
  "data": {
    "type": "article",
    "id": 1,
    "links": {
      "self": "/article/1?resourceVersion=id:43" // <- incremented
    }
  },
  "links": {
    "self": "/article/1?resourceVersion=rel:working-copy" // <- unchanged
  }
}

The working-copy link could be used instead of the top-level self link if the GET request was made directly to a resource object via an over-specific version negotiator (this would be the case if one visited /articles/1?resourceVersion=id:42 directly for some reason).

which should probably usually be immutable

I think it makes sense to treat revisions as immutable.

I think it makes sense too, but I don't think this profile needs to define that. I think it can work either way.

Drupal actually does permit updating a revision in-place (whether that's a good idea or not is beside the point 😛 ). With the scheme above, it would be possible for a server to support both in-place editing of a revision or new revision creation via PATCH depending on the self link used (top-level vs. resource object).

If a server cannot automatically create new revisions via PATCH for some reason (maybe it can't/hasn't implemented the rel negotiator), then I think the appropriate URL for creating new revisions would be at the version-history URL via POST. (this is why it makes sense for it to be a collection resource).

The language about updating resources in the spec seems to jive with what I suggested:

The URL for a resource can be obtained in the self link of the resource object. Alternatively, when a GET request returns a single resource object as primary data, the same request URL can be used for updates.

We could go a step further in that language by adding:

the same request URL or the top-level self link can be used for updates.

I agree with @ethanresnick that the fact that this profile's narrowness (only defining "read" behavior) is its biggest weakness.

(Similarly, I think #824's biggest weakness also was its narrowness, it just was different: it focused on optimistic concurrency control.)

On the other hand, I think solid read-only support and leaving modifications to a separate profile or a future iteration is preferable over having a spec that supports fewer use cases (which I think was true of #824 — it did not allow a particular revision to be retrieved). Especially if it's based on another established standard (RFC5829) and therefore likely to be more implementation-agnostic.

I'm fascinated by @gabesullice's proposal (and the sample response bodies really help, thanks! 🙏). I'm very curious to find out what @ethanresnick thinks about that :)

or reject a PATCH if the resource's working copy has changed from the working copy that the client is trying to apply its PATCH to

I neglected to give a solid answer for this. As I said above, I think the PATCH should be sent to the top-level self link: /article/1?resourceVersion=rel:working-copy.

However, this spec could add something like an appliesToRevisionId: id:42 under the meta key of the request document.

reject a PATCH if the resource's working copy has changed from the working copy that the client is trying to apply its PATCH to

Support a conflict detection mechanism as described in initial review post wasn't discussed enough in my opinion. Something similar to AWS Amplify should be easy to achieve if already having well defined revisions. It was already discussed as part of #824 some time ago.

Maybe something like this would be everything needed:

Conflict detection when updating resources

A server SHOULD include the most specific version negotiator it supports in any resource object's meta information under revision key.
A client MAY include the revision an update is based on as under revision key of meta object on a PATCH request.
A server MUST reject 409 Conflict when processing a PATCH request to update a resource if a revision is provided as meta information, which is not the latest one.
A server MAY reject a PATCH request to update a resource if server has included a revision on retrieving the resource but the PATCH request does not include a revision.