Decide on whether to rename ProblemDetail to ProblemDetails

[quaff]

Keep it consistent with RFC title Problem Details for HTTP APIs

[rstoyanchev]

Thanks for the comment. From the opening of the spec:

   This document defines a "problem detail" as a way to carry machine-
   readable details of errors in a HTTP response to avoid the need to
   define new error response formats for HTTP APIs.

It uses both singular ("problem detail") and plural ("machine-readable details") in the same sentence, so clearly there is something very intentional here. Most of the spec uses plural, but the double quotes around "problem detail" seems meant to draw a distinction. Here is my interpretation of it.

The singular form refers to the fact there is one problem to explain, you can choose one HTTP status and reason, and there is one String field called "detail". In other words, here is the problem and a description of it. The plural form, by contrast, refers to all the additional fields included in the response, which can be seen as auxiliary details along with the description.

There is a bit of an overlap of terminology there. The spec could have used a different name for the "detail" field, perhaps "description", "cause", or similar. Overall, I think neither ProblemDetail nor ProblemDetails is wrong. It just depends on your perspective. The former is more focused on the [single] problem / description, and the latter on all the auxiliary fields included in the response.

We'll try and finalize this for RC2 next week, but comments welcome in the mean time.

[membersound]

I would see the ProblemDetail class as a wrapper object, which should be singular. Compare it with shopping: you have several products, and group them into a basket (not into baskets). Or you group them into an order (not orders).

Also, http APIs are usually kept in singular names as best practice.

In contrast, the naming ProblemDetail**s** could pretend that it contains multiple ProblemDetail objects as an array. Which is not the plan afaik.

[quaff]

FYI: spring-security use UserDetails instead of UserDetail, and .net use ProblemDetails instead of ProblemDetail.

[membersound]

And AWS is using ProblemDetail (https://docs.aws.amazon.com/de_de/devicefarm/latest/APIReference/API_ProblemDetail.html). You probably find both ways 50:50.

[rstoyanchev]

The Spring Security example isn't something to go by. Yes, the same ending, but other than that, its own context and reasons. Let's stick to the case of RFC 7807. I've already laid out my interpretation of the language used there. If you have any comments or thoughts on that, please share.

@membersound I take it you see this as the plural applying to both "problem" and "detail", and that there is only one problem to be detailed.

[vpavic]

FWIW, I agree with the current naming and interpretation outlined by @rstoyanchev.

The way I see it, this is a part of story that's basically about translating an exception (singular) to some specific representation of the underlying error. The translation is 1:1 so it seems natural to me to name the representation as ProblemDetail (singular again).

[rstoyanchev]

I'm closing this in favour of the current choice, ProblemDetail, focusing on the actual problem and its description, rather than all the additional auxiliary details. Thanks for raising this in any case, it's good to have considered this with more scrutiny.