graphql / graphql-wg

Working group notes for GraphQL

GraphQL

The GraphQL specification is edited in the markdown files found in /spec the latest release of which is published at https://graphql.github.io/graphql-spec/.

The latest draft specification can be found at https://graphql.github.io/graphql-spec/draft/ which tracks the latest commit to the main branch in this repository.

Previous releases of the GraphQL specification can be found at permalinks that match their release tag. For example, https://graphql.github.io/graphql-spec/October2016/. If you are linking directly to the GraphQL specification, it's best to link to a tagged permalink for the particular referenced version.

Overview

This is a Working Draft of the Specification for GraphQL, a query language for APIs created by Facebook.

The target audience for this specification is not the client developer, but those who have, or are actively interested in, building their own GraphQL implementations and tools.

In order to be broadly adopted, GraphQL will have to target a wide variety of backend environments, frameworks, and languages, which will necessitate a collaborative effort across projects and organizations. This specification serves as a point of coordination for this effort.

Looking for help? Find resources from the community.

Getting Started

GraphQL consists of a type system, query language and execution semantics, static validation, and type introspection, each outlined below. To guide you through each of these components, we've written an example designed to illustrate the various pieces of GraphQL.

This example is not comprehensive, but it is designed to quickly introduce the core concepts of GraphQL, to provide some context before diving into the more detailed specification or the GraphQL.js reference implementation.

The premise of the example is that we want to use GraphQL to query for information about characters and locations in the original Star Wars trilogy.

Type System

At the heart of any GraphQL implementation is a description of what types of objects it can return, described in a GraphQL type system and returned in the GraphQL Schema.

For our Star Wars example, the starWarsSchema.ts file in GraphQL.js defines this type system.

The most basic type in the system will be Human, representing characters like Luke, Leia, and Han. All humans in our type system will have a name, so we define the Human type to have a field called "name". This returns a String, and we know that it is not null (since all Humans have a name), so we will define the "name" field to be a non-nullable String. Using a shorthand notation that we will use throughout the spec and documentation, we would describe the human type as:

type Human {
  name: String
}

This shorthand is convenient for describing the basic shape of a type system; the JavaScript implementation is more full-featured, and allows types and fields to be documented. It also sets up the mapping between the type system and the underlying data; for a test case in GraphQL.js, the underlying data is a set of JavaScript objects, but in most cases the backing data will be accessed through some service, and this type system layer will be responsible for mapping from types and fields to that service.

A common pattern in many APIs, and indeed in GraphQL is to give objects an ID that can be used to refetch the object. So let's add that to our Human type. We'll also add a string for their home planet.

type Human {
  id: String
  name: String
  homePlanet: String
}

Since we're talking about the Star Wars trilogy, it would be useful to describe the episodes in which each character appears. To do so, we'll first define an enum, which lists the three episodes in the trilogy:

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

Now we want to add a field to Human describing what episodes they were in. This will return a list of Episodes:

type Human {
  id: String
  name: String
  appearsIn: [Episode]
  homePlanet: String
}

Now, let's introduce another type, Droid:

type Droid {
  id: String
  name: String
  appearsIn: [Episode]
  primaryFunction: String
}

Now we have two types! Let's add a way of going between them: humans and droids both have friends. But humans can be friends with both humans and droids. How do we refer to either a human or a droid?

If we look, we note that there's common functionality between humans and droids; they both have IDs, names, and episodes in which they appear. So we'll add an interface, Character, and make both Human and Droid implement it. Once we have that, we can add the friends field, that returns a list of Characters.

Our type system so far is:

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

interface Character {
  id: String
  name: String
  friends: [Character]
  appearsIn: [Episode]
}

type Human implements Character {
  id: String
  name: String
  friends: [Character]
  appearsIn: [Episode]
  homePlanet: String
}

type Droid implements Character {
  id: String
  name: String
  friends: [Character]
  appearsIn: [Episode]
  primaryFunction: String
}

One question we might ask, though, is whether any of those fields can return null. By default, null is a permitted value for any type in GraphQL, since fetching data to fulfill a GraphQL query often requires talking to different services that may or may not be available. However, if the type system can guarantee that a type is never null, then we can mark it as Non Null in the type system. We indicate that in our shorthand by adding an "!" after the type. We can update our type system to note that the id is never null.

Note that while in our current implementation, we can guarantee that more fields are non-null (since our current implementation has hard-coded data), we didn't mark them as non-null. One can imagine we would eventually replace our hardcoded data with a backend service, which might not be perfectly reliable; by leaving these fields as nullable, we allow ourselves the flexibility to eventually return null to indicate a backend error, while also telling the client that the error occurred.

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

interface Character {
  id: String!
  name: String
  friends: [Character]
  appearsIn: [Episode]
}

type Human implements Character {
  id: String!
  name: String
  friends: [Character]
  appearsIn: [Episode]
  homePlanet: String
}

type Droid implements Character {
  id: String!
  name: String
  friends: [Character]
  appearsIn: [Episode]
  primaryFunction: String
}

We're missing one last piece: an entry point into the type system.

When we define a schema, we define an object type that is the basis for all query operations. The name of this type is Query by convention, and it describes our public, top-level API. Our Query type for this example will look like this:

type Query {
  hero(episode: Episode): Character
  human(id: String!): Human
  droid(id: String!): Droid
}

In this example, there are three top-level operations that can be done on our schema:

• hero returns the Character who is the hero of the Star Wars trilogy; it takes an optional argument that allows us to fetch the hero of a specific episode instead.
• human accepts a non-null string as a query argument, a human's ID, and returns the human with that ID.
• droid does the same for droids.

These fields demonstrate another feature of the type system, the ability for a field to specify arguments that configure their behavior.

When we package the whole type system together, defining the Query type above as our entry point for queries, this creates a GraphQL Schema.

This example just scratched the surface of the type system. The specification goes into more detail about this topic in the "Type System" section, and the type directory in GraphQL.js contains code implementing a specification-compliant GraphQL type system.

Query Syntax

GraphQL queries declaratively describe what data the issuer wishes to fetch from whoever is fulfilling the GraphQL query.

For our Star Wars example, the starWarsQueryTests.js file in the GraphQL.js repository contains a number of queries and responses. That file is a test file that uses the schema discussed above and a set of sample data, located in starWarsData.js. This test file can be run to exercise the reference implementation.

An example query on the above schema would be:

query HeroNameQuery {
  hero {
    name
  }
}

The initial line, query HeroNameQuery, defines a query with the operation name HeroNameQuery that starts with the schema's root query type; in this case, Query. As defined above, Query has a hero field that returns a Character, so we'll query for that. Character then has a name field that returns a String, so we query for that, completing our query. The result of this query would then be:

{
  "hero": {
    "name": "R2-D2"
  }
}

Specifying the query keyword and an operation name is only required when a GraphQL document defines multiple operations. We therefore could have written the previous query with the query shorthand:

{
  hero {
    name
  }
}

Assuming that the backing data for the GraphQL server identified R2-D2 as the hero. The response continues to vary based on the request; if we asked for R2-D2's ID and friends with this query:

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

then we'll get back a response like this:

{
  "hero": {
    "id": "2001",
    "name": "R2-D2",
    "friends": [
      {
        "id": "1000",
        "name": "Luke Skywalker"
      },
      {
        "id": "1002",
        "name": "Han Solo"
      },
      {
        "id": "1003",
        "name": "Leia Organa"
      }
    ]
  }
}

One of the key aspects of GraphQL is its ability to nest queries. In the above query, we asked for R2-D2's friends, but we can ask for more information about each of those objects. So let's construct a query that asks for R2-D2's friends, gets their name and episode appearances, then asks for each of their friends.

query NestedQuery {
  hero {
    name
    friends {
      name
      appearsIn
      friends {
        name
      }
    }
  }
}

which will give us the nested response

{
  "hero": {
    "name": "R2-D2",
    "friends": [
      {
        "name": "Luke Skywalker",
        "appearsIn": ["NEWHOPE", "EMPIRE", "JEDI"],
        "friends": [
          { "name": "Han Solo" },
          { "name": "Leia Organa" },
          { "name": "C-3PO" },
          { "name": "R2-D2" }
        ]
      },
      {
        "name": "Han Solo",
        "appearsIn": ["NEWHOPE", "EMPIRE", "JEDI"],
        "friends": [
          { "name": "Luke Skywalker" },
          { "name": "Leia Organa" },
          { "name": "R2-D2" }
        ]
      },
      {
        "name": "Leia Organa",
        "appearsIn": ["NEWHOPE", "EMPIRE", "JEDI"],
        "friends": [
          { "name": "Luke Skywalker" },
          { "name": "Han Solo" },
          { "name": "C-3PO" },
          { "name": "R2-D2" }
        ]
      }
    ]
  }
}

The Query type above defined a way to fetch a human given their ID. We can use it by hard-coding the ID in the query:

query FetchLukeQuery {
  human(id: "1000") {
    name
  }
}

to get

{
  "human": {
    "name": "Luke Skywalker"
  }
}

Alternately, we could have defined the query to have a query parameter:

query FetchSomeIDQuery($someId: String!) {
  human(id: $someId) {
    name
  }
}

This query is now parameterized by $someId; to run it, we must provide that ID. If we ran it with $someId set to "1000", we would get Luke; set to "1002", we would get Han. If we passed an invalid ID here, we would get null back for the human, indicating that no such object exists.

Notice that the key in the response is the name of the field, by default. It is sometimes useful to change this key, for clarity or to avoid key collisions when fetching the same field with different arguments.

We can do that with field aliases, as demonstrated in this query:

query FetchLukeAliased {
  luke: human(id: "1000") {
    name
  }
}

We aliased the result of the human field to the key luke. Now the response is:

{
  "luke": {
    "name": "Luke Skywalker"
  }
}

Notice the key is "luke" and not "human", as it was in our previous example where we did not use the alias.

This is particularly useful if we want to use the same field twice with different arguments, as in the following query:

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

We aliased the result of the first human field to the key luke, and the second to leia. So the result will be:

{
  "luke": {
    "name": "Luke Skywalker"
  },
  "leia": {
    "name": "Leia Organa"
  }
}

Now imagine we wanted to ask for Luke and Leia's home planets. We could do so with this query:

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

but we can already see that this could get unwieldy, since we have to add new fields to both parts of the query. Instead, we can extract out the common fields into a fragment, and include the fragment in the query, like this:

query UseFragment {
  luke: human(id: "1000") {
    ...HumanFragment
  }
  leia: human(id: "1003") {
    ...HumanFragment
  }
}

fragment HumanFragment on Human {
  name
  homePlanet
}

Both of those queries give this result:

{
  "luke": {
    "name": "Luke Skywalker",
    "homePlanet": "Tatooine"
  },
  "leia": {
    "name": "Leia Organa",
    "homePlanet": "Alderaan"
  }
}

The UseFragment and DuplicateFields queries will both get the same result, but UseFragment is less verbose; if we wanted to add more fields, we could add it to the common fragment rather than copying it into multiple places.

We defined the type system above, so we know the type of each object in the output; the query can ask for that type using the special field __typename, defined on every object.

query CheckTypeOfR2 {
  hero {
    __typename
    name
  }
}

Since R2-D2 is a droid, this will return

{
  "hero": {
    "__typename": "Droid",
    "name": "R2-D2"
  }
}

This was particularly useful because hero was defined to return a Character, which is an interface; we might want to know what concrete type was actually returned. If we instead asked for the hero of Episode V:

query CheckTypeOfLuke {
  hero(episode: EMPIRE) {
    __typename
    name
  }
}

We would find that it was Luke, who is a Human:

{
  "hero": {
    "__typename": "Human",
    "name": "Luke Skywalker"
  }
}

As with the type system, this example just scratched the surface of the query language. The specification goes into more detail about this topic in the "Language" section, and the language directory in GraphQL.js contains code implementing a specification-compliant GraphQL query language parser and lexer.

Validation

By using the type system, it can be predetermined whether a GraphQL query is valid or not. This allows servers and clients to effectively inform developers when an invalid query has been created, without having to rely on runtime checks.

For our Star Wars example, the file starWarsValidationTests.js contains a number of demonstrations of invalid operations, and is a test file that can be run to exercise the reference implementation's validator.

To start, let's take a complex valid query. This is the NestedQuery example from the above section, but with the duplicated fields factored out into a fragment:

query NestedQueryWithFragment {
  hero {
    ...NameAndAppearances
    friends {
      ...NameAndAppearances
      friends {
        ...NameAndAppearances
      }
    }
  }
}

fragment NameAndAppearances on Character {
  name
  appearsIn
}

And this query is valid. Let's take a look at some invalid queries!

When we query for fields, we have to query for a field that exists on the given type. So as hero returns a Character, we have to query for a field on Character. That type does not have a favoriteSpaceship field, so this query:

# INVALID: favoriteSpaceship does not exist on Character
query HeroSpaceshipQuery {
  hero {
    favoriteSpaceship
  }
}

is invalid.

Whenever we query for a field and it returns something other than a scalar or an enum, we need to specify what data we want to get back from the field. Hero returns a Character, and we've been requesting fields like name and appearsIn on it; if we omit that, the query will not be valid:

# INVALID: hero is not a scalar, so fields are needed
query HeroNoFieldsQuery {
  hero
}

Similarly, if a field is a scalar, it doesn't make sense to query for additional fields on it, and doing so will make the query invalid:

# INVALID: name is a scalar, so fields are not permitted
query HeroFieldsOnScalarQuery {
  hero {
    name {
      firstCharacterOfName
    }
  }
}

Earlier, it was noted that a query can only query for fields on the type in question; when we query for hero which returns a Character, we can only query for fields that exist on Character. What happens if we want to query for R2-D2s primary function, though?

# INVALID: primaryFunction does not exist on Character
query DroidFieldOnCharacter {
  hero {
    name
    primaryFunction
  }
}

That query is invalid, because primaryFunction is not a field on Character. We want some way of indicating that we wish to fetch primaryFunction if the Character is a Droid, and to ignore that field otherwise. We can use the fragments we introduced earlier to do this. By setting up a fragment defined on Droid and including it, we ensure that we only query for primaryFunction where it is defined.

query DroidFieldInFragment {
  hero {
    name
    ...DroidFields
  }
}

fragment DroidFields on Droid {
  primaryFunction
}

This query is valid, but it's a bit verbose; named fragments were valuable above when we used them multiple times, but we're only using this one once. Instead of using a named fragment, we can use an inline fragment; this still allows us to indicate the type we are querying on, but without naming a separate fragment:

query DroidFieldInInlineFragment {
  hero {
    name
    ... on Droid {
      primaryFunction
    }
  }
}

This has just scratched the surface of the validation system; there are a number of validation rules in place to ensure that a GraphQL query is semantically meaningful. The specification goes into more detail about this topic in the "Validation" section, and the validation directory in GraphQL.js contains code implementing a specification-compliant GraphQL validator.

Introspection

It's often useful to ask a GraphQL schema for information about what queries it supports. GraphQL allows us to do so using the introspection system!

For our Star Wars example, the file starWarsIntrospectionTests.js contains a number of queries demonstrating the introspection system, and is a test file that can be run to exercise the reference implementation's introspection system.

We designed the type system, so we know what types are available, but if we didn't, we can ask GraphQL, by querying the __schema field, always available on the root type of a Query. Let's do so now, and ask what types are available.

query IntrospectionTypeQuery {
  __schema {
    types {
      name
    }
  }
}

and we get back:

{
  "__schema": {
    "types": [
      {
        "name": "Query"
      },
      {
        "name": "Character"
      },
      {
        "name": "Human"
      },
      {
        "name": "String"
      },
      {
        "name": "Episode"
      },
      {
        "name": "Droid"
      },
      {
        "name": "__Schema"
      },
      {
        "name": "__Type"
      },
      {
        "name": "__TypeKind"
      },
      {
        "name": "Boolean"
      },
      {
        "name": "__Field"
      },
      {
        "name": "__InputValue"
      },
      {
        "name": "__EnumValue"
      },
      {
        "name": "__Directive"
      }
    ]
  }
}

Wow, that's a lot of types! What are they? Let's group them:

• Query, Character, Human, Episode, Droid - These are the ones that we defined in our type system.
• String, Boolean - These are built-in scalars that the type system provided.
• __Schema, __Type, __TypeKind, __Field, __InputValue, __EnumValue, __Directive - These all are preceded with a double underscore, indicating that they are part of the introspection system.

Now, let's try and figure out a good place to start exploring what queries are available. When we designed our type system, we specified what type all queries would start at; let's ask the introspection system about that!

query IntrospectionQueryTypeQuery {
  __schema {
    queryType {
      name
    }
  }
}

and we get back:

{
  "__schema": {
    "queryType": {
      "name": "Query"
    }
  }
}

And that matches what we said in the type system section, that the Query type is where we will start! Note that the naming here was just by convention; we could have named our Query type anything else, and it still would have been returned here if we had specified it as the starting type for queries. Naming it Query, though, is a useful convention.

It is often useful to examine one specific type. Let's take a look at the Droid type:

query IntrospectionDroidTypeQuery {
  __type(name: "Droid") {
    name
  }
}

and we get back:

{
  "__type": {
    "name": "Droid"
  }
}

What if we want to know more about Droid, though? For example, is it an interface or an object?

query IntrospectionDroidKindQuery {
  __type(name: "Droid") {
    name
    kind
  }
}

and we get back:

{
  "__type": {
    "name": "Droid",
    "kind": "OBJECT"
  }
}

kind returns a __TypeKind enum, one of whose values is OBJECT. If we asked about Character instead:

query IntrospectionCharacterKindQuery {
  __type(name: "Character") {
    name
    kind
  }
}

and we get back:

{
  "__type": {
    "name": "Character",
    "kind": "INTERFACE"
  }
}

We'd find that it is an interface.

It's useful for an object to know what fields are available, so let's ask the introspection system about Droid:

query IntrospectionDroidFieldsQuery {
  __type(name: "Droid") {
    name
    fields {
      name
      type {
        name
        kind
      }
    }
  }
}

and we get back:

{
  "__type": {
    "name": "Droid",
    "fields": [
      {
        "name": "id",
        "type": {
          "name": null,
          "kind": "NON_NULL"
        }
      },
      {
        "name": "name",
        "type": {
          "name": "String",
          "kind": "SCALAR"
        }
      },
      {
        "name": "friends",
        "type": {
          "name": null,
          "kind": "LIST"
        }
      },
      {
        "name": "appearsIn",
        "type": {
          "name": null,
          "kind": "LIST"
        }
      },
      {
        "name": "primaryFunction",
        "type": {
          "name": "String",
          "kind": "SCALAR"
        }
      }
    ]
  }
}

Those are our fields that we defined on Droid!

id looks a bit weird there, it has no name for the type. That's because it's a "wrapper" type of kind NON_NULL. If we queried for ofType on that field's type, we would find the String type there, telling us that this is a non-null String.

Similarly, both friends and appearsIn have no name, since they are the LIST wrapper type. We can query for ofType on those types, which will tell us what these are lists of.

query IntrospectionDroidWrappedFieldsQuery {
  __type(name: "Droid") {
    name
    fields {
      name
      type {
        name
        kind
        ofType {
          name
          kind
        }
      }
    }
  }
}

and we get back:

{
  "__type": {
    "name": "Droid",
    "fields": [
      {
        "name": "id",
        "type": {
          "name": null,
          "kind": "NON_NULL",
          "ofType": {
            "name": "String",
            "kind": "SCALAR"
          }
        }
      },
      {
        "name": "name",
        "type": {
          "name": "String",
          "kind": "SCALAR",
          "ofType": null
        }
      },
      {
        "name": "friends",
        "type": {
          "name": null,
          "kind": "LIST",
          "ofType": {
            "name": "Character",
            "kind": "INTERFACE"
          }
        }
      },
      {
        "name": "appearsIn",
        "type": {
          "name": null,
          "kind": "LIST",
          "ofType": {
            "name": "Episode",
            "kind": "ENUM"
          }
        }
      },
      {
        "name": "primaryFunction",
        "type": {
          "name": "String",
          "kind": "SCALAR",
          "ofType": null
        }
      }
    ]
  }
}

Let's end with a feature of the introspection system particularly useful for tooling; let's ask the system for documentation!

query IntrospectionDroidDescriptionQuery {
  __type(name: "Droid") {
    name
    description
  }
}

yields

{
  "__type": {
    "name": "Droid",
    "description": "A mechanical creature in the Star Wars universe."
  }
}

So we can access the documentation about the type system using introspection, and create documentation browsers, or rich IDE experiences.

This has just scratched the surface of the introspection system; we can query for enum values, what interfaces a type implements, and more. We can even introspect on the introspection system itself. The specification goes into more detail about this topic in the "Introspection" section, and the introspection file in GraphQL.js contains code implementing a specification-compliant GraphQL query introspection system.

Additional Content

This README walked through the GraphQL.js reference implementation's type system, query execution, validation, and introspection systems. There's more in both GraphQL.js and specification, including a description and implementation for executing queries, how to format a response, explaining how a type system maps to an underlying implementation, and how to format a GraphQL response, as well as the grammar for GraphQL.

Contributing to this repo

This repository is managed by EasyCLA. Project participants must sign the free (GraphQL Specification Membership agreement before making a contribution. You only need to do this one time, and it can be signed by individual contributors or their employers.

To initiate the signature process please open a PR against this repo. The EasyCLA bot will block the merge if we still need a membership agreement from you.

You can find detailed information here. If you have issues, please email [email protected].

If your company benefits from GraphQL and you would like to provide essential financial support for the systems and people that power our community, please also consider membership in the GraphQL Foundation.

graphql-wg's Issues

Review https://devstats.graphql.org

The GraphQL Foundation recently stood up a devstats service to provide some insights to the GraphQL community: https://devstats.graphql.org

You can also evaluate "project health"
https://devstats.graphql.org/d/53/projects-health-table?orgId=1

If you're happy with this, we can make this the official source of project stats.

[2020-08-06] Add YouTube WG links to the notes

Benjie - How to get recordings?
Lee - Zoom provides them after a few weeks as raw video files. Eventually we want to get them on youtube.
Ivan - The foundation guys have figured out how to publish on youtube!
Lee - let’s add youtube link to notes after the fact

• assignee(s): ─
• source: https://github.com/graphql/graphql-wg/blob/master/notes/2020-08-06.md#any-other-business

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

Registration for graphql slack is down

https://graphql-slack.herokuapp.com/ doesn't allow new registrations

it's linked to from the community docs: https://graphql.org/community/#slack-communities

i would have opened this in the documentation site repo, but this seemed more appropriate?

Updating CLAs and copyright notices in GraphQL repos

Some issues maintained by the GraphQL foundation still point to Contributor Licence Agreements hosted by Facebook, i.e.:

• https://github.com/graphql/libgraphqlparser/blob/master/CONTRIBUTING.md (addressed in graphql/libgraphqlparser#93)
• https://github.com/graphql/dataloader/blob/master/CONTRIBUTING.md

We could either remove the requirement to sign a CLA, or provide means to do so via the foundation (if that is possible).

A related issue for libgraphqlparser is how to deal with "facebook" in namespaces, as changes are breaking.

Agenda: Define process for the changes to the specification

At the moment it's very hard to track which features will be included in the next release.

For example, the absolute majority of the community thinks that IDL is already a part of the spec since it is implemented in all major libraries. However, it's still not merged into a spec and there is no clear indication of this PR status.

I propose to define a pipeline for all the major changes with stages marked as labels applied to PRs. I suggest using TC39 process document as the base and adapt it to the specifics of GraphQL (reference implementation, WG, etc.).

It will give the community a sense of understanding on what's happening with GraphQL and allow library authors to do an educated decision on what experimental features they should support.

As for the editorial changes like grammar, examples, clarifications, etc. I propose to add separate simplified pipeline.

Should we discuss this at the next meeting?
Slides here

Schedule working session with Input Union RFC champions

Our next step in the Input Union RFC process is to gather the individual solution champions for a working session where we can dive into the details of solutions and try to make some progress towards a proposed solution.

• https://github.com/graphql/graphql-spec/blob/master/rfcs/InputUnion.md

Our aim is to have this meeting about 1 week before the next general Working Group meeting:

• https://github.com/graphql/graphql-wg/blob/master/agendas/2020-04-02.md

Current champions: @leebyron @binaryseed @eapache @benjie

[2019-06-06] Schedule GraphQL.org meeting

Schedule 10-15m meeting to discuss where graphql.org is today and brainstorm action items

assignee: @tanaypratap
source: GraphQL Working Group Meeting 2019-07-03

Check maintainers of repository

Re: Acceptance Criteria for Editorial Changes

Check maintainers of repository

assignee: @IvanGoncharov
source: GraphQL Working Group Meeting 2019-07-03

[2020-05-07] Update Input Union RFC after recent subcommittee meetings

https://github.com/graphql/graphql-wg/blame/master/notes/2020-05-07.md#L104

https://graphql.org SSL certificate has expired

As reported by @kolobock in graphql/graphql-spec#448 (comment)

[2020-05-07] Custom scalar specification URIs editorial pass

https://github.com/graphql/graphql-wg/blame/master/notes/2020-05-07.md#L36

[2020-08-06] Review GraphQL over HTTP 124

Rob - opened up a PR to GraphQL-over-HTTP; more eyes desired
[ACTION - GraphQL-over-HTTP WG] - Review graphql/graphql-over-http/pull/124

• assignee(s): ─
• source: https://github.com/graphql/graphql-wg/blob/master/notes/2020-08-06.md#deferstream-15m-robliliana

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

[2020-08-06] Clarify the problem that Field Coordinates is addressing

Lee - For RFC to move forward, need to be clear about what problem we’re solving. Specify what this is for, and what this is not intended to be used for.
[ACTION - Mark] - clarify the above

• assignee(s): @magicmark
• source: https://github.com/graphql/graphql-wg/blob/master/notes/2020-08-06.md#field-coordinates-rfc-15m-mark

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

Create Q&A on most important details

Create Q&A on most important details (contents, etc.)

assignee: Unclaimed
source: GraphQL Working Group Meeting 2019-07-03

[2020-07-02] Read over GraphQL Custom Scalar PR

ACTION - Lee - read over this and make sure we're not missing anything, and perform the merge.
Lee: it should be clear that you can have scalars in your own domain that are only used in your domain.
Ivan: we should allow vendor URLs. It reduces our workload if people can use vendor-specific things - they'd be less pushy about pushing their scalars to be standard.
ACTION - Lee - make minor changes as a last patch before merging

Custom scalar PR: graphql/graphql-spec#649

• assignee(s): @leebyron
• source: https://github.com/graphql/graphql-wg/blob/master/notes/2020-07-02.md#graphql-custom-scalar-pr-in-spec-graphqlgraphql-specpull649

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

[2020-09-03] Contact Matt about Flow support in TypeScript version of GraphQL.js

Ivan: I should also contact Matt about Flow support because we need to figure out how to migrate to TypeScript without breaking Flow clients (at Facebook specifically)

• assignee(s): @IvanGoncharov
• source: https://github.com/graphql/graphql-wg/blob/b1bfe0cee461d752146dc77e5c35a5e8d7921272/notes/2020-09-03.md#typescript-migration-progress-in-graphql-js-5m-dotan-how-to-bootstrap-graphql-js-working-group-5m-dotan-github-infrastructure-for-managing-working-groups-10m-ivan

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

Special WG session during GraphQL EU

I originally added https://github.com/graphql/graphql-wg/blob/master/agendas/2018-07-13.md with the intent that this be a special session where as many people who can join in person in Berlin during GraphQL EU can do so. However the specific date of July 13th is only a starting suggestion.

I want to use this issue as a space for us to work out options for what day and time this session should occur so those planning travel can work around a concrete plan.

[2020-06-11] Update Tagged Types RFC to include "everything we discussed"

Lee: This was mostly meant to be an update. The next step is to draft an RFC that contains everything we discussed.
ACTION - Draft a new RFC that contains everything we discussed

• assignee(s): @benjie
• source: https://github.com/graphql/graphql-wg/blob/master/notes/2020-06-11.md#input-union--tagged-types-30m-lee-benjie-evan-vince-1

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

GraphQL @defer and @stream

We’ve been experimenting with @defer and @stream at Facebook for a while now -- Lee first discussed the idea of @defer and @stream in 2016. Over the last three years, we've done a ton of iterations as we uncovered and resolved issues and edge cases following that initial approach. We're now seeing a renewed demand for these ideas in the open source community:
graphql/graphql-js#2318
graphql/graphql-js#2319

Given that Facebook’s increased internal usage makes us more confident in our approach, it seems like a good time to start a discussion of what the next steps would be. Opening this issue with some strategic questions:

• What's the best way to drive @defer and @stream standardization?
• Should these features be part of the official spec or a supplemental specification (e.g. connections)?
• If we decide these features are worthy of standardization, what's the best way of driving towards alignment? Should we set up a stream/defer focused-WG?

[2020-09-03] Create PR merging policy and grant more contributors maintainer access to WG repo

Ivan: if we write a document with policies, we can have more people help with merging.
Lee: we can be more liberal with giving merge access to the WG repo. Anyone who's a frequent guest of these meetings we can give commit access to.
Ivan: especially the champions. You just promise to not merge anything in other people's RFCs, only in your RFC.
ACTION - Lee: make this happen

• assignee(s): @leebyron
• source: https://github.com/graphql/graphql-wg/blob/b1bfe0cee461d752146dc77e5c35a5e8d7921272/notes/2020-09-03.md#any-other-business

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

[2020-09-03] GitHub infrastructure for managing Working groups

How other working groups should be managed on GitHub?

[2020-08-06] Determine contributors, owners, merge rights for GraphQL-js

Lee: lets put a plan together for increasing bus factor. Two actions:

1. Start a Graphql.js specific call - focussed on strategy, not specific code (see #485)
2. List our contributor to GraphQL.js; specify “owners”. Who do we want to give review, but not yet merge capabilities? Keep it to a tight core set.

• assignee(s): @leebyron
• source: https://github.com/graphql/graphql-wg/blob/master/notes/2020-08-06.md#typescript-migration-plan-progress-and-next-steps-10m-dotan

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

[2020-09-03] Add checkbox to issue template to confirm agreements are signed

[Regarding cutting a version of the spec]

Ivan: I've been merging stuff into the spec/etc; if you need me to stop let me know.
Lee: If you see that contributions come from new contributors, you can flag and let Brian know.
[...]
Ivan: if someone wants to help, adding a checklist in the issue template would be a great contribution
ACTION - Lee: mention this issue template idea to Brian

• assignee(s): @leebyron @brianwarner
• source: https://github.com/graphql/graphql-wg/blob/b1bfe0cee461d752146dc77e5c35a5e8d7921272/notes/2020-09-03.md#review-previous-meetings-action-items-5m-lee

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

[2020-05-07] Making sure we have agenda items for the rest of the year

https://github.com/graphql/graphql-wg/blame/master/notes/2020-05-07.md#L29

How to encourage discussions on PRs in GraphQL Spec repo?

Just as a continuation on disscusion that we had during WG.

A few actionable ideas so far are:

• More descriptive tags on issues and PRs
• Have a "This week in GraphQL specification" newsletter

Would be great to hear other ideas?

[2020-05-07] introspection shortcuts RFC: describe the problem

Discuss RFC adding introspection shortcuts to determine full typename and named type’s name (15m, Terrence)

[ACTION - Terrance] - describe the problem, look at the landscape of potential solutions, and figure out which ones are appropriate or not

https://github.com/graphql/graphql-wg/blame/master/notes/2020-05-07.md#L67

Is there a scheduled next meeting?

I plan on pushing for this RFC again, and need to resolve merge conflicts in the RFC and reference implementation but want to plan it so I don't have more conflicts to fix by the time people can look at it.

Has there been any out-of-band discussion about the next meeting? If so, could we get a new agenda item in the repo?

[2020-05-07] Add InputUnion solution criteria that error messages are well specified

https://github.com/graphql/graphql-wg/blame/master/notes/2020-05-07.md#L120

[2020-07-02] Moving the @deprecated directive on Input Fields RFC to Stage 2

[ACTION - Lee] - Add RFC 2 tag to PR
[ACTION] - Add SHOULD statement to spec recommending that it is generally ill-advised to add @deprecated to a non-null argument or input field unless there is a default value provided.
[ACTION] - merge spec PR to master
[ACTION - Ivan] - Add schema validation to GraphQL.js that enforces @deprecated on nonnull Moved to #518
[ACTION - Evan] - talk to Shopify team and others to determine SHOULD vs MUST. Moved to #517

• assignee(s): ─
• source: https://github.com/graphql/graphql-wg/blob/master/notes/2020-07-02.md#moving-the-deprecated-directive-on-input-fields-rfc-to-stage-2-15m45m-stephen

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

[2020-06-11] GraphQL Scalars hosting - schedule call with Andi

Lee: if we reach out I'd not be surprised if we found volunteers to make this happen.
Ivan: We need Andi to be involved in the conversation. Can we schedule a call to talk to Andi and have a conversation about how to proceed?
ACTION - schedule a call with Andi (hour and a half)

• assignee(s): ─
• source: https://github.com/graphql/graphql-wg/blob/master/notes/2020-06-11.md#graphql-scalars-hosting-and-coordination-10m-evan-and-andi

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

[2020-09-03] Update @defer/@stream RFC with more thorough explanation of fragments vs fields

Discussion related to limiting @defer/@stream to only fragments vs also allowing it on fields. This was explained well in WG, Rob agreed to add it to the RFC

ACTION - Rob: Rob: I'll update the RFC PR with a more thorough explanation and then we'll get that into the spec as well.

• assignee(s): @robrichard
• source: https://github.com/graphql/graphql-wg/blob/b1bfe0cee461d752146dc77e5c35a5e8d7921272/notes/2020-09-03.md#deferstream-15m-robliliana

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

Schedule a one-off for GraphiQL discussions

👋 - I kickstarted some discussion on twitter about a what could GraphiQL 2.0 (or, I guess 1.0 as it's still not there yet :D ) after exploring some wireframes.

We should schedule a one-off meeting to talk about:

• What are the current issues with GraphiQL?
• What could / should GraphiQL do?
• Could we find a way to integrate ( or support the integration of) the features from GraphQL playground and/or explorer?

[MVP] GraphQL over HTTP

On the last WG we discussed "GraphQL over HTTP" spec and I've prepared a minimalistic draft:
https://gist.github.com/IvanGoncharov/021bdb39761e1c80b1fc698706b2ecf7

@leebyron But I'm not sure about the next steps.
Would you create "graphql/graphql-over-http" repo so I can submit this Draft as a PR?
Or should I create a personal repo and then move it afterward?

[2020-08-06] Create Issues for Action items from previous calls

Go through notes for previous calls and create action items for them.
Note: @benjie already created all action items for the Sep2020 call, so Aug2020 is the next target 🎯

• assignee(s): any volunteer
• source: something that we should do every month

---

• September 2020
• August 2020
• July 2020
• June 2020
• May 2020

[Experiment] Generic bulk queries in GraphQL

Public docs at https://help.shopify.com/en/api/guides/bulk-operations/, but this is still experimental/beta.

At Shopify we've seen a lot of clients who need to fetch large quantities of data (e.g. all 10k products on a shop). We follow relay pagination, so typically they would do this via paginated requests (e.g. 100 requests for 100 products each) but this is inefficient in that it results in a lot of round-trips, a lot of query processing overhead, some concatenation logic on the client, etc.

As a better solution, we're experimenting with a subtle variant of our GraphQL schema (or perhaps more accurately a variant of the relay pagination spec?) where clients don't specify any of the regular first/last/before/after arguments. Instead, our server iterates over pages of the query transparently, and returns the total results (e.g. all 10k products) in a single file downloadable from S3 or similar storage hosts. Details are at the link above.

As a general pattern I think this might be something that is useful or at least interesting to the broader community, which is why I wanted to share it. There was some interesting conversation in the working group meeting over whether this was technically spec-compliant or not, and I'm also interested (if it works out long-term) in potentially working this into the spec. In my mind it's similar to subscriptions, in that it's an another variant on how the data actually gets returned, built on top of the same fundamental schema (normal queries are synchronous pull, subscriptions are synchronous push, and this bulk API is asynchronous pull).

We've also talked about variations of this approach where it's more explicitly not-spec-compliant, e.g. making a separate end-point for these requests which takes the graphql request in the normal way but just returns the ID of the job that was launched instead of any spec-compliant response.

Whatever thoughts or opinions you have, please share. We're obviously paying a lot of attention to what our clients think of this, but we also want to be good citizens if there is interest or concern from the GraphQL community.

[2020-07-02] Give feedback on @defer/@stream

ACTION - Lee - give feedback on @defer/@stream spec

graphql/graphql-spec#742

• assignee(s): @leebyron
• source: https://github.com/graphql/graphql-wg/blob/master/notes/2020-07-02.md#deferstream-15m-robliliana

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

[2020-05-07] Include defer/stream problem statements in RFC doc

https://github.com/graphql/graphql-wg/blame/master/notes/2020-05-07.md#L168

Add more upcoming agendas

We should definitely have June's up before the May WG, at least 👍

GraphQL over HTTP specification

We previously discussed the possibility of such spec and I went ahead and create MVP:
https://github.com/APIs-guru/graphql-over-http
It would be great if we adopt it under GraphQL Foundation as a complementary spec.
I'm still interested in collaborating but I would love if the community and industry leaders take a lead and we can form a subgroup to work on it.

[2020-07-02] Require Argument Uniqueness

Ivan: validation for type system in chapter 3 requires uniqueness of type names, field names, etc; but we forgot to specify arguments were unique. It's not an editorial change, but pretty uncontroversial.
Lee: on the topic of having a process; we need to have a reference implementation before calling it final stage.
[...]
ACTION - Ivan - implement in GraphQL.js

• assignee(s): @IvanGoncharov
• source: https://github.com/graphql/graphql-wg/blob/master/notes/2020-07-02.md#review-previous-meetings-action-items-5m-lee

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

RFC for introspection field for spec information

RFC for introspection field for spec information

assignee: @eapache & @andimarek
source: GraphQL Working Group Meeting 2019-07-03

[2020-09-03] Organize input value deprecation spec text update and GraphQL.js merge

Lee: Ivan, since you’ve been working on graphql.js change do you want to champion this spec change proposal?
Ivan: I need a native language speaker to review changes; I've pinged Benjie before and he's been really helpful with it.
Lee: ACTION - Ivan - get the GraphQL.js change in and organize updating the spec texts.

• assignee(s): @IvanGoncharov
• source: https://github.com/graphql/graphql-wg/blob/b1bfe0cee461d752146dc77e5c35a5e8d7921272/notes/2020-09-03.md#allowing-deprecation-of-inputs-10m-evan

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

[2020-08-06] Get involved with the GraphQL Scalars Project

Get involved: https://github.com/graphql/graphql-scalars

• assignee(s): EVERYONE!
• source: https://github.com/graphql/graphql-wg/blob/master/notes/2020-08-06.md#custom-scalar-update-5m-andi

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

Details about GraphQL Configuration for cross-tool usage in August 2019 meeting

Apologies if creating an issue is not the right approach for my question.

I was going through the meeting notes for August Meeting Notes.

There is a mention of discussion around improvements for gateway services.

Where can I find details about the discussion and next steps?
For example proposals if any, scope, timelines.

Thanks,
Navneet

[2020-09-03] License missing in scalars subproject

It was pointed out that the scalars subproject does not have a license currently. Lee suggested we'd use the OWFa license, but actioned himself to follow up with Brian to make sure licensing is done right.

Andreas: that's why I've opened this issue. graphql/graphql-scalars#7
Lee: GraphQL foundation gives us clear legal rules so people know how they can use these scalars.
Andreas: agreed; this is really nice.
ACTION - Lee: I'll follow up with Brian and make sure he's prioritising this.

• assignee(s): @leebyron
• source: https://github.com/graphql/graphql-wg/blob/b1bfe0cee461d752146dc77e5c35a5e8d7921272/notes/2020-09-03.md#scalars-subproject-andreas-marek

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

[2020-10-01] Determine if there are missing action items for October 2020

I think some action items were missed from the notes, so we should go through the YouTube video and update the notes where relevant.

• assignee(s):
• source: https://github.com/graphql/graphql-wg/blob/master/notes/2020-10-01.md

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.

Spec cut date?

I'd like to start a discussion about when we should cut the next release of the GraphQL specification.

It has been 16 months since the last release, and some significant changes and iterative improvements have been made in that time. The previous two release have 20 months between them.

I'd like to return to an annualized and predictable schedule for specification releases.

WG meetup before/after GraphQL Summit

Currently, WG scheduled for 2018-11-08 and that conflicts with 2nd day of GraphQL Summit:
https://github.com/graphql/graphql-wg/blob/master/agendas/2018-11-08.md
https://summit.graphql.com/
Would be great to move WG to either November 6th or 9th?

@leebyron Do you plan to organize special WG session similar to graphql-europe?
If so would be great to decide on the date so participants are able to buy plane tickets while they still cheap.

[2019-07-03] Write up vision for code page

Write up vision for code page

assignee: @leebyron
source: GraphQL Working Group Meeting 2019-07-03

[2020-09-03] Call to organize collaboration on TypeScript migration of GraphQL.js

Ivan: TypeScript migration will be a breaking change. Let's discuss it on a call since not everyone's interested in JavaScript implementation. I think it's important to allow new contributors; Flow is a barrier for many people to contribute. TypeScript is easier, I've heard from many contributors.
[...]
Dotan: any issues, if you need help, we can put people to work on it with you. If you need help, we are here.
ACTION - Ivan - organize a call with Dotan to figure out a strategy.

• assignee(s): @IvanGoncharov @dotansimha
• source: https://github.com/graphql/graphql-wg/blob/b1bfe0cee461d752146dc77e5c35a5e8d7921272/notes/2020-09-03.md#typescript-migration-progress-in-graphql-js-5m-dotan-how-to-bootstrap-graphql-js-working-group-5m-dotan-github-infrastructure-for-managing-working-groups-10m-ivan

---

Note: Action Item issues are reviewed and closed during Working Group
meetings.