Singularization of properties and its consequences (ISSUE-25, ISSUE-27 & ISSUE-28)

Let me try to wrap this thread up in a single mail:

On Wednesday, February 05, 2014 6:20 PM, Ruben Verborgh wrote:
> The puil request that singularizes the discussed properties is
> available at
> https://github.com/HydraCG/Specifications/pull/34

Thanks a lot for taking a stab at this Ruben. Much appreciated. It LGTM but
as you say

> [...] the statusCodes issue needs fixing before it can be
> singularized:
> https://github.com/HydraCG/Specifications/issues/27

On Thursday, February 06, 2014 2:14 PM, Ruben Verborgh wrote:
> 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.

That's a very interesting and compelling way to look at it.


> 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.

Right. I think it makes it much clearer why Error is a subclass, i.e., a
specialization of StatusCodeDescription (aka Status).


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

Maybe it helps if we look separately at statusCodes used on ApiDocumentation
from statusCodes used on Operation. On an operation, I think it's reasonable
clear. The enumeration of statuses describes possible outcomes of invoking
that specific operation. On the ApiDocumentation, on the other hand, it is
not so obvious; especially not if we just call this thing "Status" and
"possibleStatus".

I think what we try to describe on the API level is what kind of potential
errors/exceptions etc. a client should be able to handle. Now it depends on
us how we model this. I think just using the obvious approach to reuse the
same thing that seems to work on operations isn't really an option here (at
least not with the proposed property "possibleStatus"). A possible approach
would be to describe error scenarios that result in a specific status.. if
you run over quota, you will get back this status. That could easily turn in
something quite complicated unless we restrict ourselves (for the time
being) to describe the error condition, i.e., the circumstances that lead to
the error/status only in natural language. What I have in mind is something
like this:

  ApiDocumentation
    - cornercases:
        - name: Quota Limit Hit
          desc: If you send more than 100 req/s you'll
                get an error 
          status:
            - statusCode: 429
              name: ?? duplicated ??
              desc: ?? duplicated ??

As you already see from the sketch, it's not fully thought through yet. I'll
have to think more deeply about this.
  


The other thing we need to discuss in this context is whether we want to
have properties that differ only in their capitalization, as, e.g.,
Schema.org (ISSUE-28).

If we merge Ruben's pull request, there are a couple of properties that
differ only in their capitalization from their corresponding types:

  hydra:apiDocumentation -> hydra:ApiDocumentation
  hydra:operation -> hydra:Operation
  hydra:supportedProperty -> hydra:SupportedProperty


Ruben thinks
 
> that's totally fine actually.
> Introducing artificial differences might make this more difficult.

and, if desired, proposed the following alternatives on GitHub:

  hydra:documentedBy ->  hydra:ApiDocumentation 
  hydra:supportsOperation -> hydra:Operation 
  hydra:supportsProperty -> hydra:SupportedProperty

Gregg proposed

  hydra:hasApiDocumentation -> hydra:ApiDocumentation
  hydra:hasOperation -> hydra:Operation
  hydra:hasSupportedProperty -> hydra:SupportedProperty

Schema.org typically adds a "Type" at the end. They have, e.g., an
"eventStatus" property which points to an "EventStatusType". I don't
particularly like that because it looks quite ugly, especially if you use
Turtle's "a":

   _:something a EventStatusType .
   <docu> a ApiDocumentationType .

It is, however not an even status *type* or API documentation *type* but an
instance thereof.

I would like to hear a couple of more opinions but I'm leaning towards
keeping the properties and the types the same (apart from their
capitalization). Is there someone who can't live with that?



--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 6 February 2014 16:46:41 UTC