Clarification on the execution of complex types

[jlouis]

Hi!

Setup

We're in the process of implementing a GraphQL server for the programming language Erlang, and we're trying to get by with only reading the specification and looking relatively little at code, in the hope this will uncover some inconsistencies in the spec. In general, I'm really happy with the specification, but I need some clarification on the combination of non-null when it is combined with the list type.

I feel this combination is part of the dynamic semantics of GraphQL, which is execution semantics. Yet, the only section in the draft spec which covers this is section 4.2.2.9, http://facebook.github.io/graphql/#sec-Combining-List-and-Non-Null which is part of the introspection system. I'm not sure why it is there, and not in the execution semantics of the spec, where I would have expected to find this. Is there another place where this is written down, and am I reading the spec with too much skimming?

Also, I'm not sure how to read the 4.2.2.9 section with respect to evaluation semantics. In order to be able to ask the question, here is my example, taken from an internal test schema where we are building a dungeon containing rooms, monsters, and so on:

type Stats {
    shellScripting: Int! # How good a monster is at shell scripting
    yell: String
}

type Monster {
    id: Id!
    name: String!
    statsV1: [Stats]
    statsV2: [Stats]!
    statsV3: [Stats!]
    statsV4: [Stats!]!
    ...
}

As you can see, we have monsters, and monsters have stats, possibly many in a list. We can represent a monster internally as a record:

#monster {
    id = "1",
    name = "Two-Headed Ogre"
    stats = [
        #stats { shell_scripting = null, yell = "I'm Ready!" },
        #stats { shell_scripting = 5, yell = "I'm NOT Ready!!!" }
    ]
}

And we can resolve the fields of statsV1, ..., statsV4 by using the stats field of that record. The question is how it would resolve.

Expectation

The two-headed ogre we just defined has a bug: when rendering stats for the two heads, the first head has a shell scripting value of null which will produce an error for the Stats object of a non-nullable shellScripting field. This means an error will be raised for the first head, while the second head will render okay.

Lets set up a query document:

query Q1 { monster(id: "1") { statsV1 { shellScripting, yell }}}
query Q2 { monster(id: "1") { statsV2 { shellScripting, yell }}}
query Q3 { monster(id: "1") { statsV3 { shellScripting, yell }}}
query Q4 { monster(id: "1") { statsV4 { shellScripting, yell }}}

Q1

In this case, I think the output would be

{ data:
    monster: {
        statsV1: [null, { shellScripting: 5, yell: "I'm NOT Ready!!!"}]
    }
}

The resolver for Stats will return null for the shellScripting field which is non-null and thus the whole object becomes null. It is reflected in the list.

Q2

I think the output would be

{ data:
    monster: null
    }
}

Since the [null, ...] output for statsV2 means there is a null value in the context of [Stats]! and this is not allowed. Thus the whole monster becomes null.

Q3

I think the output would be

{ data:
    monster: {
        statsV3: [{ shellScripting: 5, yell: "I'm NOT Ready!!!"}]
    }
}

Since the rule is that null entries are removed from the list (at least that is how I read 4.2.2.9 in this case).

Q4

Either disallowed by the static semantics, or it essentially behaves as Q2.

Current implementation I have

I run this by a recursion over the list entry. Resolution of the underlying objects in the list returns a value that is either "ok" or an "error"

{ok, Object} | {error, Reason}

This means we have the following list resolved in the execution engine:

[{error, {null_field, "shellScripting"}}, {ok, SecondHeadObject}]

Where the binding of SecondHeadObject is #{ <<"shellScripting">> => 5, <<"yell">> => <<"I'm NOT Ready!!!">> }, an Erlang map() type we can turn into a JSON object later. We can now scrutinize the modifiers. There are 4 cases:

• Q1: Turn {error, _} into null values, and {ok, _} into normal values. Easy.
• Q2: The case is a [...]!, i.e., a list wrapped in a non-null modifier. Check the list for {error, _} terms. If one is found, return {error, ...} for this field. Otherwise, turn {ok, _} into normal values and return those.
• Q3: The case is [...!], i.e., a non-null modifier wrapped in a list. Filter the list and pick {ok, _} values only.
• Q4: Handle as Q2.

What I don't particularly like about this implementation is that it doesn't compose too well. I have to look at which modifier is the outer-one (List/Non-null) and which is the inner one and then handle these by looking at both at the same time. I'd much have preferred a semantics where I could have handled non-null and list separately in the execution engine. But perhaps my semantics are just off?

Question:

Am I right or completely off track here? Can I help improving the specification in any way (Note: I'm not a native English speaker, this may have an effect)? But before I can submit a request on the specification, I would need to know the logic behind the dynamic execution semantics of the above queries in question.

Thanks in Advance!

[eapache]

I read [Stats]! as preventing the list from being null but allowing elements of the list to be null, so I would expect Q2 to behave identically to Q1.

[eapache]

Q3
Since the rule is that null entries are removed from the list (at least that is how I read 4.2.2.9 in this case).

That's not how I read 4.2.2.9 (but I could be wrong).

My interpretation of [Stats!] is that the list itself may be null but that it may not contain null elements. I don't have any spec to back this up, but I would assume that resolution would behave the same way as when a non-null field returns null, so the end result would be:

{ data:
    monster: {
        statsV3: null
    }
}

The element of the list cannot be null, so the null propagates to the list field as a whole, which can.

[eapache]

Q4
Either disallowed by the static semantics, or it essentially behaves as Q2.

This definitely behaves as you described Q2. The null propagates until it reaches monster, which is nullable.

[leebyron]

There were some recent clarification improvements to the execution phase. Specifically http://facebook.github.io/graphql/#sec-Value-Completion should describe the interrelationship between List and Non-Null types during the execution of field values.

Please let me know if you still have questions after reading this section, and hopefully we can use your feedback to further clarify or perhaps to add examples.

[leebyron]

Let me try to use your example and attempt to simplify and then show some example data:

Just for simplicity I'll use the following simple forms to represent values:

Simple	Typed
1	{some, Value: 1}
null	{none}
Error(whoops)	{error, Reason: "whoops"}

With this schema:

type Query {
  a: Wrapper
}

# Where Type is one of the types below
type Wrapper {
  b: Type
}

Where Type is one of:

• Int
• Int!
• [Int]
• [Int]!
• [Int!]
• [Int!]!

Where the value found at a.b is one of:

• 1
• null
• Error(whoops)
• []
• [1, 2]
• [1, null]
• [1, Error(whoops)]

Int

Int, 1

{
  data: { a: { b: 1 } }
}

Int, null

{
  data: { a: { b: null } }
}

Int, Error(whoops)

{
  data: { a: { b: null } },
  errors: [ { message: "whoops", path: [ "a", "b" ] } ]
}

Int, []

{
  data: { a: { b: null } },
  errors: [ { message: "invalid value", path: [ "a", "b" ] } ]
}

Int, [1, 2]

{
  data: { a: { b: null } },
  errors: [ { message: "invalid value", path: [ "a", "b" ] } ]
}

Int, [1, null]

{
  data: { a: { b: null } },
  errors: [ { message: "invalid value", path: [ "a", "b" ] } ]
}

Int, [1, Error(whoops)]

{
  data: { a: { b: null } },
  errors: [ { message: "invalid value", path: [ "a", "b" ] } ]
}

Int!

Int!, 1

{
  data: { a: { b: 1 } }
}

Int!, null

{
  data: { a: null },
  errors: [ { message: "invalid null", path: [ "a", "b" ] } ]
}

Int!, Error(whoops)

{
  data: { a: null },
  errors: [ { message: "whoops", path: [ "a", "b" ] } ]
}

Int!, []

{
  data: { a: { b: null } },
  errors: [ { message: "invalid value", path: [ "a", "b" ] } ]
}

Int!, [1, 2]

{
  data: { a: { b: null } },
  errors: [ { message: "invalid value", path: [ "a", "b" ] } ]
}

Int!, [1, null]

{
  data: { a: { b: null } },
  errors: [ { message: "invalid value", path: [ "a", "b" ] } ]
}

Int!, [1, Error(whoops)]

{
  data: { a: { b: null } },
  errors: [ { message: "invalid value", path: [ "a", "b" ] } ]
}

[Int]

[Int], 1

{
  data: { a: { b: null } },
  errors: [ { message: "invalid value", path: [ "a", "b" ] } ]
}

[Int], null

{
  data: { a: { b: null } }
}

[Int], Error(whoops)

{
  data: { a: { b: null } },
  errors: [ { message: "whoops", path: [ "a", "b" ] } ]
}

[Int], []

{
  data: { a: { b: [] } }
}

[Int], [1, 2]

{
  data: { a: { b: [1, 2] } }
}

[Int], [1, null]

{
  data: { a: { b: [1, null] } }
}

[Int], [1, Error(whoops)]

{
  data: { a: { b: [1, null] } },
  errors: [ { message: "whoops", path: [ "a", "b", 1 ] } ]
}

[Int]!

[Int]!, 1

{
  data: { a: null },
  errors: [ { message: "invalid value", path: [ "a", "b" ] } ]
}

[Int]!, null

{
  data: { a: null },
  errors: [ { message: "invalid null", path: [ "a", "b" ] } ]
}

[Int]!, Error(whoops)

{
  data: { a: null },
  errors: [ { message: "whoops", path: [ "a", "b" ] } ]
}

[Int]!, []

{
  data: { a: { b: [] } }
}

[Int]!, [1, 2]

{
  data: { a: { b: [1, 2] } }
}

[Int]!, [1, null]

{
  data: { a: { b: [1, null] } }
}

[Int]!, [1, Error(whoops)]

{
  data: { a: { b: [1, null] } },
  errors: [ { message: "whoops", path: [ "a", "b", 1 ] } ]
}

[Int!]

[Int!], 1

{
  data: { a: { b: null } },
  errors: [ { message: "invalid value", path: [ "a", "b" ] } ]
}

[Int!], null

{
  data: { a: { b: null } }
}

[Int!], Error(whoops)

{
  data: { a: { b: null } },
  errors: [ { message: "whoops", path: [ "a", "b" ] } ]
}

[Int!], []

{
  data: { a: { b: [] } }
}

[Int!], [1, 2]

{
  data: { a: { b: [1, 2] } }
}

[Int!], [1, null]

{
  data: { a: { b: null } },
  errors: [ { message: "invalid null", path: [ "a", "b", 1 ] } ]
}

[Int!], [1, Error(whoops)]

{
  data: { a: { b: null } },
  errors: [ { message: "whoops", path: [ "a", "b", 1 ] } ]
}

[Int!]!

[Int!]!, 1

{
  data: { a: null },
  errors: [ { message: "invalid value", path: [ "a", "b" ] } ]
}

[Int!]!, null

{
  data: { a: null },
  errors: [ { message: "invalid null", path: [ "a", "b" ] } ]
}

[Int!]!, Error(whoops)

{
  data: { a: null },
  errors: [ { message: "whoops", path: [ "a", "b" ] } ]
}

[Int!]!, []

{
  data: { a: { b: [] } }
}

[Int!]!, [1, 2]

{
  data: { a: { b: [1, 2] } }
}

[Int!]!, [1, null]

{
  data: { a: null },
  errors: [ { message: "invalid null", path: [ "a", "b", 1 ] } ]
}

[Int!]!, [1, Error(whoops)]

{
  data: { a: null },
  errors: [ { message: "whoops", path: [ "a", "b", 1 ] } ]
}

[leebyron]

Some notes on constraints and interpretations:

[Int]! means that the value itself must not be null, but items in the list can be null.
[Int!] means that the value itself can be null, but items in the list must not be null.

When propagating errors and inserting nulls, the index of items in a list must never be changed. So converting [1, null, 3] to [1, 3] would be illegal

[jlouis]

Hi Evan & Lee,

Thank you both for your comments. I'm somewhat offline with a cold at the moment, but I just wanted to give you a heads up and thanks. I'll come back to this with a vengeance later on once I have a better understanding (and my brain is back on-line :)

[jlouis]

Having read through it all:

In your example, there is a case I'm not sure I understand fully. The case is Int!, [] and the other "value" cases, the result you wrote is { a: { b: null } }, but as int is non-nullable, I would have expected that to propagate to the wrapper: { a: null }. But perhaps I'm mistaken?

What ultimately led me astray was the 4.2.2.9 section.

• "If the modified type of a List is Non‐Null, then that List may not contain any null items." -- I read this as [T]! for some type T. But this outright contradicts what you wrote above.
• "If the modified type of a Non‐Null is List, then null is not accepted, however an empty list is accepted." -- I read this as [T!] for some type T. Also in direct contradiction.

I see how I "flipped" the designators by accident.

Perhaps because there is a subtlety picked up naturally by native English speakers I fail to pick up? Maybe one could add the type scheme explicitly, so the mistake isn't made.

Once I read through your examples, it becomes quite clear how this is to be resolved and the documentation is actually pretty precise around CompleteValue(..). You resolve the "inner" type of the non-null field and then complete that field.

One thing I would have written different in section 6.4.3 on value completion is point 3.c on how to complete a list of values. Specifically, how do you work yourself through the list[0]? If we have a list and we have an error at completing the element with a given index i, do we still try to complete elements j > i in the list, or do we abort completion at index i without ever looking at the remaining elements? In particular, I'd make it explicit how the presence of field errors (which are thrown) propagates. Mostly because some languages are less likely to use exceptions for handling the control flow[1]. I can somewhat guess that a single field error in a list propagates that error upwards, but I don't like guessing in specifications :)

Also in section 6.4.3, point 1 tells me how to handle a non-null value, but it doesn't say how to handle the presence of an error explicitly. Specifically, in your case above we have Int! Error("whooops"). This is clearly a non-null Integer type. So we recurse on the inner type, use point 4 to resolve the Int scalar. This point says nothing about the resolution of an error. But we can argue that Error("whooops") is not a valid, so it resolves to null which point 1 knows how to handle, by throwing a field error. But if we have [Int!]! "whoops" then the non-null handler in point 1 would recurse to point 3.a and get back a thrown field error, which it says nothing about how to handle.

In point 1.c and point 3.a we can "throw a field error". What does this mean? How does thrown errors propagate the recursion stack? Are they handled at some level of the recursion, or do they bleed through to the top-level?

Perhaps my query becomes more coherent over the coming days once I start implementing the code paths of value completion as precisely as possible--but right now, the above questions are the ones I have w.r.t CompleteValue(..) call. The crux is the interaction of errors and values, and the propagation of errors in the recursion stack. I'd make the wording very boring and nitpicky: "if completedResult is an error, then ...", and "... otherwise, return the completedResult". In short I would treat exceptions as were they values. That way, you can give them exception semantics, if you want, by being explicit about their propagation.

[0] In a mechanized formalization in e.g., Agda, Coq or Twelf, you would need to be extremely specific in how you complete the list here. The interaction of completion with errors would need to be nailed down.

[1] At least Haskell, Erlang, and Go would be likely to avoid using exceptions as control flow operators, and many OCaml and Standard ML implementations would too.

[jlouis]

Hi!

Just FYI: I managed to get this working as expected in the code I have, so there is no reason to keep this issue open unless you want to improve the wording around the parts where I went astray.