Sparse field sets examples not RFC 3986 compliant

[jaspervz]

The current examples for sparse field sets use non-RFC 3986 compliant URLs: [ and ] are reserved characters and must be percent encoded.

The RFC 3986 compliant version of the example is: GET /articles?include=author&fields%5Barticles%5D=title,body&fields%5Bpeople%5D=name

Should [ and ] be used to denote the type if the client needs to encode these? At least the example needs to be updated because it isn't RFC 3986 compliant.

See: https://www.ietf.org/rfc/rfc3986.txt
3.4 Query:
query = *( pchar / "/" / "?" )

And
pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
reserved = gen-delims / sub-delims
gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@"
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="

So [ and ] must be percent encoded.

Proposal: perhaps the dot could work instead, the example becomes than:
GET /articles?include=author&fields.articles=title,body&fields.people=name

[tkellen]

ref #544

[ethanresnick]

@tkellen If our spec were the only thing in the world, I'd be in favor of using ( and ), or similar, instead of [ and ] to avoid this percent encoding trouble, but the [] syntax has become so common for expressing nested query parameters that I can't imagine we'd move away from it. So we just have to mention in our examples somewhere that the characters should be percent encoded (maybe even if we don't render them that way for usability?).

[tkellen]

Precisely my thinking as well @ethanresnick. Would you mind working up a PR?

[ethanresnick]

@tkellen Sure!

[tkellen]

Resolved!