Re: Properties and types differing only in their capitalization ISSUE-28 (was: plural properties should become singular)

> Sounds better but I'm still not entirely happy with it. An option would be
> to use "statusCodeDescription" but that would mean that the property and the
> type differ only in their capitalization. Yet another alternative would be
> "additionalStatusInformation" but that's a bit clunky.

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)?

(Also posted on https://github.com/HydraCG/Specifications/issues/27).

Best,

Ruben

Received on Thursday, 6 February 2014 13:14:43 UTC