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.”,
also
"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.
I believe the specification has it correct, as it intends to use the query URI scheme as devised in 3.4 of the RFC.
The use of ‘[’ and ‘]’ within the sparse field sets portion of the specification is effectively tunneled through the URI scheme to the application layer. The encoding ensures the application itself, and not the HTTP server, will manage the interpretation of the characters.
The distinction is JSON API is not creating an entirely new URI scheme but an extension of the query format, with additional constraints on the parameters themselves. If you were to suggest JSON API should be creating its own URI scheme, this would be a different discussion with wide reaching implications to the specification. A new URI scheme would require changes to the underlying HTTP servers themselves, not just the applications using JSON API as a message format.
Correct me if I’m wrong, but despite never reading them I believe the results of those threads are exactly what I stated. The note in the specification directly points out that %5B %5D work correctly, which allows the application not the server to handle parsing the query parameters.
It isn’t obvious to… almost anyone that ?fields%5Barticles%5D == ?fields[articles]. The spec therefor shows [] in legible format for illustrative purposes, while noting the RFC currently requires you to percent encode the [] as they are special characters.
I didn’t mean that JSON API should create its own URI scheme. I rather must have misunderstood the RFC, that it postulates these characters to be treated at server level the same way as most commonly used - defining a variable name within an array, which of course can be interpreted at app level as the resource type. Thank you for the clarification!