Should a RESTful API have a schema?

Question

I was told recently that a proper RESTful API should define a schema for the resources representations it accepts and returns. For example XSD for XML and JSON Schema for JSON.

Answer 1

They are optional. If you need fine-grained filtering of user requests with consideration on both the syntax and semantics on the contents, you use it.

1. Here's an RFC guideline mentions about XML schema.

https://tools.ietf.org/html/rfc3470

"XML Schema (defined in [41] and [42]) provides additional features to allow a tighter and more precise specification of allowable protocol syntax and data type specifications."

2. Here's IETF draft for JSON schema: https://tools.ietf.org/html/draft-zyp-json-schema-04

"JSON Schema provides a contract for what JSON data is required for a given application and how to interact with it. JSON Schema is intended to define validation, documentation, hyperlink navigation, and interaction control of JSON data."

As you can see, IETF did not accept this as an RFC (it is still a draft). They thought this is too much for simple protocol like JSON. However many open source projects rely on this draft.