Q: What is the purpose of defining the resource with a schema?
- To have the format of the object documented in a structured manner. Because it's documented in a structured manner, we can automagically create human-readable documentation from it.
- Closely-coupling structured documentation to the code will help prevent it from getting out of date.
- We can also use the schema internally to programmatically manipulate the request or response (e.g. validate required parameters, filter response based on context)
Q: Why JSON schema?
- It is quite graybeard. JSON schema has been around for a long time, and is a well-known standard.
- We can extend JSON schema base spec to include our own attributes, and publish this extension.