Meta data

ID

The ID of a schema is used to generate the class name. If no ID is present the filename of the JSON-Schema file will be used as class name

{
    "$id": "MyObject",
    "type": "object",
    "properties": {
        "example": {
            "type": "string",
        }
    }
}

The generated class will be MyObject in MyObject.php

$comment

The $comment keyword is a developer-facing annotation. Its value is emitted as a paragraph in the getter’s PHPDoc and is not used for validation.

{
    "$id": "example",
    "type": "object",
    "properties": {
        "example": {
            "type": "string",
            "$comment": "Internal note: this field maps to column user_name in the DB."
        }
    }
}

Generated getter:

/**
 * Get the value of example.
 *
 * Internal note: this field maps to column user_name in the DB.
 *
 * @return string|null
 */
public function getExample(): ?string;

examples

The examples keyword provides one or more sample values for a property. Each entry is emitted as an @example line in the getter’s PHPDoc and is not used for validation.

{
    "$id": "example",
    "type": "object",
    "properties": {
        "status": {
            "type": "string",
            "examples": ["active", "inactive", "pending"]
        }
    }
}

Generated getter:

/**
 * Get the value of status.
 * @example active
 * @example inactive
 * @example pending
 *
 * @return string|null
 */
public function getStatus(): ?string;

Non-string example values (numbers, booleans, arrays) are JSON-encoded in the annotation.

Description

If a property provides a description this description will be adopted into the generated PHP class so the documentation is available.

{
    "$id": "example",
    "type": "object",
    "properties": {
        "example": {
            "type": "string",
            "description": "My example property with a large and very helpful description"
        }
    }
}

Generated code in the PHP class:

/** @var string My example property with a large and very helpful description */
protected $example;

...

/**
 * Get the value of example.
 *
 * My example property with a large and very helpful description
 *
 * @returns string|null
 */
public function getExample(): ?string;

/**
 * Set the value of example.
 *
 * @param string $example My example property with a large and very helpful description
 *
 * @return self
 */
public function setExample(string $example): static;