[RFC] GraphQL Schema Definition Language (SDL) #90
Conversation
|
Proposal for schema: |
|
|
||
| InterfaceTypeDefinition : interface Name { FieldDefinition+ } | ||
|
|
||
| UnionTypeDefinition : union Name = UnionMembers |
There was a problem hiding this comment.
syntax for UnionMembers is missing in appendix
There was a problem hiding this comment.
Good catch, fixed!
|
Should this also include directives? Something like: This doesn't capture scope / validation rules, so perhaps it should include an 'on' clause? So include would be defined like: |
|
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): I think this is basically compatible with the language defined in this PR, with a few additions (directives). Answering the questions @leebyron asked:
then extend it as needed (I'm assuming that's what you're referencing?)
|
schema {
query: QueryType
mutation: MutationType
}
|
|
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 |
|
Updated to rebase atop recent changes and includes syntax for defining directives based on graphql/graphql-js#318 |
leebyron
force-pushed
the
rfc-idl
branch
2 times, most recently
from
df904d2
to
ace9871
Compare
|
Updated to rebase, fixed some outdated language and added |
This implements the schema definition in the spec proposal in graphql/graphql-spec#90 Adjusts AST, parser, printer, visitor, but also changes the API of buildASTSchema to require a schema definition instead of passing the type names into the function.
spec/Section 2 -- Language.md
Outdated
|
|
||
| #### Object | ||
|
|
||
| ObjectTypeDefinition : type Name ImplementsInterfaces? { FieldDefinition+ } |
There was a problem hiding this comment.
@leebyron I think I found a mismatch with the reference implementation. It uses any to parse the list of fields, but according to spec it should use many (one or more field definitions):
https://github.com/graphql/graphql-js/blob/master/src/language/parser.js#L765
Should ObjectTypeDefinition be defined like this?
ObjectTypeDefinition : type Name ImplementsInterfaces? { FieldDefinition* }
(it's the same with the InputObjectTypeDefinition)
There was a problem hiding this comment.
Thanks for the catch and close read. I'll take a closer look and figure out which is more appropriate, but I think you're probably right.
graphql/graphql-spec#90 Commit: b0885a038ec0e654962d69fb910ac86659279579 [b0885a0] Parents: fdafe32724 Author: Lee Byron <lee@leebyron.com> Date: 23 March 2016 at 6:35:37 AM SGT Commit Date: 23 March 2016 at 6:35:39 AM SGT
This implements the schema definition in the spec proposal in graphql/graphql-spec#90 Adjusts AST, parser, printer, visitor, but also changes the API of buildASTSchema to require a schema definition instead of passing the type names into the function. Commit: 8379e71f7011fe044574f4bdef2a761d18d6cf2c [8379e71] Parents: 176076c8a6 Author: Lee Byron <lee@leebyron.com> Date: 23 March 2016 at 7:38:15 AM SGT Labels: HEAD
This replaces:
```graphql
type Foo implements Bar, Baz { field: Type }
```
With:
```graphql
type Foo implements Bar & Baz { field: Type }
```
This is more consistent with other trailing lists of values which
either have an explicit separator (union members) or are prefixed
with a sigil (directives). This avoids parse ambiguity in the
case of an omitted field set, illustrated by
[github.com/graphql/graphql-js#1166](graphql/graphql-js#1166).
For now, the old method of declaration remains valid.
References:
- graphql/graphql-js#1169
- graphql/graphql-spec#90
- graphql/graphql-spec@32b55ed
|
@leebyron why is the spec still dated October 2016 at http://facebook.github.io/graphql/? |
|
@ermik Because it's the last official release. |
This replaces:
```graphql
type Foo implements Bar, Baz { field: Type }
```
With:
```graphql
type Foo implements Bar & Baz { field: Type }
```
This is more consistent with other trailing lists of values which
either have an explicit separator (union members) or are prefixed
with a sigil (directives). This avoids parse ambiguity in the
case of an omitted field set, illustrated by
[github.com/graphql/graphql-js#1166](graphql/graphql-js#1166).
For now, the old method of declaration remains valid.
References:
- graphql/graphql-js#1169
- graphql/graphql-spec#90
- graphql/graphql-spec@32b55ed
graphql/graphql-spec#90 Commit: b0885a038ec0e654962d69fb910ac86659279579 [b0885a0] Parents: fdafe32724 Author: Lee Byron <lee@leebyron.com> Date: 23 March 2016 at 6:35:37 AM SGT Commit Date: 23 March 2016 at 6:35:39 AM SGT
This implements the schema definition in the spec proposal in graphql/graphql-spec#90 Adjusts AST, parser, printer, visitor, but also changes the API of buildASTSchema to require a schema definition instead of passing the type names into the function. Commit: 8379e71f7011fe044574f4bdef2a761d18d6cf2c [8379e71] Parents: 176076c8a6 Author: Lee Byron <lee@leebyron.com> Date: 23 March 2016 at 7:38:15 AM SGT Labels: HEAD
This adds the type definition syntax to the GraphQL specification.
There are some remaining issues to solve: