graphql / graphql-spec Goto Github PK

This is a totally stylistic, bikeshedding comment... but maybe worth considering if I'm not missing something obvious.

It seems like both the informal schema format and query variables could be simplified by eliminating the colon from type definitions and dollar sign from variables. Right now the colon is used in so many different contexts (variables, types, interfaces, aliases). The similarity between type definitions and passing arguments in particular is mildly confusing.

Why not change :

type Person : NamedEntity {
  name: String
  gravatar(height: Int, width: Int): Gravatar
}

to

type Person : NamedEntity {
  name String
  gravatar(height Int, width Int) Gravatar
}

The same with queries. Why not change:

query myQuery($someTest: Boolean, $size: Boolean) {
  gravatar(size: $size)
  experimentalField @include(if: $someTest)
}

to

query myQuery($someTest Boolean, $size Boolean) {
  gravatar(size: $size)
  experimentalField @include(if: $someTest)
}

so that outer type definitions and inner arguments don't look so similar.

Finally, is the dollar sign really required? Why not just:

query myQuery(someTest Boolean, size Boolean) {
  gravatar(size: size)
  experimentalField @include(if: someTest)
}

I can understand why making types nullable by default might be a reasonable decision for growing systems adding new features but I think there are reasons why this might not be ideal:

1. This conflates the idea of nullability with providing reasonable default values. By allowing new features to be nullable by default, we push more responsibility to the application logic for determining what might be the right behavior.

2. Because making types nullable is so easy in practice, it promotes not considering if data should even be nullable or not. This could escalate the system's entropy more quickly making it hard to reason about the system's intended behaviour.

I'd love to hear other thoughts or ideas on this!

If the idea is to write a query that reads as the outcome, wouldn't we want to fetch arrays differently? Right now we fetch data like this:

query HeroNameAndFriendsQuery {
  hero {
    id
    name
    friends {
      id
      name
    }
  }
}

This doesn't give me a visual indication friends will output an array. Why wouldn't we want to write it like:

query HeroNameAndFriendsQuery {
  hero {
    id
    name
    friends [
      id
      name
    ]
  }
}

Very fascinating read! Thank you for open-sourcing :)

Looks like the Input Coercion paragraph of Non-Null types in Section 3 -- Type System has incorrectly been copied from the section right above about Lists.

Should input objects return a keyed set when introspecting for inputFields the way object do for fields?

Currently, the spec on introspection says that input objects have an inputFields query that returns a list. Object, on the other hand, have a fields query that returns a keyed set. Both input objects and objects take maps, even if the keys are just 0, 1, 2, 3. Is there a reason that introspection does not return a keyed set of fields for input objects? In a similar vein, why not just have the introspection query be 'fields' for both?

In my experience long is pretty common primitive data type. It also used to represent pretty common things like timestamps or cent amounts. As a result of it, most of modern programming languages naively support 64-bit integer values in one form or another. Is there particular reason why long scalar type was not included in the spec?

Name is context-sensitive in that, for example, the string "on" is a Name unless it appears in a place in the grammar that requires on specifically (e.g., right after an ellipsis, as in InlineFragment, or two tokens after fragment, as in FragmentDefinition). Naive application of tools like flex and bison seems likely to produce a system that doesn't allow apparent "keywords" like on/fragment/query/mutation to be used as Names (e.g., as the names of fields). We should add test cases in src/language/__tests__/parser.js that demonstrate that these are legal Names.

One thing is not clear - how should it be handled if the result is an array (like users, where age > 40) ? Should all query return with a GraphQL list type, or how do you make a difference?

I'm a developer of LoopBack (http://www.loopback.io), an open source Node.js framework for building APIs with rich data integrations. I'm opening this issue to explore the possibility of collaboration as both projects try to solve similar problems.

LoopBack already provides a lot of capabilities as you outline in the GraphQL spec, including:

1. A JSON based definition language for data models (types and validations) - http://docs.strongloop.com/display/LB/Model+definition+JSON+file
2. Relations that connect models (BelongsTo, HasMany, HasOne, HasMany-Through, EmbedsMany, ReferencesMany, Polymorphic) to form data graphs - http://docs.strongloop.com/display/LB/Creating+model+relations
3. A JSON based query language - http://docs.strongloop.com/display/LB/Querying+data
4. A large list of connectors that implement the CRUD operations based on the specs - http://docs.strongloop.com/display/LB/Connecting+models+to+data+sources

What do you think?

PS: I'm not sure if this is a good way to reach out. Please let me know if we should take it offline. Thanks in advance.

While the document explicitly mentions the inbuilt type ID ([Section 3.1.1.1.5](From the description in [Section 3.1.1.1.5]%28http://facebook.github.io/graphql/#sec-Values%29) it is not to be found in the the list of possible types a field can have (Section 8.2.4). This leaves the ID type without a specific definition! Should its value be a Name or a StringValue?

We need a way to listen to changes performed by someone else than the local client in order to build true real-time apps based on GraphQL. Similar to how Firebase and Meteor work.

I know this is being discussed on Slack but a proper ticket is missing.

in section4.md ,

Take an example query for a trivial app. In this case there is a User type with
three fields: id, user, and birthday.

user should be name

Take an example query for a trivial app. In this case there is a User type with
three fields: id, name, and birthday.

Let's say I have a schema for some translated content with a common interface for entries:

interface Entry {
  id: ID
  slug: String
  translations: [Entry]
}

type Page implements Entry {
  id: ID
  slug: String
  translations: [Page] # Page implements Entry, this should be ok
}

In graphql-js this errors, saying the translations on Page should be of type [Entry]. Since Page implements Entry and translations of a Page will only ever be Pages, this seems ok to me.

Tried the same with union types with the same result. It's not a disaster, I can widen it to the interface type and use a type fragment in queries, but it seems a little unwieldy.

Am I missing a reason why it's not valid to narrow down an interface type when implementing an interface which specifies a field of an interface type? (uh, sorry, can't make that sentence any simpler)

Didn't see anything in the spec about this. I assume it's coming?

Hi,

With GraphQL (and relay) there is the potential of fetching the data for an entire screen in one query. This is great because it is simple but sometimes (if not most of the times) you want to grab the main content first (article content) and then grab the surroundings (related content, comments, stats of the article, etc) to improve the user experience.

Of course there is the option of making two separate GraphQL queries but, since the idea (especially with relay) seems to be having everything declarative, I'd rather avoid this option.

I'm wondering if there is a way of doing this. If not, it may be interesting to consider this use case, maybe in conjunction with subscriptions (give me the article content now and send me the rest once it is computed?)

Thanks for your time.

Hey facebook,

First of all, thanks for open sourcing this, I'm so excited I forgot how to even.

With that out of the way, I have a question, how is pagination implemented in the facebook schema? There is no mention of pagination in the spec so I assume is implemented adhoc using the primitives provided by the spec. A hint on how to model this common use case would be really appreciated.

What I have in mind is some is some Page type. Which yields the following question: is it possible to define generic types the same way that List is defined? Asking because ideally such Page type would be Page<T>

Also, I'd also appreciate some advice on how to model querying for the count of a list property or a paginated property. In 2.10.1 Types of fragments there is the following example:

query FragmentTyping
{
  profiles(handles: ["zuck", "cocacola"]) {
    handle
    ...userFragment
    ...pageFragment
  }
}

fragment userFragment on User {
  friends { count }
}

fragment pageFragment on Page {
  likers { count }
}

There is no schema attached for that example, but as far as I understand, those fragments are trying to get the total number of friends of a user and the total number of likes of a Page. It is hard to say without the schema, but if we assume that a User has a List of Users, the fist fragment is really querying for the property count in each individual User of said list, and not the property count in the list itself (which is the intention, arguably). Any light in this topic would be very much appreciated.

Thanks for open sourcing this and for your time.

Please correct me if I missed it in the spec, but I haven't found a formal definition of the whitespace treatment combined with some of the tokens. For example in the detective definition. It's not 100% clear whether whitespace is allowed between @ and Name. The same is for the variable: can I put a whitespace between $ and the Name like this?

$ myVariable

Intuition tells me that in most cases whitespaces are allowed, so query like this:

query    , FetchLukeAndLeiaAliased{
  luke:human(id   :  2.1e-7) {
    name,
  }
  leia       ,  : human   ,,, ( , id ,, : ,, "10103") {
    name
  }
}

is a valid query and should be parsed without any errors. Is my assumption correct?

in section 5 ### Field Selections on Objects, Interfaces, and Unions Types,
" Because fields are not declared on unions, direct field selection on union-typed selection set. This is true even if concrete implementors of the union define the fieldName."
what does "direct field selection on union-typed selection set." mean?

Does grammar allow Unicode 'HORIZONTAL ELLIPSIS' char (U+2026) as a substitute for 3 consequent dots? If yes, then it would be nice to have this fact explicitly stated in the spec.

Section 8.2 lists TypeExtension, TypeDefinition and EnumDefinition under Definition but fails to explain these definitions.

This just feels like SQL all over again where you have to do string concatenation rather than building real data structures to talk to a server. Using a data format (or formats) would be far friendlier and less error prone to implement in the long run. For example I was working with a .NET implementation recently that didn't quite have the grammar implemented correctly and allowed for strings to be provided to the server that didn't have correctly closing curly braces. Data structure formats basically prevent this kind of thing and many other easy to create problems with custom grammars.

If the syntax could be defined in terms of data structures rather than a custom grammar it would make implementations on both client and server simpler and more flexible. Versioning the spec would likely also be simpler. Testing is definitely simpler on both ends as well since you can use the native data structures of your environment with a little conversion to json, or EDN, or whatever you want for the wire format(s).

Suppose we have a forum where users can reply to comments recursively:

type RootQuery {
  message(id: String): Message
  messages: [Message]
}

type Message {
  id: String!
  content: String
  comments: [Message]
}

How could the client query for the nested comments?

This only goes three levels deep:

{
  messages {
    comments {
      id
      content
      comments {
        id
        content
        comments {
          id
          content       
        }
      }
    }   
  }
}

Would a consecutive query starting at the last comment be the right solution?

{
  message as comment($commentId) {
    comments {
      id
      content
      comments {
        ...
      }
    }
  }
}

Original SO post

scala.js emits constructor names with$ chars , react-relay takes constructor name as mutation query name and resulting in failed transactions :(. i reported this in scala.js channel

@sjrd is it possible to remove $ in generated constructor/class names for scalajsdefined classes ? graphql supported names set /[_A-Za-z][_0-9A-Za-z]*/, with current constructor names graphql api requests are failing in fastOptJS mode

response from scala.js author :

@chandu0101 No it is not possible. graphql most be fixed to support all valid Javascript identifiers.

so is it possible to accept names that comply with javascript identifiers ?

const FooType = new GraphQLObjectType({
  name: 'Foo',
  fields: () => ({
    id: globalIdField('Food', obj => obj.id),
    bar: {
      type: new GraphQLList(BarType),
      resolve: obj => getBarsForFoo(obj.id),
      resolveCost: n => n * 5,
    },

In this example, n is the number of times this field is requested across all Foos within the query. This may not be possible in pure GraphQL, since the number of results requested is dependent on how the schema is configured, but with a standardised API for connections like in Relay, it might be possible. The 5 is arbitrary, cheap fields would probably have a 0 or 1.

The end result would be the ability to reject queries over a certain cost, but also allow IDEs to warn developers that a particular query is risky.

As originally discussed in graphql/graphql-js#45, it would be useful to be able to declare a field type to be a combination of interfaces.

As an example use-case, let's say I have an interface

interface Image {
  src: String
}

which represents an image I can display. Some images are stand-alone and I can link to them as a page, but other things share that capability (videos for instance). So I have another interface

interface Linkable {
  url: String
}

Now let's say that all users have profile pictures which are linkable. I'd like to be able to declare something like this

type User {
   profilePicture: Image + Linkable
}

When resolving such type, the only requirement is for the interfaces not to contain the same attributes. From there it should be possible to find the defining interface for each attribute and then the implementing type based on interface type resolution.

If we have a simple query, with only a SelectionSet:

{
    hero {
        name
    }
}

which is the same as

query HeroNameQuery {
    hero {
        name
    }
}

The tests in graphql.js show this expected answer:

{
    data: {
        hero: {
            name: 'R2-D2'
        }
    }
}

I know we can have many root in one query:

query FetchLukeAndLeiaAliased {
    luke: human(id: "1000") {
        name
    }
    leia: human(id: "1003") {
        name
    }
}

Resulting in this answer:

{
    data: {
        luke: {
            name: 'Luke Skywalker'
        },
        leia: {
            name: 'Leia Organa'
        }
    }
}

But, and it's my main concern, what if we have more that one operation in one query, which seems to be valid in the specifications (examples in http://facebook.github.io/graphql/#sec-All-Variable-Uses-Defined and http://facebook.github.io/graphql/#sec-All-Variables-Used).

For example what is the expected answer for this graphql query (dumb query just for the example):

query LukeAndLeiaNames {
    luke: human(id: "1000") {
        name
    }
    leia: human(id: "1003") {
        name
    }
}

query LukeAndLeiaHomePlanet {
    luke: human(id: "1000") {
        homePlanet
    }
    leia: human(id: "1003") {
        homePlanet
    }
}

I currently have no idea, except that there should be one more level between data and a query result using the name of the operation (which must be unique in the document, as said in the specification).

Or each query have its own "object" response, with data, errors... But in this case how are they "encapsulated"? In a main object with the operation names used as keys ? I could not find anything about this in the specification or the graphql.js tests.

Thanks for your answer, I'm currently writing a python graphql server and it will help me to know that ;)

The Fragment Directives section says that "At runtime, the directives provided on a fragment spread override those described on the definition.", but "override" here is not sufficiently precise. Consider the following example:

query example { ...F @bar }
fragment F on Query @foo { some_field }

Is this equivalent to using both @foo and @bar or just @bar? (Presumably, "neither" and "just @foo" wouldn't be consistent with "override.") Does it matter if @bar and @foo have any kind of interaction in their effects?

Just define it so that fields are deprecated iff they have a non-null deprecationReason.

I have a mutation which has a custom scalar type in the input field,

// Scalar Type
var PLString = new GraphQLScalarType({
    name: "PLString",
    serialize: value => {
      return value
    },
    parseValue: value => {
      return value
    },
    parseLiteral: ast => {
      throw new Error("This string is not valid")
      return ast.value
    }
  })
}

This is my mutation,

mutation: new GraphQLObjectType({
    name: 'Mutation',
    fields: {
      login: {
        type: GraphQLString,
        args: {
          text: { type: PLString }
        },
        resolve: () => "Immutant"
     }
    }
});

When I make a graphql mutation like this,

mutation PL {
  login(text: "this is text")
}

I get the error

{
  "errors": ["This string is not valid"]
}

But when I do this with query variables like this,

mutation PL($input: GraphQLString) {
  login(text: $input)
}

//variables
{
  "input": "this is text"
}

It succeeds

{
  "data": {
     "login": "Immutant" 
   }
}

Is this the expected behavior of GraphQL or is this a problem with the js implementation and maybe I should have posted there .. but its its too late now i guess..

I'm fairly certain this is not currently possible, and I'm not even sure it is desirable. That said, is there some way to specify an argument variable based on previously fetched data?

For example, lets assume we have a contentItem type. That contentItem has two fields, isLive and liveData. liveData includes a bunch of information about who set the contentItem to be live and when. We want that information, but only if the contentItem is actually live.

query content {
  contentItem {
    isLive
    liveData @include(if: $isLive) {
      liveTime
      user {
        username
      }
    }
  }
}

If it is not possible, is this a feature worth considering? I see three big downsides. First, it adds some complexity to the resolution of fields. Second, we lose some parallel execution in the query, though not all. Third, there are many use cases for such a variable that are really bad design.

I am going to admit that the original reason I wrote this issue was one of those mildly bad design decisions. Fortunately, I realized it was really bad design as I start writing it down. However, the isLive/liveData example stuck with me as useful. Granted, right now it would just return undefined or null, which is probably just as good. Still, something to think about.

The spec doesn't mention case sensitivity anywhere that I could find. The JavaScript reference implementation implies case sensitivity, but I figure that should probably be mentioned somewhere in the spec.

Spec defines __typename as a way to get 'inline' introspection for any field. I was under impression that in previous versions of the GraphQL one could get the whole type definition inline with __type__ (which, I guess, would be __type nowadays). I think it was very handy, is there any particular reason why it was removed?

The rest of reactiflux has moved over to Discord and, currently, GraphQL seems split between the two. I think it would be nice to have the community in one place.

The last paragraph of this section: http://facebook.github.io/graphql/#sec-Union-type-validation

When expected as an input type, array input values are accepted only when each item in the input array can be accepted by the item type. If the input value is not an array but can be accepted by the item type, it is coerced by creating an array with the input value as the sole item. Other input values must raise a query error indicating an incorrect type.

Is this paragraph misplaced?

We have an interface Customization and around 20 types implementing this interface. The number of subtypes of Customization will grow over time, we are even considering adding subtypes dinamically.

Each concrete type has it own set of attributes.

On the query side this is easy to represent. The problem is at the mutation side. We want to have a mutation method to add a customization to another object

addCustomizationToNode(nodeId: ID, customizationInput: CustomizationInput)

but this is not currently possible to express since Input Objects cannot have interfaces, we would rather not have one mutation field per subtype, specially since those can change dynamically, potentially.

Do you have any suggestions? Would make sense to have InputObjects take interfaces?

Thank you!

This would be a great task to claim for an aspiring contributor.

Hello, everybody there! At first, I want to say thanks to you guys, who invent this small, but powerful query language.

But the main article of this issue, that the license that apply to this specification is not fit this kind of things, I think, that BSD-3-Clause license better to apply to the source code, but the specification should be licensed with Creative Common License.

Creative Common License Attribution 4.0 Internation, I think, is better.

Thanks!

From http://facebook.github.io/graphql/#sec-Non-Null :

NOTE that null is not a valid keyword in GraphQL, so a query cannot look like:
{
field(arg: null)
}
to indicate that the argument is null.

However, this example should actually parse, according to the given grammar. It is a valid Arguments with one Argument whose Value is an EnumValue with the Name "null". This is a consequence of the keywordless approach to grammar definition. I'm not sure how to succinctly explain that this example may be legal, but not because null is a pre-defined keyword that necessarily means the same thing as "unset variable", and that there isn't a way to get it to typecheck for all calls generally given the rest of the system.

For an example, have a look at following query:

query postAndComments($postCount: Int!) {
  getRecentPosts(count: $postCount) {
    title,
    content,
    ...comments
  }
}

fragment comments on Post {
  comments(limit: $commentLimit) {
    content,
    timestamp
  }
}

Now this throws an error:

{
  "errors": [
    {
      "message": "Variable \"$commentLimit\" is not defined by operation \"postAndComments\"."
    }
  ]
}

If we allow to this, I think it'd be great. Here's the use case.

With this, I can use comments fragments in queries where commentLimit query variable does not exists as well.

What you guys think about this?

The draft states that if both the @Skip and @include directives are present, the @Skip directive should take precede. This strikes me as confusing as it opens the door to others creating directives with implicit precedence.

Wouldn't it be simpler and less confusing to say precedence is left to write in the order it was written?

If fragments are involved, then we could linearize the dependencies by saying depth first. Then there are no ambiguities.

Even though it's legal to put commas wherever you like, it's a little bit silly not to be consistent. Is this deliberate?

After creating scala GraphQL implementation I must admit, that the test quality and coverage of nodejs reference implemention is very good. In fact it helped me a lot during the development (as well as the reference implementation itself, of course). After re-implementing most of the tests in scala I now pretty confident, that most of the functionality is tested.

After seeing all these tests it become apparent to me, that there are a lot of edge cases and things that GraphQL library can get wrong, especially in terms of semantics, validation, execution, error handling, etc.. People are already created implementations in many different languages. I feel that it is important to create a TCK (Technology Compatibility Kit) for GraphQL specification in order to ensure success of GraphQL itself, higher adoption and growth of the ecosystem. Having implemented other specifications in the past, I must admit that a TCK makes specification implementation much easier and faster process. It also helps to adopt an implementation as specification evolves.

With TCK I mean a set of acceptance tests, that are distributed in some form (as a library, for instance) and can be used by library authors to verify, that their implementation confirms to the spec. Of course, TCK can't cover all of the cases, but at least it gives a good baseline and as ecosystem grows, it ensures that all parts of it remain compatible with each other or at least minimizes risk of incompatibility.

At the react-europe conference I had a short conversation with @schrockn about this topic. He said, that there are plans for something like this, so I wanted to follow-up here and ask for more information. Do you still have plans to create something like a TCK for GraphQL spec? If yes, do you already have an idea which form it will take? I guess implementing something like this can be a challenging task, considering that it suppose to test implementations written in different languages. As far as I saw, tests in the reference implementation are pretty generic - many of them take some query, execute it and then verify resulting JS object. At the moment they all implemented in terms of the nodejs implementation, but maybe they can be reused or extracted in the TCK somehow?

Thank you for this great work! The idea is awesome and README.md itself was interesting to me.

Is there any plan to write additional documentation for mutation on README.md?

Let's say you have a uniqueness constraint on a field in a mutation. For example the email field must not match any existing email in the database.

In graphql/graphql-js#179 it's been suggested that we shouldn't use the server to validate our forms. But in the case of our uniqueness constraint the server is the only place with enough information to determine if our form is valid.

The format of the errors response appears to be aimed at debugging. Specifically a line number is given as the only context for the error. Presumably this is so that a programmer can then use that line number to find the issue in their query/mutation. So to me the current errors array looks more analogous to a stack trace then an error object like we'd traditionally expect in a RESTful API (eg. {"errors": {"email": ["this email has been taken"]}}).

The advantage of the error object is that we can easily match the keys in the error to the names of the fields in our form to add an error message for our users next to the offending field.

I propose that changing the errors array to an errors object would give developers access to field names and error messages in a format that is easy to map on to their forms and display to users. Eg:

{
  "errors": {
    "email": {
      "messages": ["The email address [email protected] has already been taken"],
      "locations": []
    }
  }
}

Relevant Spec Section: https://facebook.github.io/graphql/#sec-Errors

Should there be a map type?

I have a structure that looks like this:

  Item {
     title {
        de_DE,
        fr,
        pa,
        .....
     }
  }

The point here is that the number of language strings might be arbitrary. I find this hard to model using GraphQLObject, because:

1. The number of locales is undefined. While the resolver could handle this dynamically, I think it's a problem in Relay that the schema cannot reflect these dynamic fields.
2. I would like to query all the existing locales, which isn't allowed, it seems ("must have a sub-selection").

If I make my GraphQL server return a JSON object for "title", the Relay client doesn't complain (although maybe shouldComponentUpdate breaks), but I think I'm skirting by here. At the very least, I think I couldn't generate a schema that confirms to the spec.

I was thinking through building a documentation explorer and something that'd be very useful is if you could define example queries alongside your type or field definition. These could then be auto expanded into embedded graphiql instances.

For my purpose I quickly hacked in resolveField (execute.js):

console.log("... resolveFn error:\n" + error + ": " + error.stack);

Such that I can see the error stack if there's an exception in a resolve() function. Without this the error is "silently" eaten, and only reported in the GQL result as "basic error desc" line/col in the "errors" which isn't very useful most of the time.

Is there a hook, or should a hook be added to report these type of errors in a more detailed manner?

I'm trying to implement pagination algorithm for my data and I don't know how to handle cases when first and last are negative.

What is your opinion about this?

ref: https://facebook.github.io/relay/graphql/connections.htm#sec-Pagination-algorithm

In IntrospectionQueryTypeQuery section, the query has a queryType key in __schema:

query IntrospectionQueryTypeQuery {
  __schema {
    queryType {
      name
    }
  }
}

But response with query key in __schema:

{
  "__schema": {
    "query": {
      "name": "Query"
    }
  }
}

Is there any reasons for Inconsistent keys or just a typo here?

It would be great to have some formal definition of selection set. It is introduced in the fields section without a peep.