Use markdown links in mson

[blongden]

If I was to have the following document

- name: A door
- destination: [kitchen](http://domain.io/rooms/kitchen)
- colour: green
- description: A green door

It would be great if it could be rendered in hal like the following

{
    "_links": {
        "self": { "href": "/whatever" },
        "destination": { "href": "http://domain.io/rooms/kitchen", "title": "kitchen" }
    },
    "name": "A door",
    "colour": "green",
    "description": "A green door"
}

That way, formats that can express outbound links in a defined manner (like HAL can) are able to do so without embedding the Hal '_links' field into the markdown representation.

You could format this completely differently for json-api or Siren too, depending on what's required.

Thoughts? :)

[blongden]

You already have the perfect way to do embedding too...

# Address (object)
- street: Main Street
- city: Maine
- zip: 12345

# User (object)
- name: Ben Longden
- address (Address)

{
    "_embedded": {
        "address": [
            {
                "street": "Main Street",
                "city": "Maine",
                "zip": "12345"
            }
        ]
    },
    "name": "Ben Longden"
}

Again, formats like HAL that support embedding resources are able to do so.

[fosrias]

@zdne Interesting idea of @blongden's I think that could fast track relations. Basically you could have a # Relations section and just use markdown links as the Value Definition (I think that is what we call it).

I am not sure I would recommend interspersing it with the attributes though, as an initial reaction.

[zdne]

@fosrias do you mean something like

# Resource 

## Attributes
- name: A door
- colour: green
- description: A green door

## Relations
- destination: http://domain.io/rooms/kitchen

?

[zdne]

@blongden if you wonder what @fosrias is talking about – in our "bigger picture" we plan to add dedicated section for affordances / relations as we have suggested in the concept of Resource Blueprint and demonstrated at API Craft this year. Hence the # Relations section.

Now when it comes to this:

- destination: [kitchen](http://domain.io/rooms/kitchen)

technically it would be possible, however I do think that separating the hypermedia control from the resource attibutes / data payloads is a helpful concept. Moreover MSON tries to be media-type agnostic, and as such we would have hard times representing this destination in anything other but HAL..

[fosrias]

@z Yes. That is what I meant.

On Thu, Dec 11, 2014 at 12:24 PM, Z [email protected] wrote:

@blongden https://github.com/blongden if you wonder what @fosrias
https://github.com/fosrias is talking about – in our "bigger picture"
we plan to add dedicated section for affordances / relations as we have
suggested in the concept of Resource Blueprint
https://github.com/resource-blueprint/resource-blueprint and
demonstrated https://speakerdeck.com/zdne/a-shift-of-mind?slide=26 at
API Craft this year. Hence the # Relations section.

Now when it comes to this:

• destination: kitchen

technically it would be possible, however I do think that separating the
hypermedia control from the resource attibutes / data payloads is a helpful
concept. Moreover MSON tries to be media-type agnostic, and as such we
would have hard times representing this destination in anything other but
HAL..

—
Reply to this email directly or view it on GitHub
#16 (comment).

[blongden]

Ok, I like the idea of explicitly defining a Relations header, though I wonder how this would translate into formats like JsonApi or HyperJson (where any object containing an href value is a link). Both of these are very much inline with the data.

That said, order is not important, so maybe it's not an issue.

[zdne]

@blongden now this is interesting discussion, idealistically you describe the resource attributes without its hypermedia controls (affordances, relations) and based on the media type we will provide the representation serialization.

With that being said, you can always opt-out and explicitly describe these payloads (attributes and controls) in MSON without using the "relations header". This will be probably sub optimal and hopefully not needed, but still possible, yes.

Definitely a fair point! We may not be able to accommodate all media types in this but I guess we need to do the cut somewhere (but try to get in as many as possible re Hypermedia Project)