JSON-LD support?

[kevinSuttle]

I know GraphQL theoretically has no problem fetching data in JSON-LD format, but I'm wondering if there could be more 1st-class support for:

• Schema validation
• expansion/contraction
• @embed, @link

etc.

[akuckartz]

👍

[leebyron]

Thanks for opening this. There are two topics this address that I'd like to tackle soon.

The first is normalized responses. While GraphQL operates over data modeled as a graph, it's response format looks decidedly tree-shaped not graph-shaped. The "-LD" part of JSON-LD is a critical addition to model a whole graph. There is a lot to this topic and decisions on how to address this will have implications both on how to model async and live queries where a server may want to issue "diffs" after an initial payload as well as implications on client code. Where JSON is widely accepted, anything other than vanilla JSON will require additional work by clients, so we want to settle on a common ground that weighs these things carefully.

The second is custom response formats. Right now graphql-js simply produces a (JSON compatible) JavaScript object given a GraphQL query, with the assumption that you'll call JSON.stringify before sending it back over the network. It's totally reasonable to think that you might want to produce a different output format, both for supporting normalized linked-data responses, but also for supporting other types of responses like creating Immutable.js collections to send via transit-js or for creating Protocol Buffers.

[leebyron]

Another interesting JSON format is jsongraph which represents more specific graph formalisms using JSON.

[kevinSuttle]

@leebyron I was thinking about support of JSON-LD specifically because of its relationship to the underlying tech that powers search engines.

https://schema.org/docs/about.html

[kevinSuttle]

Interesting comment in this article:

I'd be tempted to make the server send back some JSON-LD to help here: each object (the user object and the profileData subobject) can have an @id for its canonical URL and a @type as a type designator. A client-side cache could exploit this @id information to store information about the objects it already knows about. Client-side code could also use this information to deal with normalized APIs transparently: it can automatically fetch the sub-object for you if it's not embedded, at the cost of performance.

[kevinSuttle]

cc: @schrockn @dschafer

[kevinSuttle]

"Comparing GraphQL with SPARQL and JSON-LD Framing" https://lists.w3.org/Archives/Public/public-linked-json/2015Feb/0010.html

[venturecommunism]

+1 to JSON-LD

[leebyron]

Thanks for the link, that was an interesting read!

I think what would help enable next steps is to move backwards from the specific technology of JSON-LD and talk instead about the specific features and semantics we want to enable.

I'm only so familiar with JSON-LD so I defer to your experience with it, but my understanding is that the core premise is that various JSON documents served from URIs can refer to one another via IRI ids. I'm not sure I understand how that relates to GraphQL which is more of an RPC or query language that happens to return results in JSON by default. There is usually no concept of URIs or individual documents. So I'm a little concerned that the initial premise is flawed.

Some problems JSON-LD solves are very relevant though! Particularly interesting are "graph mode" which allows the representation of a true representation of a directed-graph (even containing cycles!) where plain JSON does not. That's also predicated on having a common ID format, which is something that we currently leave to the developer but could be valuable to standardize.

Another interesting element to JSON-LD is the notation for types and contexts for interpreting those types. GraphQL has this today by querying "__typename" and via introspection you can see the whole schema that applies (as I understand the equivalent to context)

Another question I have is if it's not just the individual features and semantics that interest you but the ability to inter-operate with non-GraphQL based JSON-LD. If so, I'm curious what you think this should look like.

I found a perhaps relevant presentation about MongoDB + JSON-LD. It's still a little too reliant on HTTP in particular to apply directly to our protocol agnostic spec, but perhaps can provide some insight: https://www.slideshare.net/mobile/gkellogg1/jsonld-and-mongodb

[venturecommunism]

I want to be able to say that two URIs are the same in some philosophical or practical sense as each other, in some context, for some purpose, and still know which one I'm looking at either by looking at the key or the key's namespace.

[kevinSuttle]

So, maybe let's focus on one major use case (which GraphQL may have its own methods of doing now—I'm not totally sure):

Formal relationship definitions

The expansion/compaction is confusing at first. Think of it like relative URLs. The @context is what allows that, and in a way that is both human-friendly, and machine-friendly.

Here's an example: npm uses a schema from http://schema.org to render package metadata on their site.

https://github.com/npm/newww/blob/master/templates/package/show.hbs#L232
https://www.npmjs.com/package/graphql

[joshblack]

I think it's important to note that in terms of what is machine/human-readable, this is the role of GraphQL's underlying type system. If we take a schema from schema.org, for example a person:

{
  "@context": "http://schema.org",
  "@type": "Person",
  "address": {
    "@type": "PostalAddress",
    "addressLocality": "Seattle",
    "addressRegion": "WA",
    "postalCode": "98052",
    "streetAddress": "20341 Whitworth Institute 405 N. Whitworth"
  },
  "colleague": [
    "http://www.xyz.edu/students/alicejones.html",
    "http://www.xyz.edu/students/bobsmith.html"
  ],
  "email": "mailto:jane-doe@xyz.edu",
  "image": "janedoe.jpg",
  "jobTitle": "Professor",
  "name": "Jane Doe",
  "telephone": "(425) 123-4567",
  "url": "http://www.janedoe.com"
}

We can easily model the type using GraphQL, as well as its relationships, using the underlying type system:

const personType = new GraphQLObjectType({
  name: 'Person',
  description: 'A person in our product',
  fields: () => ({
    address: {
      type:  addressType
    },
    colleagues: {
      // Note the recursive type in this case
      type: new GraphQLList(personType)
    },
    // ...
  })
});

These types are accessible to clients through introspection, and ultimately allow users to validate queries against the schema for the information that they are requesting.

Where JSON-LD will validate properties according to urls, http://schema.org/person for example, GraphQL leverages types that you define in your system. The expansion and compaction algorithms that change person to http://schema.org/person and http://schema.org/person to person respectively are unnecessary in a GraphQL context, as queries ask for the name that you would want to work with, person in this example. No mapping from name --> URI given a context is necessary.