Property types uri, email

[PaulHendriks]

Most API's use property types matching a constraint, for example:

• uri
• email

The basic type of this data is 'string'.
I'd like to add a contraint/type in the Annotation, if that's possible?
This might also fix #6

These are the constraints/formats i'm talking about: https://opis.io/json-schema/2.x/formats.html#email

[roxblnfk]

Sounds like a great feature request. Have you already thought about the design of the implementation?

[PaulHendriks]

I've submitted a pull request with this feature.
It's pretty straightforward, using an emum based on the Opis documentation as available formats.

[butschster]

Hey @PaulHendriks,

Thanks a lot for the PR! Really appreciate you taking the time to contribute this.

By the way, just a heads up—I’ve also got a PR open for union types: context-hub#1. Feel free to take a look if you're interested—maybe you’ll get some ideas or inspiration from it.

---

Working with Union Types

The JSON Schema Generator now supports PHP 8.0+ union types, allowing you to define properties that can have multiple types. In the generated JSON Schema, these are represented using the oneOf keyword.

Basic Union Types

You can use PHP's union type syntax (|) to define properties that can accept multiple types:

use Spiral\JsonSchemaGenerator\Attribute\Field;

class ExampleDTO 
{
    public function __construct(
        #[Field(title: 'String or Integer', description: 'Value can be either string or integer')]
        public readonly string|int $stringOrInt,
        
        public readonly string|float|null $multiplePrimitives = null,
    ) {
    }
}

This will generate a schema with oneOf constraints in the properties:

{
    "title": "ExampleDTO",
    "properties": {
        "stringOrInt": {
            "title": "String or Integer",
            "description": "Value can be either string or integer",
            "oneOf": [
                { "type": "string" },
                { "type": "integer" }
            ]
        },
        "multiplePrimitives": {
            "oneOf": [
                { "type": "string" },
                { "type": "number" },
                { "type": "null" }
            ]
        }
    },
    "required": ["stringOrInt"]
}

Object Union Types

Union types can also include object references, allowing for polymorphic properties:

class ExampleDTO 
{
    public function __construct(
        public readonly User|Customer|null $person = null,
    ) {
    }
}

This will generate a schema that references the appropriate object definitions:

{
    "title": "ExampleDTO",
    "properties": {
        "person": {
            "oneOf": [
                { "$ref": "#/definitions/User" },
                { "$ref": "#/definitions/Customer" },
                { "type": "null" }
            ]
        }
    },
    "definitions": {
        "User": { /* User definition */ },
        "Customer": { /* Customer definition */ }
    }
}

Handling Null Types

When a property is defined as nullable (using |null), it will include a null type in the oneOf list:

public readonly string|null $optionalText = null;

The schema will include:

"optionalText": {
    "oneOf": [
        { "type": "string" },
        { "type": "null" }
    ],
    "default": null
}

Limitations

• Intersection types (string&Stringable) are not supported since JSON Schema doesn't have a direct equivalent
• The special mixed type is not fully supported - it's better to explicitly define allowed types

[PaulHendriks]

Thank you for the heads-up @butschster 👍
Glad i could contribute to this project.
At the moment i'm working on a FIHR (https://hl7.org/fhir/R4) api implementation, which uses a pretty big schema.
Union types can certainly be useful in this context 🙂