One Of

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

{
    "$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:

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

Possible exception (if a string is provided):

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):

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:

// 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 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 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 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 for the full explanation and examples.