Clarify client expectations wrt server spec compliance fixes

Discussed with catch in chat:

I’m not sure I 100% understand what you’re saying/asking in the paragraph about bugs though. That’s why I’m pinging you, to avoid a lot of back-and-forth.
This is what `jsonapi.api.php` says:
 ```* HTTP API: URLs and JSON response structures are considered part of this
 * module's public API. However, inconsistencies with the JSON:API specification
 * will be considered bugs. Fixes which bring the module into compliance with
 * the specification are *not* guaranteed to be backwards-compatible.```
People should be able to interact with the JSON:API module’s API by just reading https://jsonapi.org/format
If they find something violating the spec, they should file a bug report.
If our code currently violates the spec, that’s a bug, and we’ll change it to match the spec.
That’s what that is saying. Is that not clear enough? Or do you have concerns about that?
I guess your concern is that any of those spec compliance bugs would leave you stuck. But here’s the thing: this module has been around for ~2 years. We’ve ironed out a lot of edge cases. So _if_ you encounter something at this point, it should range from fairly minor to extremely minor.

catch [3:41 PM]
“I guess your concern is that any of those spec compliance bugs would leave you stuck.” yes this - i.e. is there a way you can make a client agnostic of the buggy vs. non-buggy version, if so we should recommend that or something.
The way it currently reads is that if you hit a problem, we’ll fix the bug, but if you work around it in the meantime you’re on your own sort of thing.

wimleers [3:47 PM]
Yes, we expect you to update your client.
Perhaps that’s all that’s missing? `We expect you to update your client after fixing the compliance.` ?
Or are you saying that that is not acceptable?

catch [3:48 PM]
That’s what I asked, why can’t clients check for two possibilities?

wimleers [3:48 PM]
I am absolutely confident that 98% of clients will never run into this.
> That’s what I asked, why can’t clients check for two possibilities?
How would they do that?
They can for _reading_ data, but for _writing_ data they can’t

catch [3:49 PM]
OK I mean for reading data, it’s an if else for most of those cases.

wimleers [3:49 PM]
I guess that is reasonable advice for the _reading_ case.
True.
Okay that’s a great point!
Something like `When compliance bugs are found, clients are expected to be made compatible with both the pre-fix and post-fix representations.` ?
(And sorry for being so slow to understand.)

catch [3:52 PM]
Yes that sounds great :slightly_smiling_face:

🚢 since this allows me to post a new RTBC core patch at #2843147: Add JSON:API to core as a stable module :)