Greetings. I would like to discuss here the new describedby link currently part of the release candidate for version 1.1.
I would like two provide to different links to my clients: (i) a link towards the documentation (probably a Swagger page) intended to help developers specially in error messages; and (ii) a link towards a JSON Schema or OpenAPI that a piece of software can use to know how to handle the data in the request.
Additionally, I see the potential for different types of description in different contexts. For instance, I may want show the link to the OpenAPI describing the request in the links object of the response, but show the link to the JSON Schema describing the resource in the resource’s links object.
I understand that JSON:API tries to leave design decisions that are not fundamental in the hands of the implementation, but I am afraid about making decisions regarding the points above that may be resolved in a different way in future releases.
I welcome any feedback and I would be happy if the specification included better guidance on these points. Please let me know if I should move this to the GitHub repo instead.