How do I specify response code in json schema?

[Ning]

Hi,
  Is there a way of specifying the expected schema for both success case and failure case in hyper schema?

  Say if I do POST on /books. It could be successfully posted, or might fail (such as the request payload doesn't have a required property title). In the failed case, some detailed response is returned along with 400 error. I would like to have a way of describing the error response.

  Thanks.

Ning

[Eric G]

I would think with either response, you could include the schema(s) in a Link or Content-Type profile=   header, as described in the core spec: http://json-schema.org/latest/json-schema-core.html#anchor34 .

[Philippe Marsteau]

I believe question is related to targetSchema attribute, which allows to describe a schema for an hyperschema link definition.

I see at least 2 scenarios where you might want to provide hints about more than one target schema:
1- error vs success schemas
2- async vs sync schemas

I don't see in current JSON schema a way to describe more than one schema for a given link definition.

I agree that at runtime, server can advertise which schema is associated to returned payload using profile or link header.

I am interested how we can document supported error codes (a resource may not support all HTTP codes or may want to explicit error cases client should be ready to support) and more generally, how to let a link describe many possible target schemas.

Any ideas?

[Philippe Marsteau]

To elaborate on use case #2, sync vs async schemas:

Typically a server would respond synchronously to a request sending 200 along a payload.

But sometimes server may decide to defer processing of a request and reply with 202 HTTP code along a payload that would typically describe status of processing.

The client may have a query param or HTTP header to explicit async processing or the server may decide on its own (eg based on server current load). In latter case you would expect client to be aware of both potential payloads (and associated schemas), then based on content type profile parameter returned by server (or returned link header) parse response accordingly.

Makes sense?

[Geraint]

I'm not sure about some of this - the idea of a predictable error condition seems a bit odd to me. Async also seems less to do with the response, and more to do with the semantics of the link/endpoint (plus, all the different async response setups seem like they'd be hard to cover).

The Hydra vocab covers some of these, and I've not always been convinced how useful it is...

[Philippe Marsteau]

What about JSON schemas ref describing an error payload one might be ready to parse if the resource request cannot be fulfilled? Error codes and API supported error media types should be describe-able in JSON schema in a similar way exception types can be described in WSDLs. Don't you agree?

Maybe a misinterpreted the "targetSchema" semantic. I thought it was used to hint about the expected target response associated schema. Maybe we could address my need with having target schema ref'ing a schema using a combination of anyOf attribute to explicit each possible message structure to expect on response?

For async use case, not disputing the semantic aspect of it. I just used this as another case where Content-Type header of expected HTTP response may be many different values for a given resource. I thought it would be useful to have a way to describe each possible media type structure that one may expect on a given endpoint using JSON schema description language.

To get back on Ning original question, most open REST APIs do document the error codes they support. There must be a good reason for this. I like the idea of using JSON schema to auto document my APIs, and error codes would need to be part of the schema for this reason.

[Geraint Luff]

Interesting point.

Personally, I'd expect "targetSchema" to be the schema (or schema options) I'd see upon success - e.g. if I go to an endpoint and it'll returns me a File object, SymLink object or Directory object, then "targetSchema" should probably be the DirectoryEntry schema (which encompasses all three).

I think the root of my feeling that response codes shouldn't need specifying in schemas is that most HTTP status codes do not require any explanation, and the client actions for responding to them are already well-defined.

From a JSON Schema perspective, I don't think it makes any sense to document any of the 300-group responses.  400-group responses all explain specifically what the problem is, and 500-group responses can be similarly informative (and are complete error conditions anyway).

In fact, even within the 200-group responses there are often predefined actions which I think it doesn't make sense to specify in JSON Schema.  If you do an "If-Modified-Since" request and get a 204 back, then you use the cached version.  A 206 response is simlarly well-defined and well out of the scope of JSON Schema.

So basically, I think you bounce around, switching protocols, following redirects etc. until you either reach an informative error for which you don't need JSON Schema (e.g. 415) or you reach a 200-group success code which you translate into a document (or an empty acknowledgement) using standard mechanics.

I don't know - if there's overwhelming demand for something like "expectedResponseCodes" or whatever, then I guess it's worth a discussion, but I personally can't see the benefits that clearly right now.

--
You received this message because you are subscribed to a topic in the Google Groups "JSON Schema" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/json-schema/B-rcbriwNdc/unsubscribe.
To unsubscribe from this group and all its topics, send an email to json-schema...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Ning]

I think the response code is all standard, so probably nothing more to add in schema.
However, when there is an error, and there is a response body in addition to the response code, then the client would want to understand the response body.
For example, a client uses POST to create a resource, and the resource might contain multiple properties, or even children. It is possible that the requested resource payload has validation error, and even multiple errors. It is usually insufficient to only return a 4xx code and a short error message. The response body will need to contain more detailed information, such as an array of errors, and each error contains property name, error code, error message, etc. These kind of error response needs to be understood by the client, and it seems that using json schema to describe the response is a natural fit. The challenging part is how to connect this with the original resource.

[Ondřej Chmelař]

Has there been any resolution for this?

I agree with Ning that this is quite important and expected feature of documenting api endpoints but unfortunately it doesn't seem to have made it into the draft since 2014.

Dne čtvrtek 27. února 2014 20:52:25 UTC+1 Ning napsal(a):

[Austin William Wright]

Post a new thread describing your specific problem, then we can offer more specific advice.

In general, though, HTTP is self-describing, and any errors it returns should be self-describing. If you need machine-readable errors, consider a response format such as application/problem+json. I'm not sure what is accomplished by listing possible HTTP errors in a JSON Schema.