Subject: [Json] Link-relation expressed in JSON?

From: Nat Sakimura <[email-masked]>
Date: Tue, 5 Nov 2013 13:53:11 -0800

I have not been following the list very closely but has there been any
discussion of defining a standard way of expressing link-relationship in
JSON?

We have one in HTML and HTTP and I view the lack of standard for this kind
of thing for JSON as a shortcoming.

In the rechartering, perhaps something like this can be considered?

-- 
Nat Sakimura (=nat)
Chairman, OpenID Foundation
http://nat.sakimura.org/
@_nat_en

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 5 Nov 2013 13:58:14 -0800

It’s been discussed from time to time by various people. 

FWIW I just brought that possibility up obliquely in the discussion of I-JSON (the WG is meeting right now), and several sour faces were made.

Cheers,

On 5 Nov 2013, at 1:53 pm, Nat Sakimura <[email-masked]> wrote:

> I have not been following the list very closely but has there been any discussion of defining a standard way of expressing link-relationship in JSON? 
> 
> We have one in HTML and HTTP and I view the lack of standard for this kind of thing for JSON as a shortcoming. 
> 
> _______________________________________________
> json mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/json

--
Mark Nottingham   http://www.mnot.net/

---

From: Nat Sakimura <[email-masked]>
Date: Tue, 5 Nov 2013 14:27:59 -0800

Perhaps it was a bit too oblique that people did not appreciate the value
:-)

So many specs does the same thing differently.
It is a good indication that there is a value in standardizing it.
It may be a bit of effort to come to a consensus on a syntax, but it is the
whole point of standardization.

I strongly support an effort to create such a spec.

2013/11/5 Mark Nottingham <[email-masked]>

> FWIW I just brought that possibility up obliquely in the discussion of
> I-JSON (the WG is meeting right now), and several sour faces were made.
>
> Cheers,
>
>

---

From: Tim Bray <[email-masked]>
Date: Tue, 5 Nov 2013 14:39:53 -0800

If I were going to add one thing to JSON, it would be built-in date/time
literals.
On Nov 5, 2013 2:28 PM, "Nat Sakimura" <[email-masked]> wrote:

> It may be a bit of effort to come to a consensus on a syntax, but it is
> the whole point of standardization.
>

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 5 Nov 2013 14:42:53 -0800

The problem that I see is that we’re likely to need more than one syntax.

For example, if you want to serialise simple links, you could just do:

“_links": {
	“foo”: “http://www.example.com”
}

But what if you need them to contain more information (target attributes, as per RFC5988)?

Then you’d need:

“_links”: {
	“foo”: {
			“rel”: “http://www.example.com”,
			“type”: “text/xml”
	}
}

Or, what if you want to be able to express multiple links of the same relation? Etc. There are a lot of trade-offs to be made in terms of flexibility and readability that are fairly case-by-case.

Furthermore, I question what utility there is in a standard link format for JSON. Generic tools (i.e., those that don’t understand the format in use) will be able to find and exploit the links, but I wonder how useful that is for JSON data. 

I can imaging extending REDbot <http://redbot.org/> to do things with links that follow a certain format in JSON, but that doesn’t seem like a tremendously compelling use case. Am I missing something?

Cheers,

On 5 Nov 2013, at 2:27 pm, Nat Sakimura <[email-masked]> wrote:

> Perhaps it was a bit too oblique that people did not appreciate the value :-)
> 
> It may be a bit of effort to come to a consensus on a syntax, but it is the whole point of standardization. 
>

---

From: Erik Wilde <[email-masked]>
Date: Tue, 05 Nov 2013 15:07:03 -0800

hello.

> Furthermore, I question what utility there is in a standard link format for JSON. Generic tools (i.e., those that don’t understand the format in use) will be able to find and exploit the links, but…

and it may be educational to look in XML's direction. XML itself also 
does not have links. people usually do not even use the one predefined 
(but very limited) link framework that is fairly general and stable, 
which is XInclude. links are usually defined specifically for XML-based 
media types and described in whatever way that media type deems 
appropriate (often some mix of schema and documentation, sometimes using 
RFC5988 linking, sometimes other ways, and often combining both styles 
in the same media type). it looks like this has worked well so far.

over at the w3c, http://www.w3.org/community/xmlhypermedia/ is an 
attempt to define some general hypermedia framework for XML, but it 
looks as if it hasn't produced a lot of results so far.

cheers,

dret.

-- 
erik wilde | mailto:[email-masked]  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

---

From: mike amundsen <[email-masked]>
Date: Tue, 5 Nov 2013 18:14:54 -0500

IMO, it makes sense to discriminate between expressing links[1] and
expressing hypermedia[2].

I'm not making a case for either, but pointing out that it would be wise to
not conflate the two when discussing _how_ to express "links"

[1] https://gist.github.com/mamund/7328055#file-links-v-hypermedia-js-L1
[2] https://gist.github.com/mamund/7328055#file-links-v-hypermedia-js-L9

mamund
+1.859.757.1449
skype: mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://www.linkedin.com/in/mamund

On Tue, Nov 5, 2013 at 5:42 PM, Mark Nottingham <[email-masked]> wrote:

> Or, what if you want to be able to express multiple links of the same
> relation? Etc. There are a lot of trade-offs to be made in terms of
> flexibility and readability that are fairly case-by-case.
>
> Furthermore, I question what utility there is in a standard link format
> for JSON. Generic tools (i.e., those that don’t understand the format in
> use) will be able to find and exploit the links, but I wonder how useful
> that is for JSON data.
>
> I can imaging extending REDbot <http://redbot.org/> to do things with
> links that follow a certain format in JSON, but that doesn’t seem like a
> tremendously compelling use case. Am I missing something?
>
> Cheers,
>
>

---

From: Nico Williams <[email-masked]>
Date: Tue, 5 Nov 2013 17:15:13 -0600

> If I were going to add one thing to JSON, it would be built-in date/time

I think the idea is to add schema for links, not to extend JSON itself
to denote links (or comments, or add new value types, or...).
Proponents really ought to be clear on this point...

Specifying schemas requires a schema language.  Well, it could be done
in prose but...

Nico
--

---

From: Nat Sakimura <[email-masked]>
Date: Tue, 5 Nov 2013 17:09:10 -0800

Right. I am merely asking for a standard way of writing link-rel in JSON.
I am not talking about extending JSON.

Schema language is nice, but this is simple enough that we can just write
it down in plain English. A straw-man is here:
http://tools.ietf.org/id/draft-sakimura-json-meta-01.html

2013/11/5 Nico Williams <[email-masked]>

---

From: Nat Sakimura <[email-masked]>
Date: Tue, 5 Nov 2013 17:12:50 -0800

For multiple links, would not something like this do?

"_links":{
    "replies":[
        {
              "href":"http://example.com/message/123",
              "type":"text/xml"
        },
        {
              "href":"http://example.com/message/342",
              "type":"text/xml"
        }
    ]
}

I see something like this is being invented many times for each protocol.
e.g., WebFinger, SCIM. I think it would be useful for something like OAuth
as well. For example, if we have something like this in the token response,
then it will be able to return the resource endpoint on which the access
token will be used, and this resource endpoint may change depending on the
users etc. dynamically.
Currently, it is quite static. Yes, it can be done with RFC5988 in the case
of HTTP binding, but if it were bound to other protocols, having such link
relationship in the JSON itself would be useful, IMHO.

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 5 Nov 2013 17:15:27 -0800

>               "href":"http://example.com/message/342",

In some cases, yes. However, if you don’t need the ability to have multiple relations of the same type, it’s needlessly verbose, and the API for pulling out values gets more complex. That’s going to cause friction.

Cheers,

---

From: Nat Sakimura <[email-masked]>
Date: Tue, 5 Nov 2013 17:52:45 -0800

> In some cases, yes. However, if you don’t need the ability to have
> multiple relations of the same type, it’s needlessly verbose, and the API
> for pulling out values gets more complex. That’s going to cause friction.
>

Right. I was debating whether it should always be an array, or could it be
a single object. Requiring it to be always an array makes the JSON stub a
bit verbose like you say. On the other hand, f it is either an array or an
object, then the code has to test the type to start with. So there is a
trade-off for sure.

However, it probably is not much effort after all to write a code to deal
with it so either seems to be fine.

Best,

Nat

---

From: "Martin J. Dürst" <[email-masked]>
Date: Wed, 06 Nov 2013 15:08:02 +0900

Hello Erik,

On 2013/11/06 8:07, Erik Wilde wrote:
>> Furthermore, I question what utility there is in a standard link
>> format for JSON. Generic tools (i.e., those that don’t understand the
>> format in use) will be able to find and exploit the links, but I
>> wonder how useful that is for JSON data.
>
> which is XInclude.

Did you mean XLink? XInclude also uses links, but the general 
functionality it provides isn't linking, it's inclusion (as the name says).

Otherwise, I agree with you. The lesson may be that requirements on 
links vary too much from application to application (see e.g. Mark's 
examples), compared with the relatively negligible implementation 
savings from shared syntax. What's expensive when implementing linking 
is the 'back end', e.g. caching, network access, and so on, and that can 
still be (and in most cases is) shared inside an implementation.

Regards,   Martin.

> links are usually defined specifically for XML-based

---

From: Tatu Saloranta <[email-masked]>
Date: Wed, 6 Nov 2013 08:24:10 -0800

> with it so either seems to be fine.
You are making an assumption that actual programming is used for extracting
data from JSON.
This is not necessarily done especially with static typed languages, where
use of data-binding that maps JSON structure into existing native Object
structure (POJOs in Java, for example) is more prevalent (and would be even
more so if XML/DOM had not established an anti-pattern :) ).
In this case one takes care that structures of JSON and matching Object
hierarchy are compatible enough for fully automated conversion.

The problem with using "Array or Object" approach is that this maps poorly
to object hierarchies of most programming languages; it usually is a union
closely matched by "anything". In practice it may then be unmappable
without extra effort.

So I would recommend not using such composite types: JSON can easily
express it; and schemas that focus on JSON and mostly ignoring mapping
aspect (looking at you JSON Schema) can express it. But it adds impedance
in place where little should exist, between JSON and the host language.

In fact, I would go as far as claim that "developers should not care if
it's JSON or something else", and focus more on logical modeling to make
sure that data can be easily, reliably and efficiently converted between
transfer/serialization format (JSON) and processing format (internal Object
representation of the host language). And this is one of class of
anti-patterns one hits, if focus is too much on JSON side.

-+ Tatu +-

---

From: Nico Williams <[email-masked]>
Date: Wed, 6 Nov 2013 11:28:43 -0600

> You are making an assumption that actual programming is used for extracting

Well, one would think so...  Otherwise we could just use prose!  :)

> more so if XML/DOM had not established an anti-pattern :) ).

Compiler-coded destructuring is still code.

> closely matched by "anything". In practice it may then be unmappable without
> extra effort.

It's just a matter of how you build your JSON abstractions.  The jv C
library, for example, make it very easy to reach deep into a JSON
array/object by path, and the jq C library allows you to write complex
JSON query expressions.  C is statically-typed, and yet with jq/jv
it's trivial to destructure JSON texts with complex schemas.  If you
can do that in C you can do it in any language.

I'm biased because I've been using jq a fair bit, but still, if it
didn't exist, we'd have to build it.

Nico
--

---

From: Tatu Saloranta <[email-masked]>
Date: Wed, 6 Nov 2013 09:36:39 -0800

> Well, one would think so...  Otherwise we could just use prose!  :)

Fine. If we want to split hairs, explicit extraction with specific code to
traverse JSON.

> Compiler-coded destructuring is still code.
I don't follow you here.

> without
Of course, but I think that writing queries, traversing, is the minority
case: more often you let computer do the grunt work of mapping. Why would
you spend your time writing queries, expressions, when you can design the
model that automatically fits?

> didn't exist, we'd have to build it.
You did not actually address my concern at all.

Point is very simple: there is no satisfactory model for mapping "Array or
Object:" into natural and easily usable model in native object model of
most programming languages.
You can of course go into JSON-centric (aka untyped) view that world
consists only of heterogenous arrays and key-value maps; but this is not
the model that programmers handle data, given a chance. They operate on
native Objects with typing specific to proglang in use.

Put another way: you seem to be saying that if one only uses Tree-based
representation and expression language(s), it is possible to deal with any
valid JSON structure. Of course. And that is beside the point.

-+ Tatu +-

---

From: Nico Williams <[email-masked]>
Date: Wed, 6 Nov 2013 11:58:09 -0600

On Wed, Nov 06, 2013 at 09:36:39AM -0800, Tatu Saloranta wrote:
> > [...]

I'm saying that given *sufficiently* complex metadata (like that
discussed in this thread) it might not be possible to simplify it enough
(because it'd be unsatisfactory) to avoid the need for advanced
destructuring capabilities in your programming language or libraries.

I'm not saying that one ought to use Lisp, jq, or whatever.  Or that we
should carelessly write specs that end up requiring such languages in
practice.

The questions here seem to be: whether the metadata in this thread could
be simplified, and if not whether it's worth specifying a schema.  My
answer to the second part is "yes" because clearly such complexity can
be handled and it's better to have a schema than not if the pattern will
repeat often.

Nico
--

---

From: Tatu Saloranta <[email-masked]>
Date: Thu, 7 Nov 2013 10:55:05 -0800

> be handled and it's better to have a schema than not if the pattern will

Fair enough. I agree in that there are complex cases. My point is that
complexity of structure is a choice, and should be made explicit. Based on
JSON usage I have seen, I think modellers are not always aware of
complexities or resulting trade-offs.

To reiterate what I was trying to say was just that I think it is necessary
to not only consider aesthetics of JSON representation, but also its usage
and impedance to usage of data beyond simple transfer or storage.
And that certain kind of polymorphism that is easy in JSON (and
json-centric schemas) -- such as "Object or Array" -- do not map well to
object definitions of programming languages.

-+ Tatu +-

---

From: Nico Williams <[email-masked]>
Date: Thu, 7 Nov 2013 13:08:20 -0600

> complexities or resulting trade-offs.

That's fair.

JSON (and XML) allow for such complex schemas (explicit or otherwise)
that we end up needing XSLT- and jq-like query languages.  It'd be
nice if such complexity could be avoided in many cases, but there's a
trade-off: flattening the schema will simply move the complexity into
object names (keys) and result in if ladders in actual code.  Perhaps
this should be noted somewhere, but there's more pressing things to do
I think.

> And that certain kind of polymorphism that is easy in JSON (and json-centric
> schemas) -- such as "Object or Array" -- do not map well to object
> definitions of programming languages.

Right.  Having something like XSLT for JSON (jq!) really helps.

Nico
--

---

From: Erik Wilde <[email-masked]>
Date: Thu, 07 Nov 2013 11:10:34 -0800

hello.

On 2013-11-07, 10:55 , Tatu Saloranta wrote:
> complexity of structure is a choice, and should be made explicit. Based
> on JSON usage I have seen, I think modellers are not always aware of

there is so much existing JSON out there that instead of creating a 
"standard for hyperJSON", an alternative approach might be to just 
collect and document (some of the) existing design patterns out there, 
and compare and highlight their constraints in terms of what they can 
and cannot represent. that might already be a very useful starting point 
for JSON designers, and would give them a good starting point for how to 
design that aspect of their JSON representations.

cheers,

dret.