Deprecated directive (#384)

This adds a new directive as part of the experimental schema language:

```
directive @deprecated(reason: String = "No longer supported") on FIELD_DEFINITION | ENUM_VALUE
```

It also adds support for this directive in the schemaPrinter and buildASTSchema.

Additionally exports a new helper `specifiedDirectives` which is encoured to be used when addressing the collection of all directives defined by the spec. The `@deprecated` directive is optimistically added to this collection. While it's currently experimental, it will become part of the schema definition language RFC.

Commit:
5375c9b20452801b69dba208cac15d32e02ac608 [5375c9b]
Parents:
0aa78f61a2
Author:
Lee Byron <lee@leebyron.com>
Date:
9 May 2016 at 5:56:16 AM SGT
Labels:
HEAD

directives.go

@@ -24,6 +24,16 @@ const (
 	DirectiveLocationInputFieldDefinition = "INPUT_FIELD_DEFINITION"
 )
 
+// DefaultDeprecationReason Constant string used for default reason for a deprecation.
+const DefaultDeprecationReason = "No longer supported"
+
+// SpecifiedRules The full list of specified directives.
+var SpecifiedDirectives = []*Directive{
+	IncludeDirective,
+	SkipDirective,
+	DeprecatedDirective,
+}
+
 // Directive structs are used by the GraphQL runtime as a way of modifying execution
 // behavior. Type system creators will usually not create these directly.
 type Directive struct {
@@ -90,7 +100,7 @@ func NewDirective(config DirectiveConfig) *Directive {
 	return dir
 }
 
-// IncludeDirective is used to conditionally include fields or fragments
+// IncludeDirective is used to conditionally include fields or fragments.
 var IncludeDirective = NewDirective(DirectiveConfig{
 	Name: "include",
 	Description: "Directs the executor to include this field or fragment only when " +
@@ -108,7 +118,7 @@ var IncludeDirective = NewDirective(DirectiveConfig{
 	},
 })
 
-// SkipDirective Used to conditionally skip (exclude) fields or fragments
+// SkipDirective Used to conditionally skip (exclude) fields or fragments.
 var SkipDirective = NewDirective(DirectiveConfig{
 	Name: "skip",
 	Description: "Directs the executor to skip this field or fragment when the `if` " +
@@ -125,3 +135,22 @@ var SkipDirective = NewDirective(DirectiveConfig{
 		DirectiveLocationInlineFragment,
 	},
 })
+
+// DeprecatedDirective  Used to declare element of a GraphQL schema as deprecated.
+var DeprecatedDirective = NewDirective(DirectiveConfig{
+	Name:        "deprecated",
+	Description: "Marks an element of a GraphQL schema as no longer supported.",
+	Args: FieldConfigArgument{
+		"reason": &ArgumentConfig{
+			Type: String,
+			Description: "Explains why this element was deprecated, usually also including a " +
+				"suggestion for how to access supported similar data. Formatted" +
+				"in [Markdown](https://daringfireball.net/projects/markdown/).",
+			DefaultValue: DefaultDeprecationReason,
+		},
+	},
+	Locations: []string{
+		DirectiveLocationFieldDefinition,
+		DirectiveLocationEnumValue,
+	},
+})

introspection.go

@@ -136,7 +136,7 @@ func init() {
 				Description: "Location adjacent to an inline fragment.",
 			},
 			"SCHEMA": &EnumValueConfig{
-				Value: DirectiveLocationSchema,
+				Value:       DirectiveLocationSchema,
 				Description: "Location adjacent to a schema definition.",
 			},
 			"SCALAR": &EnumValueConfig{

schema.go

@@ -26,14 +26,14 @@ type TypeMap map[string]Type
 //     });
 // Note: If an array of `directives` are provided to GraphQLSchema, that will be
 // the exact list of directives represented and allowed. If `directives` is not
-// provided then a default set of the built-in `[ @include, @skip ]` directives
-// will be used. If you wish to provide *additional// directives to these
-// built-ins, you must explicitly declare them. Example:
-//     directives: [
-//       myCustomDirective,
-//       GraphQLIncludeDirective,
-//       GraphQLSkipDirective
-//     ]
+// provided then a default set of the specified directives (e.g. @include and
+// @skip) will be used. If you wish to provide *additional* directives to these
+// specified directives, you must explicitly declare them. Example:
+//
+//     const MyAppSchema = new GraphQLSchema({
+//       ...
+//       directives: specifiedDirectives.concat([ myCustomDirective ]),
+//     })
 type Schema struct {
 	typeMap    TypeMap
 	directives []*Directive
@@ -67,13 +67,10 @@ func NewSchema(config SchemaConfig) (Schema, error) {
 	schema.mutationType = config.Mutation
 	schema.subscriptionType = config.Subscription
 
-	// Provide `@include() and `@skip()` directives by default.
+	// Provide specified directives (e.g. @include and @skip) by default.
 	schema.directives = config.Directives
 	if len(schema.directives) == 0 {
-		schema.directives = []*Directive{
-			IncludeDirective,
-			SkipDirective,
-		}
+		schema.directives = SpecifiedDirectives
 	}
 	// Ensure directive definitions are error-free
 	for _, dir := range schema.directives {