Should a REST service expose a XSD for XML responses?

Question

We've build a REST service that depending on the accept header will return XML or JSON to the client, or depending the content-type header will accept XML or JSON.

Now a recent integrator asked us whether we have a XSD schema for our XML responses and requests.

Is this a common practice to have when developing REST services?

Answer 1

It is absolutely common practice to provide callers of any service, including REST, with some form of definition of the interface for that service. If you have an XML interface, an XML schema of some sort (XSD, RELAX NG, Schematron, etc) is a fine way to define the request and response interface. In addition to providing documentation, it can be used by validating parsers to catch violations of the declared interface.

You might also consider creating JSON Schema definitions of your JSON interface. It can provide some of the same benefits as an XML schema would, however it arguably is less "common practice" than XML schemas are for XML.

Answer 2

The previous answers are correct, that this is common practice.

However, I suggest that is not good practice.

The bad thing about using an xsd to validate a response, is the close binding that you create between the client and server. Ideally, a client would follow the tolerant reader pattern (see, eg, http://martinfowler.com/bliki/TolerantReader.html). The client should only require the data that it needs, and not fail unnecessarily. So if the server was to start sending extra data, or fail to send unneeded data, the client should be able to continue without complaint. The client's domain model should represent only the data the client actually needs.

Back in the old days of SOAP, this tight binding between client and server was accepted as ok, or even good, and enforced in the wsdl and xsd. REST architectures should be promoting loose coupling instead, and allowing services to evolve with as little impact as possible.

Using the xsd to validate a response is good only in rare situations. For example, when the service will never change (it might be a throwaway service to do once-off data migration), or when you think it is ok to have the client and server domain models tightly bound (I think this is ok for unit tests). An argument could be made for publishing the xsd once a service is stable, but I think this a very hard call to make.

(and even though this is still common practice, I'm finding that it is not as common as it was. I was talking to an architect at a large government agency last week, and their standard is to only use xpath to obtain data from xml responses, and never use domain objects based on an xsd)

Answer 3

Why not? If you are communicating via XML then you can add schemaLocation attribute to specify your schema URL. Otherwise how client can validate server XML and form its own requests properly?