Questions:

1. Should path be in JSON Pointer syntax (http://tools.ietf.org/html/rfc6901) (I assume: yes)?
2. Should path be "/posts/title" or just "/title" in this example and why?

Should path be "/posts/title" or just "/title" in this example and why?

In the JSON API implementation for Django REST Framework that I'm working on, we are just using /title. The discussion for why came down to it matching the JSON PATCH format for the resource level (not the root level).

I do have another related question though: How should errors across multiple fields (or not field related) be represented? Currently we are using /- as the path.

I wouldn't mind seeing examples for authentication errors as well, we are serializing them currently like

{
    "errors": [{
        "status": "403",
        "title": "Authentication credentials were not provided."
    }]
}

For what it's worth my current errors look like this:

{
  "errors": [
    { "id": "email_not_unique" },
    { "id": "password_too_small" }
  ]
}

I use the id field to look up a value in a dictionary for the appropriate i18n message for the client's determined language.

I have experienced quite a bit of unhappiness with the current errors definition.

I want to identify a scope to which one or more problems apply. The scope could be at a resource level or field level.

Json-api has links and a path and this just doesnt seem to fit. It doesn't allow multiple problems to be specified once you have identified the problem area. I am not sure why we don't just have a json pointer (what json patch uses) to identify the problem scope and allow a collection of problems.

Each problem can then have a title, detail and additional information such as code, reason or anything else the server wishes to return.

IMO errors could just be:

{
  "errors": [
    { "path": "<json pointer>",
      "problems": [{
        "title": "Some text",
        "detail": "Detailed explanation",
        "code": "some_code",
        "whatever": " you need"
        }, {
          // etc
        }
      ]
    }
  ]
}

An alternative format is to drop the errors array and return an object using the distinct json pointers as the keys:

{
  "errors": {
    "<json pointer>": [{
      "title": "Some text",
      "detail": "Detailed explanation",
      "code": "some_code",
      "whatever": " you need"
    }, {
      // etc
    }],
    "<json pointer>": [
      // etc
    ]
  }
}

This was brought up in the original errors conversation, but decided against.

@krainboltgreene Thanks. Any reference where it was discussed and more importantly why? I am aware a draft nottingham rfc was looked at, and I looked at it too and it looks like an il conceived spec given its intent. I believe it had some influence on the json -API error designbut was ultimately diverged since the draft rfc had little hope of meeting json-api requirements.

Does anyone have a set of use cases or requirements for json-api? It seems there is an unspoken set of requirements and very little rationale for how things are. Given this I don't see why we cannot change anything in the interests of pragmatism.

Json API allows multiple resources to be specified in all create and update actions so errors need to provide adressability of problems balanced with unnecessary repetition. The spec needs trimming down to a firm set of capabilities that all implementations must adhere to. Forcing a json pointer provides a definitive scope for problems, anything else is just flimsy design and ultimately the slippery slope to non interoperability.

@ahx

Sorry about the delay here! We are certainly interested in adding examples, but this does not merge any more. Are you interested in keeping up this PR? If so, let's go over them in detail, but I'm not going to review until I hear from you 😄

@steveklabnik i have updated the example. Using a Rails' i18n-ish looking "code" in the example ("errors.attributes.title.blank"), because there were some questions regarding i18n in the past and I think this is how I would use the field, even without using Rails.
Is 422 the proper status code?

I have rebased this PR. 👍 👎 ✋ ?

@ahx I don't think there is a need for a long error code like that if the path is already giving the location of the error. It could probably be something shorter like invalid_required.

@ColtonProvias I've used the long code ("errors.attributes.title.blank") to resemble a code that you can throw against some i18n library. But this probably is just distracting. So i changed it to "field_empty".

Sorry for the slow/no response @ahx. If you'd be willing to rebase this one more time and ensure it lines up with 1.0 of the spec, we can get it landed.

Please rebase/resubmit this PR if you'd like for it to be merged.

Also, any examples should target the new examples page.