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

You should document your RESTful API for those who use it. The schema is more specific to each data format that gets returned, which can be helpful. Here are example API references that define methods and response formats nicely:

The Google Maps Geocoding API (JSON and XML)

SoundCloud HTTP API Reference

CloudFlare API documentation v4

Twitter Search API

Mostly what I see are request methods documented with response examples shown and a chart explaining what to expect (not so often a formal schema on its own). Make it make sense to humans.