Having both hydra:statusCode and hydra:statusCodes should be avoided

[lanthaler]

_Raised by Ruben Verborgh as part of issue #25:_

The case of statusCodes shows to how much confusion this leads: we have both a statusCode and a statusCodes property.

The situation would be that a resource can lead to statusCodes X, Y, Z, each of which have a statusCode 200, 400, 500, respectively.

I think the correct way is that statusCodes becomes status, and that the current statusCode remains the way it is.

---

An alternative would be to rename it to possibleStatus or additionalStatusInformation.

[RubenVerborgh]

Note that fixing #25 depends on the outcomes of this: as both properties would map to statusCode after singularization, they would become indistinguishable. Therefore, I could either partially fix #25 and leave statusCodes as plural, or I could rename and then singularize.

[RubenVerborgh]

To decide on this, let's see what each property is supposed to mean.

The current statusCode associates a StatusCodeDescription with an actual HTTP status code. I think that it doesn't make much sense to express that "a description of a status code has a status code". You're either describing a status code, which would then be http://example.org/404 a :StatusCode. and attaching properties to it; or you're describing a status. Looking at the example from the spec:

{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@type": "StatusCodeDescription",
  "statusCode": 429,
  "title": "Too Many Requests",
  "description": "A maximum of 500 requests per hour and user is allowed."
}

we can see that we are describing a hydra:Status, not a status code. We are saying that there is a status where the user has hit the 500 requests per hour limit, and that this will result in a 429 response.

Hence, I think the correct way would be:

{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@type": "Status",
  "statusCode": 429,
  "title": "Too Many Requests",
  "description": "A maximum of 500 requests per hour and user is allowed."
}

So the message "you hit the limit" is a status, not a code. The property statusCode can be reused in this scenario.

The other issue is then how to associate such a status with a resource (= the current statusCodes). I am in favour of using possibleStatus for this, as this conveys the meaning of what the thing does.

But then I'm unsure about the domain of this property. What can be in this possible status? A single resource? The whole API (= all resources in this API)?

[lanthaler]

PROPOSAL: Rename "statusCodes" to "possibleStatus" and "StatusCodeDescription" to "Status" and describe that these are enumerations of possible statuses that might be returned at runtime and tell the developer (in prose in hydra:description) how to recover from errors etc. To be clear, "returns" is kept as is and expresses what kind of data can be expected in case of success.

[lanthaler]

Call for consensus: http://lists.w3.org/Archives/Public/public-hydra/2014Jul/0080.html

[lanthaler]

RESOLVED: Rename "statusCodes" to "possibleStatus" and "StatusCodeDescription" to "Status"

[lanthaler]

Should hydra:returns be moved into a Status (see http://lists.w3.org/Archives/Public/public-hydra/2014Sep/0089.html)