From 1f90a5dfbc7721a64a184719a5e983742294a35b Mon Sep 17 00:00:00 2001
From: Michael Staib <michael@chillicream.com>
Date: Fri, 27 Dec 2024 11:14:10 +0100
Subject: [PATCH] Added `@external` directive spec text (#82)

---
 spec/Section 2 -- Source Schema.md | 49 ++++++++++++++++++++++++++++--
 1 file changed, 46 insertions(+), 3 deletions(-)

diff --git a/spec/Section 2 -- Source Schema.md b/spec/Section 2 -- Source Schema.md
index 000f608..0a147ce 100644
--- a/spec/Section 2 -- Source Schema.md	
+++ b/spec/Section 2 -- Source Schema.md	
@@ -553,11 +553,54 @@ type Query {
 ### @external
 
 ```graphql
-directive @external on OBJECT_DEFINITION | INTERFACE_DEFINITION | FIELD_DEFINITION
+directive @external on FIELD_DEFINITION
 ```
 
-The `@external` directive is used in combination with the `@provides` directive
-and specifies data that is not owned by a particular source schema.
+The @external directive indicates that a field is recognized by the current
+source schema but is not directly contributed (resolved) by it. Instead, this
+schema references the field for specific composition purposes.
+
+**Entity Keys**
+
+When combined with one or more `@key` directives, an external field can serve as
+an entity identifier (or part of a composite identifier).
+
+```graphql example
+type Query {
+  productBySku(sku: String!): Product @lookup
+  productByUpc(upc: String!): Product @lookup
+}
+
+type Product @key(fields: "sku") @key(fields: "upc") {
+  sku: String! @external
+  upc: String! @external
+  name: String
+}
+```
+
+**Field Resolution**
+
+When another field in the same source schema uses `@provides` to declare that it
+can resolve certain external fields in a single data-fetching step.
+
+```graphql example
+type Review {
+  id: ID!
+  text: String
+  author: User @provides(fields: "email")
+}
+
+extend type User {
+  id: ID!
+  email: String! @external
+}
+```
+
+When a field is marked `@external`, the composition process understands that the
+field is provided by another source schema. The current source schema references
+it only for entity identification (via `@key`) or for providing a field through
+`@provides`. If no such usage exists, the presence of an `@external` field
+produces a composition error.
 
 ### @override