I have been acquainting myself with the specification over the last two days and this note caught my attention:
“Note: The above example URI shows unencoded [ and ] characters simply for readability. In practice, these characters must be percent-encoded, per the requirements in RFC 3986.”, the ‘RFC 3986’ reference linking to http://tools.ietf.org/html/rfc3986#section-3.4.
Please, correct me if I am wrong, but it seems to me this text is misleading. First of all, the referenced section of RFC 3986 does not treat at all encoding the ‘[’ and ‘]’ characters. They are discussed in https://tools.ietf.org/html/rfc3986#section-2.2 where they are listed as reserved characters for delimiters in the URI and therefore required to be escaped by percent encoding, if not used as delimiters:
“The purpose of reserved characters is to provide a set of delimiting characters that are distinguishable from other data within a URI.”,
"Thus, characters in the reserved set are protected from normalization and are therefore safe to be used by scheme-specific and producer-specific algorithms for delimiting data subcomponents within a URI."
Secondly, since the JSON API specification proposes these characters namely as delimiters, it seems to me that they MUST NOT be percent-encoded. They only should be percent-encoded if they are part of the data passed as some parameter value in the query, not when used in the syntax of the query itself.
Thanks for your thoughts on this issue!