Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

Schema Discovery turns the raw `_schema` endpoint into a small interactive API console. The page still talks to the real live Semitexa routes.

How it works

The human-facing demo page is a normal DemoFeatureResource, but each operation button issues a fetch() call against the external API endpoints under `/demo/api/...`. The schema contract and example responses are preloaded server-side so the page reads like documentation before you click anything.

Why it matters

This is closer to how people evaluate APIs in practice: they want to poke the contract, compare responses, and confirm the system shape without wiring Postman first.

Key concepts

_schema: Machine-facing schema endpoint returning JSON Schema for the product contract.
application/schema+json: Explicit media type for tooling that consumes JSON Schema documents.
Sparse fieldset: A client asks for only the fields it needs via `fields=...`.

Live response

GET schema

200 application/json

{
    "Accept": "application\/json"
}

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "/demo/api/v1/products/_schema",
    "title": "Semitexa Demo Product",
    "type": "object",
    "required": [
        "slug",
        "name",
        "price"
    ],
    "properties": {
        "slug": {
            "type": "string",
            "description": "Stable product slug used by the demo API detail route."
        },
        "name": {
            "type": "string"
        },
        "price": {
            "type": "number",
            "minimum": 0
        },
        "description": {
            "type": [
                "string",
                "null"
            ]
        },
        "status": {
            "type": "string",
            "enum": [
                "active",
                "sale",
                "archived"
            ]
        },
        "category": {
            "type": [
                "object",
                "null"
            ],
            "required": [
                "slug",
                "name"
            ],
            "properties": {
                "slug": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                }
            }
        },
        "rating": {
            "type": "number",
            "minimum": 0,
            "maximum": 5
        },
        "reviewCount": {
            "type": "integer",
            "minimum": 0
        },
        "reviews": {
            "type": "array",
            "items": {
                "type": "object",
                "required": [
                    "user",
                    "rating",
                    "body"
                ],
                "properties": {
                    "user": {
                        "type": "string"
                    },
                    "rating": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "body": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            }
        },
        "links": {
            "type": "object",
            "properties": {
                "self": {
                    "type": "string"
                },
                "collection": {
                    "type": "string"
                }
            }
        }
    }
}

#[ExternalApi] JSON Schema live explorer

Verified against Semitexa Ultimate 2026.09.19.1020

Schema Discovery

A machine-facing API should explain its own shape and let you exercise the contract without leaving the demo.

How it works

The product API exposes a dedicated _schema endpoint that returns the full JSON Schema for the product representation. The endpoint responds to both application/json and application/schema+json Accept headers, so machine tooling and human browsers get the same document at the right content type. The schema explorer on this page exercises the live contract: schema endpoint, sparse fieldset detail, and expanded graph with category and review data.

Why this matters

API clients should not have to reverse-engineer the response shape from examples. A schema endpoint gives SDK generators, validation layers, and developer tooling a single source of truth. Responding to application/schema+json makes the endpoint machine-discoverable through standard tooling without a separate OpenAPI pipeline.

1<?php23declare(strict_types=1);45namespace App\Application\Handler\Api;67use App\Application\Payload\Api\ApiSchemaDiscoveryPayload;8use App\Application\Resource\Page\ApiSchemaPageResource;9use App\Domain\Api\SchemaRegistryInterface;10use Semitexa\Core\Attribute\AsPayloadHandler;11use Semitexa\Core\Attribute\InjectAsReadonly;12use Semitexa\Core\Contract\TypedHandlerInterface;1314#[AsPayloadHandler(payload: ApiSchemaDiscoveryPayload::class, resource: ApiSchemaPageResource::class)]15final class ApiSchemaDiscoveryHandler implements TypedHandlerInterface16{17    #[InjectAsReadonly]18    protected SchemaRegistryInterface $schemaRegistry;1920    public function handle(ApiSchemaDiscoveryPayload $payload, ApiSchemaPageResource $resource): ApiSchemaPageResource21    {22        return $resource->fromSchema($this->schemaRegistry->describe());23    }24}25

<?php

declare(strict_types=1);

namespace App\Application\Handler\Api;

use App\Application\Payload\Api\ApiSchemaDiscoveryPayload;
use App\Application\Resource\Page\ApiSchemaPageResource;
use App\Domain\Api\SchemaRegistryInterface;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: ApiSchemaDiscoveryPayload::class, resource: ApiSchemaPageResource::class)]
final class ApiSchemaDiscoveryHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected SchemaRegistryInterface $schemaRegistry;

    public function handle(ApiSchemaDiscoveryPayload $payload, ApiSchemaPageResource $resource): ApiSchemaPageResource
    {
        return $resource->fromSchema($this->schemaRegistry->describe());
    }
}

1<?php23declare(strict_types=1);45namespace App\Application\Payload\Api;67use App\Application\Resource\Page\ApiSchemaPageResource;8use Semitexa\Core\Attribute\AsPublicPayload;910#[AsPublicPayload(11    path: '/docs/api/schema',12    methods: ['GET'],13    responseWith: ApiSchemaPageResource::class,14)]15final class ApiSchemaDiscoveryPayload16{17}18

<?php

declare(strict_types=1);

namespace App\Application\Payload\Api;

use App\Application\Resource\Page\ApiSchemaPageResource;
use Semitexa\Core\Attribute\AsPublicPayload;

#[AsPublicPayload(
    path: '/docs/api/schema',
    methods: ['GET'],
    responseWith: ApiSchemaPageResource::class,
)]
final class ApiSchemaDiscoveryPayload
{
}

1<?php23declare(strict_types=1);45namespace App\Application\Payload\Api;67use App\Application\Resource\Api\ProductSchemaResource;8use Semitexa\Api\Attribute\ExternalApi;9use Semitexa\Core\Attribute\AsPublicPayload;1011#[ExternalApi]12#[AsPublicPayload(13    path: '/api/schema/products',14    methods: ['GET'],15    responseWith: ProductSchemaResource::class,16    produces: ['application/schema+json'],17)]18final class ProductSchemaPayload19{20}21

<?php

declare(strict_types=1);

namespace App\Application\Payload\Api;

use App\Application\Resource\Api\ProductSchemaResource;
use Semitexa\Api\Attribute\ExternalApi;
use Semitexa\Core\Attribute\AsPublicPayload;

#[ExternalApi]
#[AsPublicPayload(
    path: '/api/schema/products',
    methods: ['GET'],
    responseWith: ProductSchemaResource::class,
    produces: ['application/schema+json'],
)]
final class ProductSchemaPayload
{
}

1<?php23declare(strict_types=1);45namespace App\Api\Product;67use Semitexa\Api\Attribute\ApiVersion;8use Semitexa\Api\Attribute\ExternalApi;9use Semitexa\Core\Attribute\AsPublicPayload;1011#[AsPublicPayload(path: '/api/v1/products', methods: ['GET'], responseWith: ProductApiResponse::class)]12#[ExternalApi(version: 'v1')]13#[ApiVersion(version: '1.0.0')]14final class ProductListPayload15{16    protected int $page = 1;17    protected int $limit = 24;1819    public function getPage(): int { return $this->page; }20    public function setPage(int|string|null $page): void { $this->page = max(1, (int) ($page ?? 1)); }2122    public function getLimit(): int { return $this->limit; }23    public function setLimit(int|string|null $limit): void { $this->limit = min(100, max(1, (int) ($limit ?? 24))); }24}25

<?php

declare(strict_types=1);

namespace App\Api\Product;

use Semitexa\Api\Attribute\ApiVersion;
use Semitexa\Api\Attribute\ExternalApi;
use Semitexa\Core\Attribute\AsPublicPayload;

#[AsPublicPayload(path: '/api/v1/products', methods: ['GET'], responseWith: ProductApiResponse::class)]
#[ExternalApi(version: 'v1')]
#[ApiVersion(version: '1.0.0')]
final class ProductListPayload
{
    protected int $page = 1;
    protected int $limit = 24;

    public function getPage(): int { return $this->page; }
    public function setPage(int|string|null $page): void { $this->page = max(1, (int) ($page ?? 1)); }

    public function getLimit(): int { return $this->limit; }
    public function setLimit(int|string|null $limit): void { $this->limit = min(100, max(1, (int) ($limit ?? 24))); }
}

1<?php23declare(strict_types=1);45namespace App\Api\Product;67use App\Api\Product\ProductApiResponse;8use Semitexa\Api\Attribute\ApiVersion;9use Semitexa\Api\Attribute\ExternalApi;10use Semitexa\Core\Attribute\AsPublicPayload;1112#[AsPublicPayload(path: '/api/v1/products/{slug}', methods: ['GET'], responseWith: ProductApiResponse::class)]13#[ExternalApi(version: 'v1')]14#[ApiVersion(version: '1.0.0')]15final class ProductDetailPayload16{17    protected string $slug = '';1819    public function getSlug(): string { return $this->slug; }20    public function setSlug(string $slug): void { $this->slug = trim($slug); }21}22

<?php

declare(strict_types=1);

namespace App\Api\Product;

use App\Api\Product\ProductApiResponse;
use Semitexa\Api\Attribute\ApiVersion;
use Semitexa\Api\Attribute\ExternalApi;
use Semitexa\Core\Attribute\AsPublicPayload;

#[AsPublicPayload(path: '/api/v1/products/{slug}', methods: ['GET'], responseWith: ProductApiResponse::class)]
#[ExternalApi(version: 'v1')]
#[ApiVersion(version: '1.0.0')]
final class ProductDetailPayload
{
    protected string $slug = '';

    public function getSlug(): string { return $this->slug; }
    public function setSlug(string $slug): void { $this->slug = trim($slug); }
}

1<?php23declare(strict_types=1);45namespace App\Application\Api;67final class DemoApiPresenter8{9    public function productList(array $products): array10    {11        return [12            'data' => array_map(13                static fn (array $product): array => [14                    'id' => $product['id'],15                    'name' => $product['name'],16                    'price' => $product['price'],17                ],18                $products,19            ),20        ];21    }22}23

<?php

declare(strict_types=1);

namespace App\Application\Api;

final class DemoApiPresenter
{
    public function productList(array $products): array
    {
        return [
            'data' => array_map(
                static fn (array $product): array => [
                    'id' => $product['id'],
                    'name' => $product['name'],
                    'price' => $product['price'],
                ],
                $products,
            ),
        ];
    }
}

Contract Notes

What this explorer is proving

Operation	What changes	Why it matters
`GET /demo/api/v1/products/_schema`	Raw JSON schema contract for the product representation.	Consumers can validate the contract before writing integration code.
`GET /demo/api/v1/products/_schema`	Same contract, explicit schema media type for machine tooling.	Consumers can validate the contract before writing integration code.
`GET /demo/api/v1/products/wireless-headphones?fields=slug,name,price`	Sparse fieldset proving the contract can be trimmed intentionally.	Consumers can validate the contract before writing integration code.
`GET /demo/api/v1/products/wireless-headphones?profile=full&expand=category,reviews`	Expanded graph with review data for internal dashboards and rich clients.	Consumers can validate the contract before writing integration code.

How it works

Why it matters

This is closer to how people evaluate APIs in practice: they want to poke the contract, compare responses, and confirm the system shape without wiring Postman first.

Key concepts

_schema: Machine-facing schema endpoint returning JSON Schema for the product contract.
application/schema+json: Explicit media type for tooling that consumes JSON Schema documents.
Sparse fieldset: A client asks for only the fields it needs via `fields=...`.

Find a concept, task, or command

Schema Discovery

What this does

How it works

Why it matters

Key concepts

Mini Swagger for the live Semitexa API

GET schema

Schema Discovery

How it works

Why this matters

What this explorer is proving

How it works

Why it matters

Key concepts