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

Also changing the subject on this thread.

On Thursday, January 30, 2014 12:14 PM, Ruben Verborgh wrote:
> Hi Markus,
> 
> > It's still early enough so it won't be that much pain. Better to
> > change things early enough.
> 
> I'm very happy to hear this; thought I'd be too late already.
> Would it be a good idea if I went ahead and created a pull request for
> this?

Yes of course. Pull requests are always welcome.


> > Hm... I don't like "status" that much as it sounds like a definite
> > list of all status codes that will ever be returned. I would like
> > to make it clearer that it is just a hint or that it just provides
> > additional documentation about *some* status codes that *might* be
> > returned.
> 
> I see. hydra:possibleStatus then?

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.

I've raised ISSUE-28 [1] as I think we should discuss whether it is fine
that some properties differ from their corresponding types only in their
capitalization:

  hydra:apiDocumentation -> hydra:ApiDocumentation

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

I know that, e.g., Schema.org tries to avoid that as newcomers do not know
about these conventions and might run into problems. What do you think? Is
it fine to use the same terms or do we want to make them differ more?


> Though (but that is a different discussion) this makes me wonder
> to what extent this possible statuses are actually necessary,
> as the HTTP spec already details them.
> But I guess the point is to add additional information about each of
> them?

Exactly. Often HTTP status codes by themselves are not descriptive enough.
Furthermore, it helps to enumerate them when you want to create a HTML
documentation (similar to what current Web APIs have) out of a Hydra
description.


[1] https://github.com/HydraCG/Specifications/issues/28


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 3 February 2014 18:00:28 UTC