diff --git a/docs/source/images/federation-dark.svg b/docs/source/images/federation-dark.svg index 2cac4fa11..038365e6d 100644 --- a/docs/source/images/federation-dark.svg +++ b/docs/source/images/federation-dark.svg @@ -50,7 +50,7 @@ - + @@ -60,18 +60,18 @@ - - + + - + - + - + diff --git a/docs/source/images/federation.svg b/docs/source/images/federation.svg index 1fbc91a06..1463a3d60 100644 --- a/docs/source/images/federation.svg +++ b/docs/source/images/federation.svg @@ -7,7 +7,7 @@ - + @@ -21,10 +21,10 @@ - + - + @@ -50,7 +50,7 @@ - + @@ -60,18 +60,18 @@ - - - - + + + + - + - + - - + + diff --git a/docs/source/reference/federation/errors.mdx b/docs/source/reference/federation/errors.mdx index f92c1ca17..3a447e318 100644 --- a/docs/source/reference/federation/errors.mdx +++ b/docs/source/reference/federation/errors.mdx @@ -19,7 +19,7 @@ Composition may flag potential improvements or _hints_ on schemas which are tech To learn more, see the [composition hints doc](/federation/hints/). -### Errors +## Errors The following errors might be raised during composition: @@ -34,7 +34,91 @@ The following errors might be raised during composition: -##### `DEFAULT_VALUE_USES_INACCESSIBLE` +###### `ABSOLUTE_CONNECT_URL_WITH_SOURCE` + +Since v2.10.0\*\* + + + + +The `@connect` directive is using a `source`, but the URL is absolute. This is not allowed because the `@source` URL is joined with the `@connect` URL, so the `@connect` URL should only be a path. + + + + + + +###### `CIRCULAR_REFERENCE` + +Since v2.10.0\*\* + + + + +A [circular reference](graphos/schema-design/connectors/troubleshooting#circular-references) was detected in a `@connect`'s `selection` argument. + + + + + + +###### `CONNECTORS_FIELD_WITH_ARGUMENTS` + +Since v2.10.0\*\* + + + + +A field resolved by a connector has arguments defined. + + + + + + +###### `CONNECTORS_UNRESOLVED_FIELD` + +Since v2.10.0\*\* + + + + +The schema includes fields that aren't resolved by a connector. + + + + + + +###### `CONNECTORS_UNSUPPORTED_ABSTRACT_TYPE` + +Since v2.10.0\*\* + + + + +[Abstract types](/graphos/schema-design/connectors/limitations#abstract-schema-types-are-unsupported) are not allowed when using connectors. + + + + + + +###### `CONNECTORS_UNSUPPORTED_FEDERATION_DIRECTIVE` + +Since v2.10.0\*\* + + + + +[Certain directives](/graphos/schema-design/connectors/limitations) are not allowed when using connectors. + + + + + + +###### `DEFAULT_VALUE_USES_INACCESSIBLE` Since v2.0.0 @@ -48,7 +132,7 @@ An element is marked as `@inaccessible` but is used in the default value of an e -##### `DIRECTIVE_COMPOSITION_ERROR` +###### `DIRECTIVE_COMPOSITION_ERROR` Since v2.1.0 @@ -63,7 +147,7 @@ Error when composing custom directives. -##### `DIRECTIVE_DEFINITION_INVALID` +###### `DIRECTIVE_DEFINITION_INVALID` Since v2.0.0 @@ -79,7 +163,7 @@ Replaces [`TAG_DEFINITION_INVALID`](#tag-definition-invalid). -##### `DISALLOWED_INACCESSIBLE` +###### `DISALLOWED_INACCESSIBLE` Since v2.0.0 @@ -93,7 +177,7 @@ An element is marked as `@inaccessible` that is not allowed to be `@inaccessible -##### `DOWNSTREAM_SERVICE_ERROR` +###### `DOWNSTREAM_SERVICE_ERROR` Since v0.x @@ -102,12 +186,27 @@ Since v0.x Indicates an error in a subgraph service query during query execution in a federated service. + + + + + + +###### `DUPLICATE_SOURCE_NAME` + +Since v2.10.0\*\* + + + + +Indicates two connector sources with the same name were created. + -##### `EMPTY_MERGED_ENUM_TYPE` +###### `EMPTY_MERGED_ENUM_TYPE` Since v2.0.0 @@ -121,7 +220,7 @@ An enum type has no value common to all the subgraphs that define the type. Merg -##### `EMPTY_MERGED_INPUT_TYPE` +###### `EMPTY_MERGED_INPUT_TYPE` Since v2.0.0 @@ -130,12 +229,69 @@ Since v2.0.0 An input object type has no field common to all the subgraphs that define the type. Merging that type would result in an invalid empty input object type. + + + + + + +###### `EMPTY_SOURCE_NAME` + +Since v2.10.0\*\* + + + + +No `name` was provided when creating a connector source with `@source`. + + + + + + +###### `ENTITY_NOT_ON_ROOT_QUERY` + +Since v2.10.0\*\* + + + + +The `@connect` directive's `entity` argument should only be used on the root `Query` field. + -##### `ENUM_VALUE_MISMATCH` +###### `ENTITY_RESOLVER_ARGUMENT_MISMATCH` + +Since v2.10.0\*\* + + + + +The arguments for an entity reference resolver do not match the entity type. + + + + + + +###### `ENTITY_TYPE_INVALID` + +Since v2.10.0\*\* + + + + +The `@connect` directive's `entity` argument should only be used with non-list, nullable, object types. + + + + + + +###### `ENUM_VALUE_MISMATCH` Since v2.0.0 @@ -149,7 +305,7 @@ An enum type that is used as both an input and output type has a value that is n -##### `EXTENSION_WITH_NO_BASE` +###### `EXTENSION_WITH_NO_BASE` Since v0.x @@ -163,7 +319,7 @@ A subgraph is attempting to `extend` a type that is not originally defined in an -##### `EXTERNAL_ARGUMENT_DEFAULT_MISMATCH` +###### `EXTERNAL_ARGUMENT_DEFAULT_MISMATCH` Since v2.0.0 @@ -177,7 +333,7 @@ An `@external` field declares an argument with a default that is incompatible wi -##### `EXTERNAL_ARGUMENT_MISSING` +###### `EXTERNAL_ARGUMENT_MISSING` Since v2.0.0 @@ -191,7 +347,7 @@ An `@external` field is missing some arguments present in the declaration(s) of -##### `EXTERNAL_ARGUMENT_TYPE_MISMATCH` +###### `EXTERNAL_ARGUMENT_TYPE_MISMATCH` Since v2.0.0 @@ -205,7 +361,7 @@ An `@external` field declares an argument with a type that is incompatible with -##### `EXTERNAL_COLLISION_WITH_ANOTHER_DIRECTIVE` +###### `EXTERNAL_COLLISION_WITH_ANOTHER_DIRECTIVE` Since v2.1.0 @@ -219,7 +375,7 @@ The `@external` directive collides with other directives in some situations. -##### `EXTERNAL_MISSING_ON_BASE` +###### `EXTERNAL_MISSING_ON_BASE` Since v0.x @@ -233,7 +389,7 @@ A field is marked as `@external` in a subgraph but with no non-external declarat -##### `EXTERNAL_ON_INTERFACE` +###### `EXTERNAL_ON_INTERFACE` Since v2.0.0 @@ -247,7 +403,7 @@ The field of an interface type is marked with `@external`: as external is about -##### `EXTERNAL_TYPE_MISMATCH` +###### `EXTERNAL_TYPE_MISMATCH` Since v0.x @@ -261,7 +417,7 @@ An `@external` field has a type that is incompatible with the declaration(s) of -##### `EXTERNAL_UNUSED` +###### `EXTERNAL_UNUSED` Since v0.x @@ -275,7 +431,7 @@ An `@external` field is not being used by any instance of `@key`, `@requires`, ` -##### `FIELD_ARGUMENT_DEFAULT_MISMATCH` +###### `FIELD_ARGUMENT_DEFAULT_MISMATCH` Since v2.0.0 @@ -289,7 +445,7 @@ An argument (of a field/directive) has a default value that is incompatible with -##### `FIELD_ARGUMENT_TYPE_MISMATCH` +###### `FIELD_ARGUMENT_TYPE_MISMATCH` Since v2.0.0 @@ -305,7 +461,7 @@ Replaces [`VALUE_TYPE_INPUT_VALUE_MISMATCH`](#value-type-input-value-mismatch). -##### `FIELD_TYPE_MISMATCH` +###### `FIELD_TYPE_MISMATCH` Since v2.0.0 @@ -321,7 +477,63 @@ Replaces [`VALUE_TYPE_FIELD_TYPE_MISMATCH`](#value-type-field-type-mismatch). -##### `IMPLEMENTED_BY_INACCESSIBLE` +###### `GRAPHQL_ERROR` + +Since v2.10.0\*\* + + + + +A problem with GraphQL syntax or semantics was found. These will usually be caught before this validation process. + + + + + + +###### `GROUP_SELECTION_IS_NOT_OBJECT` + +Since v2.10.0\*\* + + + + +A group selection mapping (`a { b }`) was used, but the field is not an object. + + + + + + +###### `GROUP_SELECTION_REQUIRED_FOR_OBJECT` + +Since v2.10.0\*\* + + + + +Fields that return an object type must use a group selection mapping `{}`. + + + + + + +###### `HTTP_HEADER_NAME_COLLISION` + +Since v2.10.0\*\* + + + + +The `name` mapping must be unique for all headers. + + + + + + +###### `IMPLEMENTED_BY_INACCESSIBLE` Since v2.0.0 @@ -335,7 +547,7 @@ An element is marked as `@inaccessible` but implements an element visible in the -##### `INPUT_FIELD_DEFAULT_MISMATCH` +###### `INPUT_FIELD_DEFAULT_MISMATCH` Since v2.0.0 @@ -349,7 +561,91 @@ An input field has a default value that is incompatible with other declarations -##### `INTERFACE_FIELD_NO_IMPLEM` +###### `INVALID_BODY` + +Since v2.10.0\*\* + + + + +The `http.body` provided in `@connect` was not valid. + + + + + + +###### `INVALID_HEADER` + +Since v2.10.0\*\* + + + + +A provided header in `@source` or `@connect` was not valid. + + + + + + +###### `INVALID_SELECTION` + +Since v2.10.0\*\* + + + + +The provided selection mapping in a `@connect`s `selection` was not valid. + + + + + + +###### `INVALID_SOURCE_NAME` + +Since v2.10.0\*\* + + + + +The `name` provided for a `@source` was invalid. Source names must start with a letter, include only letters, numbers, underscores (`_`) and hyphens (`-`), and be less than 64 characters. + + + + + + +###### `INVALID_URL` + +Since v2.10.0\*\* + + + + +A URL provided to `@source` or `@connect` was not valid. + + + + + + +###### `INVALID_URL_SCHEME` + +Since v2.10.0\*\* + + + + +A URL scheme provided to `@source` or `@connect` was not `http` or `https`. + + + + + + +###### `INTERFACE_FIELD_NO_IMPLEM` Since v2.0.0 @@ -363,7 +659,7 @@ After subgraph merging, an implementation is missing a field of one of the inter -##### `INTERFACE_KEY_MISSING_IMPLEMENTATION_TYPE` +###### `INTERFACE_KEY_MISSING_IMPLEMENTATION_TYPE` Since v2.3.0 @@ -377,7 +673,7 @@ A subgraph has a `@key` on an interface type, but that subgraph does not define -##### `INTERFACE_KEY_NOT_ON_IMPLEMENTATION` +###### `INTERFACE_KEY_NOT_ON_IMPLEMENTATION` Since v2.3.0 @@ -391,7 +687,7 @@ A `@key` is defined on an interface type, but is not defined (or is not resolvab -##### `INTERFACE_OBJECT_USAGE_ERROR` +###### `INTERFACE_OBJECT_USAGE_ERROR` Since v2.3.0 @@ -405,7 +701,7 @@ Error in the usage of the `@interfaceObject` directive. -##### `INVALID_FEDERATION_SUPERGRAPH` +###### `INVALID_FEDERATION_SUPERGRAPH` Since v2.1.0 @@ -419,7 +715,7 @@ Indicates that a schema provided for an Apollo Federation supergraph is not a va -##### `INVALID_FIELD_SHARING` +###### `INVALID_FIELD_SHARING` Since v2.0.0 @@ -433,7 +729,7 @@ A field that is non-shareable in at least one subgraph is resolved by multiple s -##### `INVALID_GRAPHQL` +###### `INVALID_GRAPHQL` Since v2.0.0 @@ -447,7 +743,7 @@ A schema is invalid GraphQL: it violates one of the rules of the specification. -##### `INVALID_LINK_DIRECTIVE_USAGE` +###### `INVALID_LINK_DIRECTIVE_USAGE` Since v2.0.0 @@ -461,7 +757,7 @@ An application of the `@link` directive is invalid/does not respect the specific -##### `INVALID_LINK_IDENTIFIER` +###### `INVALID_LINK_IDENTIFIER` Since v2.1.0 @@ -475,7 +771,7 @@ A URL/version for a `@link` feature is invalid/does not respect the specificatio -##### `INVALID_SHAREABLE_USAGE` +###### `INVALID_SHAREABLE_USAGE` Since v2.1.2 @@ -489,7 +785,7 @@ The `@shareable` Federation directive is used in an invalid way. -##### `INVALID_SUBGRAPH_NAME` +###### `INVALID_SUBGRAPH_NAME` Since v2.0.0 @@ -503,7 +799,7 @@ A subgraph name is invalid. (Subgraph names cannot be a single underscore (`_`)) -##### `KEY_DIRECTIVE_IN_FIELDS_ARG` +###### `KEY_DIRECTIVE_IN_FIELDS_ARG` Since v2.1.0 @@ -517,7 +813,7 @@ The `fields` argument of a `@key` directive includes some directive applications -##### `KEY_FIELDS_HAS_ARGS` +###### `KEY_FIELDS_HAS_ARGS` Since v2.0.0 @@ -531,7 +827,7 @@ The `fields` argument of a `@key` directive includes a field defined with argume -##### `KEY_FIELDS_SELECT_INVALID_TYPE` +###### `KEY_FIELDS_SELECT_INVALID_TYPE` Since v0.x @@ -545,7 +841,7 @@ The `fields` argument of `@key` directive includes a field whose type is a list, -##### `KEY_INVALID_FIELDS_TYPE` +###### `KEY_INVALID_FIELDS_TYPE` Since v2.0.0 @@ -559,7 +855,7 @@ The value passed to the `fields` argument of a `@key` directive is not a string. -##### `KEY_INVALID_FIELDS` +###### `KEY_INVALID_FIELDS` Since v2.0.0 @@ -573,7 +869,7 @@ The `fields` argument of a `@key` directive is invalid (it has invalid syntax, i -##### `KEY_UNSUPPORTED_ON_INTERFACE` +###### `KEY_UNSUPPORTED_ON_INTERFACE` Since v2.0.0 @@ -587,7 +883,7 @@ A `@key` directive is used on an interface, which is only supported when `@link` -##### `LINK_IMPORT_NAME_MISMATCH` +###### `LINK_IMPORT_NAME_MISMATCH` Since v2.0.0 @@ -601,7 +897,7 @@ The import name for a merged directive (as declared by the relevant `@link(impor -##### `MERGED_DIRECTIVE_APPLICATION_ON_EXTERNAL` +###### `MERGED_DIRECTIVE_APPLICATION_ON_EXTERNAL` Since v2.0.0 @@ -615,7 +911,63 @@ In a subgraph, a field is both marked `@external` and has a merged directive app -##### `NO_QUERIES` +###### `MISSING_ENTITY_CONNECTOR` + +Since v2.10.0\*\* + + + + +A `@key` was defined without a corresponding entity connector. + + + + + + +###### `MISSING_HTTP_METHOD` + +Since v2.10.0\*\* + + + + +The `@connect` directive is missing an HTTP method. + + + + + + +###### `MULTIPLE_HTTP_METHODS` + +Since v2.10.0\*\* + + + + +The `@connect` directive has multiple HTTP methods when only one is allowed. + + + + + + +###### `MUTATION_FIELD_MISSING_CONNECT` + +Since v2.10.0\*\* + + + + +A mutation field is missing the `@connect` directive. + + + + + + +###### `NO_QUERIES` Since v2.0.0 @@ -629,7 +981,49 @@ None of the composed subgraphs expose any query. -##### `ONLY_INACCESSIBLE_CHILDREN` +###### `NO_SOURCE_IMPORT` + +Since v2.10.0\*\* + + + + +The subgraph doesn't import the `@source` directive. This isn't necessarily a problem, but is likely a mistake. + + + + + + +###### `NO_SOURCES_DEFINED` + +Since v2.10.0\*\* + + + + +This is a specialization of [`SOURCE_NAME_MISMATCH`](#source_name_mismatch) error that indicates no sources were defined. + + + + + + +###### `NULLABILITY_MISMATCH` + +Since v2.10.0\*\* + + + + +A variable is nullable in a location which requires non-null at runtime. + + + + + + +###### `ONLY_INACCESSIBLE_CHILDREN` Since v2.0.0 @@ -643,7 +1037,7 @@ A type visible in the API schema has only `@inaccessible` children. -##### `OVERRIDE_COLLISION_WITH_ANOTHER_DIRECTIVE` +###### `OVERRIDE_COLLISION_WITH_ANOTHER_DIRECTIVE` Since v2.0.0 @@ -657,7 +1051,7 @@ The `@override` directive cannot be used on external fields, nor to override fie -##### `OVERRIDE_FROM_SELF_ERROR` +###### `OVERRIDE_FROM_SELF_ERROR` Since v2.0.0 @@ -671,7 +1065,7 @@ Field with `@override` directive has "from" location that references its own sub -##### `OVERRIDE_LABEL_INVALID` +###### `OVERRIDE_LABEL_INVALID` Since v2.7.0 @@ -685,7 +1079,7 @@ The `@override` directive `label` argument must match the pattern `/^[a-zA-Z][a- -##### `OVERRIDE_ON_INTERFACE` +###### `OVERRIDE_ON_INTERFACE` Since v2.3.0 @@ -699,7 +1093,7 @@ The `@override` directive cannot be used on the fields of an interface type. -##### `OVERRIDE_SOURCE_HAS_OVERRIDE` +###### `OVERRIDE_SOURCE_HAS_OVERRIDE` Since v2.0.0 @@ -713,7 +1107,7 @@ Field which is overridden to another subgraph is also marked `@override`. -##### `PROVIDES_DIRECTIVE_IN_FIELDS_ARG` +###### `PROVIDES_DIRECTIVE_IN_FIELDS_ARG` Since v2.1.0 @@ -727,7 +1121,7 @@ The `fields` argument of a `@provides` directive includes some directive applica -##### `PROVIDES_FIELDS_HAS_ARGS` +###### `PROVIDES_FIELDS_HAS_ARGS` Since v2.0.0 @@ -741,7 +1135,7 @@ The `fields` argument of a `@provides` directive includes a field defined with a -##### `PROVIDES_FIELDS_MISSING_EXTERNAL` +###### `PROVIDES_FIELDS_MISSING_EXTERNAL` Since v0.x @@ -755,7 +1149,7 @@ The `fields` argument of a `@provides` directive includes a field that is not ma -##### `PROVIDES_INVALID_FIELDS_TYPE` +###### `PROVIDES_INVALID_FIELDS_TYPE` Since v2.0.0 @@ -769,7 +1163,7 @@ The value passed to the `fields` argument of a `@provides` directive is not a st -##### `PROVIDES_INVALID_FIELDS` +###### `PROVIDES_INVALID_FIELDS` Since v2.0.0 @@ -783,7 +1177,7 @@ The `fields` argument of a `@provides` directive is invalid (it has invalid synt -##### `PROVIDES_ON_NON_OBJECT_FIELD` +###### `PROVIDES_ON_NON_OBJECT_FIELD` Since v2.0.0 @@ -797,7 +1191,7 @@ A `@provides` directive is used to mark a field whose base type is not an object -##### `PROVIDES_UNSUPPORTED_ON_INTERFACE` +###### `PROVIDES_UNSUPPORTED_ON_INTERFACE` Since v2.0.0 @@ -811,7 +1205,21 @@ A `@provides` directive is used on an interface, which is not (yet) supported. -##### `QUERY_ROOT_TYPE_INACCESSIBLE` +###### `QUERY_FIELD_MISSING_CONNECT` + +Since v2.10.0\*\* + + + + +A query field is missing the `@connect` directive. + + + + + + +###### `QUERY_ROOT_TYPE_INACCESSIBLE` Since v2.0.0 @@ -825,7 +1233,7 @@ An element is marked as `@inaccessible` but is the query root type, which must b -##### `REFERENCED_INACCESSIBLE` +###### `REFERENCED_INACCESSIBLE` Since v2.0.0 @@ -839,7 +1247,21 @@ An element is marked as `@inaccessible` but is referenced by an element visible -##### `REQUIRED_ARGUMENT_MISSING_IN_SOME_SUBGRAPH` +###### `RELATIVE_CONNECT_URL_WITHOUT_SOURCE` + +Since v2.10.0\*\* + + + + +The `@connect` directive is using a relative URL (path only) but does not define a `source`. This is a a specialization of [`INVALID_URL`](#invalid-url). + + + + + + +###### `REQUIRED_ARGUMENT_MISSING_IN_SOME_SUBGRAPH` Since v2.0.0 @@ -853,7 +1275,7 @@ An argument of a field or directive definition is mandatory in some subgraphs, b -##### `REQUIRED_INACCESSIBLE` +###### `REQUIRED_INACCESSIBLE` Since v2.0.0 @@ -867,7 +1289,7 @@ An element is marked as `@inaccessible` but is required by an element visible in -##### `REQUIRED_INPUT_FIELD_MISSING_IN_SOME_SUBGRAPH` +###### `REQUIRED_INPUT_FIELD_MISSING_IN_SOME_SUBGRAPH` Since v2.0.0 @@ -881,7 +1303,7 @@ A field of an input object type is mandatory in some subgraphs, but the field is -##### `REQUIRES_DIRECTIVE_IN_FIELDS_ARG` +###### `REQUIRES_DIRECTIVE_IN_FIELDS_ARG` Since v2.1.0 @@ -895,7 +1317,7 @@ The `fields` argument of a `@requires` directive includes some directive applica -##### `REQUIRES_FIELDS_MISSING_EXTERNAL` +###### `REQUIRES_FIELDS_MISSING_EXTERNAL` Since v0.x @@ -909,7 +1331,7 @@ The `fields` argument of a `@requires` directive includes a field that is not ma -##### `REQUIRES_INVALID_FIELDS_TYPE` +###### `REQUIRES_INVALID_FIELDS_TYPE` Since v2.0.0 @@ -923,7 +1345,7 @@ The value passed to the `fields` argument of a `@requires` directive is not a st -##### `REQUIRES_INVALID_FIELDS` +###### `REQUIRES_INVALID_FIELDS` Since v2.0.0 @@ -937,7 +1359,7 @@ The `fields` argument of a `@requires` directive is invalid (it has invalid synt -##### `REQUIRES_UNSUPPORTED_ON_INTERFACE` +###### `REQUIRES_UNSUPPORTED_ON_INTERFACE` Since v2.0.0 @@ -951,7 +1373,7 @@ A `@requires` directive is used on an interface, which is not (yet) supported. -##### `ROOT_MUTATION_USED` +###### `ROOT_MUTATION_USED` Since v0.x @@ -965,7 +1387,7 @@ A subgraph's schema defines a type with the name `mutation`, while also specifyi -##### `ROOT_QUERY_USED` +###### `ROOT_QUERY_USED` Since v0.x @@ -979,7 +1401,7 @@ A subgraph's schema defines a type with the name `query`, while also specifying -##### `ROOT_SUBSCRIPTION_USED` +###### `ROOT_SUBSCRIPTION_USED` Since v0.x @@ -993,7 +1415,7 @@ A subgraph's schema defines a type with the name `subscription`, while also spec -##### `SATISFIABILITY_ERROR` +###### `SATISFIABILITY_ERROR` Since v2.0.0 @@ -1007,7 +1429,21 @@ Subgraphs can be merged, but the resulting supergraph API would have queries tha -##### `SHAREABLE_HAS_MISMATCHED_RUNTIME_TYPES` +###### `SELECTED_FIELD_NOT_FOUND` + +Since v2.10.0\*\* + + + + +A field included in a `@connect` directive's `selection` argument is not defined on the corresponding type. + + + + + + +###### `SHAREABLE_HAS_MISMATCHED_RUNTIME_TYPES` Since v2.0.0 @@ -1021,7 +1457,35 @@ A shareable field return type has mismatched possible runtime types in the subgr -##### `TYPE_DEFINITION_INVALID` +###### `SOURCE_NAME_MISMATCH` + +Since v2.10.0\*\* + + + + +The `source` argument used in a `@connect` directive doesn't match any named connecter sources created with `@source`. + + + + + + +###### `SUBSCRIPTION_IN_CONNECTORS` + +Since v2.10.0\*\* + + + + +Connectors currently [don't support subscription operations](/graphos/schema-design/connectors/limitations#subscriptions-are-unsupported). + + + + + + +###### `TYPE_DEFINITION_INVALID` Since v2.0.0 @@ -1035,7 +1499,7 @@ A built-in or Federation type has an invalid definition in the schema. -##### `TYPE_KIND_MISMATCH` +###### `TYPE_KIND_MISMATCH` Since v2.0.0 @@ -1051,7 +1515,7 @@ Replaces `VALUE_TYPE_KIND_MISMATCH`, `EXTENSION_OF_WRONG_KIND`, `ENUM_MISMATCH_T -##### `TYPE_WITH_ONLY_UNUSED_EXTERNAL` +###### `TYPE_WITH_ONLY_UNUSED_EXTERNAL` Since v2.0.0 @@ -1065,7 +1529,49 @@ A Federation 1 schema has a composite type comprised only of unused external fie -##### `UNKNOWN_FEDERATION_LINK_VERSION` +###### `UNDEFINED_ARGUMENT` + +Since v2.10.0\*\* + + + + +Part of the `@connect` refers to an `$args` which is not defined. + + + + + + +###### `UNDEFINED_FIELD` + +Since v2.10.0\*\* + + + + +Part of the `@connect` refers to an `$this` which is not defined. + + + + + + +###### `UNKNOWN_CONNECTORS_VERSION` + +Since v2.10.0\*\* + + + + +The version set in the connectors `@link` URL is not recognized. + + + + + + +###### `UNKNOWN_FEDERATION_LINK_VERSION` Since v2.0.0 @@ -1079,7 +1585,7 @@ The version of Federation in a `@link` directive on the schema is unknown. -##### `UNKNOWN_LINK_VERSION` +###### `UNKNOWN_LINK_VERSION` Since v2.1.0 @@ -1093,7 +1599,7 @@ The version of `@link` set on the schema is unknown. -##### `UNSUPPORTED_FEATURE` +###### `UNSUPPORTED_FEATURE` Since v2.1.0 @@ -1107,7 +1613,7 @@ Indicates an error due to feature currently unsupported by Federation. -##### `UNSUPPORTED_LINKED_FEATURE` +###### `UNSUPPORTED_LINKED_FEATURE` Since v2.0.0 @@ -1116,11 +1622,31 @@ Since v2.0.0 Indicates that a feature used in a `@link` is either unsupported or is used with unsupported options. + + + + + +###### `UNSUPPORTED_VARIABLE_TYPE` + +Since v2.10.0\*\* + + + + +A type used in a connector's variable is [not yet supported](/graphos/schema-design/connectors/limitations) (i.e., unions). + + + +\*\* Error codes introduced in v2.10.0 related to Apollo Connectors are subject to change. + + + ## Removed codes The following error codes have been removed and are no longer generated by the most recent version of the `@apollo/gateway` library: @@ -1136,7 +1662,7 @@ The following error codes have been removed and are no longer generated by the m -##### `DUPLICATE_ENUM_DEFINITION` +###### `DUPLICATE_ENUM_DEFINITION` @@ -1148,7 +1674,7 @@ As duplicate enum definitions is invalid GraphQL, this will now be an error with -##### `DUPLICATE_ENUM_VALUE` +###### `DUPLICATE_ENUM_VALUE` @@ -1160,7 +1686,7 @@ As duplicate enum values are invalid in GraphQL, this will now be an error with -##### `DUPLICATE_SCALAR_DEFINITION` +###### `DUPLICATE_SCALAR_DEFINITION` @@ -1172,7 +1698,7 @@ As duplicate scalar definitions are invalid in GraphQL, this will now be an erro -##### `ENUM_MISMATCH` +###### `ENUM_MISMATCH` @@ -1184,7 +1710,7 @@ Subgraph definitions for an enum are now merged by composition. -##### `EXTERNAL_USED_ON_BASE` +###### `EXTERNAL_USED_ON_BASE` @@ -1196,7 +1722,7 @@ As there is no type ownership anymore, there is also no particular limitation as -##### `INTERFACE_FIELD_IMPLEM_TYPE_MISMATCH` +###### `INTERFACE_FIELD_IMPLEM_TYPE_MISMATCH` @@ -1208,7 +1734,7 @@ This error was thrown by a validation introduced to avoid running into a known r -##### `KEY_FIELDS_MISSING_EXTERNAL` +###### `KEY_FIELDS_MISSING_EXTERNAL` @@ -1220,7 +1746,7 @@ Using `@external` for key fields is now discouraged, unless the field is truly m -##### `KEY_FIELDS_MISSING_ON_BASE` +###### `KEY_FIELDS_MISSING_ON_BASE` @@ -1232,7 +1758,7 @@ Keys can now use any field from any other subgraph. -##### `KEY_MISSING_ON_BASE` +###### `KEY_MISSING_ON_BASE` @@ -1244,7 +1770,7 @@ Each subgraph is now free to declare a key only if it needs it. -##### `KEY_NOT_SPECIFIED` +###### `KEY_NOT_SPECIFIED` @@ -1256,7 +1782,7 @@ Each subgraph can declare a key independently of any other subgraph. -##### `MULTIPLE_KEYS_ON_EXTENSION` +###### `MULTIPLE_KEYS_ON_EXTENSION` @@ -1268,7 +1794,7 @@ Every subgraph can have multiple keys, as necessary. -##### `NON_REPEATABLE_DIRECTIVE_ARGUMENTS_MISMATCH` +###### `NON_REPEATABLE_DIRECTIVE_ARGUMENTS_MISMATCH` @@ -1280,7 +1806,7 @@ Since Federation v2.1.0, the case this error used to cover is now a warning (wit -##### `PROVIDES_FIELDS_SELECT_INVALID_TYPE` +###### `PROVIDES_FIELDS_SELECT_INVALID_TYPE` @@ -1292,7 +1818,7 @@ Since Federation v2.1.0, the case this error used to cover is now a warning (wit -##### `PROVIDES_NOT_ON_ENTITY` +###### `PROVIDES_NOT_ON_ENTITY` @@ -1304,7 +1830,7 @@ Since Federation v2.1.0, the case this error used to cover is now a warning (wit -##### `REQUIRES_FIELDS_HAS_ARGS` +###### `REQUIRES_FIELDS_HAS_ARGS` @@ -1316,7 +1842,7 @@ Since Federation v2.1.1, using fields with arguments in a `@requires` is fully s -##### `REQUIRES_FIELDS_MISSING_ON_BASE` +###### `REQUIRES_FIELDS_MISSING_ON_BASE` @@ -1328,7 +1854,7 @@ Fields in `@requires` can now be from any subgraph. -##### `REQUIRES_USED_ON_BASE` +###### `REQUIRES_USED_ON_BASE` @@ -1340,7 +1866,7 @@ As there is no type ownership anymore, there is also no particular limitation as -##### `RESERVED_FIELD_USED` +###### `RESERVED_FIELD_USED` @@ -1352,7 +1878,7 @@ This error was previously not correctly enforced: the service and entities, if p -##### `VALUE_TYPE_NO_ENTITY` +###### `VALUE_TYPE_NO_ENTITY` @@ -1364,7 +1890,7 @@ There is no strong difference between entity and value types in the model (they -##### `VALUE_TYPE_UNION_TYPES_MISMATCH` +###### `VALUE_TYPE_UNION_TYPES_MISMATCH` diff --git a/docs/source/reference/federation/versions.mdx b/docs/source/reference/federation/versions.mdx index 615788713..168631d52 100644 --- a/docs/source/reference/federation/versions.mdx +++ b/docs/source/reference/federation/versions.mdx @@ -10,7 +10,7 @@ For a comprehensive changelog for Apollo Federation and its associated libraries - To use a feature introduced in a particular federation version, make sure your subgraph schema's `@link` directive targets that version (or higher): - ```graphql + ```graphql showLineNumbers=false disableCopy=true extend schema @link(url: "https://specs.apollo.dev/federation/v2.3", #highlight-line import: ["@key", "@shareable", "@interfaceObject"]) @@ -26,282 +26,141 @@ For a comprehensive changelog for Apollo Federation and its associated libraries - If you maintain a [subgraph-compatible library](/graphos/reference/federation/compatible-subgraphs), consult this article to stay current with recently added directives. All of these directive definitions are also listed in the [subgraph specification](/graphos/reference/federation/subgraph-spec/#subgraph-schema-additions). -## v2.9 +## v2.10
- - -
+| First release | Available in GraphOS? | Minimum router version | +| ------------- | --------------------- | ---------------------- | +| **February 2025** | **Yes** | **`2.0.0`** | -First release
-**August 2024** +#### Directive changes -
+#### `@connect` -
+Introduced. [Learn more](/graphos/schema-design/connectors/directives#connect). -Available in GraphOS?
-**Yes** +```graphql showLineNumbers=false disableCopy=true +directive @connect( + source: String + http: ConnectHTTP! + selection: JSONSelection! + entity: Boolean +) repeatable on FIELD_DEFINITION; -
+``` -
+#### `@source` -Minimum router version
-**`1.53.0`** +Introduced. [Learn more](/graphos/schema-design/connectors/directives#source). -
+```graphql showLineNumbers=false disableCopy=true +directive @source( + name: String! + http: SourceHTTP! +) repeatable on SCHEMA; +``` - +## v2.9
-#### Directive changes - - - - - - - - +| First release | Available in GraphOS? | Minimum router version | +| ------------- | --------------------- | ---------------------- | +| **August 2024** | **Yes** | **`1.53.0`** | - - - - - - - - - - - - -
TopicDescription
+#### Directive changes #### `@cost` - - Introduced. [Learn more](/federation/federated-schemas/federated-directives#cost). -```graphql -directive @cost(weight: Int!) on ARGUMENT_DEFINITION | ENUM | FIELD_DEFINITION | INPUT_FIELD_DEFINITION | OBJECT | SCALAR +```graphql showLineNumbers=false disableCopy=true +directive @cost(weight: Int!) on + | ARGUMENT_DEFINITION + | ENUM + | FIELD_DEFINITION + | INPUT_FIELD_DEFINITION + | OBJECT + | SCALAR; ``` -
- #### `@listSize` - - Introduced. [Learn more](/federation/federated-schemas/federated-directives#listsize). -```graphql -directive @listSize(assumedSize: Int, slicingArguments: [String!], sizedFields: [String!], requireOneSlicingArgument: Boolean = true) on FIELD_DEFINITION +```graphql showLineNumbers=false disableCopy=true +directive @listSize( + assumedSize: Int + slicingArguments: [String!] + sizedFields: [String!] + requireOneSlicingArgument: Boolean = true +) +on FIELD_DEFINITION; ``` -
- ## v2.8
- - -
- -First release
-**May 2024** - -
- -
- -Available in GraphOS?
-**Yes** - -
- -
- -Minimum router version
-**`1.48.0`** - -
- - - -
+| First release | Available in GraphOS? | Minimum router version | +| ------------- | --------------------- | ---------------------- | +| **May 2024** | **Yes** | **`1.48.0`** | #### Directive changes - - - - - - - - - - - - - - - - - - - - -
TopicDescription
- ##### `@context` - - Introduced. [Learn more](/graphos/reference/federation/directives/#context). -```graphql +```graphql showLineNumbers=false disableCopy=true directive @context(name: String!) on OBJECT | INTERFACE | UNION; ``` -
- ##### `@fromContext` - - Introduced. [Learn more](/graphos/reference/federation/directives/#fromcontext). -```graphql +```graphql showLineNumbers=false disableCopy=true scalar ContextFieldValue; directive @fromContext(field: ContextFieldValue) on ARGUMENT_DEFINITION; ``` -
- ## v2.7
- - -
- -First release
-**February 2024** - -
- -
- -Available in GraphOS?
-**Yes** - -
- -
- -Minimum router version
-**`1.39.0`** - -
- - - -
+| First release | Available in GraphOS? | Minimum router version | +| ------------- | --------------------- | ---------------------- | +| **February 2024** | **Yes** | **`1.39.0`** | #### Directive changes - - - - - - - - - - - - - - - -
TopicDescription
- ##### Progressive `@override` - - Added progressive `@override`. [Learn more.](/graphos/reference/federation/directives/#progressive-override) -```graphql +```graphql showLineNumbers=false disableCopy=true directive @override(from: String!, label: String) on FIELD_DEFINITION ``` -
- ## v2.6
- - -
- -First release
-**November 2023** - -
- -
- -Available in GraphOS?
-**Yes** - -
- -
- -Minimum router version
-**`1.35.0`** - -
- - - -
+| First release | Available in GraphOS? | Minimum router version | +| ------------- | --------------------- | ---------------------- | +| **November 2023** | **Yes** | **`1.35.0`** | #### Directive changes - - - - - - - - - - - - - - - -
TopicDescription
- ##### `@policy` - - Introduced. [Learn more.](/graphos/routing/security/authorization) -```graphql +```graphql showLineNumbers=false disableCopy=true directive @policy(policies: [[federation__Policy!]!]!) on | FIELD_DEFINITION | OBJECT @@ -309,14 +168,7 @@ directive @policy(policies: [[federation__Policy!]!]!) on | SCALAR | ENUM ``` - -
- -#### Subgraph changes +##### Subgraph changes @@ -346,56 +198,18 @@ Policy
- - -
- -First release
-**July 2023** - -
- -
- -Available in GraphOS?
-**Yes** - -
- -
- -Minimum router version
-**`1.29.1`** - -
- - - -
+| First release | Available in GraphOS? | Minimum router version | +| ------------- | --------------------- | ---------------------- | +| **July 2023** | **Yes** | **`1.29.1`** | #### Directive changes -
- - - - - - - - - - - - - - - - - - - -
TopicDescription
- ##### `@authenticated` - - Introduced. [Learn more.](/graphos/routing/security/authorization) -```graphql +```graphql showLineNumbers=false disableCopy=true directive @authenticated on FIELD_DEFINITION | OBJECT @@ -404,21 +218,12 @@ directive @authenticated on | ENUM ``` -
- ##### `@requiresScopes` - - Introduced. [Learn more.](/graphos/routing/security/authorization) -```graphql +```graphql showLineNumbers=false disableCopy=true directive @requiresScopes(scopes: [[federation__Scope!]!]!) on FIELD_DEFINITION | OBJECT @@ -427,12 +232,6 @@ directive @requiresScopes(scopes: [[federation__Scope!]!]!) on | ENUM ``` -
- #### Subgraph changes @@ -463,32 +262,9 @@ Scope
- - -
- -First release
-**March 2023** - -
- -
- -Available in GraphOS?
-**Yes** - -
- -
- -Minimum router version
-**`1.13.1`** - -
- - - -
+| First release | Available in GraphOS? | Minimum router version | +| ------------- | --------------------- | ---------------------- | +| **March 2023** | **Yes** | **`1.13.1`** | #### Subgraph changes @@ -521,216 +297,72 @@ Subscriptions
- - -
- -First release
-**February 2023**
- -
- -
- -Available in GraphOS?
-**Yes** - -
- -
- -Minimum router version
-**`1.10.2`** - -
- - - -
+| First release | Available in GraphOS? | Minimum router version | +| ------------- | --------------------- | ---------------------- | +| **February 2023**| **Yes** | **`1.10.2`** | #### Directive changes -
- - - - - - - - - - - - - - - - - - - -
TopicDescription
- ##### `@interfaceObject` - - Introduced. [Learn more.](/graphos/schema-design/federated-schemas/entities/interfaces) -```graphql +```graphql showLineNumbers=false disableCopy=true directive @interfaceObject on OBJECT ``` -
- ##### `@key` - - Can now be applied to interface definitions to support [entity interfaces](/graphos/schema-design/federated-schemas/entities/interfaces/). (Previous versions of composition threw an error if `@key` was applied to an interface definition.) -
- ## v2.2
- - -
- -First release

-**November 2022** - -
- -
- -Available in GraphOS?
-**No** - -
- -
- -Minimum router version
-**`1.6.0`** - -
- - - -
+| First release | Available in GraphOS? | Minimum router version | +| ------------- | --------------------- | ---------------------- | +| **November 2022** | **No**| **`1.6.0`** | #### Directive changes - - - - - - - - - - - - - - - -
TopicDescription
- ##### `@shareable` - - Added `repeatable` to the directive definition. -```graphql +```graphql showLineNumbers=false disableCopy=true directive @shareable repeatable on OBJECT | FIELD_DEFINITION ``` Additionally, composition now throws an error if `@shareable` is applied to fields of an `interface` definition. -
- ## v2.1
- - -
- -First release
-**August 2022** - -
- -
- -Available in GraphOS?
-**Yes** - -
- -
- -Minimum router version
-**`1.0.0`** - -
- - - -
+| First release | Available in GraphOS? | Minimum router version | +| ------------- | --------------------- | ---------------------- | +| **August 2022** | **Yes** | **`1.0.0`** | #### Directive changes - - - - - - - - - - - - - - - - - - - - -
TopicDescription
- ##### `@composeDirective` - - Introduced. [Learn more.](/graphos/reference/federation/directives#composedirective) -```graphql +```graphql showLineNumbers=false disableCopy=true directive @composeDirective(name: String!) repeatable on SCHEMA ``` -
- ##### `@requires` - - The `fields` argument can now include fields that themselves take arguments. [Learn more.](/graphos/schema-design/federated-schemas/entities/contribute-fields#using-requires-with-fields-that-take-arguments) (Functionality added in v2.1.2) -```graphql +```graphql showLineNumbers=false disableCopy=true type Product @key(fields: "id") { id: ID! weight(units: String): Int! @external @@ -740,48 +372,19 @@ type Product @key(fields: "id") { } ``` -
- ## v2.0
- - -
- -First release
-**April 2022** - -
- -
- -Available in GraphOS?
-**Yes** - -
- -
- -Minimum router version
-**`1.0.0`** - -
- - - -
+| First release | Available in GraphOS? | Minimum router version | +| ------------- | --------------------- | ---------------------- | +| **April 2022** | **Yes** | **`1.0.0`** | #### Directive changes Subgraph schemas "opt in" to Federation 2 features by applying the `@link` directive to the `schema` type, like so: -```graphql +```graphql showLineNumbers=false disableCopy=true extend schema @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@shareable"]) @@ -791,63 +394,30 @@ The `import` list of this definition must include each federation-specific direc For details on these directives as defined in Federation 2, see [Federation-specific GraphQL directives](/graphos/reference/federation/directives/). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TopicDescription
- ##### `@key` - - Added optional `resolvable` argument. -```graphql +```graphql showLineNumbers=false disableCopy=true directive @key( fields: FieldSet!, resolvable: Boolean = true # highlight-line ) repeatable on OBJECT | INTERFACE ``` -
- ##### `@shareable` - - Introduced. -```graphql +```graphql showLineNumbers=false disableCopy=true directive @shareable on OBJECT | FIELD_DEFINITION ``` -
- ##### `@inaccessible` - - Introduced. -```graphql +```graphql showLineNumbers=false disableCopy=true directive @inaccessible on | FIELD_DEFINITION | OBJECT @@ -861,37 +431,19 @@ directive @inaccessible on | INPUT_FIELD_DEFINITION ``` -
- ##### `@override` - - Introduced. -```graphql +```graphql showLineNumbers=false disableCopy=true directive @override(from: String!) on FIELD_DEFINITION ``` -
- ##### `@link` - - Introduced. -```graphql +```graphql showLineNumbers=false disableCopy=true directive @link( url: String, as: String, @@ -900,25 +452,10 @@ directive @link( ) repeatable on SCHEMA ``` -
- ##### `@extends`, `@external`, `@provides`, `@requires`, `@tag` - - No changes. -
- #### Subgraph changes @@ -978,7 +515,6 @@ Value types
- ## v1.1 @@ -989,26 +525,11 @@ Apollo Router Core and GraphOS Router v1.60 and later don't support Federation v #### Directive changes - - - - - - - - - - - - - - - -
TopicDescription
- ##### `@tag` - - Introduced. -```graphql +```graphql showLineNumbers=false disableCopy=true directive @tag(name: String!) repeatable on | FIELD_DEFINITION | INTERFACE @@ -1016,12 +537,6 @@ directive @tag(name: String!) repeatable on | UNION ``` -
- ## v1.0 @@ -1034,103 +549,46 @@ Apollo Router Core and GraphOS Router v1.60 and later don't support Federation v For details on these directives as defined in Federation 1, see the [Federation 1 subgraph spec](/federation/v1/federation-spec). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TopicDescription
- ##### `@key` - - Introduced. -```graphql +```graphql showLineNumbers=false disableCopy=true directive @key(fields: _FieldSet!) repeatable on OBJECT | INTERFACE ``` -
- ##### `@external` - - Introduced. -```graphql +```graphql showLineNumbers=false disableCopy=true directive @external on FIELD_DEFINITION ``` -
- ##### `@requires` - - Introduced. -```graphql +```graphql showLineNumbers=false disableCopy=true directive @requires(fields: _FieldSet!) on FIELD_DEFINITION ``` -
- ##### `@provides` - - Introduced. -```graphql +```graphql showLineNumbers=false disableCopy=true directive @provides(fields: _FieldSet!) on FIELD_DEFINITION ``` -
- ##### `@extends` - - Introduced. -```graphql +```graphql showLineNumbers=false disableCopy=true directive @extends on OBJECT | INTERFACE ``` -
- #### Subgraph changes