Add Id field class for customizing resource ID behavior

Author: tobyzerner

CHANGELOG.md

@@ -8,14 +8,27 @@ and this project adheres to
 
 ## [Unreleased]
 
+### ⚠️ Breaking Changes
+
+- Replace `Resource::getId(object $model, Context $context): string` method with
+  `Resource::id(): Id` method, which returns an `Id` field instance to define ID
+  schema, validation, and writability
+
 ### Added
 
+- Add `Id` field class for customizing resource ID behavior, including type
+  constraints, client-generated IDs via `writableOnCreate()`, and validation
 - Add `linkageMeta()` method to relationship fields for adding meta to resource
   identifier objects in linkage
+- Add static `location()` method to field classes to determine where they appear
+  in the JSON:API document (`attributes`, `relationships`, or root level for
+  `id`)
 
 ### Changed
 
 - Various performance optimizations to improve serialization speed
+- Improve OpenAPI schema generation to properly handle ID field constraints and
+  avoid redundant properties
 
 ## [1.0.0-beta.6] - 2025-10-02
 

docs/.vitepress/config.ts

@@ -22,6 +22,7 @@ export default defineConfig({
                 items: [
                     { text: 'Defining Resources', link: '/resources' },
                     { text: 'Fields', link: '/fields' },
+                    { text: 'ID', link: '/id' },
                     { text: 'Attributes', link: '/attributes' },
                     { text: 'Relationships', link: '/relationships' },
                     { text: 'Filtering', link: '/filtering' },

docs/context.md

@@ -62,6 +62,9 @@ class Context
     // Get a resource by type
     public function resource(string $type): Resource;
 
+    // Get the ID for a model
+    public function id(Resource $resource, mixed $model): string;
+
     // Get the fields for the given resource, keyed by name
     public function fields(Resource $resource): array;
 

docs/id.md

@@ -0,0 +1,80 @@
+# ID
+
+Every JSON:API resource has an `id` field that uniquely identifies it. By
+default, the `id` is managed automatically by your resource implementation, but
+you can customize its behavior using the `Id` field class.
+
+The `Id` field extends the base `Field` class, so all [field methods](fields.md)
+like `required()`, `default()`, and `validate()` are available.
+
+## Customizing the ID Field
+
+To customize how the ID is handled, define an `id()` method on your resource
+that returns an `Id` field instance:
+
+```php
+use Tobyz\JsonApiServer\Schema\Id;
+
+class PostsResource extends AbstractResource
+{
+    // ...
+
+    public function id(): Id
+    {
+        return Id::make();
+    }
+}
+```
+
+## Type Constraints
+
+The `Id` field uses a string type by default, but you can customize it to define
+additional constraints:
+
+```php
+use Tobyz\JsonApiServer\Schema\Type;
+
+Id::make()->type(Type\Str::make()->pattern('^[0-9]+$'));
+```
+
+## Client-Generated IDs
+
+By default, resource IDs are server-generated. To allow clients to provide their
+own IDs when creating resources, use the `writableOnCreate()` method:
+
+```php
+Id::make()->writableOnCreate();
+```
+
+Clients can then include an `id` in the request body when creating a resource:
+
+```json
+{
+    "data": {
+        "type": "posts",
+        "id": "custom-id-123",
+        "attributes": {
+            "title": "My Post"
+        }
+    }
+}
+```
+
+You can combine this with other field methods:
+
+```php
+Id::make()
+    ->writableOnCreate()
+    ->required() // Client MUST provide an ID
+    ->validate(function ($value, $fail) {
+        if (!preg_match('/^[a-z0-9-]+$/', $value)) {
+            $fail(
+                'ID must contain only lowercase letters, numbers, and hyphens',
+            );
+        }
+    });
+
+Id::make()
+    ->writableOnCreate()
+    ->default(fn() => Str::uuid()->toString()); // Fallback if not provided
+```

docs/openapi.md

@@ -11,3 +11,13 @@ $api = new JsonApi();
 
 $definition = (new OpenApiGenerator())->generate($api);
 ```
+
+## Schemas
+
+The OpenAPI generator creates three schemas for each resource:
+
+- `{type}` - The full resource schema including all fields
+- `{type}_create` - Schema for creating resources (includes only fields that are
+  writable on creation)
+- `{type}_update` - Schema for updating resources (includes only writable
+  fields)

docs/resources.md

@@ -55,25 +55,32 @@ $api->resource(new PostsResource());
 
 ## Identifier
 
-When serializing a model into a JSON:API resource object, the `getId` method on
-your resource class will be used to get the `id` for the model. A default
-implementation is provided in the `AbstractResource` class which assumes that
-your models have an `id` property. You may override this if needed:
+Every JSON:API resource has an `id` field. You can customize how the ID is
+handled by defining an `id()` method on your resource that returns an `Id` field
+instance:
 
 ```php
-use Tobyz\JsonApiServer\Context;
+use Tobyz\JsonApiServer\Schema\Id;
 
 class PostsResource extends AbstractResource
 {
     // ...
 
-    public function getId(object $model, Context $context): string
+    public function id(): Id
     {
-        return $model->getKey();
+        return Id::make()
+            ->writableOnCreate() // Allow client-generated IDs
+            ->validate(fn($value, $fail) => /* ... */);
     }
 }
 ```
 
+If you don't define an `id()` method, a default implementation will be used that
+reads the `id` property from your model.
+
+Learn more about customizing the [Resource ID](id.md), including
+client-generated IDs and validation.
+
 ## Fields
 
 A resource object's attributes and relationships are collectively called its

src/Context.php

@@ -30,12 +30,16 @@ class Context
     private ?string $path;
 
     private WeakMap $endpoints;
+    private WeakMap $resourceIds;
+    private WeakMap $modelIds;
     private WeakMap $fields;
     private WeakMap $sparseFields;
 
     public function __construct(public JsonApi $api, public ServerRequestInterface $request)
     {
         $this->endpoints = new WeakMap();
+        $this->resourceIds = new WeakMap();
+        $this->modelIds = new WeakMap();
         $this->fields = new WeakMap();
         $this->sparseFields = new WeakMap();
 
@@ -95,6 +99,17 @@ public function endpoints(Collection $collection): array
         return $this->endpoints[$collection] ??= $collection->endpoints();
     }
 
+    public function id(Resource $resource, $model): string
+    {
+        if (isset($this->modelIds[$model])) {
+            return $this->modelIds[$model];
+        }
+
+        $id = $this->resourceIds[$resource] ??= $resource->id();
+
+        return $this->modelIds[$model] = $id->serializeValue($id->getValue($this), $this);
+    }
+
     /**
      * Get the fields for the given resource, keyed by name.
      *

src/Endpoint/Concerns/SavesData.php

@@ -9,10 +9,11 @@
 use Tobyz\JsonApiServer\Exception\Sourceable;
 use Tobyz\JsonApiServer\Exception\UnprocessableEntityException;
 use Tobyz\JsonApiServer\Schema\Field\Field;
+use Tobyz\JsonApiServer\Schema\Id;
 
+use function Tobyz\JsonApiServer\field_path;
 use function Tobyz\JsonApiServer\get_value;
 use function Tobyz\JsonApiServer\has_value;
-use function Tobyz\JsonApiServer\location;
 use function Tobyz\JsonApiServer\set_value;
 
 trait SavesData
@@ -47,15 +48,11 @@ private function parseData(Context $context): array
                 ]);
             }
 
-            if ($body['data']['id'] !== $context->resource->getId($context->model, $context)) {
+            if ($body['data']['id'] !== $context->id($context->resource, $context->model)) {
                 throw (new ConflictException('data.id does not match the resource ID'))->setSource([
                     'pointer' => '/data/id',
                 ]);
             }
-        } elseif (isset($body['data']['id'])) {
-            throw (new ForbiddenException('Client-generated IDs are not supported'))->setSource([
-                'pointer' => '/data/id',
-            ]);
         }
 
         if (!in_array($body['data']['type'], $context->collection->resources())) {
@@ -85,6 +82,17 @@ private function parseData(Context $context): array
         return array_merge(['attributes' => [], 'relationships' => []], $body['data']);
     }
 
+    private function getFields(Context $context, bool $creating = false): array
+    {
+        $fields = $context->fields($context->resource);
+
+        if ($creating) {
+            array_unshift($fields, $context->resource->id());
+        }
+
+        return $fields;
+    }
+
     /**
      * Assert that the fields contained within a data object are valid.
      */
@@ -101,13 +109,13 @@ private function assertFieldsValid(Context $context, array $data, bool $creating
      */
     private function assertFieldsExist(Context $context, array $data): void
     {
-        $fields = $context->fields($context->resource);
+        $fields = $this->getFields($context);
 
         foreach (['attributes', 'relationships'] as $location) {
             foreach ($data[$location] as $name => $value) {
-                if (!isset($fields[$name]) || $location !== location($fields[$name])) {
+                if (!isset($fields[$name]) || $location !== $fields[$name]->location()) {
                     throw (new BadRequestException("Unknown field [$name]"))->setSource([
-                        'pointer' => "/data/$location/$name",
+                        'pointer' => '/data/' . implode('/', array_filter([$location, $name])),
                     ]);
                 }
             }
@@ -124,17 +132,15 @@ private function assertFieldsWritable(
         array $data,
         bool $creating = false,
     ): void {
-        foreach ($context->fields($context->resource) as $field) {
+        foreach ($this->getFields($context, $creating) as $field) {
             if (!has_value($data, $field)) {
                 continue;
             }
 
             try {
                 $this->assertFieldWritable($context, $field, $creating);
             } catch (Sourceable $e) {
-                throw $e->prependSource([
-                    'pointer' => '/data/' . location($field) . '/' . $field->name,
-                ]);
+                throw $e->prependSource(['pointer' => '/data' . field_path($field)]);
             }
         }
     }
@@ -156,9 +162,9 @@ private function assertFieldWritable(
     /**
      *
      */
-    private function deserializeValues(Context $context, array &$data): void
+    private function deserializeValues(Context $context, array &$data, bool $creating = false): void
     {
-        foreach ($context->fields($context->resource) as $field) {
+        foreach ($this->getFields($context, $creating) as $field) {
             if (!has_value($data, $field)) {
                 continue;
             }
@@ -168,9 +174,7 @@ private function deserializeValues(Context $context, array &$data): void
             try {
                 set_value($data, $field, $field->deserializeValue($value, $context));
             } catch (Sourceable $e) {
-                throw $e->prependSource([
-                    'pointer' => '/data/' . location($field) . '/' . $field->name,
-                ]);
+                throw $e->prependSource(['pointer' => '/data' . field_path($field)]);
             }
         }
     }
@@ -184,7 +188,7 @@ private function assertDataValid(Context $context, array $data, bool $validateAl
     {
         $errors = [];
 
-        foreach ($context->fields($context->resource) as $field) {
+        foreach ($this->getFields($context, $validateAll) as $field) {
             $present = has_value($data, $field);
 
             if (!$present && (!$field->required || !$validateAll)) {
@@ -201,7 +205,7 @@ private function assertDataValid(Context $context, array $data, bool $validateAl
                 $errors,
                 array_map(
                     fn($error) => $error + [
-                        'source' => ['pointer' => '/data/' . location($field) . '/' . $field->name],
+                        'source' => ['pointer' => '/data' . field_path($field)],
                     ],
                     $fieldErrors,
                 ),
@@ -213,7 +217,7 @@ private function assertDataValid(Context $context, array $data, bool $validateAl
         }
     }
 
-    private function validateField(Context $context, Field $field, mixed $value): array
+    private function validateField(Context $context, Field|Id $field, mixed $value): array
     {
         $errors = [];
 
@@ -229,9 +233,9 @@ private function validateField(Context $context, Field $field, mixed $value): ar
     /**
      * Set field values from a data object to the model instance.
      */
-    private function setValues(Context $context, array $data): void
+    private function setValues(Context $context, array $data, bool $creating = false): void
     {
-        foreach ($context->fields($context->resource) as $field) {
+        foreach ($this->getFields($context, $creating) as $field) {
             if (!has_value($data, $field)) {
                 continue;
             }
@@ -245,9 +249,9 @@ private function setValues(Context $context, array $data): void
     /**
      * Run any field save callbacks.
      */
-    private function saveFields(Context $context, array $data): void
+    private function saveFields(Context $context, array $data, bool $creating = false): void
     {
-        foreach ($context->fields($context->resource) as $field) {
+        foreach ($this->getFields($context, $creating) as $field) {
             if (!has_value($data, $field)) {
                 continue;
             }

src/Endpoint/Concerns/ShowsResources.php

@@ -16,7 +16,7 @@ private function selfLink($model, Context $context): string
         return implode('/', [
             $context->api->basePath,
             $context->collection->name(),
-            $context->resource->getId($model, $context),
+            $context->id($context->resource, $model),
         ]);
     }
 }