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

 note
You can use ignored conditions settings to ignore all potentially breaking changes when detected on a variant without traffic.

Removals

These changes remove a schema element. If an operation is actively using a removed element, that operation will start returning an error.

NameDescription
FIELD_REMOVEDA field used by at least one operation was removed.
TYPE_REMOVEDA scalar or object used by at least one operation was removed.
ARG_REMOVEDAn argument used by at least one operation was removed from a field.
TYPE_REMOVED_FROM_UNIONA type was removed from a union used by at least one operation.
FIELD_REMOVED_FROM_INPUT_OBJECTA 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_ENUMA value was removed from an enum used by at least one operation.
TYPE_REMOVED_FROM_INTERFACEAn 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.

NameDescription
REQUIRED_ARG_ADDEDA non-nullable argument was added to field that's used by at least one operation.
REQUIRED_FIELD_ADDED_TO_INPUT_OBJECTA 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.

 note
In some cases, in-place updates are compatible with affected clients at runtime (such as a type rename or a conversion from an object to an interface that uses the same fields). However, schema checks still marks these as breaking changes, because validation does not have enough information to ensure that they are safe.
NameDescription
FIELD_CHANGED_TYPEAn existing field used by at least one operation changed its type.
FIELD_ON_INPUT_OBJECT_CHANGED_TYPEAn 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_KINDAn existing type used by at least one operation changed its "kind." For example, an object type was changed to a union type.
ARG_CHANGED_TYPEAn existing argument on a field used by at least one operation changed its type.
ARG_CHANGED_TYPE_OPTIONAL_TO_REQUIREDAn 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.

 note
You can use ignored conditions settings to ignore default value changes. Default value removals can still be breaking changes.
NameDescription
ARG_DEFAULT_VALUE_CHANGEAn existing field used by at least one operation had a default value added, changed, or removed.
INPUT_OBJECT_FIELD_DEFAULT_VALUE_CHANGEAn existing input object field used by at least one operation had a default value changed.
INPUT_OBJECT_FIELD_DEFAULT_VALUE_REMOVEDAn 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

NameDescription
FIELD_ADDEDA field was added to an existing type.
TYPE_ADDEDA type was added to the schema.
VALUE_ADDED_TO_ENUMA 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_UNIONA type was added to a union used by at least one operation.
TYPE_ADDED_TO_INTERFACEAn interface was applied to an object used by at least one operation.
OPTIONAL_ARG_ADDEDA nullable argument was added to an existing field.
OPTIONAL_FIELD_ADDED_TO_INPUT_OBJECTAn optional field was added to an existing input object.
INPUT_OBJECT_FIELD_DEFAULT_VALUE_ADDEDAn existing input object field used by at least one operation had a default value added.

Deprecations

NameDescription
FIELD_DEPRECATEDAn existing field was deprecated.
FIELD_DEPRECATION_REMOVEDA previously deprecated field is no longer deprecated.
FIELD_DEPRECATED_REASON_CHANGEThe specified reason for a field's deprecation changed.
ENUM_DEPRECATEDAn existing enum was deprecated.
ENUM_DEPRECATION_REMOVEDA previously deprecated enum is no longer deprecated.
ENUM_DEPRECATED_REASON_CHANGEThe specified reason for an enum's deprecation changed.

Descriptions

NameDescription
TYPE_DESCRIPTION_CHANGEAn existing type's description changed.
FIELD_DESCRIPTION_CHANGEAn existing field's description changed.
ENUM_VALUE_DESCRIPTION_CHANGEAn existing enum value's description changed.
ARG_DESCRIPTION_CHANGEAn existing argument's description changed.