Resources should match the Collection+JSON convention

[rgladwell]

Recently came across this syntax for collections of JSON object:

http://www.amundsen.com/media-types/collection/

and wondered if the Resources generic type in spring-hateoas should meet it? Discussion?

[jbrisbin]

I would be hesitant to get behind any one JSON structure spec right now because there are several good contenders and each of them has something good in them (though I find all of them generally lacking in balance...e.g. they solve one problem well at the expense of others).

I don't really like this structure for JSON because it is, IMO, unnecessarily verbose. It combines a schema-like structure definition with the actual data, which I don't think is a good idea and too similar to XML, which is proven to be very prone to overuse and overkill. The "templates" here are an attempt to separate the structure of the document with its data, but even using a template one still has to include elements of a structural definition in the data (e.g. {"name": "propertyName", "value": "some value"}). It's not a clean separation between the data and the template.

JSON Schema is actually much cleaner in that regard. It separates the description of the structure of the document with its actual data. Being able to externally define a document is beneficial in a large set of use cases, particularly if you are generating forms, or otherwise creating helpers that want to interact with the expected data. It's also possible to mix-in document structures for a very flexible schema. I can't see that being possible with the static nature of the Collection+JSON approach.

So far as I could see, this solution also doesn't address linking of data (providing a links property isn't really what I'm talking about here). JSON-LD does address this, although it also has peculiarities that one might find annoying in real use. Of particular note in JSON-LD is the "context" of a node. Being able to namespace a JSON document would be very, very useful.

IMO a balanced approach would be to take something like JSON Schema (but with far fewer variances on the types of nodes within a schema to make parsers and validators far easier to write) and combine that with a JSON-LD type linking schema.

It may be that HATEOAS needs to provide Resource as a marker interface and provide implementations that are structured differently based on these various specs.

[rgladwell]

You mean something like this:

Resources
 |
 | -- CollectionJsonResources
 |
 | -- JsonLdResources
 |
 \ -- JsonSchemaResources

Maybe with relevant builders/factories, something like:

buildLdResources(Object... objects)

[gregturn]

Superceded by #482