From 969c71aa8e3cf1ec17121f00bfdd6190e6ab0880 Mon Sep 17 00:00:00 2001
From: "t.munk (workhorse)" <t.munk@herzogkommunikation.de>
Date: Thu, 8 Oct 2026 11:57:12 +0000
Subject: [PATCH 1/3] feat(metadata): generate order parameters for collection
 operations (spike) [*]

Opt-in auto_order: a metadata factory decorating with priority 1100
adds one SortFilter QueryParameter per sortable scalar field and per
to-one relation label, skipping properties with an explicit
OrderFilter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 config/services_auto_order.yaml               |  20 ++
 .../ApiPlatformUtilsExtension.php             |  10 +-
 src/DependencyInjection/Configuration.php     |  13 +-
 ...OrderResourceMetadataCollectionFactory.php | 255 ++++++++++++++++++
 4 files changed, 296 insertions(+), 2 deletions(-)
 create mode 100644 config/services_auto_order.yaml
 create mode 100644 src/Metadata/AutoOrderResourceMetadataCollectionFactory.php

diff --git a/config/services_auto_order.yaml b/config/services_auto_order.yaml
new file mode 100644
index 0000000..3360ecc
--- /dev/null
+++ b/config/services_auto_order.yaml
@@ -0,0 +1,20 @@
+# file generated with AI assistance: Claude Code - 2026-10-08 12:00:00 UTC
+
+services:
+    _defaults:
+        autowire: false
+        autoconfigure: false
+        public: false
+
+    # Auto-generated order[<property>] query parameters (SortFilter) for
+    # GetCollection operations of Doctrine ORM resources. Priority 1100 runs
+    # before API Platform's parameter factory (1000), which completes schema,
+    # OpenAPI and nested_properties_info of the generated parameters.
+    Dmstr\ApiPlatformUtils\Metadata\AutoOrderResourceMetadataCollectionFactory:
+        decorates: 'api_platform.metadata.resource.metadata_collection_factory'
+        decoration_priority: 1100
+        arguments:
+            $decorated: '@.inner'
+            $managerRegistry: '@doctrine'
+            $labelPropertyCandidates: '%dmstr_api_platform_utils.relation_field_decorator.label_property_candidates%'
+            $orderParameterName: '%api_platform.collection.order_parameter_name%'
diff --git a/src/DependencyInjection/ApiPlatformUtilsExtension.php b/src/DependencyInjection/ApiPlatformUtilsExtension.php
index f20687d..9597791 100644
--- a/src/DependencyInjection/ApiPlatformUtilsExtension.php
+++ b/src/DependencyInjection/ApiPlatformUtilsExtension.php
@@ -1,5 +1,5 @@
 <?php
-// file generated with AI assistance: Claude Code - 2025-11-22
+// file generated with AI assistance: Claude Code - 2025-11-22, revised 2026-10-08 12:00:00 UTC
 
 declare(strict_types=1);
 
@@ -42,6 +42,8 @@ public function load(array $configs, ContainerBuilder $container): void
 
         $container->setParameter('dmstr_api_platform_utils.partial_uuid_item_provider.enabled', $config['partial_uuid_item_provider']['enabled']);
 
+        $container->setParameter('dmstr_api_platform_utils.auto_order.enabled', $config['auto_order']['enabled']);
+
         // Load service definitions
         $loader = new YamlFileLoader($container, new FileLocator(__DIR__ . '/../../config'));
         $loader->load('services.yaml');
@@ -52,6 +54,12 @@ public function load(array $configs, ContainerBuilder $container): void
         if ($config['partial_uuid_item_provider']['enabled']) {
             $loader->load('services_partial_uuid.yaml');
         }
+
+        // Conditionally load the auto-order metadata factory. Off by default:
+        // it adds query parameters to every Doctrine GetCollection operation.
+        if ($config['auto_order']['enabled']) {
+            $loader->load('services_auto_order.yaml');
+        }
     }
 
     public function getAlias(): string
diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php
index 2aea5d2..ec719e7 100644
--- a/src/DependencyInjection/Configuration.php
+++ b/src/DependencyInjection/Configuration.php
@@ -1,5 +1,5 @@
 <?php
-// file generated with AI assistance: Claude Code - 2025-11-22
+// file generated with AI assistance: Claude Code - 2025-11-22, revised 2026-10-08 12:00:00 UTC
 
 declare(strict_types=1);
 
@@ -113,6 +113,17 @@ public function getConfigTreeBuilder(): TreeBuilder
                     ->end()
                 ->end()
 
+                // Auto-generated order[<property>] parameters
+                ->arrayNode('auto_order')
+                    ->addDefaultsIfNotSet()
+                    ->children()
+                        ->booleanNode('enabled')
+                            ->defaultFalse()
+                            ->info('Generate order[<property>] query parameters (SortFilter) for the GetCollection operations of Doctrine ORM resources: sortable scalar fields and to-one relations via their label property (relation_field_decorator.label_property_candidates). Properties with an explicit #[ApiFilter(OrderFilter::class)] are left alone.')
+                        ->end()
+                    ->end()
+                ->end()
+
                 // Partial UUID Item Provider
                 ->arrayNode('partial_uuid_item_provider')
                     ->addDefaultsIfNotSet()
diff --git a/src/Metadata/AutoOrderResourceMetadataCollectionFactory.php b/src/Metadata/AutoOrderResourceMetadataCollectionFactory.php
new file mode 100644
index 0000000..78f0f48
--- /dev/null
+++ b/src/Metadata/AutoOrderResourceMetadataCollectionFactory.php
@@ -0,0 +1,255 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:00:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Metadata;
+
+use ApiPlatform\Doctrine\Common\Filter\OrderFilterInterface;
+use ApiPlatform\Doctrine\Orm\Filter\SortFilter;
+use ApiPlatform\Metadata\ApiFilter;
+use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\Operations;
+use ApiPlatform\Metadata\Parameters;
+use ApiPlatform\Metadata\QueryParameter;
+use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
+use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
+use Doctrine\ORM\Mapping\ClassMetadata;
+use Doctrine\Persistence\ManagerRegistry;
+
+/**
+ * Generates `order[<property>]` query parameters (backed by API Platform's
+ * {@see SortFilter}) for the GetCollection operations of Doctrine ORM
+ * resources, so that every sortable column is declared by the backend
+ * without a hand-written `#[ApiFilter(OrderFilter::class, ...)]`.
+ *
+ * Generated parameters:
+ *   - scalar Doctrine fields whose DBAL type is in {@see SORTABLE_TYPES}
+ *     (identifiers, text, json, binary, vector etc. are skipped);
+ *   - to-one associations (ManyToOne, owning OneToOne) as `<rel>.<label>`,
+ *     where `<label>` is the first configured label property candidate that
+ *     is a sortable field of the target entity. No candidate, no parameter.
+ *
+ * Properties covered by an explicit `#[ApiFilter(OrderFilter::class)]`
+ * (class or property level) are left alone, so the explicit filter wins and
+ * no variable is documented twice. A class-level OrderFilter without
+ * `properties` covers every property and disables auto-ordering for the
+ * resource.
+ *
+ * Decoration priority must be higher than 1000: the factory then runs
+ * BEFORE API Platform's ParameterResourceMetadataCollectionFactory, which
+ * fills in schema, OpenAPI parameter and `nested_properties_info` (needed by
+ * SortFilter to join the relation) for the parameters added here.
+ * Consequence: `#[ApiFilter]` attributes are not merged into the operation
+ * yet (that happens at priority 200), hence they are read via reflection.
+ */
+final class AutoOrderResourceMetadataCollectionFactory implements ResourceMetadataCollectionFactoryInterface
+{
+    /** DBAL type names that can be sorted meaningfully. */
+    public const SORTABLE_TYPES = [
+        'string', 'ascii_string',
+        'integer', 'smallint', 'bigint',
+        'float', 'smallfloat', 'decimal',
+        'boolean',
+        'date', 'date_immutable',
+        'datetime', 'datetime_immutable',
+        'datetimetz', 'datetimetz_immutable',
+        'time', 'time_immutable',
+    ];
+
+    /**
+     * @param list<string> $labelPropertyCandidates
+     */
+    public function __construct(
+        private readonly ResourceMetadataCollectionFactoryInterface $decorated,
+        private readonly ManagerRegistry $managerRegistry,
+        private readonly array $labelPropertyCandidates = ['name', 'title', 'label', 'displayName'],
+        private readonly string $orderParameterName = 'order',
+    ) {
+    }
+
+    public function create(string $resourceClass): ResourceMetadataCollection
+    {
+        $collection = $this->decorated->create($resourceClass);
+
+        foreach ($collection as $i => $resource) {
+            $operations = $resource->getOperations();
+            if (null === $operations || 0 === \count($operations)) {
+                continue;
+            }
+
+            $changed = false;
+            $rebuilt = [];
+            foreach ($operations as $name => $operation) {
+                if ($operation instanceof GetCollection && null === $operation->getProvider()) {
+                    $entityClass = $operation->getClass() ?? $resourceClass;
+                    $properties = $this->sortableProperties($entityClass);
+                    if ([] !== $properties) {
+                        $operation = $operation->withParameters($this->addParameters($operation->getParameters(), $properties));
+                        $changed = true;
+                    }
+                }
+                $rebuilt[$name] = $operation;
+            }
+
+            if ($changed) {
+                $collection[$i] = $resource->withOperations(new Operations($rebuilt));
+            }
+        }
+
+        return $collection;
+    }
+
+    /**
+     * One QueryParameter per property (`order[<p>]` with `property: <p>`).
+     * Parameters the resource already declares under the same key win.
+     *
+     * A single `order[:property]` parameter with `properties: [...]` yields
+     * the same metadata after API Platform's placeholder expansion, but the
+     * per-key form allows the collision check below and keeps each
+     * parameter independent of the others.
+     *
+     * @param list<string> $properties
+     */
+    private function addParameters(?Parameters $parameters, array $properties): Parameters
+    {
+        // clone: the attribute-level Parameters instance must not be mutated
+        $parameters = null === $parameters ? new Parameters() : clone $parameters;
+
+        foreach ($properties as $property) {
+            $key = \sprintf('%s[%s]', $this->orderParameterName, $property);
+            if ($parameters->has($key)) {
+                continue;
+            }
+            $parameters->add($key, new QueryParameter(
+                key: $key,
+                property: $property,
+                filter: new SortFilter(),
+                // a single direction, no `order[p][]` variant in OpenAPI
+                castToArray: false,
+            ));
+        }
+
+        return $parameters;
+    }
+
+    /**
+     * @return list<string> property paths, `<field>` or `<relation>.<label>`
+     */
+    private function sortableProperties(string $entityClass): array
+    {
+        $metadata = $this->classMetadata($entityClass);
+        if (null === $metadata) {
+            return [];
+        }
+
+        $explicit = $this->explicitOrderProperties($metadata->getReflectionClass());
+        if (null === $explicit) {
+            return [];
+        }
+
+        $properties = [];
+        foreach ($metadata->getFieldNames() as $field) {
+            if ($this->isSortableField($metadata, $field) && !\in_array($field, $explicit, true)) {
+                $properties[] = $field;
+            }
+        }
+
+        foreach ($metadata->getAssociationNames() as $association) {
+            if (!$metadata->isSingleValuedAssociation($association) || $metadata->isAssociationInverseSide($association)) {
+                continue;
+            }
+            $target = $this->classMetadata($metadata->getAssociationTargetClass($association));
+            $label = null === $target ? null : $this->labelProperty($target);
+            if (null === $label) {
+                continue;
+            }
+            $path = $association.'.'.$label;
+            if (!\in_array($path, $explicit, true)) {
+                $properties[] = $path;
+            }
+        }
+
+        return $properties;
+    }
+
+    private function isSortableField(ClassMetadata $metadata, string $field): bool
+    {
+        // embedded fields ("embed.field") and identifiers are not offered
+        if (str_contains($field, '.') || $metadata->isIdentifier($field)) {
+            return false;
+        }
+
+        return \in_array($metadata->getTypeOfField($field), self::SORTABLE_TYPES, true);
+    }
+
+    /**
+     * Same candidate list as RelationFieldSchemaDecorator::inferLabelProperty(),
+     * but without its "first string property" fallback: sorting by an
+     * arbitrary string would look like a feature and be noise.
+     */
+    private function labelProperty(ClassMetadata $target): ?string
+    {
+        foreach ($this->labelPropertyCandidates as $candidate) {
+            if ($target->hasField($candidate) && $this->isSortableField($target, $candidate)) {
+                return $candidate;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Properties covered by an explicit `#[ApiFilter(OrderFilter::class)]`.
+     *
+     * @return list<string>|null null = a class-level OrderFilter without
+     *                           `properties` covers every property
+     */
+    private function explicitOrderProperties(\ReflectionClass $class): ?array
+    {
+        $explicit = [];
+
+        foreach ($class->getAttributes(ApiFilter::class, \ReflectionAttribute::IS_INSTANCEOF) as $attribute) {
+            $filter = $attribute->newInstance();
+            if (!is_a($filter->filterClass, OrderFilterInterface::class, true)) {
+                continue;
+            }
+            if ([] === $filter->properties) {
+                return null;
+            }
+            foreach ($filter->properties as $key => $value) {
+                // list form ['createdAt'] or map form ['createdAt' => 'DESC']
+                $explicit[] = \is_int($key) ? (string) $value : (string) $key;
+            }
+        }
+
+        foreach ($class->getProperties() as $property) {
+            foreach ($property->getAttributes(ApiFilter::class, \ReflectionAttribute::IS_INSTANCEOF) as $attribute) {
+                $filter = $attribute->newInstance();
+                if (!is_a($filter->filterClass, OrderFilterInterface::class, true)) {
+                    continue;
+                }
+                $explicit[] = $property->getName();
+                foreach ($filter->properties as $key => $value) {
+                    $explicit[] = $property->getName().'.'.(\is_int($key) ? (string) $value : (string) $key);
+                }
+            }
+        }
+
+        return $explicit;
+    }
+
+    private function classMetadata(string $class): ?ClassMetadata
+    {
+        $manager = $this->managerRegistry->getManagerForClass($class);
+        if (null === $manager) {
+            return null;
+        }
+        $metadata = $manager->getClassMetadata($class);
+        if (!$metadata instanceof ClassMetadata || $metadata->isMappedSuperclass || $metadata->isEmbeddedClass) {
+            return null;
+        }
+
+        return $metadata;
+    }
+}

From 5f921314c991b7bb8dc980b0edae8bbacb24834a Mon Sep 17 00:00:00 2001
From: "t.munk (workhorse)" <t.munk@herzogkommunikation.de>
Date: Thu, 8 Oct 2026 12:15:35 +0000
Subject: [PATCH 2/3] feat(metadata): auto order, stable order and output
 relation labels [*]

- auto_order: per-property SortFilter parameters for readable scalar
  fields and to-one relation labels (candidates only), identifiers
  excluded, explicit OrderFilter wins, #[AutoOrder] per entity,
  configurable default_order (name ASC, createdAt DESC)
- stable_order: StableOrderExtension (priority -40) appends the
  identifier as tie-breaker for stable pagination
- output schemas carry x-label-property and x-resource-class
- email added to the default label property candidates
- CHANGELOG: 0.4.0 section for the hydra:operation filtering

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  17 +-
 README.md                                     |  68 +++-
 composer.json                                 |   3 +-
 config/services_auto_order.yaml               |  14 +-
 config/services_stable_order.yaml             |  14 +
 src/Attribute/AutoOrder.php                   |  52 +++
 .../ApiPlatformUtilsExtension.php             |  19 +-
 src/DependencyInjection/Configuration.php     |  38 +-
 .../Orm/Extension/StableOrderExtension.php    |  77 ++++
 ...OrderResourceMetadataCollectionFactory.php | 248 ++++++++++---
 src/OpenApi/RelationFieldSchemaDecorator.php  | 164 ++++++++-
 .../ApiPlatformUtilsExtensionTest.php         |  93 +++++
 .../Extension/StableOrderExtensionTest.php    | 107 ++++++
 tests/Fixtures/AutoOrder/Author.php           |  26 ++
 tests/Fixtures/AutoOrder/AuthorView.php       |  13 +
 tests/Fixtures/AutoOrder/Book.php             |  51 +++
 tests/Fixtures/AutoOrder/CompositeKey.php     |  23 ++
 tests/Fixtures/AutoOrder/DisabledBook.php     |  21 ++
 tests/Fixtures/AutoOrder/ExcludedBook.php     |  30 ++
 .../Fixtures/AutoOrder/ExplicitOrderBook.php  |  30 ++
 tests/Fixtures/AutoOrder/MetadataLoader.php   |  32 ++
 tests/Fixtures/AutoOrder/OrderAllBook.php     |  23 ++
 tests/Fixtures/AutoOrder/Publisher.php        |  20 ++
 ...rResourceMetadataCollectionFactoryTest.php | 328 ++++++++++++++++++
 .../RelationFieldSchemaDecoratorTest.php      | 145 ++++++++
 25 files changed, 1597 insertions(+), 59 deletions(-)
 create mode 100644 config/services_stable_order.yaml
 create mode 100644 src/Attribute/AutoOrder.php
 create mode 100644 src/Doctrine/Orm/Extension/StableOrderExtension.php
 create mode 100644 tests/DependencyInjection/ApiPlatformUtilsExtensionTest.php
 create mode 100644 tests/Doctrine/Orm/Extension/StableOrderExtensionTest.php
 create mode 100644 tests/Fixtures/AutoOrder/Author.php
 create mode 100644 tests/Fixtures/AutoOrder/AuthorView.php
 create mode 100644 tests/Fixtures/AutoOrder/Book.php
 create mode 100644 tests/Fixtures/AutoOrder/CompositeKey.php
 create mode 100644 tests/Fixtures/AutoOrder/DisabledBook.php
 create mode 100644 tests/Fixtures/AutoOrder/ExcludedBook.php
 create mode 100644 tests/Fixtures/AutoOrder/ExplicitOrderBook.php
 create mode 100644 tests/Fixtures/AutoOrder/MetadataLoader.php
 create mode 100644 tests/Fixtures/AutoOrder/OrderAllBook.php
 create mode 100644 tests/Fixtures/AutoOrder/Publisher.php
 create mode 100644 tests/Metadata/AutoOrderResourceMetadataCollectionFactoryTest.php
 create mode 100644 tests/OpenApi/RelationFieldSchemaDecoratorTest.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 38127e1..6e7c885 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,4 @@
-<!-- file generated with AI assistance: Claude Code - 2026-07-22 -->
+<!-- file generated with AI assistance: Claude Code - 2026-07-22, revised 2026-10-08 13:30:00 UTC -->
 
 # Changelog
 
@@ -6,6 +6,21 @@
 
 ### Added
 
+- `auto_order` (opt-in, default off): generated `order[<property>]` query parameters (API Platform `SortFilter`) for the `GetCollection` operations of Doctrine ORM resources — sortable scalar fields (type whitelist, identifiers excluded) and to-one relations as `order[<relation>.<label>]`, label from `relation_field_decorator.label_property_candidates` only. Only API-readable properties (name collection, `readable`, normalization groups) are offered; explicit `#[ApiFilter(OrderFilter::class)]` declarations and parameters the operation declares itself win per property; operations with their own `provider` are skipped; DTO resources are mapped via `stateOptions` `entityClass`. Requires API Platform >= 4.3.
+- `auto_order.default_order` (default `{name: ASC, createdAt: DESC}`): default sort for `GetCollection` operations without an own `order`; the first key that is a sortable property of the resource wins.
+- `#[AutoOrder(enabled: false)]` / `#[AutoOrder(exclude: [...])]` attribute to switch auto-ordering off or restrict it per class.
+- `stable_order` (opt-in, default off): `StableOrderExtension` appends `ORDER BY <identifier> ASC` to Doctrine ORM collection queries that do not sort by the identifier yet (priority -40, between `OrderExtension` and pagination), for stable paging over non-unique sort columns. Skipped for composite/foreign identifiers and `GROUP BY` queries.
+- Output schemas: relation properties (`format: iri-reference`) get `x-label-property` and `x-resource-class` — label from the candidate list only, no `x-collection`/`x-value-property`/`x-search-property`, so read-only relations are not turned into pickers. Input schemas are unchanged.
+
+### Changed
+
+- `email` added to the default `relation_field_decorator.label_property_candidates` (`name`, `title`, `label`, `displayName`, `email`). Projects that set the list explicitly are not affected.
+- Label property candidates from several config files are de-duplicated (list nodes are appended to each other when merged).
+
+## 0.4.0 - 2026-07-22
+
+### Added
+
 - `hydra:operation` on collection GET responses (`hydra:Collection`): collection-level operations (create `POST`, custom collection actions), analogous to the existing item enrichment (#5)
 - Security filtering for `hydra:operation`: operations whose `security` expression does not grant access to the current token are omitted, evaluated via API Platform's `ResourceAccessChecker`; item operations are checked with the loaded entity as `object` (#5)
 - New config flag `hydra_operations.filter_operations_by_security` (default `true`) to switch the filtering off (#5)
diff --git a/README.md b/README.md
index 5d612ad..dc0aa7d 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-<!-- file generated with AI assistance: Claude Code - 2026-06-09 19:27:00 UTC -->
+<!-- file generated with AI assistance: Claude Code - 2026-06-09 19:27:00 UTC, revised 2026-10-08 13:35:00 UTC -->
 
 # dmstr/api-platform-utils-bundle
 
@@ -13,6 +13,8 @@ Generic helpers for API Platform projects.
   OpenAPI schema factory for autocomplete-rendered IRI collections
 - DB-JSON CLI tools (`db:export-json`, `db:import-json`)
 - `AbstractJsonSchemaInputCommand` base class for JSON-Schema-validated CLI
+- Generated sort parameters, default sort and a stable-pagination tie-breaker (`auto_order`, `#[AutoOrder]`, `stable_order`)
+- Relation label (`x-label-property`) in input and output schemas
 
 ## Hydra operations (`hydra:operation`)
 
@@ -49,6 +51,70 @@ dmstr_api_platform_utils:
 
 With filtering active, item and collection responses become **user-dependent**: the subscriber emits `Vary: Authorization` so shared HTTP caches never serve one user's operation set to another. The static `/api/docs.jsonld` stays role-independent and cacheable. If your stack caches API responses in a reverse proxy, verify it honors `Vary` — otherwise exclude these responses from caching.
 
+## Sorting
+
+### Generated sort parameters (`auto_order`)
+
+With `auto_order.enabled`, every `GetCollection` operation of a Doctrine ORM resource gets one `order[<property>]` query parameter per sortable property, backed by API Platform's `SortFilter`. They appear in the OpenAPI document and in `hydra:search`, so a client can derive its sortable columns from the API instead of guessing. Requires API Platform >= 4.3 (nested `SortFilter` support).
+
+Which properties get a parameter:
+
+- **Scalar fields** whose Doctrine type is sortable: `string`, `ascii_string`, `integer`, `smallint`, `bigint`, `float`, `smallfloat`, `decimal`, `boolean`, `date`, `datetime`, `datetimetz`, `time` (and their `_immutable` variants). Not offered: identifiers of any type, `text`, `json`, `array`/`simple_array`, `blob`/`binary`, `guid`/`uuid`, custom types such as `vector`, and embedded fields.
+- **To-one relations** (`ManyToOne`, owning `OneToOne`) as `order[<relation>.<label>]`, sorted by the related entity's label via a `LEFT JOIN` (rows without a relation stay in the list). The label is the first entry of `relation_field_decorator.label_property_candidates` that is a sortable, readable field of the target entity. There is no fallback: a relation without a candidate gets no parameter.
+- Only properties the API exposes: the property must be in API Platform's property name collection and readable with the operation's normalization groups. `#[ApiProperty(readable: false)]` and properties outside the groups get no parameter.
+
+Precedence and exclusions:
+
+- A parameter the operation declares itself under the same key wins.
+- An explicit `#[ApiFilter(OrderFilter::class, properties: [...])]` (class or property level) wins per property; a class-level `OrderFilter` without `properties` covers all properties, so no parameter is generated then. Order filters registered by service id (`ApiResource(filters: [...])`) are not recognised.
+- Operations with their own `provider` are skipped. DTO resources are mapped to their entity via `stateOptions: new Options(entityClass: ...)`; the DTO's properties decide what is exposed.
+
+```yaml
+dmstr_api_platform_utils:
+    relation_field_decorator:
+        label_property_candidates: [name, title, label, displayName, email]
+    auto_order:
+        enabled: true
+        # default sort for GetCollection operations without an own `order`
+        default_order:
+            name: ASC
+            createdAt: DESC
+```
+
+### Default sort (`auto_order.default_order`)
+
+A `GetCollection` operation without an own `order` gets the first entry of `default_order` that is a sortable property of the resource as its `order` (default: `name ASC`, else `createdAt DESC`). API Platform's `OrderExtension` applies it only when the client sends no sort parameter, so a client sort always replaces it. Without a match the operation keeps API Platform's own default (identifier). An empty map (`default_order: {}`) switches the default sort off. The map is replaced, not merged, when several config files set it.
+
+### Per class: `#[AutoOrder]`
+
+```php
+use Dmstr\ApiPlatformUtils\Attribute\AutoOrder;
+
+#[AutoOrder(enabled: false)]                      // no parameters, no default sort
+#[AutoOrder(exclude: ['hash', 'collection'])]     // no order[hash], no order[collection.<label>]
+```
+
+The attribute is read from the resource class and, for DTO resources, from the entity class too. An `exclude` entry matches the path and everything below it; excluded properties are no default sort candidates either.
+
+### Stable pagination (`stable_order`)
+
+Sorting by a non-unique column leaves the order of equal rows to the database, which may differ between two page requests: rows show up twice or never while paging. With `stable_order.enabled`, `StableOrderExtension` appends `ORDER BY <root>.<identifier> ASC` to every Doctrine ORM collection query whose ORDER BY does not contain the identifier yet. It is tagged with priority -40, after the sort (`OrderExtension`, -32) and before pagination (-64). Entities with a composite or foreign identifier and queries with `GROUP BY` are left alone.
+
+```yaml
+dmstr_api_platform_utils:
+    stable_order:
+        enabled: true
+```
+
+## Relation labels in schemas (`x-label-property`)
+
+`RelationFieldSchemaDecorator` adds `x-*` extensions to relation properties (`format: iri-reference`) of Doctrine resources:
+
+- **Input schemas** (forms): `x-collection`, `x-label-property`, `x-value-property`, `x-search-property`, `x-resource-class`, for autocomplete pickers. The label is the first candidate the target class declares, else its first string property.
+- **Output schemas** (read models, list columns): only `x-label-property` and `x-resource-class`, label from the candidate list only (no extension without a candidate). Without `x-collection` a read-only relation is not turned into a picker, while a list can still show and sort the relation by its label (`order[<relation>.<label>]`).
+
+Output processing touches only the definitions the built schema references, read with the Doctrine metadata of the operation's output class. When input and output share a definition name (no serialization groups, same format), that definition carries the input extensions.
+
 ## License
 
 MIT © diemeisterei GmbH
diff --git a/composer.json b/composer.json
index f9d703a..8fdd13f 100644
--- a/composer.json
+++ b/composer.json
@@ -33,7 +33,8 @@
         "psr/log": "^3.0"
     },
     "require-dev": {
-        "phpunit/phpunit": "^12.0"
+        "phpunit/phpunit": "^12.0",
+        "symfony/yaml": "^7.0"
     },
     "autoload": {
         "psr-4": {
diff --git a/config/services_auto_order.yaml b/config/services_auto_order.yaml
index 3360ecc..7ba4ee9 100644
--- a/config/services_auto_order.yaml
+++ b/config/services_auto_order.yaml
@@ -1,4 +1,4 @@
-# file generated with AI assistance: Claude Code - 2026-10-08 12:00:00 UTC
+# file generated with AI assistance: Claude Code - 2026-10-08 12:20:00 UTC
 
 services:
     _defaults:
@@ -6,15 +6,19 @@ services:
         autoconfigure: false
         public: false
 
-    # Auto-generated order[<property>] query parameters (SortFilter) for
-    # GetCollection operations of Doctrine ORM resources. Priority 1100 runs
-    # before API Platform's parameter factory (1000), which completes schema,
-    # OpenAPI and nested_properties_info of the generated parameters.
+    # Auto-generated order[<property>] query parameters (SortFilter) and the
+    # default sort for GetCollection operations of Doctrine ORM resources.
+    # Priority 1100 runs before API Platform's parameter factory (1000),
+    # which completes schema, OpenAPI and nested_properties_info of the
+    # generated parameters.
     Dmstr\ApiPlatformUtils\Metadata\AutoOrderResourceMetadataCollectionFactory:
         decorates: 'api_platform.metadata.resource.metadata_collection_factory'
         decoration_priority: 1100
         arguments:
             $decorated: '@.inner'
             $managerRegistry: '@doctrine'
+            $propertyNameCollectionFactory: '@api_platform.metadata.property.name_collection_factory'
+            $propertyMetadataFactory: '@api_platform.metadata.property.metadata_factory'
             $labelPropertyCandidates: '%dmstr_api_platform_utils.relation_field_decorator.label_property_candidates%'
+            $defaultOrder: '%dmstr_api_platform_utils.auto_order.default_order%'
             $orderParameterName: '%api_platform.collection.order_parameter_name%'
diff --git a/config/services_stable_order.yaml b/config/services_stable_order.yaml
new file mode 100644
index 0000000..336f17b
--- /dev/null
+++ b/config/services_stable_order.yaml
@@ -0,0 +1,14 @@
+# file generated with AI assistance: Claude Code - 2026-10-08 12:20:00 UTC
+
+services:
+    _defaults:
+        autowire: false
+        autoconfigure: false
+        public: false
+
+    # Tie-breaker for stable pagination: appends ORDER BY <identifier> ASC
+    # to collection queries. Priority -40 runs after OrderExtension (-32)
+    # and before pagination (-64).
+    Dmstr\ApiPlatformUtils\Doctrine\Orm\Extension\StableOrderExtension:
+        tags:
+            - { name: 'api_platform.doctrine.orm.query_extension.collection', priority: -40 }
diff --git a/src/Attribute/AutoOrder.php b/src/Attribute/AutoOrder.php
new file mode 100644
index 0000000..d602ab6
--- /dev/null
+++ b/src/Attribute/AutoOrder.php
@@ -0,0 +1,52 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:05:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Attribute;
+
+use Attribute;
+
+/**
+ * Per-class switch for the auto-generated `order[<property>]` parameters
+ * and the default sort (config `auto_order`, see
+ * {@see \Dmstr\ApiPlatformUtils\Metadata\AutoOrderResourceMetadataCollectionFactory}).
+ *
+ * Put it on the API resource class or on its Doctrine entity class (when
+ * they differ, e.g. a DTO resource with `stateOptions`); both are read.
+ *
+ * Examples:
+ *
+ *   // no generated sort parameters and no default sort for this resource
+ *   #[AutoOrder(enabled: false)]
+ *
+ *   // no order[hash] and no order[collection.<label>]
+ *   #[AutoOrder(exclude: ['hash', 'collection'])]
+ *
+ * An `exclude` entry matches the property path itself and everything below
+ * it: `collection` excludes `collection.name`. Excluded properties are not
+ * used for the default sort either.
+ */
+#[Attribute(Attribute::TARGET_CLASS)]
+final class AutoOrder
+{
+    /**
+     * @param list<string> $exclude property paths that get no generated parameter
+     */
+    public function __construct(
+        public readonly bool $enabled = true,
+        public readonly array $exclude = [],
+    ) {
+    }
+
+    public function excludes(string $path): bool
+    {
+        foreach ($this->exclude as $excluded) {
+            if ($path === $excluded || str_starts_with($path, $excluded.'.')) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}
diff --git a/src/DependencyInjection/ApiPlatformUtilsExtension.php b/src/DependencyInjection/ApiPlatformUtilsExtension.php
index 9597791..2ea6441 100644
--- a/src/DependencyInjection/ApiPlatformUtilsExtension.php
+++ b/src/DependencyInjection/ApiPlatformUtilsExtension.php
@@ -1,10 +1,12 @@
 <?php
-// file generated with AI assistance: Claude Code - 2025-11-22, revised 2026-10-08 12:00:00 UTC
+// file generated with AI assistance: Claude Code - 2025-11-22, revised 2026-10-08 12:25:00 UTC
 
 declare(strict_types=1);
 
 namespace Dmstr\ApiPlatformUtils\DependencyInjection;
 
+use ApiPlatform\Doctrine\Orm\Filter\SortFilter;
+use Symfony\Component\Config\Definition\Exception\InvalidConfigurationException;
 use Symfony\Component\Config\FileLocator;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Extension\Extension;
@@ -27,7 +29,8 @@ public function load(array $configs, ContainerBuilder $container): void
         $container->setParameter('dmstr_api_platform_utils.relation_field_decorator.enabled', $config['relation_field_decorator']['enabled']);
         $container->setParameter('dmstr_api_platform_utils.relation_field_decorator.api_prefix', $config['relation_field_decorator']['api_prefix']);
         $container->setParameter('dmstr_api_platform_utils.relation_field_decorator.decoration_priority', $config['relation_field_decorator']['decoration_priority']);
-        $container->setParameter('dmstr_api_platform_utils.relation_field_decorator.label_property_candidates', $config['relation_field_decorator']['label_property_candidates']);
+        // de-duplicated: list nodes of several config files are appended to each other
+        $container->setParameter('dmstr_api_platform_utils.relation_field_decorator.label_property_candidates', array_values(array_unique($config['relation_field_decorator']['label_property_candidates'])));
 
         $container->setParameter('dmstr_api_platform_utils.hydra_operations.enabled', $config['hydra_operations']['enabled']);
         $container->setParameter('dmstr_api_platform_utils.hydra_operations.api_prefix', $config['hydra_operations']['api_prefix']);
@@ -43,6 +46,9 @@ public function load(array $configs, ContainerBuilder $container): void
         $container->setParameter('dmstr_api_platform_utils.partial_uuid_item_provider.enabled', $config['partial_uuid_item_provider']['enabled']);
 
         $container->setParameter('dmstr_api_platform_utils.auto_order.enabled', $config['auto_order']['enabled']);
+        $container->setParameter('dmstr_api_platform_utils.auto_order.default_order', $config['auto_order']['default_order']);
+
+        $container->setParameter('dmstr_api_platform_utils.stable_order.enabled', $config['stable_order']['enabled']);
 
         // Load service definitions
         $loader = new YamlFileLoader($container, new FileLocator(__DIR__ . '/../../config'));
@@ -58,8 +64,17 @@ public function load(array $configs, ContainerBuilder $container): void
         // Conditionally load the auto-order metadata factory. Off by default:
         // it adds query parameters to every Doctrine GetCollection operation.
         if ($config['auto_order']['enabled']) {
+            if (!class_exists(SortFilter::class)) {
+                throw new InvalidConfigurationException('dmstr_api_platform_utils.auto_order requires API Platform >= 4.3 (ApiPlatform\\Doctrine\\Orm\\Filter\\SortFilter with nested property support).');
+            }
             $loader->load('services_auto_order.yaml');
         }
+
+        // Conditionally load the tie-breaker query extension. Off by default:
+        // it changes the ORDER BY of every Doctrine collection query.
+        if ($config['stable_order']['enabled']) {
+            $loader->load('services_stable_order.yaml');
+        }
     }
 
     public function getAlias(): string
diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php
index ec719e7..6ba26ae 100644
--- a/src/DependencyInjection/Configuration.php
+++ b/src/DependencyInjection/Configuration.php
@@ -1,5 +1,5 @@
 <?php
-// file generated with AI assistance: Claude Code - 2025-11-22, revised 2026-10-08 12:00:00 UTC
+// file generated with AI assistance: Claude Code - 2025-11-22, revised 2026-10-08 12:25:00 UTC
 
 declare(strict_types=1);
 
@@ -54,8 +54,8 @@ public function getConfigTreeBuilder(): TreeBuilder
                         ->end()
                         ->arrayNode('label_property_candidates')
                             ->scalarPrototype()->end()
-                            ->defaultValue(['name', 'title', 'label', 'displayName'])
-                            ->info('Property names to check for entity labels (in order of preference)')
+                            ->defaultValue(['name', 'title', 'label', 'displayName', 'email'])
+                            ->info('Property names to check for entity labels (in order of preference); also used by auto_order for the label of to-one relations')
                         ->end()
                     ->end()
                 ->end()
@@ -113,13 +113,41 @@ public function getConfigTreeBuilder(): TreeBuilder
                     ->end()
                 ->end()
 
-                // Auto-generated order[<property>] parameters
+                // Auto-generated order[<property>] parameters and default sort
                 ->arrayNode('auto_order')
                     ->addDefaultsIfNotSet()
                     ->children()
                         ->booleanNode('enabled')
                             ->defaultFalse()
-                            ->info('Generate order[<property>] query parameters (SortFilter) for the GetCollection operations of Doctrine ORM resources: sortable scalar fields and to-one relations via their label property (relation_field_decorator.label_property_candidates). Properties with an explicit #[ApiFilter(OrderFilter::class)] are left alone.')
+                            ->info('Generate order[<property>] query parameters (SortFilter) for the GetCollection operations of Doctrine ORM resources: sortable scalar fields and to-one relations via their label property (relation_field_decorator.label_property_candidates). Properties with an explicit #[ApiFilter(OrderFilter::class)] are left alone; #[AutoOrder] restricts or disables it per class. Requires API Platform >= 4.3.')
+                        ->end()
+                        ->arrayNode('default_order')
+                            ->info('Default sort for GetCollection operations without an own `order`: the first property that is sortable on the resource wins, e.g. {name: ASC, createdAt: DESC}. Empty map = no default sort (API Platform orders by identifier).')
+                            ->useAttributeAsKey('property')
+                            ->normalizeKeys(false)
+                            ->performNoDeepMerging()
+                            ->scalarPrototype()
+                                ->beforeNormalization()
+                                    ->ifString()
+                                    ->then(static fn (string $v): string => strtoupper($v))
+                                ->end()
+                                ->validate()
+                                    ->ifNotInArray(['ASC', 'DESC'])
+                                    ->thenInvalid('Invalid sort direction %s, expected ASC or DESC.')
+                                ->end()
+                            ->end()
+                            ->defaultValue(['name' => 'ASC', 'createdAt' => 'DESC'])
+                        ->end()
+                    ->end()
+                ->end()
+
+                // Tie-breaker for stable pagination
+                ->arrayNode('stable_order')
+                    ->addDefaultsIfNotSet()
+                    ->children()
+                        ->booleanNode('enabled')
+                            ->defaultFalse()
+                            ->info('Append ORDER BY <identifier> ASC to Doctrine ORM collection queries whose ORDER BY does not contain the identifier, so that paging over a non-unique sort column is stable. Skipped for composite/foreign identifiers and GROUP BY queries.')
                         ->end()
                     ->end()
                 ->end()
diff --git a/src/Doctrine/Orm/Extension/StableOrderExtension.php b/src/Doctrine/Orm/Extension/StableOrderExtension.php
new file mode 100644
index 0000000..c0faf46
--- /dev/null
+++ b/src/Doctrine/Orm/Extension/StableOrderExtension.php
@@ -0,0 +1,77 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:20:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Doctrine\Orm\Extension;
+
+use ApiPlatform\Doctrine\Orm\Extension\QueryCollectionExtensionInterface;
+use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
+use ApiPlatform\Metadata\Operation;
+use Doctrine\ORM\Query\Expr\OrderBy;
+use Doctrine\ORM\QueryBuilder;
+
+/**
+ * Tie-breaker for stable pagination: appends `ORDER BY <root>.<identifier>
+ * ASC` to collection queries whose ORDER BY does not contain the identifier
+ * yet.
+ *
+ * Sorting by a non-unique column (status, a name with duplicates, a date)
+ * leaves the order of equal rows to the database, which may differ between
+ * two page requests, so rows can show up twice or never while paging. The
+ * identifier as the last sort key makes the order total.
+ *
+ * Runs after API Platform's sort (filters/parameters at -16, OrderExtension
+ * at -32) and before pagination (-64): tagged with priority -40.
+ *
+ * Skipped: entities with a composite or foreign identifier (like
+ * OrderExtension does) and queries with GROUP BY, where an extra ORDER BY
+ * column may not be valid SQL.
+ */
+final class StableOrderExtension implements QueryCollectionExtensionInterface
+{
+    public function applyToCollection(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, ?string $resourceClass = null, ?Operation $operation = null, array $context = []): void
+    {
+        $rootEntities = $queryBuilder->getRootEntities();
+        $rootAliases = $queryBuilder->getRootAliases();
+        if (!isset($rootEntities[0], $rootAliases[0])) {
+            return;
+        }
+
+        if ([] !== ($queryBuilder->getDQLPart('groupBy') ?? [])) {
+            return;
+        }
+
+        $metadata = $queryBuilder->getEntityManager()->getClassMetadata($rootEntities[0]);
+        if ($metadata->containsForeignIdentifier || $metadata->isIdentifierComposite) {
+            return;
+        }
+
+        $identifiers = $metadata->getIdentifierFieldNames();
+        if (1 !== \count($identifiers)) {
+            return;
+        }
+
+        $field = $rootAliases[0].'.'.$identifiers[0];
+        if ($this->isOrderedBy($queryBuilder, $field)) {
+            return;
+        }
+
+        $queryBuilder->addOrderBy($field, 'ASC');
+    }
+
+    private function isOrderedBy(QueryBuilder $queryBuilder, string $field): bool
+    {
+        foreach ($queryBuilder->getDQLPart('orderBy') ?? [] as $orderBy) {
+            $parts = $orderBy instanceof OrderBy ? $orderBy->getParts() : [(string) $orderBy];
+            foreach ($parts as $part) {
+                // a part is "<expression> <direction>", e.g. "o.id ASC"
+                if (strtok(trim((string) $part), " \t") === $field) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+}
diff --git a/src/Metadata/AutoOrderResourceMetadataCollectionFactory.php b/src/Metadata/AutoOrderResourceMetadataCollectionFactory.php
index 78f0f48..84e0a1c 100644
--- a/src/Metadata/AutoOrderResourceMetadataCollectionFactory.php
+++ b/src/Metadata/AutoOrderResourceMetadataCollectionFactory.php
@@ -1,5 +1,5 @@
 <?php
-// file generated with AI assistance: Claude Code - 2026-10-08 12:00:00 UTC
+// file generated with AI assistance: Claude Code - 2026-10-08 12:10:00 UTC
 
 declare(strict_types=1);
 
@@ -7,13 +7,17 @@
 
 use ApiPlatform\Doctrine\Common\Filter\OrderFilterInterface;
 use ApiPlatform\Doctrine\Orm\Filter\SortFilter;
+use ApiPlatform\Doctrine\Orm\State\Options as OrmOptions;
 use ApiPlatform\Metadata\ApiFilter;
 use ApiPlatform\Metadata\GetCollection;
 use ApiPlatform\Metadata\Operations;
 use ApiPlatform\Metadata\Parameters;
+use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
+use ApiPlatform\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
 use ApiPlatform\Metadata\QueryParameter;
 use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
 use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
+use Dmstr\ApiPlatformUtils\Attribute\AutoOrder;
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\Persistence\ManagerRegistry;
 
@@ -21,20 +25,38 @@
  * Generates `order[<property>]` query parameters (backed by API Platform's
  * {@see SortFilter}) for the GetCollection operations of Doctrine ORM
  * resources, so that every sortable column is declared by the backend
- * without a hand-written `#[ApiFilter(OrderFilter::class, ...)]`.
+ * without a hand-written `#[ApiFilter(OrderFilter::class, ...)]`, and sets a
+ * default sort on operations that declare none.
  *
  * Generated parameters:
  *   - scalar Doctrine fields whose DBAL type is in {@see SORTABLE_TYPES}
- *     (identifiers, text, json, binary, vector etc. are skipped);
+ *     (identifiers of any type, text, json, binary, vector etc. are skipped);
  *   - to-one associations (ManyToOne, owning OneToOne) as `<rel>.<label>`,
  *     where `<label>` is the first configured label property candidate that
- *     is a sortable field of the target entity. No candidate, no parameter.
+ *     is a sortable, readable field of the target entity. No candidate, no
+ *     parameter (there is deliberately no "first string property" fallback).
  *
- * Properties covered by an explicit `#[ApiFilter(OrderFilter::class)]`
- * (class or property level) are left alone, so the explicit filter wins and
- * no variable is documented twice. A class-level OrderFilter without
- * `properties` covers every property and disables auto-ordering for the
- * resource.
+ * Only properties the API actually exposes are offered: a property must be
+ * in the resource's property name collection and readable with the
+ * operation's normalization groups (`#[ApiProperty(readable: false)]` and
+ * properties outside the groups are skipped).
+ *
+ * Precedence: a parameter the operation already declares under the same key
+ * wins, and so does an explicit `#[ApiFilter(OrderFilter::class)]` (class or
+ * property level) per property. A class-level OrderFilter without
+ * `properties` covers every property, so no parameter is generated then.
+ * `#[AutoOrder(enabled: false)]` switches a class off, `#[AutoOrder(exclude:
+ * [...])]` drops single properties.
+ *
+ * Default sort: when the operation has no `order`, the first key of the
+ * configured default order that is a sortable property of the resource
+ * becomes the operation's `order`. API Platform's OrderExtension applies it
+ * only when the client sends no sort parameter. Without a match the
+ * operation keeps API Platform's own default (identifier).
+ *
+ * Skipped operations: non-GetCollection operations, operations with their
+ * own `provider`, and classes that are not Doctrine ORM entities. A DTO
+ * resource is mapped to its entity via `stateOptions: new Options(entityClass: ...)`.
  *
  * Decoration priority must be higher than 1000: the factory then runs
  * BEFORE API Platform's ParameterResourceMetadataCollectionFactory, which
@@ -42,6 +64,8 @@
  * SortFilter to join the relation) for the parameters added here.
  * Consequence: `#[ApiFilter]` attributes are not merged into the operation
  * yet (that happens at priority 200), hence they are read via reflection.
+ * Filters registered by service id (`ApiResource(filters: [...])`) are not
+ * recognised.
  */
 final class AutoOrderResourceMetadataCollectionFactory implements ResourceMetadataCollectionFactoryInterface
 {
@@ -58,12 +82,16 @@ final class AutoOrderResourceMetadataCollectionFactory implements ResourceMetada
     ];
 
     /**
-     * @param list<string> $labelPropertyCandidates
+     * @param list<string>          $labelPropertyCandidates relation label candidates, in order of preference
+     * @param array<string, string> $defaultOrder            property => ASC|DESC, first sortable key wins
      */
     public function __construct(
         private readonly ResourceMetadataCollectionFactoryInterface $decorated,
         private readonly ManagerRegistry $managerRegistry,
-        private readonly array $labelPropertyCandidates = ['name', 'title', 'label', 'displayName'],
+        private readonly PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory,
+        private readonly PropertyMetadataFactoryInterface $propertyMetadataFactory,
+        private readonly array $labelPropertyCandidates = ['name', 'title', 'label', 'displayName', 'email'],
+        private readonly array $defaultOrder = ['name' => 'ASC', 'createdAt' => 'DESC'],
         private readonly string $orderParameterName = 'order',
     ) {
     }
@@ -82,11 +110,25 @@ public function create(string $resourceClass): ResourceMetadataCollection
             $rebuilt = [];
             foreach ($operations as $name => $operation) {
                 if ($operation instanceof GetCollection && null === $operation->getProvider()) {
-                    $entityClass = $operation->getClass() ?? $resourceClass;
-                    $properties = $this->sortableProperties($entityClass);
-                    if ([] !== $properties) {
-                        $operation = $operation->withParameters($this->addParameters($operation->getParameters(), $properties));
-                        $changed = true;
+                    $apiClass = $operation->getClass() ?? $resourceClass;
+                    $stateOptions = $operation->getStateOptions();
+                    $entityClass = $stateOptions instanceof OrmOptions && null !== $stateOptions->getEntityClass()
+                        ? $stateOptions->getEntityClass()
+                        : $apiClass;
+
+                    $groups = $operation->getNormalizationContext()['groups'] ?? null;
+                    $sortable = $this->sortableProperties($entityClass, $apiClass, null === $groups ? null : (array) $groups);
+
+                    if (null !== $sortable) {
+                        if ([] !== $sortable['generated']) {
+                            $operation = $operation->withParameters($this->addParameters($operation->getParameters(), $sortable['generated']));
+                            $changed = true;
+                        }
+
+                        if ([] === ($operation->getOrder() ?? []) && null !== ($order = $this->defaultOrderFor($sortable['all']))) {
+                            $operation = $operation->withOrder($order);
+                            $changed = true;
+                        }
                     }
                 }
                 $rebuilt[$name] = $operation;
@@ -124,6 +166,7 @@ private function addParameters(?Parameters $parameters, array $properties): Para
             $parameters->add($key, new QueryParameter(
                 key: $key,
                 property: $property,
+                description: $this->describe($property),
                 filter: new SortFilter(),
                 // a single direction, no `order[p][]` variant in OpenAPI
                 castToArray: false,
@@ -133,25 +176,62 @@ private function addParameters(?Parameters $parameters, array $properties): Para
         return $parameters;
     }
 
+    private function describe(string $property): string
+    {
+        if (false === $pos = strpos($property, '.')) {
+            return \sprintf('Sort by `%s` (asc or desc).', $property);
+        }
+
+        return \sprintf(
+            'Sort by `%s` of the related `%s` (asc or desc).',
+            substr($property, $pos + 1),
+            substr($property, 0, $pos),
+        );
+    }
+
     /**
-     * @return list<string> property paths, `<field>` or `<relation>.<label>`
+     * @param list<string> $sortable
+     *
+     * @return array<string, string>|null
      */
-    private function sortableProperties(string $entityClass): array
+    private function defaultOrderFor(array $sortable): ?array
+    {
+        foreach ($this->defaultOrder as $property => $direction) {
+            if (\in_array((string) $property, $sortable, true)) {
+                return [(string) $property => strtoupper($direction)];
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * @param list<string>|null $groups normalization groups of the operation
+     *
+     * @return array{all: list<string>, generated: list<string>}|null property
+     *         paths (`<field>` or `<relation>.<label>`): `all` sortable ones
+     *         (default sort candidates), `generated` those that get a
+     *         parameter; null = not a Doctrine entity or switched off
+     */
+    private function sortableProperties(string $entityClass, string $apiClass, ?array $groups): ?array
     {
         $metadata = $this->classMetadata($entityClass);
         if (null === $metadata) {
-            return [];
+            return null;
         }
 
-        $explicit = $this->explicitOrderProperties($metadata->getReflectionClass());
-        if (null === $explicit) {
-            return [];
+        $autoOrder = $this->autoOrder($apiClass, $entityClass);
+        if (false === $autoOrder?->enabled) {
+            return null;
         }
 
-        $properties = [];
+        $options = null === $groups ? [] : ['serializer_groups' => $groups];
+        $exposed = $this->exposedProperties($apiClass, $options);
+
+        $all = [];
         foreach ($metadata->getFieldNames() as $field) {
-            if ($this->isSortableField($metadata, $field) && !\in_array($field, $explicit, true)) {
-                $properties[] = $field;
+            if ($this->isSortableField($metadata, $field) && $this->isReadable($apiClass, $field, $options, $exposed)) {
+                $all[] = $field;
             }
         }
 
@@ -159,23 +239,30 @@ private function sortableProperties(string $entityClass): array
             if (!$metadata->isSingleValuedAssociation($association) || $metadata->isAssociationInverseSide($association)) {
                 continue;
             }
-            $target = $this->classMetadata($metadata->getAssociationTargetClass($association));
-            $label = null === $target ? null : $this->labelProperty($target);
-            if (null === $label) {
+            if (!$this->isReadable($apiClass, $association, $options, $exposed)) {
                 continue;
             }
-            $path = $association.'.'.$label;
-            if (!\in_array($path, $explicit, true)) {
-                $properties[] = $path;
+            $label = $this->labelProperty($metadata->getAssociationTargetClass($association));
+            if (null !== $label) {
+                $all[] = $association.'.'.$label;
             }
         }
 
-        return $properties;
+        if (null !== $autoOrder) {
+            $all = array_values(array_filter($all, static fn (string $path): bool => !$autoOrder->excludes($path)));
+        }
+
+        $explicit = $this->explicitOrderProperties(new \ReflectionClass($apiClass));
+        $generated = null === $explicit
+            ? []
+            : array_values(array_filter($all, static fn (string $path): bool => !\in_array($path, $explicit, true)));
+
+        return ['all' => $all, 'generated' => $generated];
     }
 
     private function isSortableField(ClassMetadata $metadata, string $field): bool
     {
-        // embedded fields ("embed.field") and identifiers are not offered
+        // embedded fields ("embed.field") and identifiers of any type are not offered
         if (str_contains($field, '.') || $metadata->isIdentifier($field)) {
             return false;
         }
@@ -184,21 +271,101 @@ private function isSortableField(ClassMetadata $metadata, string $field): bool
     }
 
     /**
-     * Same candidate list as RelationFieldSchemaDecorator::inferLabelProperty(),
-     * but without its "first string property" fallback: sorting by an
-     * arbitrary string would look like a feature and be noise.
+     * @param array<string, mixed> $options
+     *
+     * @return list<string>|null null = the name collection is not available
      */
-    private function labelProperty(ClassMetadata $target): ?string
+    private function exposedProperties(string $apiClass, array $options): ?array
     {
+        try {
+            return array_values(iterator_to_array($this->propertyNameCollectionFactory->create($apiClass, $options), false));
+        } catch (\Throwable) {
+            return null;
+        }
+    }
+
+    /**
+     * @param array<string, mixed> $options
+     * @param list<string>|null    $exposed
+     */
+    private function isReadable(string $apiClass, string $property, array $options, ?array $exposed): bool
+    {
+        if (null === $exposed || !\in_array($property, $exposed, true)) {
+            return false;
+        }
+
+        try {
+            return false !== $this->propertyMetadataFactory->create($apiClass, $property, $options)->isReadable();
+        } catch (\Throwable) {
+            return false;
+        }
+    }
+
+    /**
+     * First configured label candidate that is a sortable and readable field
+     * of the target entity. Same candidate list as
+     * RelationFieldSchemaDecorator, but without its "first string property"
+     * fallback: sorting by an arbitrary string would look like a feature and
+     * be noise.
+     */
+    private function labelProperty(string $targetClass): ?string
+    {
+        $target = $this->classMetadata($targetClass);
+        if (null === $target) {
+            return null;
+        }
+
         foreach ($this->labelPropertyCandidates as $candidate) {
-            if ($target->hasField($candidate) && $this->isSortableField($target, $candidate)) {
-                return $candidate;
+            if (!$target->hasField($candidate) || !$this->isSortableField($target, $candidate)) {
+                continue;
             }
+            try {
+                if (false === $this->propertyMetadataFactory->create($targetClass, $candidate)->isReadable()) {
+                    continue;
+                }
+            } catch (\Throwable) {
+                continue;
+            }
+
+            return $candidate;
         }
 
         return null;
     }
 
+    /**
+     * Merged `#[AutoOrder]` of the API class and the entity class: disabled
+     * if either disables it, exclusions are combined.
+     */
+    private function autoOrder(string $apiClass, string $entityClass): ?AutoOrder
+    {
+        $found = [];
+        foreach (array_unique([$apiClass, $entityClass]) as $class) {
+            if (!class_exists($class)) {
+                continue;
+            }
+            foreach ((new \ReflectionClass($class))->getAttributes(AutoOrder::class) as $attribute) {
+                $found[] = $attribute->newInstance();
+            }
+        }
+
+        if ([] === $found) {
+            return null;
+        }
+        if (1 === \count($found)) {
+            return $found[0];
+        }
+
+        $enabled = true;
+        $exclude = [];
+        foreach ($found as $autoOrder) {
+            $enabled = $enabled && $autoOrder->enabled;
+            $exclude = [...$exclude, ...$autoOrder->exclude];
+        }
+
+        return new AutoOrder($enabled, array_values(array_unique($exclude)));
+    }
+
     /**
      * Properties covered by an explicit `#[ApiFilter(OrderFilter::class)]`.
      *
@@ -241,6 +408,9 @@ private function explicitOrderProperties(\ReflectionClass $class): ?array
 
     private function classMetadata(string $class): ?ClassMetadata
     {
+        if (!class_exists($class)) {
+            return null;
+        }
         $manager = $this->managerRegistry->getManagerForClass($class);
         if (null === $manager) {
             return null;
diff --git a/src/OpenApi/RelationFieldSchemaDecorator.php b/src/OpenApi/RelationFieldSchemaDecorator.php
index 001db2a..595145f 100644
--- a/src/OpenApi/RelationFieldSchemaDecorator.php
+++ b/src/OpenApi/RelationFieldSchemaDecorator.php
@@ -1,5 +1,5 @@
 <?php
-// file generated with AI assistance: Claude Code - 2025-11-22
+// file generated with AI assistance: Claude Code - 2025-11-22, revised 2026-10-08 13:15:00 UTC
 
 declare(strict_types=1);
 
@@ -37,16 +37,30 @@
  *     "x-resource-class": "Customer"
  *   }
  * }
+ *
+ * Input schemas (forms) get all five extensions. Output schemas (read
+ * models, list columns) get only `x-label-property` and `x-resource-class`:
+ * `x-collection` there would make IRI picker editors claim read-only
+ * relations. The output label comes from the configured candidates only;
+ * a relation without a candidate gets no extension there (input schemas
+ * keep the "first string property" fallback). Output processing is limited to the definitions the built
+ * schema references directly, read with the Doctrine metadata of the
+ * operation's output class. When input and output share a definition name
+ * (no serialization groups, same format), the definition carries the input
+ * extensions.
  */
 class RelationFieldSchemaDecorator implements SchemaFactoryInterface
 {
+    /** Extensions that output (read) schemas get; the rest is input only. */
+    private const OUTPUT_EXTENSIONS = ['x-label-property', 'x-resource-class'];
+
     public function __construct(
         private readonly SchemaFactoryInterface $decorated,
         private readonly EntityManagerInterface $entityManager,
         private readonly ResourceMetadataCollectionFactoryInterface $resourceMetadataFactory,
         private readonly LoggerInterface $logger,
         private readonly string $apiPrefix = '/api',
-        private readonly array $labelPropertyCandidates = ['name', 'title', 'label', 'displayName']
+        private readonly array $labelPropertyCandidates = ['name', 'title', 'label', 'displayName', 'email']
     ) {
     }
 
@@ -69,7 +83,11 @@ public function buildSchema(
             $forceCollection
         );
 
-        // Only add extensions for INPUT schemas (forms)
+        if ($type === Schema::TYPE_OUTPUT) {
+            return $this->decorateOutputSchema($schema, $className, $operation);
+        }
+
+        // Full extensions for INPUT schemas (forms)
         if ($type !== Schema::TYPE_INPUT) {
             $this->logger->debug('Skipping RelationFieldSchemaDecorator for non-INPUT schema', [
                 'className' => $className,
@@ -127,6 +145,113 @@ public function buildSchema(
         return $schema;
     }
 
+    /**
+     * Adds `x-label-property` / `x-resource-class` to the relation properties
+     * of the definitions this output schema references (item definition, or
+     * the member items of a collection schema), including properties nested
+     * in `allOf` (JSON-LD wraps them next to the Hydra base schema).
+     */
+    private function decorateOutputSchema(Schema $schema, string $className, ?Operation $operation): Schema
+    {
+        $outputClass = $className;
+        if (null !== $operation) {
+            $output = $operation->getOutput();
+            if (false === $output) {
+                return $schema;
+            }
+            if (\is_string($output)) {
+                $outputClass = $output;
+            } elseif (\is_array($output) && \array_key_exists('class', $output)) {
+                if (null === $output['class']) {
+                    return $schema;
+                }
+                $outputClass = $output['class'];
+            }
+        }
+
+        try {
+            $metadata = $this->entityManager->getClassMetadata($outputClass);
+        } catch (\Exception) {
+            return $schema;
+        }
+
+        $definitions = $schema->getDefinitions();
+        $keys = $this->referencedDefinitionKeys($schema->getArrayCopy(false));
+        foreach ($keys as $key) {
+            if (!isset($definitions[$key])) {
+                continue;
+            }
+            $definition = $definitions[$key];
+            $definition = $this->withOutputExtensions($definition, $metadata);
+            if (\is_array($allOf = $definition['allOf'] ?? null)) {
+                foreach ($allOf as $i => $part) {
+                    if (\is_array($part) || $part instanceof \ArrayObject) {
+                        $allOf[$i] = $this->withOutputExtensions($part, $metadata);
+                    }
+                }
+                // reassign: ArrayObject elements cannot be modified indirectly
+                $definition['allOf'] = $allOf;
+            }
+            $definitions[$key] = $definition;
+        }
+
+        return $schema;
+    }
+
+    /**
+     * @param array<mixed>|\ArrayObject<mixed, mixed> $definition
+     *
+     * @return array<mixed>|\ArrayObject<mixed, mixed>
+     */
+    private function withOutputExtensions(array|\ArrayObject $definition, ClassMetadata $metadata): array|\ArrayObject
+    {
+        if (!isset($definition['properties']) || !is_iterable($definition['properties'])) {
+            return $definition;
+        }
+
+        $properties = $definition['properties'];
+        foreach ($properties as $propertyName => $propertyDef) {
+            if (($propertyDef['format'] ?? null) !== 'iri-reference') {
+                continue;
+            }
+            $extensions = $this->getRelationExtensions($metadata, (string) $propertyName, true);
+            if ($extensions === null) {
+                continue;
+            }
+            $properties[$propertyName] = array_merge(
+                \is_array($propertyDef) ? $propertyDef : (array) $propertyDef,
+                array_intersect_key($extensions, array_flip(self::OUTPUT_EXTENSIONS))
+            );
+        }
+        $definition['properties'] = $properties;
+
+        return $definition;
+    }
+
+    /**
+     * Definition keys referenced by `$ref` in the schema itself (not inside
+     * its definitions).
+     *
+     * @return list<string>
+     */
+    private function referencedDefinitionKeys(mixed $node): array
+    {
+        if (!is_iterable($node)) {
+            return [];
+        }
+
+        $keys = [];
+        foreach ($node as $key => $value) {
+            if ($key === '$ref' && \is_string($value)) {
+                $keys[] = substr($value, (int) strrpos($value, '/') + 1);
+            } elseif (is_iterable($value)) {
+                $keys = [...$keys, ...$this->referencedDefinitionKeys($value)];
+            }
+        }
+
+        return array_values(array_unique($keys));
+    }
+
     private function processProperties(Schema $schema, ClassMetadata $metadata, string $propertiesKey): void
     {
         $properties = $schema[$propertiesKey] ?? [];
@@ -204,7 +329,13 @@ private function processDefinitionProperties(\ArrayObject &$definitions, string
         }
     }
 
-    private function getRelationExtensions(ClassMetadata $metadata, string $propertyName): ?array
+    /**
+     * @param bool $candidatesOnly label only from the configured candidates
+     *                             (output schemas): no "first string
+     *                             property" fallback, no extensions without
+     *                             a candidate
+     */
+    private function getRelationExtensions(ClassMetadata $metadata, string $propertyName, bool $candidatesOnly = false): ?array
     {
         $this->logger->debug('Getting relation extensions', [
             'className' => $metadata->getName(),
@@ -253,7 +384,10 @@ private function getRelationExtensions(ClassMetadata $metadata, string $property
         }
 
         // Infer label property from target entity
-        $labelProperty = $this->inferLabelProperty($targetClass);
+        $labelProperty = $candidatesOnly ? $this->candidateLabelProperty($targetClass) : $this->inferLabelProperty($targetClass);
+        if ($labelProperty === null) {
+            return null;
+        }
 
         // Get short resource name
         $shortName = $this->getShortName($targetClass);
@@ -329,6 +463,26 @@ private function getCollectionPath(ResourceMetadataCollection $resourceMetadata)
         return null;
     }
 
+    /**
+     * First label candidate the class declares, or null.
+     */
+    private function candidateLabelProperty(string $className): ?string
+    {
+        try {
+            $reflectionClass = new ReflectionClass($className);
+        } catch (\ReflectionException) {
+            return null;
+        }
+
+        foreach ($this->labelPropertyCandidates as $candidate) {
+            if ($reflectionClass->hasProperty($candidate)) {
+                return $candidate;
+            }
+        }
+
+        return null;
+    }
+
     private function inferLabelProperty(string $className): string
     {
         try {
diff --git a/tests/DependencyInjection/ApiPlatformUtilsExtensionTest.php b/tests/DependencyInjection/ApiPlatformUtilsExtensionTest.php
new file mode 100644
index 0000000..10b2484
--- /dev/null
+++ b/tests/DependencyInjection/ApiPlatformUtilsExtensionTest.php
@@ -0,0 +1,93 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 13:10:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\DependencyInjection;
+
+use Dmstr\ApiPlatformUtils\DependencyInjection\ApiPlatformUtilsExtension;
+use Dmstr\ApiPlatformUtils\Doctrine\Orm\Extension\StableOrderExtension;
+use Dmstr\ApiPlatformUtils\Metadata\AutoOrderResourceMetadataCollectionFactory;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Config\Definition\Exception\InvalidConfigurationException;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+
+final class ApiPlatformUtilsExtensionTest extends TestCase
+{
+    private const BASE = ['credential_encryption' => ['key' => 'a2V5']];
+
+    public function testSwitchesAreOffByDefault(): void
+    {
+        $container = $this->load([self::BASE]);
+
+        self::assertFalse($container->hasDefinition(AutoOrderResourceMetadataCollectionFactory::class));
+        self::assertFalse($container->hasDefinition(StableOrderExtension::class));
+        self::assertFalse($container->getParameter('dmstr_api_platform_utils.auto_order.enabled'));
+        self::assertFalse($container->getParameter('dmstr_api_platform_utils.stable_order.enabled'));
+        self::assertSame(['name' => 'ASC', 'createdAt' => 'DESC'], $container->getParameter('dmstr_api_platform_utils.auto_order.default_order'));
+        self::assertSame(
+            ['name', 'title', 'label', 'displayName', 'email'],
+            $container->getParameter('dmstr_api_platform_utils.relation_field_decorator.label_property_candidates'),
+        );
+    }
+
+    public function testAutoOrderService(): void
+    {
+        $container = $this->load([self::BASE + ['auto_order' => ['enabled' => true, 'default_order' => ['title' => 'asc']]]]);
+
+        $definition = $container->getDefinition(AutoOrderResourceMetadataCollectionFactory::class);
+        self::assertSame(['api_platform.metadata.resource.metadata_collection_factory', null, 1100], \array_slice($definition->getDecoratedService(), 0, 3));
+        self::assertSame(['title' => 'ASC'], $container->getParameter('dmstr_api_platform_utils.auto_order.default_order'));
+    }
+
+    public function testDefaultOrderIsReplacedNotMerged(): void
+    {
+        $container = $this->load([
+            self::BASE + ['auto_order' => ['default_order' => ['name' => 'ASC', 'createdAt' => 'DESC']]],
+            ['auto_order' => ['default_order' => ['createdAt' => 'DESC']]],
+        ]);
+
+        self::assertSame(['createdAt' => 'DESC'], $container->getParameter('dmstr_api_platform_utils.auto_order.default_order'));
+    }
+
+    public function testInvalidDirectionIsRejected(): void
+    {
+        $this->expectException(InvalidConfigurationException::class);
+
+        $this->load([self::BASE + ['auto_order' => ['default_order' => ['name' => 'up']]]]);
+    }
+
+    public function testStableOrderServiceTag(): void
+    {
+        $container = $this->load([self::BASE + ['stable_order' => ['enabled' => true]]]);
+
+        self::assertSame(
+            [['priority' => -40]],
+            $container->getDefinition(StableOrderExtension::class)->getTag('api_platform.doctrine.orm.query_extension.collection'),
+        );
+    }
+
+    public function testLabelCandidatesOfSeveralConfigsAreDeduplicated(): void
+    {
+        $container = $this->load([
+            self::BASE + ['relation_field_decorator' => ['label_property_candidates' => ['name', 'title']]],
+            ['relation_field_decorator' => ['label_property_candidates' => ['name', 'title', 'email']]],
+        ]);
+
+        self::assertSame(
+            ['name', 'title', 'email'],
+            $container->getParameter('dmstr_api_platform_utils.relation_field_decorator.label_property_candidates'),
+        );
+    }
+
+    /**
+     * @param list<array<string, mixed>> $configs
+     */
+    private function load(array $configs): ContainerBuilder
+    {
+        $container = new ContainerBuilder();
+        (new ApiPlatformUtilsExtension())->load($configs, $container);
+
+        return $container;
+    }
+}
diff --git a/tests/Doctrine/Orm/Extension/StableOrderExtensionTest.php b/tests/Doctrine/Orm/Extension/StableOrderExtensionTest.php
new file mode 100644
index 0000000..66bf7a1
--- /dev/null
+++ b/tests/Doctrine/Orm/Extension/StableOrderExtensionTest.php
@@ -0,0 +1,107 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 13:00:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\Doctrine\Orm\Extension;
+
+use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
+use Dmstr\ApiPlatformUtils\Doctrine\Orm\Extension\StableOrderExtension;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\Book;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\CompositeKey;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\MetadataLoader;
+use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\ORM\Mapping\ClassMetadata;
+use Doctrine\ORM\QueryBuilder;
+use PHPUnit\Framework\TestCase;
+
+final class StableOrderExtensionTest extends TestCase
+{
+    public function testAppendsIdentifierAfterTheSort(): void
+    {
+        $queryBuilder = $this->queryBuilder(Book::class)->addOrderBy('o.title', 'DESC');
+
+        $this->apply($queryBuilder);
+
+        self::assertSame('SELECT o FROM '.Book::class.' o ORDER BY o.title DESC, o.id ASC', $queryBuilder->getDQL());
+    }
+
+    public function testAppendsIdentifierWithoutAnySort(): void
+    {
+        $queryBuilder = $this->queryBuilder(Book::class);
+
+        $this->apply($queryBuilder);
+
+        self::assertSame('SELECT o FROM '.Book::class.' o ORDER BY o.id ASC', $queryBuilder->getDQL());
+    }
+
+    public function testKeepsAnExistingIdentifierSort(): void
+    {
+        $queryBuilder = $this->queryBuilder(Book::class)->addOrderBy('o.title', 'ASC')->addOrderBy('o.id', 'DESC');
+
+        $this->apply($queryBuilder);
+
+        self::assertSame('SELECT o FROM '.Book::class.' o ORDER BY o.title ASC, o.id DESC', $queryBuilder->getDQL());
+    }
+
+    public function testJoinedColumnWithIdentifierNameIsNotTheRootIdentifier(): void
+    {
+        $queryBuilder = $this->queryBuilder(Book::class)
+            ->leftJoin('o.author', 'author_a1')
+            ->addOrderBy('author_a1.id', 'ASC');
+
+        $this->apply($queryBuilder);
+
+        self::assertStringEndsWith('ORDER BY author_a1.id ASC, o.id ASC', $queryBuilder->getDQL());
+    }
+
+    public function testSkipsCompositeIdentifier(): void
+    {
+        $queryBuilder = $this->queryBuilder(CompositeKey::class)->addOrderBy('o.name', 'ASC');
+
+        $this->apply($queryBuilder);
+
+        self::assertSame('SELECT o FROM '.CompositeKey::class.' o ORDER BY o.name ASC', $queryBuilder->getDQL());
+    }
+
+    public function testSkipsForeignIdentifier(): void
+    {
+        $metadata = clone MetadataLoader::load(Book::class);
+        $metadata->containsForeignIdentifier = true;
+        $queryBuilder = $this->queryBuilder(Book::class, $metadata)->addOrderBy('o.title', 'ASC');
+
+        $this->apply($queryBuilder);
+
+        self::assertSame('SELECT o FROM '.Book::class.' o ORDER BY o.title ASC', $queryBuilder->getDQL());
+    }
+
+    public function testSkipsGroupBy(): void
+    {
+        $queryBuilder = $this->queryBuilder(Book::class)->groupBy('o.title')->addOrderBy('o.title', 'ASC');
+
+        $this->apply($queryBuilder);
+
+        self::assertStringEndsWith('GROUP BY o.title ORDER BY o.title ASC', $queryBuilder->getDQL());
+    }
+
+    private function apply(QueryBuilder $queryBuilder): void
+    {
+        (new StableOrderExtension())->applyToCollection(
+            $queryBuilder,
+            $this->createStub(QueryNameGeneratorInterface::class),
+            Book::class,
+        );
+    }
+
+    /**
+     * @param class-string $class
+     */
+    private function queryBuilder(string $class, ?ClassMetadata $metadata = null): QueryBuilder
+    {
+        $metadata ??= MetadataLoader::load($class);
+        $entityManager = $this->createStub(EntityManagerInterface::class);
+        $entityManager->method('getClassMetadata')->willReturn($metadata);
+
+        return (new QueryBuilder($entityManager))->select('o')->from($class, 'o');
+    }
+}
diff --git a/tests/Fixtures/AutoOrder/Author.php b/tests/Fixtures/AutoOrder/Author.php
new file mode 100644
index 0000000..d323d77
--- /dev/null
+++ b/tests/Fixtures/AutoOrder/Author.php
@@ -0,0 +1,26 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:50:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder;
+
+use Doctrine\ORM\Mapping as ORM;
+
+/** Relation target with a label candidate (`name`) and `email`. */
+#[ORM\Entity]
+class Author
+{
+    #[ORM\Id]
+    #[ORM\Column(type: 'guid')]
+    public string $id;
+
+    #[ORM\Column(type: 'string')]
+    public string $name;
+
+    #[ORM\Column(type: 'string')]
+    public string $email;
+
+    #[ORM\Column(type: 'datetime_immutable')]
+    public \DateTimeImmutable $createdAt;
+}
diff --git a/tests/Fixtures/AutoOrder/AuthorView.php b/tests/Fixtures/AutoOrder/AuthorView.php
new file mode 100644
index 0000000..c12b459
--- /dev/null
+++ b/tests/Fixtures/AutoOrder/AuthorView.php
@@ -0,0 +1,13 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:50:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder;
+
+/** DTO resource mapped to Author via stateOptions entityClass; has no `email`. */
+class AuthorView
+{
+    public string $name;
+    public \DateTimeImmutable $createdAt;
+}
diff --git a/tests/Fixtures/AutoOrder/Book.php b/tests/Fixtures/AutoOrder/Book.php
new file mode 100644
index 0000000..6e8d668
--- /dev/null
+++ b/tests/Fixtures/AutoOrder/Book.php
@@ -0,0 +1,51 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:50:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder;
+
+use Doctrine\ORM\Mapping as ORM;
+
+/**
+ * Covers the type whitelist: sortable scalars, an integer identifier,
+ * text/json/vector columns, to-one relations with and without a label
+ * candidate, and an inverse-side to-many.
+ */
+#[ORM\Entity]
+class Book
+{
+    #[ORM\Id]
+    #[ORM\Column(type: 'integer')]
+    public int $id;
+
+    #[ORM\Column(type: 'string')]
+    public string $title;
+
+    #[ORM\Column(type: 'decimal')]
+    public string $price;
+
+    #[ORM\Column(type: 'boolean')]
+    public bool $available;
+
+    #[ORM\Column(type: 'text')]
+    public string $summary;
+
+    #[ORM\Column(type: 'json')]
+    public array $metadata;
+
+    #[ORM\Column(type: 'vector')]
+    public array $embedding;
+
+    #[ORM\Column(type: 'string')]
+    public string $secret;
+
+    #[ORM\Column(type: 'datetime_immutable')]
+    public \DateTimeImmutable $createdAt;
+
+    #[ORM\ManyToOne(targetEntity: Author::class)]
+    public ?Author $author = null;
+
+    #[ORM\ManyToOne(targetEntity: Publisher::class)]
+    public ?Publisher $publisher = null;
+}
diff --git a/tests/Fixtures/AutoOrder/CompositeKey.php b/tests/Fixtures/AutoOrder/CompositeKey.php
new file mode 100644
index 0000000..82ca3cd
--- /dev/null
+++ b/tests/Fixtures/AutoOrder/CompositeKey.php
@@ -0,0 +1,23 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:50:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder;
+
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+class CompositeKey
+{
+    #[ORM\Id]
+    #[ORM\Column(type: 'integer')]
+    public int $a;
+
+    #[ORM\Id]
+    #[ORM\Column(type: 'integer')]
+    public int $b;
+
+    #[ORM\Column(type: 'string')]
+    public string $name;
+}
diff --git a/tests/Fixtures/AutoOrder/DisabledBook.php b/tests/Fixtures/AutoOrder/DisabledBook.php
new file mode 100644
index 0000000..505a9b1
--- /dev/null
+++ b/tests/Fixtures/AutoOrder/DisabledBook.php
@@ -0,0 +1,21 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:50:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder;
+
+use Dmstr\ApiPlatformUtils\Attribute\AutoOrder;
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+#[AutoOrder(enabled: false)]
+class DisabledBook
+{
+    #[ORM\Id]
+    #[ORM\Column(type: 'integer')]
+    public int $id;
+
+    #[ORM\Column(type: 'string')]
+    public string $name;
+}
diff --git a/tests/Fixtures/AutoOrder/ExcludedBook.php b/tests/Fixtures/AutoOrder/ExcludedBook.php
new file mode 100644
index 0000000..5154e34
--- /dev/null
+++ b/tests/Fixtures/AutoOrder/ExcludedBook.php
@@ -0,0 +1,30 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:50:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder;
+
+use Dmstr\ApiPlatformUtils\Attribute\AutoOrder;
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+#[AutoOrder(exclude: ['name', 'author'])]
+class ExcludedBook
+{
+    #[ORM\Id]
+    #[ORM\Column(type: 'integer')]
+    public int $id;
+
+    #[ORM\Column(type: 'string')]
+    public string $name;
+
+    #[ORM\Column(type: 'integer')]
+    public int $pages;
+
+    #[ORM\Column(type: 'datetime_immutable')]
+    public \DateTimeImmutable $createdAt;
+
+    #[ORM\ManyToOne(targetEntity: Author::class)]
+    public ?Author $author = null;
+}
diff --git a/tests/Fixtures/AutoOrder/ExplicitOrderBook.php b/tests/Fixtures/AutoOrder/ExplicitOrderBook.php
new file mode 100644
index 0000000..2226463
--- /dev/null
+++ b/tests/Fixtures/AutoOrder/ExplicitOrderBook.php
@@ -0,0 +1,30 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:50:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder;
+
+use ApiPlatform\Doctrine\Orm\Filter\OrderFilter;
+use ApiPlatform\Metadata\ApiFilter;
+use Doctrine\ORM\Mapping as ORM;
+
+/** Explicit OrderFilter on class level (title) and property level (author.name). */
+#[ORM\Entity]
+#[ApiFilter(OrderFilter::class, properties: ['title' => 'ASC'])]
+class ExplicitOrderBook
+{
+    #[ORM\Id]
+    #[ORM\Column(type: 'integer')]
+    public int $id;
+
+    #[ORM\Column(type: 'string')]
+    public string $title;
+
+    #[ORM\Column(type: 'integer')]
+    public int $pages;
+
+    #[ORM\ManyToOne(targetEntity: Author::class)]
+    #[ApiFilter(OrderFilter::class, properties: ['name'])]
+    public ?Author $author = null;
+}
diff --git a/tests/Fixtures/AutoOrder/MetadataLoader.php b/tests/Fixtures/AutoOrder/MetadataLoader.php
new file mode 100644
index 0000000..86f1698
--- /dev/null
+++ b/tests/Fixtures/AutoOrder/MetadataLoader.php
@@ -0,0 +1,32 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:50:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder;
+
+use Doctrine\ORM\Mapping\ClassMetadata;
+use Doctrine\ORM\Mapping\Driver\AttributeDriver;
+use Doctrine\Persistence\Mapping\RuntimeReflectionService;
+
+/** Builds Doctrine ClassMetadata from the fixture attributes, without an EntityManager. */
+final class MetadataLoader
+{
+    /** @var array<class-string, ClassMetadata> */
+    private static array $cache = [];
+
+    /**
+     * @param class-string $class
+     */
+    public static function load(string $class): ClassMetadata
+    {
+        if (!isset(self::$cache[$class])) {
+            $metadata = new ClassMetadata($class);
+            $metadata->initializeReflection(new RuntimeReflectionService());
+            (new AttributeDriver([__DIR__]))->loadMetadataForClass($class, $metadata);
+            self::$cache[$class] = $metadata;
+        }
+
+        return self::$cache[$class];
+    }
+}
diff --git a/tests/Fixtures/AutoOrder/OrderAllBook.php b/tests/Fixtures/AutoOrder/OrderAllBook.php
new file mode 100644
index 0000000..5fe67e3
--- /dev/null
+++ b/tests/Fixtures/AutoOrder/OrderAllBook.php
@@ -0,0 +1,23 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:50:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder;
+
+use ApiPlatform\Doctrine\Orm\Filter\OrderFilter;
+use ApiPlatform\Metadata\ApiFilter;
+use Doctrine\ORM\Mapping as ORM;
+
+/** Class-level OrderFilter without properties: covers every property. */
+#[ORM\Entity]
+#[ApiFilter(OrderFilter::class)]
+class OrderAllBook
+{
+    #[ORM\Id]
+    #[ORM\Column(type: 'integer')]
+    public int $id;
+
+    #[ORM\Column(type: 'string')]
+    public string $name;
+}
diff --git a/tests/Fixtures/AutoOrder/Publisher.php b/tests/Fixtures/AutoOrder/Publisher.php
new file mode 100644
index 0000000..b5f47db
--- /dev/null
+++ b/tests/Fixtures/AutoOrder/Publisher.php
@@ -0,0 +1,20 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:50:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder;
+
+use Doctrine\ORM\Mapping as ORM;
+
+/** Relation target without a label candidate: only a string `code`. */
+#[ORM\Entity]
+class Publisher
+{
+    #[ORM\Id]
+    #[ORM\Column(type: 'integer')]
+    public int $id;
+
+    #[ORM\Column(type: 'string')]
+    public string $code;
+}
diff --git a/tests/Metadata/AutoOrderResourceMetadataCollectionFactoryTest.php b/tests/Metadata/AutoOrderResourceMetadataCollectionFactoryTest.php
new file mode 100644
index 0000000..6f45396
--- /dev/null
+++ b/tests/Metadata/AutoOrderResourceMetadataCollectionFactoryTest.php
@@ -0,0 +1,328 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 12:55:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\Metadata;
+
+use ApiPlatform\Doctrine\Orm\Filter\SortFilter;
+use ApiPlatform\Doctrine\Orm\State\Options;
+use ApiPlatform\Metadata\ApiProperty;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\Operations;
+use ApiPlatform\Metadata\Parameters;
+use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
+use ApiPlatform\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
+use ApiPlatform\Metadata\Property\PropertyNameCollection;
+use ApiPlatform\Metadata\QueryParameter;
+use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
+use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
+use Dmstr\ApiPlatformUtils\Metadata\AutoOrderResourceMetadataCollectionFactory;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\Author;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\AuthorView;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\Book;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\DisabledBook;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\ExcludedBook;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\ExplicitOrderBook;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\MetadataLoader;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\OrderAllBook;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\Publisher;
+use Doctrine\ORM\Mapping\Entity;
+use Doctrine\Persistence\ManagerRegistry;
+use Doctrine\Persistence\ObjectManager;
+use PHPUnit\Framework\TestCase;
+
+final class AutoOrderResourceMetadataCollectionFactoryTest extends TestCase
+{
+    private const DEFAULT_ORDER = ['name' => 'ASC', 'createdAt' => 'DESC'];
+
+    public function testTypeWhitelistAndIdentifierExclusion(): void
+    {
+        $operation = $this->collectionOperation($this->create(new GetCollection(class: Book::class)));
+
+        // integer id, text, json, vector: no parameter
+        self::assertSame(
+            ['order[title]', 'order[price]', 'order[available]', 'order[secret]', 'order[createdAt]', 'order[author.name]'],
+            $this->keys($operation),
+        );
+    }
+
+    public function testParameterShape(): void
+    {
+        $operation = $this->collectionOperation($this->create(new GetCollection(class: Book::class)));
+
+        $parameter = $operation->getParameters()->get('order[author.name]');
+        self::assertInstanceOf(QueryParameter::class, $parameter);
+        self::assertSame('author.name', $parameter->getProperty());
+        self::assertInstanceOf(SortFilter::class, $parameter->getFilter());
+        self::assertFalse($parameter->getCastToArray());
+        self::assertSame('Sort by `name` of the related `author` (asc or desc).', $parameter->getDescription());
+        self::assertSame('Sort by `title` (asc or desc).', $operation->getParameters()->get('order[title]')->getDescription());
+    }
+
+    public function testRelationLabelOnlyFromCandidates(): void
+    {
+        // Publisher has only a string `code`: no "first string property" fallback
+        $keys = $this->keys($this->collectionOperation($this->create(new GetCollection(class: Book::class))));
+        self::assertNotContains('order[publisher.code]', $keys);
+        self::assertEmpty(array_filter($keys, static fn (string $k): bool => str_starts_with($k, 'order[publisher')));
+
+        // candidate order decides: `email` only when `name` is not a candidate
+        $keys = $this->keys($this->collectionOperation($this->create(new GetCollection(class: Book::class), candidates: ['email', 'name'])));
+        self::assertContains('order[author.email]', $keys);
+        self::assertNotContains('order[author.name]', $keys);
+    }
+
+    public function testUnreadableAndUnexposedPropertiesAreSkipped(): void
+    {
+        $operation = $this->collectionOperation($this->create(
+            new GetCollection(class: Book::class),
+            hidden: ['secret'],
+            unreadable: ['available', 'author'],
+        ));
+
+        $keys = $this->keys($operation);
+        self::assertNotContains('order[secret]', $keys);
+        self::assertNotContains('order[available]', $keys);
+        self::assertNotContains('order[author.name]', $keys);
+        self::assertContains('order[title]', $keys);
+    }
+
+    public function testNormalizationGroupsArePassedToThePropertyFactories(): void
+    {
+        $operation = $this->collectionOperation($this->create(
+            new GetCollection(class: Book::class, normalizationContext: ['groups' => ['book:list']]),
+            grouped: ['title', 'author'],
+        ));
+
+        self::assertSame(['order[title]', 'order[author.name]'], $this->keys($operation));
+    }
+
+    public function testExplicitOrderFilterWinsPerProperty(): void
+    {
+        $operation = $this->collectionOperation($this->create(new GetCollection(class: ExplicitOrderBook::class)));
+
+        // title (class level) and author.name (property level) are explicit
+        self::assertSame(['order[pages]'], $this->keys($operation));
+    }
+
+    public function testClassLevelOrderFilterWithoutPropertiesDisablesParameters(): void
+    {
+        $operation = $this->collectionOperation($this->create(new GetCollection(class: OrderAllBook::class)));
+
+        self::assertSame([], $this->keys($operation));
+        // the default sort still applies: `name` is sortable
+        self::assertSame(['name' => 'ASC'], $operation->getOrder());
+    }
+
+    public function testDeclaredParameterWins(): void
+    {
+        $own = new QueryParameter(key: 'order[title]', description: 'mine');
+        $operation = $this->collectionOperation($this->create(
+            new GetCollection(class: Book::class, parameters: new Parameters(['order[title]' => $own])),
+        ));
+
+        self::assertSame('mine', $operation->getParameters()->get('order[title]')->getDescription());
+        self::assertCount(1, array_filter($this->keys($operation), static fn (string $k): bool => 'order[title]' === $k));
+    }
+
+    public function testAutoOrderAttributeDisables(): void
+    {
+        $operation = $this->collectionOperation($this->create(new GetCollection(class: DisabledBook::class)));
+
+        self::assertSame([], $this->keys($operation));
+        self::assertNull($operation->getOrder());
+    }
+
+    public function testAutoOrderAttributeExcludes(): void
+    {
+        $operation = $this->collectionOperation($this->create(new GetCollection(class: ExcludedBook::class)));
+
+        // `name` and `author` (incl. author.name) excluded
+        self::assertSame(['order[pages]', 'order[createdAt]'], $this->keys($operation));
+        // excluded `name` is no default sort candidate either
+        self::assertSame(['createdAt' => 'DESC'], $operation->getOrder());
+    }
+
+    public function testDefaultOrderFirstSortableKeyWins(): void
+    {
+        $author = $this->collectionOperation($this->create(new GetCollection(class: Author::class), resourceClass: Author::class));
+        self::assertSame(['name' => 'ASC'], $author->getOrder());
+
+        $book = $this->collectionOperation($this->create(new GetCollection(class: Book::class)));
+        self::assertSame(['createdAt' => 'DESC'], $book->getOrder());
+
+        // neither key exists: API Platform's default (identifier) stays
+        $publisher = $this->collectionOperation($this->create(new GetCollection(class: Publisher::class), resourceClass: Publisher::class));
+        self::assertNull($publisher->getOrder());
+    }
+
+    public function testDefaultOrderKeepsOperationOrder(): void
+    {
+        $operation = $this->collectionOperation($this->create(new GetCollection(class: Author::class, order: ['email' => 'ASC']), resourceClass: Author::class));
+
+        self::assertSame(['email' => 'ASC'], $operation->getOrder());
+    }
+
+    public function testDefaultOrderCanBeEmpty(): void
+    {
+        $operation = $this->collectionOperation($this->create(new GetCollection(class: Author::class), resourceClass: Author::class, defaultOrder: []));
+
+        self::assertNull($operation->getOrder());
+        self::assertContains('order[name]', $this->keys($operation));
+    }
+
+    public function testOperationsWithOwnProviderAndItemOperationsAreUntouched(): void
+    {
+        $collection = $this->create(new GetCollection(class: Book::class, provider: 'some.provider'));
+
+        foreach ($collection[0]->getOperations() as $operation) {
+            self::assertSame([], $this->keys($operation));
+            self::assertNull($operation->getOrder());
+        }
+    }
+
+    public function testStateOptionsEntityClass(): void
+    {
+        $operation = $this->collectionOperation($this->create(
+            new GetCollection(class: AuthorView::class, stateOptions: new Options(entityClass: Author::class)),
+            resourceClass: AuthorView::class,
+        ));
+
+        // Author's fields, filtered by what the DTO exposes (no email)
+        self::assertSame(['order[name]', 'order[createdAt]'], $this->keys($operation));
+    }
+
+    public function testNonDoctrineResourceIsUntouched(): void
+    {
+        $operation = $this->collectionOperation($this->create(new GetCollection(class: AuthorView::class), resourceClass: AuthorView::class));
+
+        self::assertSame([], $this->keys($operation));
+        self::assertNull($operation->getOrder());
+    }
+
+    /**
+     * @param list<string>      $hidden     properties missing from the name collection
+     * @param list<string>      $unreadable properties with readable: false
+     * @param list<string>|null $grouped    properties in the operation's groups
+     * @param list<string>      $candidates
+     * @param array<string, string> $defaultOrder
+     */
+    private function create(
+        GetCollection $collectionOperation,
+        string $resourceClass = Book::class,
+        array $hidden = [],
+        array $unreadable = [],
+        ?array $grouped = null,
+        array $candidates = ['name', 'title', 'label', 'displayName', 'email'],
+        array $defaultOrder = self::DEFAULT_ORDER,
+    ): ResourceMetadataCollection {
+        $resource = (new ApiResource(class: $resourceClass))->withOperations(new Operations([
+            'get_collection' => $collectionOperation,
+            'get' => new Get(class: $resourceClass),
+        ]));
+
+        $decorated = $this->createStub(ResourceMetadataCollectionFactoryInterface::class);
+        $decorated->method('create')->willReturnCallback(
+            static fn (string $class): ResourceMetadataCollection => new ResourceMetadataCollection($class, [$resource])
+        );
+
+        $factory = new AutoOrderResourceMetadataCollectionFactory(
+            $decorated,
+            $this->managerRegistry(),
+            $this->nameFactory($hidden),
+            $this->propertyFactory($unreadable, $grouped),
+            $candidates,
+            $defaultOrder,
+        );
+
+        return $factory->create($resourceClass);
+    }
+
+    private function collectionOperation(ResourceMetadataCollection $collection): GetCollection
+    {
+        foreach ($collection[0]->getOperations() as $operation) {
+            if ($operation instanceof GetCollection) {
+                return $operation;
+            }
+        }
+        self::fail('no GetCollection');
+    }
+
+    /**
+     * @return list<string>
+     */
+    private function keys(object $operation): array
+    {
+        $keys = [];
+        foreach ($operation->getParameters() ?? [] as $key => $parameter) {
+            $keys[] = $key;
+        }
+
+        return $keys;
+    }
+
+    private function managerRegistry(): ManagerRegistry
+    {
+        $manager = $this->createStub(ObjectManager::class);
+        $manager->method('getClassMetadata')->willReturnCallback(MetadataLoader::load(...));
+
+        $registry = $this->createStub(ManagerRegistry::class);
+        $registry->method('getManagerForClass')->willReturnCallback(
+            static fn (string $class): ?ObjectManager => [] !== (new \ReflectionClass($class))->getAttributes(Entity::class) ? $manager : null
+        );
+
+        return $registry;
+    }
+
+    /**
+     * @param list<string> $hidden
+     */
+    private function nameFactory(array $hidden): PropertyNameCollectionFactoryInterface
+    {
+        return new class($hidden) implements PropertyNameCollectionFactoryInterface {
+            public function __construct(private readonly array $hidden)
+            {
+            }
+
+            public function create(string $resourceClass, array $options = []): PropertyNameCollection
+            {
+                $names = [];
+                foreach ((new \ReflectionClass($resourceClass))->getProperties() as $property) {
+                    if (!\in_array($property->getName(), $this->hidden, true)) {
+                        $names[] = $property->getName();
+                    }
+                }
+
+                return new PropertyNameCollection($names);
+            }
+        };
+    }
+
+    /**
+     * @param list<string>      $unreadable
+     * @param list<string>|null $grouped
+     */
+    private function propertyFactory(array $unreadable, ?array $grouped): PropertyMetadataFactoryInterface
+    {
+        return new class($unreadable, $grouped) implements PropertyMetadataFactoryInterface {
+            public function __construct(private readonly array $unreadable, private readonly ?array $grouped)
+            {
+            }
+
+            public function create(string $resourceClass, string $property, array $options = []): ApiProperty
+            {
+                if (\in_array($property, $this->unreadable, true)) {
+                    return new ApiProperty(readable: false);
+                }
+                if (isset($options['serializer_groups'])) {
+                    return new ApiProperty(readable: \in_array($property, $this->grouped ?? [], true));
+                }
+
+                return new ApiProperty(readable: true);
+            }
+        };
+    }
+}
diff --git a/tests/OpenApi/RelationFieldSchemaDecoratorTest.php b/tests/OpenApi/RelationFieldSchemaDecoratorTest.php
new file mode 100644
index 0000000..0ee7424
--- /dev/null
+++ b/tests/OpenApi/RelationFieldSchemaDecoratorTest.php
@@ -0,0 +1,145 @@
+<?php
+// file generated with AI assistance: Claude Code - 2026-10-08 13:05:00 UTC
+
+declare(strict_types=1);
+
+namespace Dmstr\ApiPlatformUtils\Tests\OpenApi;
+
+use ApiPlatform\JsonSchema\Schema;
+use ApiPlatform\JsonSchema\SchemaFactoryInterface;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\Metadata\Operations;
+use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
+use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
+use Dmstr\ApiPlatformUtils\OpenApi\RelationFieldSchemaDecorator;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\Author;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\Book;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\MetadataLoader;
+use Dmstr\ApiPlatformUtils\Tests\Fixtures\AutoOrder\Publisher;
+use Doctrine\ORM\EntityManagerInterface;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\NullLogger;
+
+final class RelationFieldSchemaDecoratorTest extends TestCase
+{
+    private const RELATION = ['type' => 'string', 'format' => 'iri-reference'];
+
+    public function testOutputSchemaGetsOnlyLabelAndResourceClass(): void
+    {
+        $schema = $this->build(Schema::TYPE_OUTPUT, 'Book.jsonld');
+        $properties = $schema->getDefinitions()['Book.jsonld']['allOf'][1]['properties'];
+
+        self::assertSame(
+            self::RELATION + ['x-label-property' => 'name', 'x-resource-class' => 'Author'],
+            $properties['author'],
+        );
+        self::assertArrayNotHasKey('x-collection', $properties['author']);
+        self::assertArrayNotHasKey('x-value-property', $properties['author']);
+        self::assertArrayNotHasKey('x-search-property', $properties['author']);
+    }
+
+    public function testOutputSchemaHasNoStringFallbackLabel(): void
+    {
+        $schema = $this->build(Schema::TYPE_OUTPUT, 'Book.jsonld');
+
+        // Publisher has no label candidate, only `code`
+        self::assertSame(self::RELATION, $schema->getDefinitions()['Book.jsonld']['allOf'][1]['properties']['publisher']);
+    }
+
+    public function testOutputSchemaLeavesOtherDefinitionsAlone(): void
+    {
+        $schema = $this->build(Schema::TYPE_OUTPUT, 'Book.jsonld');
+
+        // the input definition sharing the definitions map is not touched
+        self::assertSame(self::RELATION, $schema->getDefinitions()['Book']['properties']['author']);
+    }
+
+    public function testInputSchemaKeepsAllExtensionsAndFallback(): void
+    {
+        $schema = $this->build(Schema::TYPE_INPUT, 'Book');
+        $properties = $schema->getDefinitions()['Book']['properties'];
+
+        self::assertSame([
+            'type' => 'string',
+            'format' => 'iri-reference',
+            'x-collection' => '/api/authors',
+            'x-label-property' => 'name',
+            'x-value-property' => '@id',
+            'x-search-property' => 'name',
+            'x-resource-class' => 'Author',
+        ], $properties['author']);
+        // input keeps the "first string property" fallback
+        self::assertSame('code', $properties['publisher']['x-label-property']);
+        self::assertSame('/api/publishers', $properties['publisher']['x-collection']);
+    }
+
+    public function testOutputClassOfTheOperationIsUsed(): void
+    {
+        // an operation whose output is not a Doctrine entity: nothing added
+        $schema = $this->build(Schema::TYPE_OUTPUT, 'Book.jsonld', new GetCollection(class: Book::class, output: \stdClass::class));
+
+        self::assertSame(self::RELATION, $schema->getDefinitions()['Book.jsonld']['allOf'][1]['properties']['author']);
+    }
+
+    private function build(string $type, string $rootKey, ?Operation $operation = null): Schema
+    {
+        $definitions = new \ArrayObject([
+            'Book' => ['type' => 'object', 'properties' => [
+                'title' => ['type' => 'string'],
+                'author' => self::RELATION,
+                'publisher' => self::RELATION,
+            ]],
+            'Book.jsonld' => ['allOf' => [
+                ['$ref' => '#/definitions/HydraItemBaseSchema'],
+                ['type' => 'object', 'properties' => [
+                    'title' => ['type' => 'string'],
+                    'author' => self::RELATION,
+                    'publisher' => self::RELATION,
+                ]],
+            ]],
+            'HydraItemBaseSchema' => ['type' => 'object', 'properties' => ['@id' => ['type' => 'string', 'format' => 'iri-reference']]],
+        ]);
+
+        $inner = $this->createStub(SchemaFactoryInterface::class);
+        $inner->method('buildSchema')->willReturnCallback(static function () use ($definitions, $rootKey): Schema {
+            $schema = new Schema();
+            $schema->setDefinitions($definitions);
+            $schema['$ref'] = '#/definitions/'.$rootKey;
+
+            return $schema;
+        });
+
+        $entityManager = $this->createStub(EntityManagerInterface::class);
+        $entityManager->method('getClassMetadata')->willReturnCallback(static function (string $class) {
+            if (!\in_array($class, [Book::class, Author::class, Publisher::class], true)) {
+                throw new \RuntimeException('not an entity');
+            }
+
+            return MetadataLoader::load($class);
+        });
+
+        $resources = $this->createStub(ResourceMetadataCollectionFactoryInterface::class);
+        $resources->method('create')->willReturnCallback(static function (string $class): ResourceMetadataCollection {
+            $path = '/'.strtolower((new \ReflectionClass($class))->getShortName()).'s';
+
+            return new ResourceMetadataCollection($class, [
+                (new ApiResource(class: $class))->withOperations(new Operations([
+                    'get_collection' => new GetCollection(uriTemplate: $path, class: $class),
+                ])),
+            ]);
+        });
+
+        $decorator = new RelationFieldSchemaDecorator(
+            $inner,
+            $entityManager,
+            $resources,
+            new NullLogger(),
+            '/api',
+            ['name', 'title', 'label', 'displayName', 'email'],
+        );
+
+        return $decorator->buildSchema(Book::class, 'jsonld', $type, $operation);
+    }
+}

From 8b8e4514044e966cb6be1409184d7396acf2e1f8 Mon Sep 17 00:00:00 2001
From: "t.munk (workhorse)" <t.munk@herzogkommunikation.de>
Date: Thu, 8 Oct 2026 13:39:06 +0000
Subject: [PATCH 3/3] fix(composer): require symfony/yaml at runtime [*]

The extension always loads config/services.yaml via YamlFileLoader;
neither framework-bundle nor dependency-injection pulls symfony/yaml in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md  | 3 ++-
 composer.json | 6 +++---
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6e7c885..a36e44a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,4 @@
-<!-- file generated with AI assistance: Claude Code - 2026-07-22, revised 2026-10-08 13:30:00 UTC -->
+<!-- file generated with AI assistance: Claude Code - 2026-07-22, revised 2026-10-08 13:37:13 UTC -->
 
 # Changelog
 
@@ -16,6 +16,7 @@
 
 - `email` added to the default `relation_field_decorator.label_property_candidates` (`name`, `title`, `label`, `displayName`, `email`). Projects that set the list explicitly are not affected.
 - Label property candidates from several config files are de-duplicated (list nodes are appended to each other when merged).
+- `symfony/yaml` moved from `require-dev` to `require`: the bundle extension always loads `config/services.yaml` via `YamlFileLoader`, so it is a runtime dependency.
 
 ## 0.4.0 - 2026-07-22
 
diff --git a/composer.json b/composer.json
index 8fdd13f..83d1cb2 100644
--- a/composer.json
+++ b/composer.json
@@ -30,11 +30,11 @@
         "symfony/uid": "^7.0",
         "api-platform/core": "^3.0|^4.0",
         "doctrine/orm": "^2.0|^3.0",
-        "psr/log": "^3.0"
+        "psr/log": "^3.0",
+        "symfony/yaml": "^7.0"
     },
     "require-dev": {
-        "phpunit/phpunit": "^12.0",
-        "symfony/yaml": "^7.0"
+        "phpunit/phpunit": "^12.0"
     },
     "autoload": {
         "psr-4": {