[WIP] New schema for all query/schema examples

[stubailo]

I went on a quest to design a schema that exercises every feature of GraphQL schemas I know of, and this is what I have so far.

The other goal is to reimplement the schema using the schema language directly, rather than having it in comments that are in danger of becoming outdated.

[stubailo]

Notes from @tmeasday:

• Input object types?
• Mutations not defined
• Argument to search shouldn't be called query, it's too vague

[leebyron]

It's good to encourage the best practice of using ID type for id fields/arguments

[stubailo]

Yeah I noticed that the old example schema had String instead of ID, but let's upgrade.

[lacker]

I don't see why that is a best practice - the only benefit of ID is that you can pass it an int and it will automatically cast to a string, right? normally you would not want to do that in your schema AFAICT. if it's a string in your database it seems safer to have it be a string in graphql.

[stubailo]

I also don't really see the benefit of IDs, but it seems like a lot of people value them. Dan Schafer went out of his way in his React Europe talk to mention how non-user-readable IDs should be treated specially.

[leebyron]

Being more generally accepting of a wider range of input is one benefit, but the primary benefit is the semantic value. It distinguishes from strings you might display to a user.

It also helps in migrations when you might start using Int based ids but later realize the scale problem and want to migrate to 64int or String based ids. Or when you need to unify multiple systems which use different storage types for their ids. This is a very real problem we faced at Facebook many times, and so making String/Int backing an implementation detail of the semantic ID offers more freedom for implementors and shields clients from that

[leebyron]

Perhaps for mutations you can add a rating to a film and query ratings? That seems more realistic than adding characters to a film

[stubailo]

I was trying to figure out a use case for input objects, and creating a new object seems like the most common use for them. But perhaps we could just skip input objects.

[leebyron]

Also while you're at it - take a look at some of the examples on /index.html - they're chosen for simplicity to fit on the screen, but it would be awesome if they aligned well with the schema used throughout examples.

[leebyron]

For input objects, how about:

input ReviewInput {
  # 0-5 stars
  stars: Int

  # what'd you think?
  commentary: String
}

type Mutation {
  addReview(film: ID!, review: ReviewInput!): AddReviewResult
}

type AddReviewResult {
  didSucceed: Boolean!
  film: Film
  review: Review
}

[stubailo]

OK, I see that you're thinking of the schema as strictly about the movies, not as an in-universe thing (adding characters, or giving someone credits, doesn't make sense if you're thinking about it as a movie resource for fans). So the schema use case is "a schema for an app where fans can learn and interact about starwars"

[leebyron]

It could go either way, but we need to expand it in some sensible way to support these other featuees for ease of explanation :)

[leebyron]

Re IDs:

Being more generally accepting of a wider range of input is one benefit, but the primary benefit is the semantic value. It distinguishes from strings you might display to a user.

It also helps in migrations when you might start using Int based ids but later realize the scale problem and want to migrate to 64int or String based ids. Or when you need to unify multiple systems which use different storage types for their ids. This is a very real problem we faced at Facebook many times, and so making String/Int backing an implementation detail of the semantic ID offers more freedom for implementors and shields clients from that

[stubailo]

For reference, here are all the code samples from index.html:

• 1

"hero": {
    "name": "Luke Skywalker",
    "eyeColor": "blue",
    "hairColor": "blond"
  }

• 2

{
  hero {
    name
    friends {
      name
    }
  }
}

• 3

{
  hero {
    name
    friends {
      name
      homeWorld {
        name
        climate
      }
      species {
        name
        lifespan
        origin {
          name
        }
      }
    }
  }
}

type Query {
  hero: Character
}

type Character {
  name: String
  friends: [Character]
  homeWorld: Planet
  species: Species
}

type Planet {
  name: String
  climate: String
}

type Species {
  name: String
  lifespan: Int
  origin: Planet
}

• 4

type Film {
  title: String
  episode: Int
  releaseDate: String
  openingCrawl: String
  director: String @deprecated
  directedBy: Person
}

type Person {
  name: String
  directed: [Film]
  actedIn: [Film]
}

I don't think we should update the example schema to include all of these types, but I think we can rewrite the examples to draw from a more concise schema.

[leebyron]

Cool. Doesn't have to be perfect. Front page should optimize for simplicity rather than consistency with the rest of the docs, but places where consistency is a no brainer should change

[stubailo]

OK, going to merge this for now since all of the existing examples have been converted.