inadarei / hyper

Base hypermedia type for use in Representor pattern

hyper

Base hypermedia type for use in Representor pattern

Source code of http://hyperjson.io/

hyper's Issues

CURIEs and "working links"

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.

Types, rels, and other types

We currently have

• rel for link relations
• h:link.template.fields[key].type for form/template field hinting
• h:link.template.contentType for mimetype of requests
• h:type for... something kind of like link relations, but applying to specific values, and possibly also including datatypes

The h:type language suggests that there is some vocabulary of basic type indicators, but this is, as far as I can tell, not the case. Siren punts to HTML5 types for the equivalent of h:link.template.fields[key].type, which imports an enormous amount of complexity into the spec, in my opinion.

• Should we unify h:link.template.fields[key].type and h:type?
• Should we unify rel and h:type?

If neither, then we should definitely put more description in the h:type definition about what "standard types" are.

Remove profiles?

As discussed in chat, perhaps we can move the profiles responsibility to the transport, such as HTTP headers.

how to declare and use CURIE prefixes

i am a little confused how exactly CURIE prefixes are declared and applied. it's essentially the same problem HAL faces (and so far doesn't clearly specify). how are conflicting declarations handled? what about multiple declarations on "parallel levels" (but those seem to be discouraged/disallowed)? why doesn't it clearly say "there MUST NOT be more than one h:head at the top level, and there MUST NOT be any h:head at lower levels"?

"any JSON is hyper" claim

that claim is outright magical and needs to be detailed. in any JSON format i've ever seen, a format puts constraints on how to use JSON. these constraints can be in the form of a schema, or the form of a spec.
i can see how JSON not containing hyper properties can be hyper. that's pretty much the HAL approach to allow plain JSON.
however, as soon as there is data that's mixed in that claims to be hyper, it seems outlandish that every possible JSON data you put in these properties is valid hyper. the spec has a lot of constraints how to use properties. what happens if those constraints are not satisfied? per the claim, that would still need to be valid hyper and thus those constraints have to be removed because every possible value must have a valid hyper interpretation.
as mentioned, the claim as it is made seems magical, and needs a lot of explanation in order to explain to people that as a logical conclusion of that claim, there is no such thing as invalid hyper.

plurals ("curies" vs "h:link")

In some places (maybe only curies and profiles), we use a plural, and in others a singular, even where both of the places support a multiple of the described definition.

Should we normalize all of these to singular or plural?

hreflang considered imprecise

Currently Hyper has hreflang as a top-level, primary key in the header section. I recommend we remove it.

Some reasons:

1. Hyper can be used to represent human-language documents, but there's already a hypermedia format for that as a primary use case: HTML5. An HTML document is intended to be directly read, and as such it is very common for the data in it to be mostly textual and mostly in one language, since that's how human-readable documents usually appear. It makes sense to hint what language the document is in so that a browser can request another version, offer to translate, or whatever. Machine-readable data is less likely to have a meaningful language that covers the entire document.
2. For HTTP, at least, there are already the headers Accept-Language and Content-Language.
3. Specifying the language of the document, if necessary, could be accomplished through a link with an appropriate relation.

extension semantics and processing

it seems that apart from the h vocabulary, all others are supposed to be optional, and will be defined by extensions. that's good, but in order to make processing hyper safe, it must be clear how to process any hyper instance.
one way to go would be to support robust extensibility (http://dret.typepad.com/dretblog/2016/04/robust-extensibility.html), so that extensions are always safe to ignore. but if that's the goal, then hyper must require extensions to only have localized semantics: no extension can change the semantics of something outside their own scope, meaning that clients can ignore or process extensions, and will always be on the safe side.

CURIEs

Given HAL's example, let's be careful about CURIE usage.

which type

We should follow the suggestion of https://www.w3.org/TR/2010/NOTE-curie-20101216/#sec_2.2. in specifying that fields contain either IRIs or CURIEs, or else limiting CURIEs to SafeCURIEs where the value might also be an IRI. This removes ambiguity, since unsafe CURIEs can have the same character sequence as IRIs.

where

CURIEs are at least useful for rels, but where else may they be used? At least some examples show CURIE usage in uri. However, it seems like there's an opportunity to make things simpler if we treat the h namespace as a CURIE and specify it as a default CURIE always available:

{"prefix": "h", "href": "http://hyperjson.io/names/"} 

If we then specify that the names (object keys) should never be treated as IRIs, then we can dispense with the SafeCURIE requirement for those. Or not; requiring that no key in the body is semantically an IRI seems like a fairly large restriction to impose on users!

Combining those (except all SafeCURIEs), we'd have a minimal example of

{
  "head": {
    "curies": [{"prefix": "ex", "href": "http://api.example.com/"}],
    "links": [{"uri": "[ex:employees]", "rels": ["self"]}]
  },
  "body": {
    "department": "North-East",
    "employees": {
      "label": "Department Employees",
      "[h:value]": {
        "cca78b82-59d5-49d3-bbfe-779de5248dbd": {
          "firstname": "Brianne",
          "lastname": "Watsica",
          "job-title": "Senior Infrastructure Administrator",
          "[h:links]": [
            {
              "uri": "[ex:employees/cca78b82-59d5-49d3-bbfe-779de5248dbd]",
              "rels": ["[ex:employee]"]
            }
          ]
        },
        "5e552416-f143-4bee-9a07-0e6fa8e96c12": {
          "firstname": "Jose",
          "lastname": "Jakubowski",
          "title": "Regional Sales Representative",
          "[h:links]": [
            {
              "uri": "[ex:employees/5e552416-f143-4bee-9a07-0e6fa8e96c12]",
              "rels": ["[ex:employee]"]
            }
          ]
        }
      }
    },
    "budget": "500M USD"
  }
}