GeezerVison

Proposal for schema:

schema {
  query: QueryType
  mutation: MutationType
}

SchemaDefinition : schema { OperationTypeDefinition+ }
OperationTypeDefinition : OperationType : NamedType

Should this also include directives? Something like:

DirectiveDefinition : directive Name ArgumentsDefinition?

This doesn't capture scope / validation rules, so perhaps it should include an 'on' clause?

DirectiveDefinition : directive Name ArgumentsDefinition? DirectiveScopes?
DirectiveScopes : on DirectiveScope+
DirectiveScope : field | fragment | operation

So include would be defined like:

directive include(if: Boolean!) on field, fragment

Is there any movement on this? This is a pretty compelling piece of the GraphQL puzzle and opens up the possibility of tooling around schema design and also allows the creation of a cross language test suite.

I ended up implementing most of this grammar in a project I'm working on. Here's the relevant lines from a PEG grammar (just the type parsing stuff):

TypeDefinition <- ObjectTypeDefinition / InterfaceTypeDefinition / UnionTypeDefinition / ScalarTypeDefinition / EnumTypeDefinition / InputObjectTypeDefinition / TypeExtensionDefinition / DirectiveDefinition
ObjectTypeDefinition <- "type" _ Name _ ImplementsInterfaces? _ "{" __ (FieldDefinition __)* "}"
ImplementsInterfaces <- "implements" _ (Name _)+
FieldDefinition <- Name _ ArgumentsDefinition? _ ':' _ InputType
ArgumentsDefinition <- '(' _ ( InputValueDefinition _ )* ')'
InputValueDefinition <- Name _ ':' _ InputType _ DefaultValue?
InterfaceTypeDefinition <- "interface" _ Name _ '{' __ (FieldDefinition __)+ '}'
UnionTypeDefinition <- ("union" / "Union") _ Name _ "=" _ UnionMembers
UnionMembers <- NamedType _ ("|" _ NamedType _)*
ScalarTypeDefinition <- "scalar" _ Name
EnumTypeDefinition <- "enum" _ Name _ "{" __ (EnumValue __)+ __ "}"
InputTypeDefinition <- Name _ ':' _ InputType _ DefaultValue?
InputObjectTypeDefinition <- "input" _ Name _ "{" __ (InputTypeDefinition __)+ "}"
DirectiveDefinition <- "directive" _ Name _ "on" _ (Name _)+ ArgumentsDefinition?
TypeExtensionDefinition <- "extend" _ ObjectTypeDefinition

I think this is basically compatible with the language defined in this PR, with a few additions (directives).

Answering the questions @leebyron asked:

• description and deprecation are both expressed via directives
• not sure what top level schema means - we define a query root object like:

type QueryRoot{}

then extend it as needed (I'm assuming that's what you're referencing?)

extend type QueryRoot {
    __schema : __Schema!
    __type(name: String!) : __Type
}

• It's not clear what validation would be required. We're doing a little to catch compliance with the relay extensions and handle some of our own extensions, but nothing that passes the grammar has brought up anything interesting.

• Got a concrete example for implementing metadata (description, isDeprecated, etc) using directives @nuance ?
• Top level schema I think refers to being able to parse the schema itself which is fairly trivial, just needs to be spec'd fully, but it looks like your example could use existing primitives

schema {
  query: QueryType
  mutation: MutationType
}

• You can't mix type defs and queries which is described in the spec already, but presumably not in the execution section yet
• Schema validation would be somewhat different to query validation, but as you point out if it is parsable then it's probably right, not sure what semantics could be validated? Guidance on orphan/unreferenced types, circular references, for a start

For reference there are some concrete examples here: https://github.com/matthewmueller/graph.ql

Descriptions are assumed to be in comments immediately preceding the thing it's describing, assuming deprecation etc could be handled in a similar fashion with a specially formatted comment.

Another possibility for metadata might be type annotations starting with @:

@description Describes a person
type Person {
  @isDeprecated true
  field: Int
}

Thinking more about how this is done with directives, you could make something quite readable:

@metadata(description: "Describes a person")
type Person {
  @metadata(isDeprecated true)
  field: Int
}

Enums are also an issue, since values are not able to be supplied using the current syntax

Updated to rebase atop recent changes and includes syntax for defining directives based on graphql/graphql-js#318

Updated to rebase, fixed some outdated language and added SchemaDefinition

@leebyron why is the spec still dated October 2016 at http://facebook.github.io/graphql/?

@ermik Because it's the last official release.
You can find the draft of the next release (including SDL) here:
http://facebook.github.io/graphql/draft/