@apollo/federation-internals 2.0.0-preview.5 → 2.0.0-preview.9

package/src/coreSpec.ts

@@ -1,10 +1,14 @@
 import { ASTNode, DirectiveLocation, GraphQLError, StringValueNode } from "graphql";
 import { URL } from "url";
-import { CoreFeature, Directive, DirectiveDefinition, EnumType, ListType, NamedType, NonNullType, ScalarType, Schema, SchemaDefinition } from "./definitions";
+import { CoreFeature, Directive, DirectiveDefinition, EnumType, ErrGraphQLValidationFailed, InputType, ListType, NamedType, NonNullType, ScalarType, Schema, SchemaDefinition } from "./definitions";
 import { sameType } from "./types";
 import { err } from '@apollo/core-schema';
 import { assert } from './utils';
 import { ERRORS } from "./error";
+import { valueToString } from "./values";
+import { coreFeatureDefinitionIfKnown, registerKnownFeature } from "./knownCoreFeatures";
+import { didYouMean, suggestionList } from "./suggestions";
+import { ArgumentSpecification, createDirectiveSpecification, createEnumTypeSpecification, createScalarTypeSpecification, DirectiveSpecification, TypeSpecification } from "./directiveAndTypeSpecification";
 
 export const coreIdentity = 'https://specs.apollo.dev/core';
 export const linkIdentity = 'https://specs.apollo.dev/link';
@@ -61,7 +65,9 @@ export abstract class FeatureDefinition {
     return nameInSchema != undefined && (directive.name === nameInSchema || directive.name.startsWith(`${nameInSchema}__`));
   }
 
-  abstract addElementsToSchema(schema: Schema): void;
+  abstract addElementsToSchema(schema: Schema): GraphQLError[];
+
+  abstract allElementNames(): string[];
 
   protected nameInSchema(schema: Schema): string | undefined {
     const feature = this.featureInSchema(schema);
@@ -73,9 +79,9 @@ export abstract class FeatureDefinition {
     return feature ? feature.directiveNameInSchema(directiveName) : undefined;
   }
 
-  protected typeNameInSchema(schema: Schema, directiveName: string): string | undefined {
+  protected typeNameInSchema(schema: Schema, typeName: string): string | undefined {
     const feature = this.featureInSchema(schema);
-    return feature ? feature.typeNameInSchema(directiveName) : undefined;
+    return feature ? feature.typeNameInSchema(typeName) : undefined;
   }
 
   protected rootDirective<TApplicationArgs extends {[key: string]: any}>(schema: Schema): DirectiveDefinition<TApplicationArgs> | undefined {
@@ -101,6 +107,14 @@ export abstract class FeatureDefinition {
     return schema.addDirectiveDefinition(this.directiveNameInSchema(schema, name)!);
   }
 
+  protected addDirectiveSpec(schema: Schema, spec: DirectiveSpecification): GraphQLError[] {
+    return spec.checkOrAdd(schema, this.directiveNameInSchema(schema, spec.name));
+  }
+
+  protected addTypeSpec(schema: Schema, spec: TypeSpecification): GraphQLError[] {
+    return spec.checkOrAdd(schema, this.typeNameInSchema(schema, spec.name));
+  }
+
   protected addScalarType(schema: Schema, name: string): ScalarType {
     return schema.addType(new ScalarType(this.typeNameInSchema(schema, name)!));
   }
@@ -144,33 +158,115 @@ export type CoreImport = {
   as?: string,
 };
 
-export function extractCoreFeatureImports(directive: Directive<SchemaDefinition, CoreOrLinkDirectiveArgs>): CoreImport[] {
+export function extractCoreFeatureImports(url: FeatureUrl, directive: Directive<SchemaDefinition, CoreOrLinkDirectiveArgs>): CoreImport[] {
+  // Note: up to this point, we've kind of cheated with typing and force-casted the arguments to `CoreOrLinkDirectiveArgs`, and while this
+  // graphQL type validations ensure this is "mostly" true, the `import' arg is an exception becuse it uses the `link__Import` scalar,
+  // and so there is no fine-grained graphQL-side validation of the values. So we'll need to double-check that the values are indeed
+  // either a string or a valid `CoreImport` value.
   const args = directive.arguments();
-  if (!('import' in args)) {
+  if (!('import' in args) || !args.import) {
     return [];
   }
-  const importArg = args.import;
-  const imports: CoreImport[] = importArg ? importArg.map((a) => typeof a === 'string' ? { name: a } : a) : [];
-  for (const i of imports) {
-    if (!i.as) {
+  const importArgValue = args.import;
+  const definition = coreFeatureDefinitionIfKnown(url);
+  const knownElements = definition?.allElementNames();
+  const errors: GraphQLError[] = [];
+  const imports: CoreImport[] = [];
+
+  importArgLoop:
+  for (const elt of importArgValue) {
+    if (typeof elt === 'string') {
+      imports.push({ name: elt });
+      validateImportedName(elt, knownElements, errors, directive);
       continue;
     }
-    if (i.name.charAt(0) === '@' && i.as.charAt(0) !== '@') {
-      throw ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
-        message: `Invalid @link import renaming: directive ${i.name} imported name should starts with a '@' character, but got "${i.as}"`,
+    if (typeof elt !== 'object') {
+      errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+        message: `Invalid sub-value ${valueToString(elt)} for @link(import:) argument: values should be either strings or input object values of the form { name: "<importedElement>", as: "<alias>" }.`,
         nodes: directive.sourceAST
-      });
+      }));
+      continue;
+    }
+    let name: string | undefined;
+    for (const [key, value] of Object.entries(elt)) {
+      switch (key) {
+        case 'name':
+          if (typeof value !== 'string') {
+            errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+              message: `Invalid value for the "name" field for sub-value ${valueToString(elt)} of @link(import:) argument: must be a string.`,
+              nodes: directive.sourceAST
+            }));
+            continue importArgLoop;
+          }
+          name = value;
+          break;
+        case 'as':
+          if (typeof value !== 'string') {
+            errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+              message: `Invalid value for the "as" field for sub-value ${valueToString(elt)} of @link(import:) argument: must be a string.`,
+              nodes: directive.sourceAST
+            }));
+            continue importArgLoop;
+          }
+          break;
+        default:
+          errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+            message: `Unknown field "${key}" for sub-value ${valueToString(elt)} of @link(import:) argument.`,
+            nodes: directive.sourceAST
+          }));
+          continue importArgLoop;
+      }
     }
-    if (i.name.charAt(0) !== '@' && i.as.charAt(0) === '@') {
-      throw ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
-        message: `Invalid @link import renaming: type ${i.name} imported name should not starts with a '@' character, but got "${i.as}" (or, if @${i.name} is a directive, then it should be refered to with a '@')`,
+    if (name) {
+      const i = elt as CoreImport;
+      imports.push(i);
+      if (i.as) {
+        if (i.name.charAt(0) === '@' && i.as.charAt(0) !== '@') {
+          errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+            message: `Invalid @link import renaming: directive "${i.name}" imported name should start with a '@' character, but got "${i.as}".`,
+            nodes: directive.sourceAST
+          }));
+        }
+        else if (i.name.charAt(0) !== '@' && i.as.charAt(0) === '@') {
+          errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+            message: `Invalid @link import renaming: type "${i.name}" imported name should not start with a '@' character, but got "${i.as}" (or, if @${i.name} is a directive, then it should be referred to with a '@').`,
+            nodes: directive.sourceAST
+          }));
+        }
+      }
+      validateImportedName(name, knownElements, errors, directive);
+    } else {
+      errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+        message: `Invalid sub-value ${valueToString(elt)} for @link(import:) argument: missing mandatory "name" field.`,
         nodes: directive.sourceAST
-      });
+      }));
     }
   }
+
+  if (errors.length > 0) {
+    throw ErrGraphQLValidationFailed(errors);
+  }
   return imports;
 }
 
+function validateImportedName(name: string, knownElements: string[] | undefined, errors: GraphQLError[], directive: Directive<SchemaDefinition>) {
+  if (knownElements && !knownElements.includes(name)) {
+    let details = '';
+    if (!name.startsWith('@') && knownElements.includes('@' + name)) {
+      details = ` Did you mean directive "@${name}"?`;
+    } else {
+      const suggestions = suggestionList(name, knownElements);
+      if (suggestions) {
+        details = didYouMean(suggestions);
+      }
+    }
+    errors.push(ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+      message: `Cannot import unknown element "${name}".${details}`,
+      nodes: directive.sourceAST
+    }));
+  }
+}
+
 export function isCoreSpecDirectiveApplication(directive: Directive<SchemaDefinition, any>): directive is Directive<SchemaDefinition, CoreOrLinkDirectiveArgs> {
   const definition = directive.definition;
   if (!definition) {
@@ -184,7 +280,7 @@ export function isCoreSpecDirectiveApplication(directive: Directive<SchemaDefini
     return false;
   }
   const urlArg = definition.argument('url') ?? definition.argument('feature');
-  if (!urlArg || !sameType(urlArg.type!, new NonNullType(directive.schema().stringType()))) {
+  if (!urlArg || !isValidUrlArgumentType(urlArg.type!, directive.schema())) {
     return false;
   }
 
@@ -201,53 +297,112 @@ export function isCoreSpecDirectiveApplication(directive: Directive<SchemaDefini
   }
 }
 
+function isValidUrlArgumentType(type: InputType, schema: Schema): boolean {
+  // Note that the 'url' arg is defined as nullable (mostly for future proofing reasons) but we allow use to provide a definition
+  // where it's non-nullable (and in practice, @core (which we never generate anymore, but recognize) definition technically uses
+  // with a non-nullable argument, and some fed2 previews did if for @link, so this ensure we handle reading schema generated
+  // by those versions just fine).
+  return sameType(type, schema.stringType())
+    || sameType(type, new NonNullType(schema.stringType()));
+}
+
+const linkPurposeTypeSpec = createEnumTypeSpecification({
+  name: 'Purpose',
+  values: corePurposes.map((name) => ({ name, description: purposesDescription(name)}))
+});
+
+const linkImportTypeSpec = createScalarTypeSpecification({ name: 'Import' });
+
 export class CoreSpecDefinition extends FeatureDefinition {
+  private readonly directiveDefinitionSpec: DirectiveSpecification;
+
   constructor(version: FeatureVersion, identity: string = linkIdentity, name: string = linkDirectiveDefaultName) {
     super(new FeatureUrl(identity, name, version));
+    this.directiveDefinitionSpec = createDirectiveSpecification({
+      name,
+      locations: [DirectiveLocation.SCHEMA],
+      repeatable: true,
+      argumentFct: (schema, nameInSchema) => this.createDefinitionArgumentSpecifications(schema, nameInSchema),
+    });
+  }
+
+  private createDefinitionArgumentSpecifications(schema: Schema, nameInSchema?: string): { args: ArgumentSpecification[], errors: GraphQLError[] } {
+    const args: ArgumentSpecification[] = [
+      { name: this.urlArgName(), type: schema.stringType() },
+      { name: 'as', type: schema.stringType() },
+    ];
+    if (this.supportPurposes()) {
+      const purposeName = `${nameInSchema ?? this.url.name}__${linkPurposeTypeSpec.name}`;
+      const errors = linkPurposeTypeSpec.checkOrAdd(schema, purposeName);
+      if (errors.length > 0) {
+        return { args, errors }
+      }
+      args.push({ name: 'for', type: schema.type(purposeName) as InputType });
+    }
+    if (this.supportImport()) {
+      const importName = `${nameInSchema ?? this.url.name}__${linkImportTypeSpec.name}`;
+      const errors = linkImportTypeSpec.checkOrAdd(schema, importName);
+      if (errors.length > 0) {
+        return { args, errors }
+      }
+      args.push({ name: 'import', type: new ListType(schema.type(importName)!) });
+    }
+    return { args, errors: [] };
   }
 
-  addElementsToSchema(_: Schema): void {
+  addElementsToSchema(_: Schema): GraphQLError[] {
     // Core is special and the @core directive is added in `addToSchema` below
+    return [];
+  }
+
+  // TODO: we may want to allow some `import` as argument to this method. When we do, we need to watch for imports of
+  // `Purpose` and `Import` and add the types under their imported name.
+  addToSchema(schema: Schema, as?: string): GraphQLError[] {
+    const errors = this.addDefinitionsToSchema(schema, as);
+    if (errors.length > 0) {
+      return errors;
+    }
+
+    // Note: we don't use `applyFeatureToSchema` because it would complain the schema is not a core schema, which it isn't
+    // until the next line.
+    const args = { [this.urlArgName()]: this.toString() } as unknown as CoreOrLinkDirectiveArgs;
+    if (as) {
+      args.as = as;
+    }
+    schema.schemaDefinition.applyDirective(as ?? this.url.name, args, true);
+    return [];
   }
 
-  addToSchema(schema: Schema, as?: string) {
-    const existing = schema.coreFeatures;
-    if (existing) {
-      if (existing.coreItself.url.identity === this.identity) {
+  addDefinitionsToSchema(schema: Schema, as?: string): GraphQLError[] {
+    const existingCore = schema.coreFeatures;
+    if (existingCore) {
+      if (existingCore.coreItself.url.identity === this.identity) {
         // Already exists with the same version, let it be.
-        return;
+        return [];
       } else {
-        throw buildError(`Cannot add feature ${this} to the schema, it already uses ${existing.coreItself.url}`);
+        return [ERRORS.INVALID_LINK_DIRECTIVE_USAGE.err({
+          message: `Cannot add feature ${this} to the schema, it already uses ${existingCore.coreItself.url}`
+        })];
       }
     }
 
     const nameInSchema = as ?? this.url.name;
-    const core = schema.addDirectiveDefinition(nameInSchema).addLocations(DirectiveLocation.SCHEMA);
-    core.repeatable = true;
-    core.addArgument(this.urlArgName(), new NonNullType(schema.stringType()));
-    core.addArgument('as', schema.stringType());
+    return this.directiveDefinitionSpec.checkOrAdd(schema, nameInSchema);
+  }
+
+  /**
+   * The list of all the element names that can be "imported" from this feature. Importantly, directive names
+   * must start with a `@`.
+   */
+  allElementNames(): string[] {
+    const names = [ `@${this.url.name}` ];
     if (this.supportPurposes()) {
-      const purposeEnum = schema.addType(new EnumType(`${nameInSchema}__Purpose`));
-      for (const purpose of corePurposes) {
-        purposeEnum.addValue(purpose).description = purposesDescription(purpose);
-      }
-      core.addArgument('for', purposeEnum);
+      names.push('Purpose');
     }
     if (this.supportImport()) {
-      if (schema.type(`${nameInSchema}__Import`)) {
-        console.trace();
-      }
-      const importType = schema.addType(new ScalarType(`${nameInSchema}__Import`));
-      core.addArgument('import', new ListType(importType));
+      names.push('Import');
     }
-
-    // Note: we don't use `applyFeatureToSchema` because it would complain the schema is not a core schema, which it isn't
-    // until the next line.
-    const args = { [this.urlArgName()]: this.toString() } as unknown as CoreOrLinkDirectiveArgs;
-    if (as) {
-      args.as = as;
-    }
-    schema.schemaDefinition.applyDirective(nameInSchema, args);
+    return names;
   }
 
   private supportPurposes() {
@@ -280,7 +435,7 @@ export class CoreSpecDefinition extends FeatureDefinition {
     return feature.url.version;
   }
 
-  applyFeatureToSchema(schema: Schema, feature: FeatureDefinition, as?: string, purpose?: CorePurpose) {
+  applyFeatureToSchema(schema: Schema, feature: FeatureDefinition, as?: string, purpose?: CorePurpose): GraphQLError[] {
     const coreDirective = this.coreDirective(schema);
     const args = {
       [this.urlArgName()]: feature.toString(),
@@ -290,7 +445,7 @@ export class CoreSpecDefinition extends FeatureDefinition {
       args.for = purpose;
     }
     schema.schemaDefinition.applyDirective(coreDirective, args);
-    feature.addElementsToSchema(schema);
+    return feature.addElementsToSchema(schema);
   }
 
   extractFeatureUrl(args: CoreOrLinkDirectiveArgs): FeatureUrl {
@@ -548,6 +703,9 @@ export const CORE_VERSIONS = new FeatureDefinitions<CoreSpecDefinition>(coreIden
 export const LINK_VERSIONS = new FeatureDefinitions<CoreSpecDefinition>(linkIdentity)
   .add(new CoreSpecDefinition(new FeatureVersion(1, 0)));
 
+registerKnownFeature(CORE_VERSIONS);
+registerKnownFeature(LINK_VERSIONS);
+
 export function removeFeatureElements(schema: Schema, feature: CoreFeature) {
   // Removing directives first, so that when we remove types, the checks that there is no references don't fail due a directive of a the feature
   // actually using the type.

package/src/definitions.ts

@@ -39,12 +39,15 @@ import { SDLValidationRule } from "graphql/validation/ValidationContext";
 import { specifiedSDLRules } from "graphql/validation/specifiedRules";
 import { validateSchema } from "./validate";
 import { createDirectiveSpecification, createScalarTypeSpecification, DirectiveSpecification, TypeSpecification } from "./directiveAndTypeSpecification";
+import { didYouMean, suggestionList } from "./suggestions";
+import { withModifiedErrorMessage } from "./error";
 
 const validationErrorCode = 'GraphQLValidationFailed';
+const DEFAULT_VALIDATION_ERROR_MESSAGE = 'The schema is not a valid GraphQL schema.';
 
-export const ErrGraphQLValidationFailed = (causes: GraphQLError[]) =>
+export const ErrGraphQLValidationFailed = (causes: GraphQLError[], message: string = DEFAULT_VALIDATION_ERROR_MESSAGE) =>
   err(validationErrorCode, {
-    message: 'The schema is not a valid GraphQL schema',
+    message,
     causes
   });
 
@@ -381,7 +384,7 @@ export class DirectiveTargetElement<T extends DirectiveTargetElement<T>> {
 }
 
 export function sourceASTs(...elts: ({ sourceAST?: ASTNode } | undefined)[]): ASTNode[] {
-  return elts.map(elt => elt?.sourceAST).filter(elt => elt !== undefined) as ASTNode[];
+  return elts.map(elt => elt?.sourceAST).filter((elt): elt is ASTNode => elt !== undefined);
 }
 
 // Not exposed: mostly about avoid code duplication between SchemaElement and Directive (which is not a SchemaElement as it can't
@@ -490,7 +493,8 @@ export abstract class SchemaElement<TOwnType extends SchemaElement<any, TParent>
 
   applyDirective<TApplicationArgs extends {[key: string]: any} = {[key: string]: any}>(
     nameOrDefOrDirective: Directive<TOwnType, TApplicationArgs> | DirectiveDefinition<TApplicationArgs> | string,
-    args?: TApplicationArgs
+    args?: TApplicationArgs,
+    asFirstDirective: boolean = false,
   ): Directive<TOwnType, TApplicationArgs> {
     let toAdd: Directive<TOwnType, TApplicationArgs>;
     if (nameOrDefOrDirective instanceof Directive) {
@@ -503,9 +507,15 @@ export abstract class SchemaElement<TOwnType extends SchemaElement<any, TParent>
       let name: string;
       if (typeof nameOrDefOrDirective === 'string') {
         this.checkUpdate();
-        const def = this.schema().directive(nameOrDefOrDirective) ?? this.schema().blueprint.onMissingDirectiveDefinition(this.schema(), nameOrDefOrDirective);
+        const def = this.schema().directive(nameOrDefOrDirective) ?? this.schema().blueprint.onMissingDirectiveDefinition(this.schema(), nameOrDefOrDirective, args);
         if (!def) {
-          throw new GraphQLError(`Cannot apply unknown directive "@${nameOrDefOrDirective}"`);
+          throw this.schema().blueprint.onGraphQLJSValidationError(
+            this.schema(),
+            new GraphQLError(`Unknown directive "@${nameOrDefOrDirective}".`)
+          );
+        }
+        if (Array.isArray(def)) {
+          throw ErrGraphQLValidationFailed(def);
         }
         name = nameOrDefOrDirective;
       } else {
@@ -516,7 +526,11 @@ export abstract class SchemaElement<TOwnType extends SchemaElement<any, TParent>
       Element.prototype['setParent'].call(toAdd, this);
     }
     // TODO: we should typecheck arguments or our TApplicationArgs business is just a lie.
-    this._appliedDirectives.push(toAdd);
+    if (asFirstDirective) {
+      this._appliedDirectives.unshift(toAdd);
+    } else {
+      this._appliedDirectives.push(toAdd);
+    }
     DirectiveDefinition.prototype['addReferencer'].call(toAdd.definition!, toAdd);
     this.onModification();
     return toAdd;
@@ -823,13 +837,14 @@ abstract class BaseExtensionMember<TExtended extends ExtendableElement> extends
 }
 
 export class SchemaBlueprint {
-  onMissingDirectiveDefinition(_schema: Schema, _name: string): DirectiveDefinition | undefined {
+  onMissingDirectiveDefinition(_schema: Schema, _name: string, _args?: {[key: string]: any}): DirectiveDefinition | GraphQLError[] | undefined {
     // No-op by default, but used for federation.
     return undefined;
   }
 
-  onDirectiveDefinitionAndSchemaParsed(_: Schema) {
+  onDirectiveDefinitionAndSchemaParsed(_: Schema): GraphQLError[] {
     // No-op by default, but used for federation.
+    return [];
   }
 
   ignoreParsedField(_type: NamedType, _fieldName: string): boolean {
@@ -857,6 +872,38 @@ export class SchemaBlueprint {
   validationRules(): readonly SDLValidationRule[] {
     return specifiedSDLRules;
   }
+
+  /**
+   * Allows to intercept some graphQL-js error messages when we can provide additional guidance to users.
+   */
+  onGraphQLJSValidationError(schema: Schema, error: GraphQLError): GraphQLError {
+    // For now, the main additional guidance we provide is around directives, where we could provide additional help in 2 main ways:
+    // - if a directive name is likely misspelled (somehow, graphQL-js has methods to offer suggestions on likely mispelling, but don't use this (at the
+    //   time of this writting) for directive names).
+    // - for fed 2 schema, if a federation directive is refered under it's "default" naming but is not properly imported (not enforced
+    //   in the method but rather in the `FederationBlueprint`).
+    //
+    // Note that intercepting/parsing error messages to modify them is never ideal, but pragmatically, it's probably better than rewriting the relevant
+    // rules entirely (in that later case, our "copied" rule would stop getting any potential graphQL-js made improvements for instance). And while such
+    // parsing is fragile, in that it'll break if the original message change, we have unit tests to surface any such breakage so it's not really a risk.
+    const matcher = /^Unknown directive "@(?<directive>[_A-Za-z][_0-9A-Za-z]*)"\.$/.exec(error.message);
+    const name = matcher?.groups?.directive;
+    if (!name) {
+      return error;
+    }
+
+    const allDefinedDirectiveNames = schema.allDirectives().map((d) => d.name);
+    const suggestions = suggestionList(name, allDefinedDirectiveNames);
+    if (suggestions.length === 0) {
+      return this.onUnknownDirectiveValidationError(schema, name, error);
+    } else {
+      return withModifiedErrorMessage(error, `${error.message}${didYouMean(suggestions.map((s) => '@' + s))}`);
+    }
+  }
+
+  onUnknownDirectiveValidationError(_schema: Schema, _unknownDirectiveName: string, error: GraphQLError): GraphQLError {
+    return error;
+  }
 }
 
 export const defaultSchemaBlueprint = new SchemaBlueprint();
@@ -873,7 +920,8 @@ export class CoreFeature {
 
   isFeatureDefinition(element: NamedType | DirectiveDefinition): boolean {
     return element.name.startsWith(this.nameInSchema + '__')
-      || (element.kind === 'DirectiveDefinition' && element.name === this.nameInSchema);
+      || (element.kind === 'DirectiveDefinition' && element.name === this.nameInSchema)
+      || !!this.imports.find((i) => element.name === (i.as ?? i.name));
   }
 
   directiveNameInSchema(name: string): string {
@@ -931,7 +979,7 @@ export class CoreFeatures {
     if (existing) {
       throw error(`Duplicate inclusion of feature ${url.identity}`);
     }
-    const imports = extractCoreFeatureImports(typedDirective);
+    const imports = extractCoreFeatureImports(url, typedDirective);
     const feature = new CoreFeature(url, args.as ?? url.name, directive, imports, args.for);
     this.add(feature);
     directive.schema().blueprint.onAddedCoreFeature(directive.schema(), feature);
@@ -976,25 +1024,29 @@ const graphQLBuiltInDirectivesSpecifications: readonly DirectiveSpecification[]
   createDirectiveSpecification({
     name: 'include',
     locations: [DirectiveLocation.FIELD, DirectiveLocation.FRAGMENT_SPREAD, DirectiveLocation.INLINE_FRAGMENT],
-    argumentFct: (schema) => [{ name: 'if', type: new NonNullType(schema.booleanType()) }]
+    argumentFct: (schema) => ({ args: [{ name: 'if', type: new NonNullType(schema.booleanType()) }], errors: [] })
   }),
   createDirectiveSpecification({
     name: 'skip',
     locations: [DirectiveLocation.FIELD, DirectiveLocation.FRAGMENT_SPREAD, DirectiveLocation.INLINE_FRAGMENT],
-    argumentFct: (schema) => [{ name: 'if', type: new NonNullType(schema.booleanType()) }]
+    argumentFct: (schema) => ({ args: [{ name: 'if', type: new NonNullType(schema.booleanType()) }], errors: [] })
   }),
   createDirectiveSpecification({
     name: 'deprecated',
     locations: [DirectiveLocation.FIELD_DEFINITION, DirectiveLocation.ENUM_VALUE, DirectiveLocation.ARGUMENT_DEFINITION, DirectiveLocation.INPUT_FIELD_DEFINITION],
-    argumentFct: (schema) => [{ name: 'reason', type: schema.stringType(), defaultValue: 'No longer supported' }]
+    argumentFct: (schema) => ({ args: [{ name: 'reason', type: schema.stringType(), defaultValue: 'No longer supported' }], errors: [] })
   }),
   createDirectiveSpecification({
     name: 'specifiedBy',
     locations: [DirectiveLocation.SCALAR],
-    argumentFct: (schema) => [{ name: 'url', type: new NonNullType(schema.stringType()) }]
+    argumentFct: (schema) => ({ args: [{ name: 'url', type: new NonNullType(schema.stringType()) }], errors: [] })
   }),
 ];
 
+
+// A coordinate is up to 3 "graphQL name" ([_A-Za-z][_0-9A-Za-z]*).
+const coordinateRegexp = /^@?[_A-Za-z][_0-9A-Za-z]*(\.[_A-Za-z][_0-9A-Za-z]*)?(\([_A-Za-z][_0-9A-Za-z]*:\))?$/;
+
 export class Schema {
   private _schemaDefinition: SchemaDefinition;
   private readonly _builtInTypes = new MapWithCachedArrays<string, NamedType>();
@@ -1311,7 +1363,7 @@ export class Schema {
 
     // TODO: we check that all types are properly set (aren't undefined) in `validateSchema`, but `validateSDL` will error out beforehand. We should
     // probably extract that part of `validateSchema` and run `validateSDL` conditionally on that first check.
-    let errors = validateSDL(this.toAST(), undefined, this.blueprint.validationRules());
+    let errors = validateSDL(this.toAST(), undefined, this.blueprint.validationRules()).map((e) => this.blueprint.onGraphQLJSValidationError(this, e));
     errors = errors.concat(validateSchema(this));
 
     // We avoid adding federation-specific validations if the base schema is not proper graphQL as the later can easily trigger
@@ -1364,6 +1416,56 @@ export class Schema {
   specifiedByDirective(schema: Schema): DirectiveDefinition<{url: string}> {
     return this.getBuiltInDirective(schema, 'specifiedBy');
   }
+
+  /**
+   * Gets an element of the schema given its "schema coordinate".
+   *
+   * Note that the syntax for schema coordinates is the one from the upcoming GraphQL spec: https://github.com/graphql/graphql-spec/pull/794.
+   */
+  elementByCoordinate(coordinate: string): NamedSchemaElement<any, any, any> | undefined {
+    if (!coordinate.match(coordinateRegexp)) {
+      throw error(`Invalid argument "${coordinate}: it is not a syntactically valid graphQL coordinate."`);
+    }
+
+    const argStartIdx = coordinate.indexOf('(');
+    const start = argStartIdx < 0 ? coordinate : coordinate.slice(0, argStartIdx);
+    // Argument syntax is `foo(argName:)`, so the arg name start after the open parenthesis and go until the final ':)'.
+    const argName = argStartIdx < 0 ? undefined : coordinate.slice(argStartIdx + 1, coordinate.length - 2);
+    const splittedStart = start.split('.');
+    const typeOrDirectiveName = splittedStart[0];
+    const fieldOrEnumName = splittedStart[1];
+    const isDirective = typeOrDirectiveName.startsWith('@');
+    if (isDirective) {
+      if (fieldOrEnumName) {
+        throw error(`Invalid argument "${coordinate}: it is not a syntactically valid graphQL coordinate."`);
+      }
+      const directive = this.directive(typeOrDirectiveName.slice(1));
+      return argName ? directive?.argument(argName) : directive;
+    } else {
+      const type = this.type(typeOrDirectiveName);
+      if (!type || !fieldOrEnumName) {
+        return type;
+      }
+      switch (type.kind) {
+        case 'ObjectType':
+        case 'InterfaceType':
+          const field = type.field(fieldOrEnumName);
+          return argName ? field?.argument(argName) : field;
+        case 'InputObjectType':
+          if (argName) {
+            throw error(`Invalid argument "${coordinate}: it is not a syntactically valid graphQL coordinate."`);
+          }
+          return type.field(fieldOrEnumName);
+        case 'EnumType':
+          if (argName) {
+            throw error(`Invalid argument "${coordinate}: it is not a syntactically valid graphQL coordinate."`);
+          }
+          return type.value(fieldOrEnumName);
+        default:
+          throw error(`Invalid argument "${coordinate}: it is not a syntactically valid graphQL coordinate."`);
+      }
+    }
+  }
 }
 
 export class RootType extends BaseExtensionMember<SchemaDefinition> {
@@ -1391,9 +1493,10 @@ export class SchemaDefinition extends SchemaElement<SchemaDefinition, Schema>  {
 
   applyDirective<TApplicationArgs extends {[key: string]: any} = {[key: string]: any}>(
     nameOrDefOrDirective: Directive<SchemaDefinition, TApplicationArgs> | DirectiveDefinition<TApplicationArgs> | string,
-    args?: TApplicationArgs
+    args?: TApplicationArgs,
+    asFirstDirective: boolean = false,
   ): Directive<SchemaDefinition, TApplicationArgs> {
-    const applied = super.applyDirective(nameOrDefOrDirective, args) as Directive<SchemaDefinition, TApplicationArgs>;
+    const applied = super.applyDirective(nameOrDefOrDirective, args, asFirstDirective) as Directive<SchemaDefinition, TApplicationArgs>;
     const schema = this.schema();
     const coreFeatures = schema.coreFeatures;
     if (isCoreSpecDirectiveApplication(applied)) {
@@ -1403,9 +1506,13 @@ export class SchemaDefinition extends SchemaElement<SchemaDefinition, Schema>  {
       const schemaDirective = applied as Directive<SchemaDefinition, CoreOrLinkDirectiveArgs>;
       const args = schemaDirective.arguments();
       const url = FeatureUrl.parse((args.url ?? args.feature)!);
-      const imports = extractCoreFeatureImports(schemaDirective);
+      const imports = extractCoreFeatureImports(url, schemaDirective);
       const core = new CoreFeature(url, args.as ?? url.name, schemaDirective, imports, args.for);
       Schema.prototype['markAsCoreSchema'].call(schema, core);
+      // We also any core features that may have been added before we saw the @link for link itself
+      this.appliedDirectives
+        .filter((a) => a !== applied)
+        .forEach((other) => CoreFeatures.prototype['maybeAddFeature'].call(schema.coreFeatures, other));
     } else if (coreFeatures) {
       CoreFeatures.prototype['maybeAddFeature'].call(coreFeatures, applied);
     }
@@ -2711,9 +2818,9 @@ export class Directive<
     this.onModification();
     const coreFeatures = this.schema().coreFeatures;
     if (coreFeatures && this.name === coreFeatures.coreItself.nameInSchema) {
-      // We're removing a @core directive application, so we remove it from the list of core features. And
+      // We're removing a @core/@link directive application, so we remove it from the list of core features. And
       // if it is @core itself, we clean all features (to avoid having things too inconsistent).
-      const url = FeatureUrl.parse(this._args['feature']!);
+      const url = FeatureUrl.parse(this._args[coreFeatures.coreDefinition.urlArgName()]!);
       if (url.identity === coreFeatures.coreItself.url.identity) {
         // Note that we unmark first because the loop after that will nuke our parent.
         Schema.prototype['unmarkAsCoreSchema'].call(this.schema());