Update DefiningSchema.md

Author: peldax

docs/DefiningSchema.md

@@ -116,7 +116,7 @@ final class Starship extends Type
 
 Fields are defined using `getFieldDefinition` function. This is (apart from secondary performance advantages) done because of a possible cyclic dependency across fields. Fields are therefore loaded lazily using this method, instead of passing FieldSet directly to constructor.
 
-The `validateNonNullValue` function allows the programmer to check if the parent resolver passed a correct value for this type. When false an `InvalidValue` is thrown.
+The `validateNonNullValue` function allows the programmer to check if the parent resolver passed a correct value for this type. The argument is any value resolved from parent resolver, except `null` which has a special meaning for the GraphQL. When the function returns `false` an `InvalidValue` is thrown.
 
 #### Implementing interface
 
@@ -150,6 +150,8 @@ interface Character {
 
 namespace App\Type;
 
+use App\Dto\Human as HumanDto;
+use App\Dto\Droid as DroidDto;
 use App\Type\Episode;
 use Graphpinator\Typesystem\Attribute\Description;
 use Graphpinator\Typesystem\Container;
@@ -160,40 +162,53 @@ use Graphpinator\Typesystem\InterfaceType;
 #[Description('My Character interface')]
 final class Character extends InterfaceType
 {
-  protected const NAME = 'Character';
-  
-  public function __construct(
-      private Episode $episode,
-  )
-  {
-      parent::__construct();
-  }
-  
-  protected function getFieldDefinition() : FieldSet
-  {
-      return new FieldSet([
-          Field::create(
-              'id', 
-              Container::ID()->notNull(), 
-          ),
-          Field::create(
-              'name', 
-              Container::String()->notNull(), 
-          ),
-          Field::create(
-              'friends', 
-              $this->list(), // nullable list with nullable contents
-          ),
-          Field::create(
-              'appearsIn', 
-              $this->episode->list()->notNull(),  // not-null list with nullable contents
-          ),
-      ]);
-  } 
+    protected const NAME = 'Character';
+    
+    public function __construct(
+        private Episode $episode,
+        private CharacterAccessor $characterAccessor,
+    )
+    {
+        parent::__construct();
+    }
+    
+    protected function getFieldDefinition() : FieldSet
+    {
+        return new FieldSet([
+            Field::create(
+                'id', 
+                Container::ID()->notNull(), 
+            ),
+            Field::create(
+                'name', 
+                Container::String()->notNull(), 
+            ),
+            Field::create(
+                'friends', 
+                $this->list(), // nullable list with nullable contents
+            ),
+            Field::create(
+                'appearsIn', 
+                $this->episode->list()->notNull(),  // not-null list with nullable contents
+            ),
+        ]);
+    }
+
+    public function createResolvedValue(mixed $rawValue) : TypeIntermediateValue
+    {
+        return match ($rawValue::class) {
+            HumanDto::class => new TypeIntermediateValue($this->characterAccessor->getHumanType(), $rawValue),
+            DroidDto::class => new TypeIntermediateValue($this->characterAccessor->getDroidType(), $rawValue),
+        };
+    }
 }
 ```
 
-Fields are defined using `getFieldDefinition` function using the same concept as for defining Types. The only difference is the absence of a resolve function, because Interfaces cannot be resolved directly. Field definitions are used to validate contract with Types implementing this interface.
+Fields are defined using `getFieldDefinition` function using the same concept as for defining `Type`. The only difference is the absence of a resolve function, because Interfaces cannot be resolved directly. Field definitions are used to validate contract with Types implementing this interface.
+
+Additionally, the `createResolvedValue` function must be implemented to decide which concrete type the resolved value belongs to. The argument is any value resolved from parent resolver, except `null` which has a special meaning for the GraphQL. The result of this method is a structure of the concrete type and the undelying value which will be passed into it. 
+
+This may cause trouble as the cyclic dependency appears, the contrete types need the interface in order to implement it and the interface need the conrete types in order to resolve the value. This is a common scenario in the GraphQL, as the types reference each other and can resolve in cycles. In this example we worked around it by passing an accessor as a constructor dependency instead of the types directly. The implementation of the accessor depends on which framework and/or DI solution you use.
 
 Interfaces can also implement other interfaces using the same procedure as types - passing `InterfaceSet` into parent constructor.
 In this case the fields from parent interface are automatically included and there is no need to repeat the field definitions in the child, unless you wish to be more specific - but keep in mind that covariance/contravariance rules must be applied.
@@ -211,25 +226,44 @@ union SearchResult = Human | Droid | Starship
 
 namespace App\Type;
 
+use App\Dto\Human as HumanDto;
+use App\Dto\Droid as DroidDto;
+use App\Dto\Starship as StarshipDto;
 use App\Type\Human;
 use App\Type\Droid;
 use App\Type\Starship;
 use Graphpinator\Typesystem\Attribute\Description;
 use Graphpinator\Typesystem\TypeSet;
 use Graphpinator\Typesystem\UnionType;
+use Graphpinator\Value\TypeIntermediateValue;
 
 #[Description('My SearchResult union')]
 final class SearchResult extends UnionType
 {
     protected const NAME = 'SearchResult';
 
-    public function __construct(Human $human, Droid $droid, Starship $starship)
+    public function __construct(
+        private Human $human,
+        private Droid $droid,
+        private Starship $starship,
+    )
     {
         parent::__construct(new TypeSet([$human, $droid, $starship]));
     }
+
+    public function createResolvedValue(mixed $rawValue) : TypeIntermediateValue
+    {
+        return match ($rawValue::class) {
+            HumanDto::class => new TypeIntermediateValue($this->human, $rawValue),
+            DroidDto::class => new TypeIntermediateValue($this->droid, $rawValue),
+            StarshipDto::class => new TypeIntermediateValue($this->starship, $rawValue),
+        };
+    }
 }
 ```
 
+In similar fashion as for the `Interface`, the `createResolvedValue` function must be implemented to decide which type the resolved value belongs to.
+
 ### Scalar
 
 ### Enum