This is a very important sentence for understanding how profiles are meant to be implemented for maximum interoperability! I'm glad we're adding it after all :)

I find this example not very convincing. I cannot imagine authentication is often embedded into JSON:API documents. Authentication is an orthogonal concern.

Which leaves me wondering: what is a good example of this? Why is this "common"?

I think it's strange that this statement broadly contradicts the one before it by saying "Generally servers should not require profiles" and then "in many common cases, servers can require profiles".

I think it's hard to think of an example where extra data must be provided (a revision key is the best I could come up with), but I can think of requirements about how that data is provided (i.e. different profiles for different date/time formats).

I find this example not very convincing. I cannot imagine authentication is often embedded into JSON:API documents. Authentication is an orthogonal concern.

Authentication isn't a great example; I was imagining a case where maybe a request signature could show up in the body (e.g., in top-level meta), but Gabe's examples are better tbh. I can update the PR and the wording.

I think it's strange that this statement broadly contradicts the one before it by saying "Generally servers should not require profiles" and then "in many common cases, servers can require profiles".

How would you suggest wording it?

A server MAY require that a client applies a specific profile to its request.

However, it is NOT RECOMMENDED for servers to require profiles which require additional query parameters or additional request document members, as such requirements reduce interoperability between clients and servers.

Note: Profiles with optional document members, specific value formats (e.g. ISO 8601 date and time format), or specific query parameters within a query parameter family already reserved by this specification should be treated with care, but do not have the same level of interoperability concerns.

My theory here is that:

1. anything optional obviously doesn't have interop concerns.
2. query parameters within query parameter families are usually implementation specific (filter, sort, etc) so clients will likely not have them hardcoded.
3. like Consider relaxing some MUSTs #2, value formats are usually "passed through" a client library and aren't hardcoded; they typically come from a frontend developer working against a specific backend.

s/extension/profile/

I can't think of a use case for the missing array index. What am I missing?

E.g., a profile that takes data in an [x,y,z] coordinate pair is given an array with fewer entries. More importantly, though, it just seems good to general here

The coordinate example helps, thanks!

But I thought profiles only could add elements to the document structure (per
https://jsonapi.org/format/1.1/#profile-keywords-and-aliases), which means they must have a name, and hence a JSON object key? Wouldn't the coordinate example be a value of an object key, and therefore z being absent from [x,y,z] would not result in a missing error since the key would be present, the value itself would just be invalid. In other words: invalid, not missing?

I'm probably still missing something, sorry.

Wouldn't the coordinate example be a value of an object key, and therefore z being absent from [x,y,z] would not result in a missing error since the key would be present, the value itself would just be invalid.

It's both. I.e., the value is invalid because a key (index 2) is missing.

In other words, if a client client sends:

{ "meta": { "homeBase": [x,y] }

then the server's error object would ideally contain "pointer": "/meta/homeBase", whether it contains "missing" or not. But that just tells you that the value at /meta/homeBase had an error. Being able to supplement the pointer with "missing": { "key": "2" } just makes it a bit more specific about what the error was.

In theory, you never need "missing": { "key": "... " }, because you can always reinterpret your error as being not that some key is missing, but that the value that's supposed to contain the key (pointed to by "pointer") is invalid. But missing is a way to be more specific about "invalid how".

s/extension/profile/

Even if server-required profiles doesn't make it into 1.1, I think this is a worthwhile addition, paired with the language added in e75cec1 to clarify that the pointer must reference an element in the original request. In the case of a missing key, this should be paired with some other data point (e.g., this element) to tell the client exactly which data was missing.