search

inadarei / hyper

Base hypermedia type for use in Representor pattern
http://hyperjson.io
MIT License
2 stars 3 forks source link

CURIEs and "working links" #12

Open dret opened 6 years ago

dret commented 6 years ago

currently the spec makes the same mistake as HAL, mixing the idea of URIs for identification, and for dereferencing. i would expect CURIEs strictly to be used so that URI-identified properties can be written in an abbreviated form. however, the spec currently jumps to the idea that i can dereference that URI and get a property's definition/description. that's something entirely different. the spec should be clear about whether properties are simply just identified by URI, and whether there is any assumption about that URI being one that dereferences to a definition/description.

inadarei commented 6 years ago

Thank you, Erik. Disclaimer: the text of the spec may indeed be misleading, always a possibility, however the intention of the spec is as follows:

  1. Object attributes and link rels (an addition to the genuinely URI fields like in h:link and h:ref, which MUST be URIs) MAY be URIs.
  2. URIs in object attributes and link rels MAY be dereferenceable, but doesn't have to be.
  3. Any URI anywhere in the document MAY be CURIEd
  4. If a URI in attribute names and link rels is dereferenceable it SHOULD point to a resource that provides information about the semantics and proper usage of the corresponding Hyper extension and/or link relation. This, howevers, is not strictly required because the URI may be just establishing the namespace and corresponding semantics and rule can be explained elsewhere, out of band e.g. in a encyclopedia :)
  5. If link is dereferenceable authors of the extensions MAY use content-negotiation to provide information in a variety of formats (e.g. human-friendly HTML and machine-friendly ALPS)
  6. Hyper parsers MUST assume default extension h: -> http://hyperjson.io/props and all items in that vocabulary are linked to by dereferenceable URIs, and those URIs do explain usage rules.

I believe this intent is compliant with your suggestion that there shouldn't be any assumption of URI being dereferenceable.... that said - having a preference of it being dereferenceable and making default extension/CURIE both dereferenceable and self-documenting is not a violation and I think is a positive thing.

dret commented 6 years ago

On 2017-12-28 15:34, Irakli Nadareishvili wrote:

  1. URIs in object attributes and link rels MAY be dereferenceable, but doesn't have to be.

good. i'd make that explicit.

  1. Any URI anywhere in the document MAY be CURIEd

any, not just any hyper? JSON doesn't even have a URI type, so i think you wouldn't even know which ones are supposed to be URIs or may just look like one, right?

  1. If a URI in attribute names and link rels is dereferenceable it SHOULD point to a resource that provides information about the semantics and proper usage of the corresponding Hyper extension and/or link relation. This, howevers, is not strictly required because the URI may be just establishing the namespace and corresponding semantics and rule can be explained elsewhere, out of band e.g. in a encyclopedia :)

i would keep this short and sweet. just say that URIs may be used for identification and optionally documentation, but that any further details about that latter part are out of scope.

  1. If link is dereferenceable authors of the extensions MAY use content-negotiation to provide information in a variety of formats (e.g. human-friendly HTML and machine-friendly ALPS)

as said above: short and sweet and anything here seems out of scope.

  1. Hyper parsers MUST assume default extension |h: -> http://hyperjson.io/props| and all items in that vocabulary are linked to by dereferenceable URIs, and those URIs do explain usage rules.

i like XML's rule of defining the "xml" prefix as magically present, but to also allow instances to make it explicit. it keeps things nicely consistent with a minimum of magic.

I believe this intent is compliant with your suggestion that there shouldn't be any assumption of URI being dereferenceable.... that said - having a /preference/ of it being dereferenceable and making default extension/CURIE both dereferenceable and self-documenting is not a violation and I think is a positive thing.

maybe. from what i see it seems to create more confusion than anything else, starting with XML namespaces which started this pattern.