One Of
======

The `oneOf` keyword can be used to combine multiple subschemas. The provided value must be valid against exactly one of the subschemas.

.. code-block:: json

    {
        "$id": "example",
        "type": "object",
        "properties": {
            "example": {
                "oneOf": [
                    {
                        "type": "number",
                        "multipleOf": 5
                    },
                    {
                        "type": "number",
                        "multipleOf": 3
                    }
                ]
            }
        }
    }

Valid values are eg. 3, 5, 6, 9, 10, 12. Invalid values are eg. 1, 2, 4, 7, 8, 11 or any non numeric values.

Generated interface:

.. code-block:: php

    public function setExample(float $example): static;
    public function getExample(): float;


Possible exception (if a string is provided):

.. code-block:: none

    Invalid value for example declined by composition constraint.
      Requires to match one composition element but matched 0 elements.
      - Composition element #1: Failed
        * Invalid type for example. Requires float, got string
      - Composition element #2: Failed
        * Invalid type for example. Requires float, got string


Possible exception (if eg. 15 is provided, which matches both subschemas):

.. code-block:: none

    Invalid value for example declined by composition constraint.
      Requires to match one composition element but matched 2 elements.
      - Composition element #1: Valid
      - Composition element #2: Valid

The thrown exception will be a *PHPModelGenerator\\Exception\\ComposedValue\\OneOfException* which provides the following methods to get further error details:

.. code-block:: php

    // returns a two-dimensional array which contains all validation exceptions grouped by composition elements
    public function getCompositionErrorCollection(): array
    // get the amount of succeeded composition elements
    public function getSucceededCompositionElements(): int
    // get the name of the property which failed
    public function getPropertyName(): string
    // get the value provided to the property
    public function getProvidedValue()

.. note::

    ``oneOf`` branches can be the boolean literals ``true`` or ``false``.

    - ``true`` branch — treated as an empty schema; always satisfies the branch.
    - ``false`` branch — can never be satisfied; always-failing branches participate in the
      composition but never succeed. If all branches are ``false``, any provided value raises a
      ``OneOfException`` at runtime, and the generator emits a warning at generation time.
      Absent optional properties are still allowed.

.. hint::

    When combining multiple nested objects with an `oneOf` composition a `merged property <mergedProperty.html>`__ will be generated

.. note::

    When a property is also defined in the root ``properties`` section, the root type definition
    is authoritative. ``oneOf`` branches may add further constraints but will not widen the
    property's type. When branches define the same property with different types, the generator
    widens the property to a union type. See
    `Cross-typed compositions <crossTypedComposition.html>`__ for the full explanation including
    nullability rules and the ``allOf`` contrast.

.. note::

    For object-level ``oneOf`` compositions, when a property appears in the ``required`` array of
    **every** branch, the generator promotes that property to non-nullable in the generated class.
    Exactly one branch applies at runtime; because all branches guarantee the property's presence,
    the getter can safely be non-nullable. See `Cross-typed compositions <crossTypedComposition.html>`__
    for the full promotion rules.

.. note::

    Properties in object-level ``oneOf`` branches may carry a ``"default"`` value. The generator
    applies the branch default only when that branch is the active one — determined at construction
    time by which branch the provided data satisfies. A user-supplied value always overrides the
    branch default. Branch defaults are **not** included in ``getRawModelDataInput()``.

    When two ``oneOf`` branches define a default for the same property, or when a branch default
    conflicts with a root ``properties`` default or a ``patternProperties`` default, the generator
    throws a ``SchemaException`` at generation time.

    See `Default values <../generic/default.html#branch-defaults-in-compositions>`__ for the full
    explanation and examples.