Format of error object

[chrisdpeters]

While poking around with this gem, I noticed the error formatter provides this sort of response:

{
  "errors": [
    {
      "title": "Title can't be blank",
      "id": "title",
      "code": "100",
      "status": "422"
    }
  ]
}

I've seen the format prescribed like so in examples:

{
  "errors": [
    {
      "status": "422",
      "source": { "pointer": "/data/attributes/title" },
      "title":  "Invalid Attribute",
      "detail": "Title can't be blank.",
      "code": "100"
    }
  ]
}

Also, I noticed that according to the spec, title may not be used properly as this gem currently stands because it is displaying an error message instead of a generic summary that could be localized:

title: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

Do you think that JSONAPI::Utils should be updated to use the source.pointer style of error reporting instead of using id like it current is?

[tiagopog]

Hey there!

Well, I guess there's a little misunderstanding due to the spec's similarity of title and detail. In the spec we can see that title is more generic – and how generic it is seems to be open for discussion – while the detail member brings something specific to that error case.

I guess this password error example, taken from the specs might be clearer:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.api+json

{
  "jsonapi": { "version": "1.0" },
  "errors": [
    {
      "code":   "123",
      "source": { "pointer": "/data/attributes/first-name" },
      "title":  "Value is too short",
      "detail": "First name must contain at least three characters."
    },
    {
      "code":   "225",
      "source": { "pointer": "/data/attributes/password" },
      "title": "Passwords must contain a letter, number, and punctuation character.",
      "detail": "The password provided is missing a punctuation character."
    },
    {
      "code":   "226",
      "source": { "pointer": "/data/attributes/password" },
      "title": "Password and password confirmation do not match."
    }
  ]
}

Check specifically the error case for 225, there we have a generic error message for title – like the ones JU already renders – while for detail we have an error message related to the password's value provided by the client.

[tiagopog]

IMHO, there's nothing to fix on title since it's compliant to the specs you mentioned. However, this issue brought up some ideas:

• We could implement the source member only for AR's validation errors since a more generic implementation might be quite complex in terms of inferring the path for a given context;
• Improve de README docs for jsonapi_render_errors since this method support custom error objects which can then implement different members other than the default ones provided by the gem.

I will add the cards onto the gem's GitHub "General" project.

[chrisdpeters]

Sounds like a good plan. That helps clarify how I understand title, so thank you.

I think I was mainly thrown off by the lack of source.pointer. It would be nice to move that from id to source.pointer for ActiveRecord, like you suggest.

[chrisdpeters]

@tiagopog I'm 95% of the way on the JSON pointer thing: liveeditor/jsonapi-utils@71dec55

Problem: the error keys are not formatted according to the json_key_format setting. Where do you think I should handle that? Perhaps in JSONAPI::Utils::Reponse::Formatters? Any suggestions as to how I would go about doing that?

[tiagopog]

Nice, I will take a look and come back with some ideas.

[tiagopog]

I saw that you applied the key formatting at the exception class level and I think that's the right place to put such logic 👍