BREAKING(feat(federation)): full @link support

[dariuszkuc]

📝 Description

Introduce full @link support that includes namespacing and renaming of the imported elements.

The @link directive allows users to link definitions within the document to external schemas. It is the core feature of the Apollo federation v2. While imported elements still need to have their definitions in the local schema, @link allows users to namespace and/or rename those items to avoid any local type conflicts. By default, all external types that are not explicitly imported have to be namespaced using the spec name or a provided custom namespace.

Updated @link definition

directive @link(url: String!, as: String, import: [link__Import]) repeatable on SCHEMA

scalar link__Import

• url - external specification url
• as - optional custom namespace
• import - list of elements to import, can either be simple Strings (e.g. @key) or custom imports that rename elements (e.g. { name: "@key", as: "@myKey" })

By default, graphql-kotlin will continue to apply @link directive using latest supported federation specification but will only auto-import federation specific directives up to version 2.3 and only if they are present (i.e. applied to an element) in the schema. All new fed v2.4+ won't be included in the auto-imports and instead will be namespaced with the spec name, e.g. @federation__authenticated.

Users can provide custom @link information by providing a schema object with @LinkDirective information, e.g.

@LinkDirective(url = "https://specs.apollo.dev/federation/v2.3", `as`: "fed", import = [LinkImport(name = "@key", `as` = "@myKey"), LinkImport(name = "@requires")])
class MyCustomLinkSchema

Will generate following schema

schema @link(as: "fed", import : [{name : "@key", as : "@myKey"}, "@requires"], url : "https://specs.apollo.dev/federation/v2.3"){
  query: Query
}

// directive imported with custom name
"Space separated list of primary keys needed to access federated object"
directive @myKey(fields: fed__FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE

// directive imported with same name
"Specifies required input field set from the base type for a resolver"
directive @requires(fields: fed__FieldSet!) on FIELD_DEFINITION

// type imported with custom namespace
"Federation type representing set of fields"
scalar fed__FieldSet

When importing custom specifications, in order to be able to identify whether element is part of custom specification, we need to annotate it with new @LinkedSpec annotation. All federation directives were updated to rely on this mechanism, e.g.

@LinkedSpec(FEDERATION_SPEC)
@Repeatable
@GraphQLDirective(
    name = KEY_DIRECTIVE_NAME,
    description = KEY_DIRECTIVE_DESCRIPTION,
    locations = [DirectiveLocation.OBJECT, DirectiveLocation.INTERFACE]
)
annotation class KeyDirective(val fields: FieldSet, val resolvable: Boolean = true)

🔗 Related Issues