I don't think this extra clarification is necessary given this statement in the same section:

@-Members MAY appear anywhere in a JSON:API document.

I just closed #1367 with the comment:

Upon reading and re-reading these issues and the current v1.1 section on @ members, it now is clear to me that @ members are fully in the domain of implementation semantics rather than specification semantics. As such, their usage can be governed by profiles, but not the base spec or extensions.

I think that explicitly focusing on the contents of attribute values doesn't really help clarify this central point. But I am open to broader clarifications.

It's see your point. Treating @-Members as implementation specific resolves my confusion. I think it also addresses the question raised by @freddrake in #1584.

However I'm not eure if current specification expresses that intent well.

JSON:API processors MUST completely ignore @-Members

This statement does not express that it's up to the implementation how to handle @-Members. Instead it seems to forbid depending on them at all.

It includes an example to clarify what ignore means:

i.e. not treat them as JSON:API data

That example confuses me even more to be honest. The term "JSON:API data" does not seem to be defined. Is the data represented as a JSON:API resource part of that JSON:API data?

Also what is meant by a "JSON:API processor" does not seem to be defined well. What part of processing the request/response and the data encoded in it is done by "JSON:API processor"? Which part is done by domain-specific processors?

This leads to a couple of specific questions:

1. Is it okay to validate for presence or absence of a key starting with @ in an object used as attribute value?
2. Should a server treat a key starting with @ of an object used as attribute value as part of the data encoded by the JSON:API resource object? Should it remove that key before persisting the data?

I think you are right. It's not that much about adding a special note for objects used as attribute values. Maybe it's more about clarifying that paragraph.

In particular, "JSON:API processor" is not defined in the specification.

I suspect the intent is that the parts of an application that deal with JSON:API structures specifically should ignore the @-members, but other aspects of the application (JSON-LD processors?) can handle them as they see fit.

This statement that JSON:API processors must completely ignore @-members needs to be rewritten to avoid the undefined term, either by defining the term clearly somewhere, or by stating @-members are allowed in JSON:API-defined structures, but have no impact on JSON:API-defined interpretation of the structures.

@jelhan @freddrake I agree that there is a lot to be improved with this section about @ members.

The wording around "JSON:API processors" is unclear. The intention is basically "servers and clients interpreting this specification". Now of course, these same servers and clients should interpret these @ members in another context, such as through JSON-LD.

This leads to a couple of specific questions:
Is it okay to validate for presence or absence of a key starting with @ in an object used as attribute value?
Should a server treat a key starting with @ of an object used as attribute value as part of the data encoded by the JSON:API resource object? Should it remove that key before persisting the data?

These questions are not the domain of this specification, but rather the specific implementation (which may provide instructions via a profile). JSON:API can't answer these questions any more than it can provide instructions about interpreting meta values.

I will attempt to clarify this whole section in a separate PR.