I was reading the GH discussion on the revision member, and there was debate about whether a MUST clause would break compatibility with 1.0 clients, since they would be unaware of said requirement.
Since this is a feature targeted for the v1.1 spec, I would read a “MUST” here as not binding for 1.0 clients.
If a MUST clause in a post-1.0 spec were considered binding for 1.0 implementations, then, obviously, no new MUSTs could ever again be added without making them expressly conditional:
A client implementing such and such feature MUST blah blah…
Is this the intent?
Considering that optional features may be further expanded in future JSON API revisions, how about some sort of uniform notation to indicate the JSON API versions that a requirement applies to? This would eliminate the need to qualify each statement separately.
For example, the section about the revision member would be tagged with “1.1”, indicating to readers that the feature was not present in JSON API 1.0., and any MUST clauses within the section need to be interpreted in that context.
@bintoro When I first pitched the statement if a server returned a resource with the optional revision member, then the client MUST supply the revision member in any PATCH call. But the team came back and basically wanted a json:api 1.0 client to be able to make a PATCH call to a json:api 1.1 server and not fail so I changed the MUST to a MAY. The json:api team is serious in their “wholly additive” edict.
With that said, I like your train of thought of using the JsonApi object of a document for a client to specify what “version” of the json:api specification it is talking and let the server react accordingly? If no JsonApi object explicitly stating what version of JsonApi it is talking is in the document then assume 1.0, etc.
The way I see it, a server should be allowed to advertise itself as, say, JSON API 1.1 only. This is simply pragmatic. Applications are always going to have some special requirements, so it would serve no purpose to automatically declare an implementation noncompliant if it doesn’t support all clients down to 1.0.
For example, 1.0 doesn’t seem to permit a server to require a particular attribute to be present in every PATCH request. An application that for some reason depends on this would have to remain noncompliant forever, even if v1.1 happened to allow mandatory attributes. This seems silly.
Compatibility/versioning is a really complicated issue but, at the very least, I agree that there are a few different places where the spec could be more rigorous in defining its terms. I’ve opened an issue on Github for this, and it links to a post I made about the topic in #915.
Maybe… or it promotes interoperability. Although, for the particular case of a required PATCH attribute, the relevant compatibility requirement would be “mustProduce” (i.e. the client must produce a request with x data) as opposed to the more problematic “mustUnderstand” requirement. The current plan is actually to allow servers to impose at least some mustProduce requirements—because that’s already necessary for authorization etc—though one outstanding question in #915 is exactly how far servers can go in imposing such requirements.
That would be great. But if there’s nothing to stop a server from requiring, say, a revision attribute, what is there to be gained by preventing it from imposing the same requirement on essentially the same member once it becomes officially recognized and is no longer an attribute?