- update Introspection to include isOneOf field

- add oneOfDirective definition, allowed on INPUT_OBJECT
- add isOneOf to InputObjectType config
- update BuldSchema to account for oneOf directive
- add OneOfInputObjectsRule to validation rules

Author: jasonbahl

src/Type/Definition/Directive.php

@@ -27,6 +27,7 @@ class Directive
     public const SKIP_NAME = 'skip';
     public const DEPRECATED_NAME = 'deprecated';
     public const REASON_ARGUMENT_NAME = 'reason';
+    public const ONE_OF_NAME = 'oneOf';
 
     /**
      * Lazily initialized.
@@ -86,6 +87,7 @@ public static function getInternalDirectives(): array
             self::INCLUDE_NAME => self::includeDirective(),
             self::SKIP_NAME => self::skipDirective(),
             self::DEPRECATED_NAME => self::deprecatedDirective(),
+            self::ONE_OF_NAME => self::oneOfDirective(),
         ];
     }
 
@@ -151,6 +153,19 @@ public static function deprecatedDirective(): Directive
         ]);
     }
 
+    /** @throws InvariantViolation */
+    public static function oneOfDirective(): Directive
+    {
+        return self::$internalDirectives[self::ONE_OF_NAME] ??= new self([
+            'name' => self::ONE_OF_NAME,
+            'description' => 'Indicates that an input object is a oneof input object and exactly one of the input fields must be specified.',
+            'locations' => [
+                DirectiveLocation::INPUT_OBJECT,
+            ],
+            'args' => [],
+        ]);
+    }
+
     /** @throws InvariantViolation */
     public static function isSpecifiedDirective(Directive $directive): bool
     {

src/Type/Definition/InputObjectType.php

@@ -18,6 +18,7 @@
  *   name?: string|null,
  *   description?: string|null,
  *   fields: iterable<FieldConfig>|callable(): iterable<FieldConfig>,
+ *   isOneOf?: bool|null,
  *   parseValue?: callable(array<string, mixed>): mixed,
  *   astNode?: InputObjectTypeDefinitionNode|null,
  *   extensionASTNodes?: array<InputObjectTypeExtensionNode>|null
@@ -35,6 +36,8 @@ class InputObjectType extends Type implements InputType, NullableType, NamedType
     /** @phpstan-var InputObjectConfig */
     public array $config;
 
+    public bool $isOneOf;
+
     /**
      * Lazily initialized.
      *
@@ -55,6 +58,7 @@ public function __construct(array $config)
         $this->description = $config['description'] ?? null;
         $this->astNode = $config['astNode'] ?? null;
         $this->extensionASTNodes = $config['extensionASTNodes'] ?? [];
+        $this->isOneOf = $config['isOneOf'] ?? false;
 
         $this->config = $config;
     }
@@ -91,6 +95,12 @@ public function hasField(string $name): bool
         return isset($this->fields[$name]);
     }
 
+    /** Returns true if this is a oneOf input object type. */
+    public function isOneOf(): bool
+    {
+        return $this->isOneOf;
+    }
+
     /**
      * @throws InvariantViolation
      *
@@ -196,6 +206,44 @@ public function assertValid(): void
         foreach ($resolvedFields as $field) {
             $field->assertValid($this);
         }
+
+        // Additional validation for oneOf input objects
+        if ($this->isOneOf()) {
+            $this->validateOneOfConstraints($resolvedFields);
+        }
+    }
+
+    /**
+     * Validates that oneOf input object constraints are met.
+     *
+     * @param array<string, InputObjectField> $fields
+     *
+     * @throws InvariantViolation
+     */
+    private function validateOneOfConstraints(array $fields): void
+    {
+        if (count($fields) === 0) {
+            throw new InvariantViolation("OneOf input object type {$this->name} must define one or more fields.");
+        }
+
+        foreach ($fields as $fieldName => $field) {
+            $fieldType = $field->getType();
+
+            // OneOf fields must be nullable (not wrapped in NonNull)
+            if ($fieldType instanceof NonNull) {
+                throw new InvariantViolation("OneOf input object type {$this->name} field {$fieldName} must be nullable.");
+            }
+
+            // OneOf fields cannot have default values
+            if ($field->defaultValueExists()) {
+                throw new InvariantViolation("OneOf input object type {$this->name} field {$fieldName} cannot have a default value.");
+            }
+
+            // OneOf fields cannot be deprecated (optional constraint for now)
+            if ($field->isDeprecated()) {
+                throw new InvariantViolation("OneOf input object type {$this->name} field {$fieldName} cannot be deprecated.");
+            }
+        }
     }
 
     public function astNode(): ?InputObjectTypeDefinitionNode

src/Type/Introspection.php

@@ -437,6 +437,12 @@ public static function _type(): ObjectType
                         ? $type->getWrappedType()
                         : null,
                 ],
+                'isOneOf' => [
+                    'type' => Type::boolean(),
+                    'resolve' => static fn ($type): ?bool => $type instanceof InputObjectType
+                        ? $type->isOneOf()
+                        : null,
+                ],
             ],
         ]);
     }

src/Utils/BuildSchema.php

@@ -238,6 +238,9 @@ static function (string $typeName): Type {
         if (! isset($directivesByName['deprecated'])) {
             $directives[] = Directive::deprecatedDirective();
         }
+        if (! isset($directivesByName['oneOf'])) {
+            $directives[] = Directive::oneOfDirective();
+        }
 
         // Note: While this could make early assertions to get the correctly
         // typed values below, that would throw immediately while type system

src/Validator/DocumentValidator.php

@@ -22,6 +22,7 @@
 use GraphQL\Validator\Rules\NoUndefinedVariables;
 use GraphQL\Validator\Rules\NoUnusedFragments;
 use GraphQL\Validator\Rules\NoUnusedVariables;
+use GraphQL\Validator\Rules\OneOfInputObjectsRule;
 use GraphQL\Validator\Rules\OverlappingFieldsCanBeMerged;
 use GraphQL\Validator\Rules\PossibleFragmentSpreads;
 use GraphQL\Validator\Rules\PossibleTypeExtensions;
@@ -179,6 +180,7 @@ public static function defaultRules(): array
             VariablesInAllowedPosition::class => new VariablesInAllowedPosition(),
             OverlappingFieldsCanBeMerged::class => new OverlappingFieldsCanBeMerged(),
             UniqueInputFieldNames::class => new UniqueInputFieldNames(),
+            OneOfInputObjectsRule::class => new OneOfInputObjectsRule(),
         ];
     }
 

src/Validator/Rules/OneOfInputObjectsRule.php

@@ -0,0 +1,65 @@
+<?php declare(strict_types=1);
+
+namespace GraphQL\Validator\Rules;
+
+use GraphQL\Error\Error;
+use GraphQL\Language\AST\NodeKind;
+use GraphQL\Language\AST\ObjectValueNode;
+use GraphQL\Type\Definition\InputObjectType;
+use GraphQL\Type\Definition\Type;
+use GraphQL\Validator\QueryValidationContext;
+
+/**
+ * OneOf Input Objects validation rule.
+ *
+ * Validates that OneOf Input Objects have exactly one non-null field provided.
+ */
+class OneOfInputObjectsRule extends ValidationRule
+{
+    public function getVisitor(QueryValidationContext $context): array
+    {
+        return [
+            NodeKind::OBJECT => static function (ObjectValueNode $node) use ($context): void {
+                $type = $context->getInputType();
+
+                if ($type === null) {
+                    return;
+                }
+
+                $namedType = Type::getNamedType($type);
+                if (! ($namedType instanceof InputObjectType) || ! $namedType->isOneOf()) {
+                    return;
+                }
+
+                $providedFields = [];
+                foreach ($node->fields as $fieldNode) {
+                    $fieldName = $fieldNode->name->value;
+                    $providedFields[] = $fieldName;
+                }
+
+                $fieldCount = count($providedFields);
+
+                if ($fieldCount === 0) {
+                    $context->reportError(new Error(
+                        static::oneOfInputObjectExpectedExactlyOneFieldMessage($namedType->name),
+                        [$node]
+                    ));
+                } elseif ($fieldCount > 1) {
+                    $context->reportError(new Error(
+                        static::oneOfInputObjectExpectedExactlyOneFieldMessage($namedType->name, $fieldCount),
+                        [$node]
+                    ));
+                }
+            },
+        ];
+    }
+
+    public static function oneOfInputObjectExpectedExactlyOneFieldMessage(string $typeName, ?int $providedCount = null): string
+    {
+        if ($providedCount === null) {
+            return "OneOf input object '{$typeName}' must specify exactly one field.";
+        }
+
+        return "OneOf input object '{$typeName}' must specify exactly one field, but {$providedCount} fields were provided.";
+    }
+}