Schema Checks Reference
Reference for types of schema changes that checks can detect
This reference describes the operations checks statuses you see in GraphOS Studio and the schema change types reported by the Rover CLI subgraph check
response .
Operations check statuses
GraphOS classifies operations checks with the following statuses:
Status | Description |
---|---|
Broken | The operation is invalid and not executable against the new schema. |
Potentially affected | The operation is valid against the new schema but may result in errors or unexpected behavior. |
Unaffected | The operation is unaffected by schema change(s). |
Safe | A user has marked schema change(s) for this operation as safe . |
Ignored | A user has chosen to ignore schema change(s) for this operation. |
Types of schema changes
When you run a schema check, the check response classifies each schema change with the following codes.
Not every change to a schema is a potentially breaking change. Additive changes (such as adding a field to a type) are usually safe and do not affect active clients. Deletions and modifications (such as removing a field or changing a return type), however, can break clients that use affected types and fields.
If you use the GraphOS Router to report operation metrics , you can configure extended reference reporting for more accurate schema checks.
Potentially breaking changes
Removals
These changes remove a schema element. If an operation is actively using a removed element, that operation will start returning an error.
Name | Description |
---|---|
FIELD_REMOVED | A field used by at least one operation was removed. |
TYPE_REMOVED | A scalar or object used by at least one operation was removed. |
ARG_REMOVED | An argument used by at least one operation was removed from a field. |
TYPE_REMOVED_FROM_UNION | A type was removed from a union used by at least one operation. |
FIELD_REMOVED_FROM_INPUT_OBJECT | A field was removed from an input type. That field is referenced by an argument on another field that's used by at least one operation. |
VALUE_REMOVED_FROM_ENUM | A value was removed from an enum used by at least one operation. |
TYPE_REMOVED_FROM_INTERFACE | An object was removed from an interface used by at least one operation. |
Addition of required arguments
These changes add a required input to a schema element. If an operation is actively using an element of your graph and doesn't add the new required input argument, the graph will return an error to affected clients.
Name | Description |
---|---|
REQUIRED_ARG_ADDED | A non-nullable argument was added to field that's used by at least one operation. |
REQUIRED_FIELD_ADDED_TO_INPUT_OBJECT | A non-nullable field without a default value was added to an input object used by at least one operation. |
In-place updates
These changes update an existing schema element. If an operation is actively using an element that is updated, the operation might start receiving an error from your graph. It also might receive an unexpected result.
Name | Description |
---|---|
FIELD_CHANGED_TYPE | An existing field used by at least one operation changed its type. |
FIELD_ON_INPUT_OBJECT_CHANGED_TYPE | An existing field of an input object changed its type. That field is referenced by an argument on another field that's used by at least one operation. |
TYPE_CHANGED_KIND | An existing type used by at least one operation changed its "kind." For example, an object type was changed to a union type. |
ARG_CHANGED_TYPE | An existing argument on a field used by at least one operation changed its type. |
ARG_CHANGED_TYPE_OPTIONAL_TO_REQUIRED | An existing argument on a field used by at least one operation changed from an optional type to a required type. |
Default values
These changes update the default value for an argument or input type. If an operation is using an element of your graph and does not specify a value for this argument, the operation might get an unexpected result when the schema is updated if it was relying on the original default value.
Name | Description |
---|---|
ARG_DEFAULT_VALUE_CHANGE | An existing field used by at least one operation had a default value added, changed, or removed. |
INPUT_OBJECT_FIELD_DEFAULT_VALUE_CHANGE | An existing input object field used by at least one operation had a default value changed. |
INPUT_OBJECT_FIELD_DEFAULT_VALUE_REMOVED | An existing input object field used by at least one operation had a default value removed. |
Non-breaking changes
These changes are detected by schema checks, but they are "safe." They never affect the behavior of any existing clients if deployed.
Schema additions
Name | Description |
---|---|
FIELD_ADDED | A field was added to an existing type. |
TYPE_ADDED | A type was added to the schema. |
VALUE_ADDED_TO_ENUM | A value was added to an enum. If clients contain a switch statement on the enum's value and do not include a default case, this change might cause unexpected behavior. |
TYPE_ADDED_TO_UNION | A type was added to a union used by at least one operation. |
TYPE_ADDED_TO_INTERFACE | An interface was applied to an object used by at least one operation. |
OPTIONAL_ARG_ADDED | A nullable argument was added to an existing field. |
OPTIONAL_FIELD_ADDED_TO_INPUT_OBJECT | An optional field was added to an existing input object. |
INPUT_OBJECT_FIELD_DEFAULT_VALUE_ADDED | An existing input object field used by at least one operation had a default value added. |
Deprecations
Name | Description |
---|---|
FIELD_DEPRECATED | An existing field was deprecated. |
FIELD_DEPRECATION_REMOVED | A previously deprecated field is no longer deprecated. |
FIELD_DEPRECATED_REASON_CHANGE | The specified reason for a field's deprecation changed. |
ENUM_DEPRECATED | An existing enum was deprecated. |
ENUM_DEPRECATION_REMOVED | A previously deprecated enum is no longer deprecated. |
ENUM_DEPRECATED_REASON_CHANGE | The specified reason for an enum's deprecation changed. |
Descriptions
Name | Description |
---|---|
TYPE_DESCRIPTION_CHANGE | An existing type's description changed. |
FIELD_DESCRIPTION_CHANGE | An existing field's description changed. |
ENUM_VALUE_DESCRIPTION_CHANGE | An existing enum value's description changed. |
ARG_DESCRIPTION_CHANGE | An existing argument's description changed. |