Skip to content

add @experimental #944

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions spec/Section 3 -- Type System.md
Original file line number Diff line number Diff line change
Expand Up @@ -879,6 +879,8 @@ of rules must be adhered to by every Object type in a GraphQL schema.
{"\_\_"} (two underscores).
2. The argument must accept a type where {IsInputType(argumentType)}
returns {true}.
3. If argument type is Non-Null and a default value is not defined:
- The `@experimental` directive shall not be applied to this argument.
3. An object type may declare that it implements one or more unique interfaces.
4. An object type must be a super-set of all interfaces it implements:
1. Let this object type be {objectType}.
Expand Down Expand Up @@ -995,6 +997,22 @@ type ExampleType {
}
```

### Experimental fields

Fields in an object may be marked as experimental as deemed necessary by the
application. Experimental fields can be included in selection sets but might be
changed in a backward incompatible manner. The fields should be appropriately
treated in documentation and tooling.

When using the type system definition language, `@experimental` directives are
used to indicate that a field is experimental:

```graphql example
type ExampleType {
newField: String @experimental
}
```

### Object Extensions

ObjectTypeExtension :
Expand Down Expand Up @@ -1652,6 +1670,8 @@ input ExampleInputObject {
{"\_\_"} (two underscores).
3. The input field must accept a type where {IsInputType(inputFieldType)}
returns {true}.
4. If input field type is Non-Null and a default value is not defined:
- The `@experimental` directive shall not be applied to this input field.
3. If an Input Object references itself either directly or through referenced
Input Objects, at least one of the fields in the chain of references must be
either a nullable or a List type.
Expand Down Expand Up @@ -1895,6 +1915,10 @@ GraphQL implementations that support the type system definition language must
provide the `@deprecated` directive if representing deprecated portions of the
schema.

GraphQL implementations that support the type system definition language must
provide the `@experimental` directive if representing experimental portions of
the schema.

GraphQL implementations that support the type system definition language should
provide the `@specifiedBy` directive if representing custom scalar definitions.

Expand Down Expand Up @@ -2067,6 +2091,40 @@ type ExampleType {
}
```

### @experimental

```graphql
directive @experimental(
reason: String = "Experimental"
) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE
```

The `@experimental` _built-in directive_ is used within the type system
definition language to indicate experimental portions of a GraphQL service's
schema, such as experimental fields on a type, arguments on a field, input
fields on an input type, or values of an enum type.

In this example type definition, `newField` and `newArg` are experimental and
might be changed in a backward incompatible way. For an example, it could be
renamed and/or its type may be changed.

```graphql example
type ExampleType {
newField: String @experimental

anotherField(newArg: String @experimental): String
}
```

The `@experimental` directive must not appear on required (non-null without a
default) arguments or input object field definitions.

```graphql counter-example
type ExampleType {
invalidField(newArg: String! @experimental): String
}
```

### @specifiedBy

```graphql
Expand Down