@apollo/federation-internals 2.6.2 → 2.7.0

package/src/error.ts

@@ -513,6 +513,12 @@ const OVERRIDE_ON_INTERFACE = makeCodeDefinition(
   { addedIn: '2.3.0' },
 );
 
+const OVERRIDE_LABEL_INVALID = makeCodeDefinition(
+  'OVERRIDE_LABEL_INVALID',
+  'The @override directive `label` argument must match the pattern /^[a-zA-Z][a-zA-Z0-9_\-:./]*$/ or /^percent\((\d{1,2}(\.\d{1,8})?|100)\)$/',
+  { addedIn: '2.7.0' },
+);
+
 const UNSUPPORTED_FEATURE = makeCodeDefinition(
   'UNSUPPORTED_FEATURE',
   'Indicates an error due to feature currently unsupported by federation.',
@@ -555,6 +561,112 @@ const INTERFACE_KEY_MISSING_IMPLEMENTATION_TYPE = makeCodeDefinition(
   { addedIn: '2.3.0' },
 )
 
+const SOURCE_API_NAME_INVALID = makeCodeDefinition(
+  'SOURCE_API_NAME_INVALID',
+  'Each `@sourceAPI` directive must take a unique and valid name as an argument',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_API_PROTOCOL_INVALID = makeCodeDefinition(
+  'SOURCE_API_PROTOCOL_INVALID',
+  'Each `@sourceAPI` directive must specify exactly one of the known protocols',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_API_HTTP_BASE_URL_INVALID = makeCodeDefinition(
+  'SOURCE_API_HTTP_BASE_URL_INVALID',
+  'The `@sourceAPI` directive must specify a valid http.baseURL',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_HTTP_HEADERS_INVALID = makeCodeDefinition(
+  'SOURCE_HTTP_HEADERS_INVALID',
+  'The `http.headers` argument of `@source*` directives must specify valid HTTP headers',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_TYPE_API_ERROR = makeCodeDefinition(
+  'SOURCE_TYPE_API_ERROR',
+  'The `api` argument of the `@sourceType` directive must match a valid `@sourceAPI` name',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_TYPE_PROTOCOL_INVALID = makeCodeDefinition(
+  'SOURCE_TYPE_PROTOCOL_INVALID',
+  'The `@sourceType` directive must specify the same protocol as its corresponding `@sourceAPI`',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_TYPE_HTTP_METHOD_INVALID = makeCodeDefinition(
+  'SOURCE_TYPE_HTTP_METHOD_INVALID',
+  'The `@sourceType` directive must specify exactly one of `http.GET` or `http.POST`',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_TYPE_HTTP_PATH_INVALID = makeCodeDefinition(
+  'SOURCE_TYPE_HTTP_PATH_INVALID',
+  'The `@sourceType` directive must specify a valid URL template for `http.GET` or `http.POST`',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_TYPE_HTTP_BODY_INVALID = makeCodeDefinition(
+  'SOURCE_TYPE_HTTP_BODY_INVALID',
+  'If the `@sourceType` specifies `http.body`, it must be a valid `JSONSelection`',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_TYPE_ON_NON_OBJECT_OR_NON_ENTITY = makeCodeDefinition(
+  'SOURCE_TYPE_ON_NON_OBJECT_OR_NON_ENTITY',
+  'The `@sourceType` directive must be applied to an object or interface type that also has `@key`',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_TYPE_SELECTION_INVALID = makeCodeDefinition(
+  'SOURCE_TYPE_SELECTION_INVALID',
+  'The `selection` argument of the `@sourceType` directive must be a valid `JSONSelection` that outputs fields of the GraphQL type',
+);
+
+const SOURCE_FIELD_API_ERROR = makeCodeDefinition(
+  'SOURCE_FIELD_API_ERROR',
+  'The `api` argument of the `@sourceField` directive must match a valid `@sourceAPI` name',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_FIELD_PROTOCOL_INVALID = makeCodeDefinition(
+  'SOURCE_FIELD_PROTOCOL_INVALID',
+  'If `@sourceField` specifies a protocol, it must match the corresponding `@sourceAPI` protocol',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_FIELD_HTTP_METHOD_INVALID = makeCodeDefinition(
+  'SOURCE_FIELD_HTTP_METHOD_INVALID',
+  'The `@sourceField` directive must specify at most one of `http.{GET,POST,PUT,PATCH,DELETE}`',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_FIELD_HTTP_PATH_INVALID = makeCodeDefinition(
+  'SOURCE_FIELD_HTTP_PATH_INVALID',
+  'The `@sourceField` directive must specify a valid URL template for `http.{GET,POST,PUT,PATCH,DELETE}`',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_FIELD_HTTP_BODY_INVALID = makeCodeDefinition(
+  'SOURCE_FIELD_HTTP_BODY_INVALID',
+  'If `@sourceField` specifies http.body, it must be a valid `JSONSelection` matching available arguments and fields',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_FIELD_SELECTION_INVALID = makeCodeDefinition(
+  'SOURCE_FIELD_SELECTION_INVALID',
+  'The `selection` argument of the `@sourceField` directive must be a valid `JSONSelection` that outputs fields of the GraphQL type',
+  { addedIn: '2.7.0' },
+);
+
+const SOURCE_FIELD_NOT_ON_ROOT_OR_ENTITY_FIELD = makeCodeDefinition(
+  'SOURCE_FIELD_NOT_ON_ROOT_OR_ENTITY_FIELD',
+  'The `@sourceField` directive must be applied to a field of the `Query` or `Mutation` types, or of an entity type',
+  { addedIn: '2.7.0' },
+);
 
 export const ERROR_CATEGORIES = {
   DIRECTIVE_FIELDS_MISSING_EXTERNAL,
@@ -633,6 +745,7 @@ export const ERRORS = {
   OVERRIDE_FROM_SELF_ERROR,
   OVERRIDE_SOURCE_HAS_OVERRIDE,
   OVERRIDE_ON_INTERFACE,
+  OVERRIDE_LABEL_INVALID,
   UNSUPPORTED_FEATURE,
   INVALID_FEDERATION_SUPERGRAPH,
   DOWNSTREAM_SERVICE_ERROR,
@@ -643,6 +756,25 @@ export const ERRORS = {
   INTERFACE_OBJECT_USAGE_ERROR,
   INTERFACE_KEY_NOT_ON_IMPLEMENTATION,
   INTERFACE_KEY_MISSING_IMPLEMENTATION_TYPE,
+  // Errors related to @sourceAPI, @sourceType, and/or @sourceField
+  SOURCE_API_NAME_INVALID,
+  SOURCE_API_PROTOCOL_INVALID,
+  SOURCE_API_HTTP_BASE_URL_INVALID,
+  SOURCE_HTTP_HEADERS_INVALID,
+  SOURCE_TYPE_API_ERROR,
+  SOURCE_TYPE_PROTOCOL_INVALID,
+  SOURCE_TYPE_HTTP_METHOD_INVALID,
+  SOURCE_TYPE_HTTP_PATH_INVALID,
+  SOURCE_TYPE_HTTP_BODY_INVALID,
+  SOURCE_TYPE_ON_NON_OBJECT_OR_NON_ENTITY,
+  SOURCE_TYPE_SELECTION_INVALID,
+  SOURCE_FIELD_API_ERROR,
+  SOURCE_FIELD_PROTOCOL_INVALID,
+  SOURCE_FIELD_HTTP_METHOD_INVALID,
+  SOURCE_FIELD_HTTP_PATH_INVALID,
+  SOURCE_FIELD_HTTP_BODY_INVALID,
+  SOURCE_FIELD_SELECTION_INVALID,
+  SOURCE_FIELD_NOT_ON_ROOT_OR_ENTITY_FIELD,
 };
 
 const codeDefByCode = Object.values(ERRORS).reduce((obj: {[code: string]: ErrorCodeDefinition}, codeDef: ErrorCodeDefinition) => { obj[codeDef.code] = codeDef; return obj; }, {});

package/src/extractSubgraphsFromSupergraph.ts

@@ -418,15 +418,15 @@ function extractObjOrItfContent(args: ExtractArguments, info: TypeInfo<ObjectTyp
           }).length > 1;
 
         for (const application of fieldApplications) {
-          const args = application.arguments();
+          const joinFieldArgs = application.arguments();
           // We use a @join__field with no graph to indicates when a field in the supergraph does not come
           // directly from any subgraph and there is thus nothing to do to "extract" it.
-          if (!args.graph) {
+          if (!joinFieldArgs.graph) {
             continue;
           }
 
-          const { type: subgraphType, subgraph } = subgraphsInfo.get(args.graph)!;
-          addSubgraphField({ field, type: subgraphType, subgraph, isShareable, joinFieldArgs: args});
+          const { type: subgraphType, subgraph } = subgraphsInfo.get(joinFieldArgs.graph)!;
+          addSubgraphField({ field, type: subgraphType, subgraph, isShareable, joinFieldArgs });
         }
       }
     }
@@ -615,11 +615,14 @@ function addSubgraphField({
     subgraphField.applyDirective(subgraph.metadata().externalDirective());
   }
   const usedOverridden = !!joinFieldArgs?.usedOverridden;
-  if (usedOverridden) {
+  if (usedOverridden && !joinFieldArgs?.overrideLabel) {
     subgraphField.applyDirective(subgraph.metadata().externalDirective(), {'reason': '[overridden]'});
   }
   if (joinFieldArgs?.override) {
-    subgraphField.applyDirective(subgraph.metadata().overrideDirective(), {'from': joinFieldArgs.override});
+    subgraphField.applyDirective(subgraph.metadata().overrideDirective(), {
+      from: joinFieldArgs.override,
+      ...(joinFieldArgs.overrideLabel ? { label: joinFieldArgs.overrideLabel } : {})
+    });
   }
   if (isShareable && !external && !usedOverridden) {
     subgraphField.applyDirective(subgraph.metadata().shareableDirective());

package/src/federation.ts

@@ -83,8 +83,13 @@ import {
 import { defaultPrintOptions, PrintOptions as PrintOptions, printSchema } from "./print";
 import { createObjectTypeSpecification, createScalarTypeSpecification, createUnionTypeSpecification } from "./directiveAndTypeSpecification";
 import { didYouMean, suggestionList } from "./suggestions";
-import { coreFeatureDefinitionIfKnown } from "./knownCoreFeatures";
+import { coreFeatureDefinitionIfKnown, validateKnownFeatures } from "./knownCoreFeatures";
 import { joinIdentity } from "./specs/joinSpec";
+import {
+  SourceAPIDirectiveArgs,
+  SourceFieldDirectiveArgs,
+  SourceTypeDirectiveArgs,
+} from "./specs/sourceSpec";
 
 const linkSpec = LINK_VERSIONS.latest();
 const tagSpec = TAG_VERSIONS.latest();
@@ -578,8 +583,7 @@ export class FederationMetadata {
   private _fieldUsedPredicate?: (field: FieldDefinition<CompositeType>) => boolean;
   private _isFed2Schema?: boolean;
 
-  constructor(readonly schema: Schema) {
-  }
+  constructor(readonly schema: Schema) {}
 
   private onInvalidate() {
     this._externalTester = undefined;
@@ -722,7 +726,7 @@ export class FederationMetadata {
     return this.getLegacyFederationDirective(FederationDirectiveName.KEY);
   }
 
-  overrideDirective(): DirectiveDefinition<{from: string}> {
+  overrideDirective(): DirectiveDefinition<{from: string, label?: string}> {
     return this.getLegacyFederationDirective(FederationDirectiveName.OVERRIDE);
   }
 
@@ -774,6 +778,18 @@ export class FederationMetadata {
     return this.getPost20FederationDirective(FederationDirectiveName.POLICY);
   }
 
+  sourceAPIDirective(): Post20FederationDirectiveDefinition<SourceAPIDirectiveArgs> {
+    return this.getPost20FederationDirective(FederationDirectiveName.SOURCE_API);
+  }
+
+  sourceTypeDirective(): Post20FederationDirectiveDefinition<SourceTypeDirectiveArgs> {
+    return this.getPost20FederationDirective(FederationDirectiveName.SOURCE_TYPE);
+  }
+
+  sourceFieldDirective(): Post20FederationDirectiveDefinition<SourceFieldDirectiveArgs> {
+    return this.getPost20FederationDirective(FederationDirectiveName.SOURCE_FIELD);
+  }
+
   allFederationDirectives(): DirectiveDefinition[] {
     const baseDirectives: DirectiveDefinition[] = [
       this.keyDirective(),
@@ -814,6 +830,19 @@ export class FederationMetadata {
       baseDirectives.push(policyDirective);
     }
 
+    const sourceAPIDirective = this.sourceAPIDirective();
+    if (isFederationDirectiveDefinedInSchema(sourceAPIDirective)) {
+      baseDirectives.push(sourceAPIDirective);
+    }
+    const sourceTypeDirective = this.sourceTypeDirective();
+    if (isFederationDirectiveDefinedInSchema(sourceTypeDirective)) {
+      baseDirectives.push(sourceTypeDirective);
+    }
+    const sourceFieldDirective = this.sourceFieldDirective();
+    if (isFederationDirectiveDefinedInSchema(sourceFieldDirective)) {
+      baseDirectives.push(sourceFieldDirective);
+    }
+
     return baseDirectives;
   }
 
@@ -1051,6 +1080,11 @@ export class FederationBlueprint extends SchemaBlueprint {
     validateKeyOnInterfacesAreAlsoOnAllImplementations(metadata, errorCollector);
     validateInterfaceObjectsAreOnEntities(metadata, errorCollector);
 
+    // FeatureDefinition objects passed to registerKnownFeature can register
+    // validation functions for subgraph schemas by overriding the
+    // validateSubgraphSchema method.
+    validateKnownFeatures(schema, errorCollector);
+
     // If tag is redefined by the user, make sure the definition is compatible with what we expect
     const tagDirective = metadata.tagDirective();
     if (tagDirective) {
@@ -1191,9 +1225,9 @@ export function setSchemaAsFed2Subgraph(schema: Schema) {
 
 // This is the full @link declaration as added by `asFed2SubgraphDocument`. It's here primarily for uses by tests that print and match
 // subgraph schema to avoid having to update 20+ tests every time we use a new directive or the order of import changes ...
-export const FEDERATION2_LINK_WITH_FULL_IMPORTS = '@link(url: "https://specs.apollo.dev/federation/v2.6", import: ["@key", "@requires", "@provides", "@external", "@tag", "@extends", "@shareable", "@inaccessible", "@override", "@composeDirective", "@interfaceObject", "@authenticated", "@requiresScopes", "@policy"])';
+export const FEDERATION2_LINK_WITH_FULL_IMPORTS = '@link(url: "https://specs.apollo.dev/federation/v2.7", import: ["@key", "@requires", "@provides", "@external", "@tag", "@extends", "@shareable", "@inaccessible", "@override", "@composeDirective", "@interfaceObject", "@authenticated", "@requiresScopes", "@policy", "@sourceAPI", "@sourceType", "@sourceField"])';
 // This is the full @link declaration that is added when upgrading fed v1 subgraphs to v2 version. It should only be used by tests.
-export const FEDERATION2_LINK_WITH_AUTO_EXPANDED_IMPORTS = '@link(url: "https://specs.apollo.dev/federation/v2.6", import: ["@key", "@requires", "@provides", "@external", "@tag", "@extends", "@shareable", "@inaccessible", "@override", "@composeDirective", "@interfaceObject"])';
+export const FEDERATION2_LINK_WITH_AUTO_EXPANDED_IMPORTS = '@link(url: "https://specs.apollo.dev/federation/v2.7", import: ["@key", "@requires", "@provides", "@external", "@tag", "@extends", "@shareable", "@inaccessible", "@override", "@composeDirective", "@interfaceObject"])';
 
 /**
  * Given a document that is assumed to _not_ be a fed2 schema (it does not have a `@link` to the federation spec),
@@ -1439,7 +1473,7 @@ function completeFed2SubgraphSchema(schema: Schema): GraphQLError[] {
   const spec = FEDERATION_VERSIONS.find(fedFeature.url.version);
   if (!spec) {
     return [ERRORS.UNKNOWN_FEDERATION_LINK_VERSION.err(
-      `Invalid version ${fedFeature.url.version} for the federation feature in @link direction on schema`,
+      `Invalid version ${fedFeature.url.version} for the federation feature in @link directive on schema`,
       { nodes: fedFeature.directive.sourceAST },
     )];
   }
@@ -1561,7 +1595,7 @@ export function collectTargetFields({
       validate,
     });
   } catch (e) {
-    // If we explicitely requested no validation, then we shouldn't throw a (graphQL) error, but if we do, we swallow it
+    // If we explicitly requested no validation, then we shouldn't throw a (graphQL) error, but if we do, we swallow it
     // (returning a partial result, but we assume it is fine).
     const isGraphQLError = errorCauses(e) !== undefined
     if (!isGraphQLError || validate) {

package/src/index.ts

@@ -23,3 +23,4 @@ export * from './argumentCompositionStrategies';
 export * from './specs/authenticatedSpec';
 export * from './specs/requiresScopesSpec';
 export * from './specs/policySpec';
+export * from './specs/sourceSpec';

package/src/knownCoreFeatures.ts

@@ -1,6 +1,8 @@
+import { GraphQLError } from "graphql";
+import { Schema } from "./definitions";
 import { FeatureDefinition, FeatureDefinitions, FeatureUrl } from "./specs/coreSpec";
 
-const registeredFeatures: Map<string, FeatureDefinitions> = new Map();
+const registeredFeatures = new Map<string, FeatureDefinitions>();
 
 export function registerKnownFeature(definitions: FeatureDefinitions) {
   if (!registeredFeatures.has(definitions.identity)) {
@@ -12,6 +14,19 @@ export function coreFeatureDefinitionIfKnown(url: FeatureUrl): FeatureDefinition
   return registeredFeatures.get(url.identity)?.find(url.version);
 }
 
+export function validateKnownFeatures(
+  schema: Schema,
+  errorCollector: GraphQLError[] = [],
+): GraphQLError[] {
+  registeredFeatures.forEach(definitions => {
+    const feature = definitions.latest();
+    if (feature.validateSubgraphSchema !== FeatureDefinition.prototype.validateSubgraphSchema) {
+      errorCollector.push(...feature.validateSubgraphSchema(schema));
+    }
+  });
+  return errorCollector;
+}
+
 /**
  * Removes a feature from the set of known features.
  *

package/src/specs/coreSpec.ts

@@ -117,6 +117,11 @@ export abstract class FeatureDefinition {
       .concat(this.typeSpecs().map((spec) => spec.name));
   }
 
+  // No-op implementation that can be overridden by subclasses.
+  validateSubgraphSchema(_schema: Schema): GraphQLError[] {
+    return [];
+  }
+
   protected nameInSchema(schema: Schema): string | undefined {
     const feature = this.featureInSchema(schema);
     return feature?.nameInSchema;
@@ -750,7 +755,14 @@ export class FeatureUrl {
     public readonly element?: string,
   ) { }
 
-  /// Parse a spec URL or throw
+  public static maybeParse(input: string, node?: ASTNode): FeatureUrl | undefined {
+    try {
+      return FeatureUrl.parse(input, node);
+    } catch (err) {
+      return undefined;
+    }
+  }
+    /// Parse a spec URL or throw
   public static parse(input: string, node?: ASTNode): FeatureUrl {
     const url = new URL(input)
     if (!url.pathname || url.pathname === '/') {

package/src/specs/federationSpec.ts

@@ -18,6 +18,7 @@ import { INACCESSIBLE_VERSIONS } from "./inaccessibleSpec";
 import { AUTHENTICATED_VERSIONS } from "./authenticatedSpec";
 import { REQUIRES_SCOPES_VERSIONS } from "./requiresScopesSpec";
 import { POLICY_VERSIONS } from './policySpec';
+import { SOURCE_VERSIONS } from './sourceSpec';
 
 export const federationIdentity = 'https://specs.apollo.dev/federation';
 
@@ -40,6 +41,9 @@ export enum FederationDirectiveName {
   AUTHENTICATED = 'authenticated',
   REQUIRES_SCOPES = 'requiresScopes',
   POLICY = 'policy',
+  SOURCE_API = 'sourceAPI',
+  SOURCE_TYPE = 'sourceType',
+  SOURCE_FIELD = 'sourceField',
 }
 
 const fieldSetTypeSpec = createScalarTypeSpecification({ name: FederationTypeName.FIELD_SET });
@@ -124,11 +128,22 @@ export class FederationSpecDefinition extends FeatureDefinition {
 
     this.registerSubFeature(INACCESSIBLE_VERSIONS.getMinimumRequiredVersion(version));
 
-    this.registerDirective(createDirectiveSpecification({
-      name: FederationDirectiveName.OVERRIDE,
-      locations: [DirectiveLocation.FIELD_DEFINITION],
-      args: [{ name: 'from', type: (schema) => new NonNullType(schema.stringType()) }],
-    }));
+    if (version >= (new FeatureVersion(2, 7))) {
+      this.registerDirective(createDirectiveSpecification({
+        name: FederationDirectiveName.OVERRIDE,
+        locations: [DirectiveLocation.FIELD_DEFINITION],
+        args: [
+          { name: 'from', type: (schema) => new NonNullType(schema.stringType()) },
+          { name: 'label', type: (schema) => schema.stringType() },
+        ],
+      }));
+    } else {
+      this.registerDirective(createDirectiveSpecification({
+        name: FederationDirectiveName.OVERRIDE,
+        locations: [DirectiveLocation.FIELD_DEFINITION],
+        args: [{ name: 'from', type: (schema) => new NonNullType(schema.stringType()) }],
+      }));
+    }
 
     if (version.gte(new FeatureVersion(2, 1))) {
       this.registerDirective(createDirectiveSpecification({
@@ -155,6 +170,10 @@ export class FederationSpecDefinition extends FeatureDefinition {
     if (version.gte(new FeatureVersion(2, 6))) {
       this.registerSubFeature(POLICY_VERSIONS.find(new FeatureVersion(0, 1))!);
     }
+
+    if (version.gte(new FeatureVersion(2, 7))) {
+      this.registerSubFeature(SOURCE_VERSIONS.find(new FeatureVersion(0, 1))!);
+    }
   }
 }
 
@@ -165,6 +184,7 @@ export const FEDERATION_VERSIONS = new FeatureDefinitions<FederationSpecDefiniti
   .add(new FederationSpecDefinition(new FeatureVersion(2, 3)))
   .add(new FederationSpecDefinition(new FeatureVersion(2, 4)))
   .add(new FederationSpecDefinition(new FeatureVersion(2, 5)))
-  .add(new FederationSpecDefinition(new FeatureVersion(2, 6)));
+  .add(new FederationSpecDefinition(new FeatureVersion(2, 6)))
+  .add(new FederationSpecDefinition(new FeatureVersion(2, 7)));
 
 registerKnownFeature(FEDERATION_VERSIONS);

package/src/specs/joinSpec.ts

@@ -6,6 +6,7 @@ import {
   ScalarType,
   Schema,
   NonNullType,
+  ListType,
 } from "../definitions";
 import { Subgraph, Subgraphs } from "../federation";
 import { registerKnownFeature } from '../knownCoreFeatures';
@@ -46,8 +47,15 @@ export type JoinFieldDirectiveArguments = {
   type?: string,
   external?: boolean,
   usedOverridden?: boolean,
+  overrideLabel?: string,
 }
 
+export type JoinDirectiveArguments = {
+  graphs: string[],
+  name: string,
+  args?: Record<string, any>,
+};
+
 export class JoinSpecDefinition extends FeatureDefinition {
   constructor(version: FeatureVersion, minimumFederationVersion?: FeatureVersion) {
     super(new FeatureUrl(joinIdentity, 'join', version), minimumFederationVersion);
@@ -126,6 +134,27 @@ export class JoinSpecDefinition extends FeatureDefinition {
       joinEnumValue.addArgument('graph', new NonNullType(graphEnum));
     }
 
+    if (this.version.gte(new FeatureVersion(0, 4))) {
+      const joinDirective = this.addDirective(schema, 'directive').addLocations(
+        DirectiveLocation.SCHEMA,
+        DirectiveLocation.OBJECT,
+        DirectiveLocation.INTERFACE,
+        DirectiveLocation.FIELD_DEFINITION,
+      );
+      joinDirective.repeatable = true;
+      // Note this 'graphs' argument is plural, since the same directive
+      // application can appear on the same schema element in multiple subgraphs.
+      // Repetition of a graph in this 'graphs' list is allowed, and corresponds
+      // to repeated application of the same directive in the same subgraph, which
+      // is allowed.
+      joinDirective.addArgument('graphs', new ListType(new NonNullType(graphEnum)));
+      joinDirective.addArgument('name', new NonNullType(schema.stringType()));
+      joinDirective.addArgument('args', this.addScalarType(schema, 'DirectiveArguments'));
+
+      //progressive override
+      joinField.addArgument('overrideLabel', schema.stringType());
+    }
+
     if (this.isV01()) {
       const joinOwner = this.addDirective(schema, 'owner').addLocations(DirectiveLocation.OBJECT);
       joinOwner.addArgument('graph', new NonNullType(graphEnum));
@@ -192,6 +221,10 @@ export class JoinSpecDefinition extends FeatureDefinition {
     return this.directive(schema, 'graph')!;
   }
 
+  directiveDirective(schema: Schema): DirectiveDefinition<JoinDirectiveArguments> {
+    return this.directive(schema, 'directive')!;
+  }
+
   typeDirective(schema: Schema): DirectiveDefinition<JoinTypeDirectiveArguments> {
     return this.directive(schema, 'type')!;
   }
@@ -227,9 +260,11 @@ export class JoinSpecDefinition extends FeatureDefinition {
 //    for federation 2 in general.
 //  - 0.2: this is the original version released with federation 2.
 //  - 0.3: adds the `isInterfaceObject` argument to `@join__type`, and make the `graph` in `@join__field` skippable.
+//  - 0.4: adds the optional `overrideLabel` argument to `@join_field` for progressive override.
 export const JOIN_VERSIONS = new FeatureDefinitions<JoinSpecDefinition>(joinIdentity)
   .add(new JoinSpecDefinition(new FeatureVersion(0, 1)))
   .add(new JoinSpecDefinition(new FeatureVersion(0, 2)))
-  .add(new JoinSpecDefinition(new FeatureVersion(0, 3), new FeatureVersion(2, 0)));
+  .add(new JoinSpecDefinition(new FeatureVersion(0, 3), new FeatureVersion(2, 0)))
+  .add(new JoinSpecDefinition(new FeatureVersion(0, 4), new FeatureVersion(2, 7)));
 
 registerKnownFeature(JOIN_VERSIONS);