docs: require resource server token errors to have a JSON body

[andrewbonney]

Resolves #64

RFC6750 only requires error data to be returned in the headers, presumably because it may be used against non-JSON resources. As our APIs always use JSON, it seems reasonable to expect resource servers to respond with JSON in a similar way to the authorization server. If others agree, this adds a suitable schema and reference in the docs.

[andrewbonney]

I'm not sure. That would be another option, and perhaps makes things more consistent for Resource Server implementations. The original intent was to conform this to the format used by Authorization Servers given that the same keywords are available ('error', 'error_description' etc).

[prince-chrismc]

Who sees this error response? I would expect the user-agent and/or controller, who expects to consume the typical error schema.

I certainly am okay with this format, it's just an exception to the other error response from a node/registry

[garethsb]

I had the same thought. Seems worth discussing. Also an odd situation that the JSON properties are limited to ASCII (actually the subset %x20-21 / %x23-5B / %x5D-7E) presumably due to the concerns in RFC 6749 Appendix B about UTF-8 and URI-encoding as these same definitions apply for the redirect URI query parameters form.

[andrewbonney]

Coming back to this, I think I'd be in favour of using the existing error response JSON for resource servers. This matches best with what we have already, and given that the error data is still conveyed in the header we're not missing out on anything. If this makes sense to others then we probably don't need the schema to be re-defined here - in fact there may be no need to change this spec at all (just the tests).

[lo-simon]

makes sense to me too