fix: make composite primary key path param behavior opt-in

Author: zachdaniel

.formatter.exs

@@ -36,6 +36,7 @@ spark_locals_without_parens = [
   patch_relationship: 1,
   patch_relationship: 2,
   patch_relationship: 3,
+  path_param_is_composite_key: 1,
   post: 1,
   post: 2,
   post: 3,

documentation/dsls/DSL-AshJsonApi.Domain.md

@@ -132,6 +132,10 @@ A GET route to retrieve a single record
 get :read
 ```
 
+```
+get :read, path_param_is_composite_key: :id
+```
+
 
 
 ### Arguments
@@ -151,6 +155,7 @@ get :read
 | [`name`](#json_api-routes-get-name){: #json_api-routes-get-name } | `String.t` |  | A globally unique name for this route, to be used when generating docs and open api specifications |
 | [`derive_sort?`](#json_api-routes-get-derive_sort?){: #json_api-routes-get-derive_sort? } | `boolean` | `true` | Whether or not to derive a sort parameter based on the sortable fields of the resource |
 | [`derive_filter?`](#json_api-routes-get-derive_filter?){: #json_api-routes-get-derive_filter? } | `boolean` | `true` | Whether or not to derive a filter parameter based on the sortable fields of the resource |
+| [`path_param_is_composite_key`](#json_api-routes-get-path_param_is_composite_key){: #json_api-routes-get-path_param_is_composite_key } | `atom` |  | The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details. |
 
 
 
@@ -195,6 +200,7 @@ index :read
 | [`name`](#json_api-routes-index-name){: #json_api-routes-index-name } | `String.t` |  | A globally unique name for this route, to be used when generating docs and open api specifications |
 | [`derive_sort?`](#json_api-routes-index-derive_sort?){: #json_api-routes-index-derive_sort? } | `boolean` | `true` | Whether or not to derive a sort parameter based on the sortable fields of the resource |
 | [`derive_filter?`](#json_api-routes-index-derive_filter?){: #json_api-routes-index-derive_filter? } | `boolean` | `true` | Whether or not to derive a filter parameter based on the sortable fields of the resource |
+| [`path_param_is_composite_key`](#json_api-routes-index-path_param_is_composite_key){: #json_api-routes-index-path_param_is_composite_key } | `atom` |  | The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details. |
 
 
 
@@ -239,6 +245,7 @@ post :create
 | [`name`](#json_api-routes-post-name){: #json_api-routes-post-name } | `String.t` |  | A globally unique name for this route, to be used when generating docs and open api specifications |
 | [`derive_sort?`](#json_api-routes-post-derive_sort?){: #json_api-routes-post-derive_sort? } | `boolean` | `true` | Whether or not to derive a sort parameter based on the sortable fields of the resource |
 | [`derive_filter?`](#json_api-routes-post-derive_filter?){: #json_api-routes-post-derive_filter? } | `boolean` | `true` | Whether or not to derive a filter parameter based on the sortable fields of the resource |
+| [`path_param_is_composite_key`](#json_api-routes-post-path_param_is_composite_key){: #json_api-routes-post-path_param_is_composite_key } | `atom` |  | The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details. |
 | [`relationship_arguments`](#json_api-routes-post-relationship_arguments){: #json_api-routes-post-relationship_arguments } | `list(atom \| {:id, atom})` | `[]` | Arguments to be used to edit relationships. See the [relationships guide](/documentation/topics/relationships.md) for more. |
 | [`upsert?`](#json_api-routes-post-upsert?){: #json_api-routes-post-upsert? } | `boolean` | `false` | Whether or not to use the `upsert?: true` option when calling `Ash.create/2`. |
 | [`upsert_identity`](#json_api-routes-post-upsert_identity){: #json_api-routes-post-upsert_identity } | `atom` | `false` | Which identity to use for the upsert |
@@ -266,6 +273,10 @@ A PATCH route to update a record
 patch :update
 ```
 
+```
+patch :update, path_param_is_composite_key: :id
+```
+
 
 
 ### Arguments
@@ -288,6 +299,7 @@ patch :update
 | [`name`](#json_api-routes-patch-name){: #json_api-routes-patch-name } | `String.t` |  | A globally unique name for this route, to be used when generating docs and open api specifications |
 | [`derive_sort?`](#json_api-routes-patch-derive_sort?){: #json_api-routes-patch-derive_sort? } | `boolean` | `true` | Whether or not to derive a sort parameter based on the sortable fields of the resource |
 | [`derive_filter?`](#json_api-routes-patch-derive_filter?){: #json_api-routes-patch-derive_filter? } | `boolean` | `true` | Whether or not to derive a filter parameter based on the sortable fields of the resource |
+| [`path_param_is_composite_key`](#json_api-routes-patch-path_param_is_composite_key){: #json_api-routes-patch-path_param_is_composite_key } | `atom` |  | The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details. |
 
 
 
@@ -312,6 +324,10 @@ A DELETE route to destroy a record
 delete :destroy
 ```
 
+```
+delete :destroy, path_param_is_composite_key: :id
+```
+
 
 
 ### Arguments
@@ -333,6 +349,7 @@ delete :destroy
 | [`name`](#json_api-routes-delete-name){: #json_api-routes-delete-name } | `String.t` |  | A globally unique name for this route, to be used when generating docs and open api specifications |
 | [`derive_sort?`](#json_api-routes-delete-derive_sort?){: #json_api-routes-delete-derive_sort? } | `boolean` | `true` | Whether or not to derive a sort parameter based on the sortable fields of the resource |
 | [`derive_filter?`](#json_api-routes-delete-derive_filter?){: #json_api-routes-delete-derive_filter? } | `boolean` | `true` | Whether or not to derive a filter parameter based on the sortable fields of the resource |
+| [`path_param_is_composite_key`](#json_api-routes-delete-path_param_is_composite_key){: #json_api-routes-delete-path_param_is_composite_key } | `atom` |  | The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details. |
 
 
 
@@ -378,6 +395,7 @@ related :comments, :read
 | [`name`](#json_api-routes-related-name){: #json_api-routes-related-name } | `String.t` |  | A globally unique name for this route, to be used when generating docs and open api specifications |
 | [`derive_sort?`](#json_api-routes-related-derive_sort?){: #json_api-routes-related-derive_sort? } | `boolean` | `true` | Whether or not to derive a sort parameter based on the sortable fields of the resource |
 | [`derive_filter?`](#json_api-routes-related-derive_filter?){: #json_api-routes-related-derive_filter? } | `boolean` | `true` | Whether or not to derive a filter parameter based on the sortable fields of the resource |
+| [`path_param_is_composite_key`](#json_api-routes-related-path_param_is_composite_key){: #json_api-routes-related-path_param_is_composite_key } | `atom` |  | The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details. |
 
 
 
@@ -423,6 +441,7 @@ relationship :comments, :read
 | [`name`](#json_api-routes-relationship-name){: #json_api-routes-relationship-name } | `String.t` |  | A globally unique name for this route, to be used when generating docs and open api specifications |
 | [`derive_sort?`](#json_api-routes-relationship-derive_sort?){: #json_api-routes-relationship-derive_sort? } | `boolean` | `true` | Whether or not to derive a sort parameter based on the sortable fields of the resource |
 | [`derive_filter?`](#json_api-routes-relationship-derive_filter?){: #json_api-routes-relationship-derive_filter? } | `boolean` | `true` | Whether or not to derive a filter parameter based on the sortable fields of the resource |
+| [`path_param_is_composite_key`](#json_api-routes-relationship-path_param_is_composite_key){: #json_api-routes-relationship-path_param_is_composite_key } | `atom` |  | The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details. |
 
 
 
@@ -467,6 +486,7 @@ post_to_relationship :comments
 | [`name`](#json_api-routes-post_to_relationship-name){: #json_api-routes-post_to_relationship-name } | `String.t` |  | A globally unique name for this route, to be used when generating docs and open api specifications |
 | [`derive_sort?`](#json_api-routes-post_to_relationship-derive_sort?){: #json_api-routes-post_to_relationship-derive_sort? } | `boolean` | `true` | Whether or not to derive a sort parameter based on the sortable fields of the resource |
 | [`derive_filter?`](#json_api-routes-post_to_relationship-derive_filter?){: #json_api-routes-post_to_relationship-derive_filter? } | `boolean` | `true` | Whether or not to derive a filter parameter based on the sortable fields of the resource |
+| [`path_param_is_composite_key`](#json_api-routes-post_to_relationship-path_param_is_composite_key){: #json_api-routes-post_to_relationship-path_param_is_composite_key } | `atom` |  | The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details. |
 
 
 
@@ -511,6 +531,7 @@ patch_relationship :comments
 | [`name`](#json_api-routes-patch_relationship-name){: #json_api-routes-patch_relationship-name } | `String.t` |  | A globally unique name for this route, to be used when generating docs and open api specifications |
 | [`derive_sort?`](#json_api-routes-patch_relationship-derive_sort?){: #json_api-routes-patch_relationship-derive_sort? } | `boolean` | `true` | Whether or not to derive a sort parameter based on the sortable fields of the resource |
 | [`derive_filter?`](#json_api-routes-patch_relationship-derive_filter?){: #json_api-routes-patch_relationship-derive_filter? } | `boolean` | `true` | Whether or not to derive a filter parameter based on the sortable fields of the resource |
+| [`path_param_is_composite_key`](#json_api-routes-patch_relationship-path_param_is_composite_key){: #json_api-routes-patch_relationship-path_param_is_composite_key } | `atom` |  | The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details. |
 
 
 
@@ -555,6 +576,7 @@ delete_from_relationship :comments
 | [`name`](#json_api-routes-delete_from_relationship-name){: #json_api-routes-delete_from_relationship-name } | `String.t` |  | A globally unique name for this route, to be used when generating docs and open api specifications |
 | [`derive_sort?`](#json_api-routes-delete_from_relationship-derive_sort?){: #json_api-routes-delete_from_relationship-derive_sort? } | `boolean` | `true` | Whether or not to derive a sort parameter based on the sortable fields of the resource |
 | [`derive_filter?`](#json_api-routes-delete_from_relationship-derive_filter?){: #json_api-routes-delete_from_relationship-derive_filter? } | `boolean` | `true` | Whether or not to derive a filter parameter based on the sortable fields of the resource |
+| [`path_param_is_composite_key`](#json_api-routes-delete_from_relationship-path_param_is_composite_key){: #json_api-routes-delete_from_relationship-path_param_is_composite_key } | `atom` |  | The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details. |
 
 
 
@@ -601,6 +623,7 @@ route :get, "say_hi/:name", :say_hello
 | [`name`](#json_api-routes-route-name){: #json_api-routes-route-name } | `String.t` |  | A globally unique name for this route, to be used when generating docs and open api specifications |
 | [`derive_sort?`](#json_api-routes-route-derive_sort?){: #json_api-routes-route-derive_sort? } | `boolean` | `true` | Whether or not to derive a sort parameter based on the sortable fields of the resource |
 | [`derive_filter?`](#json_api-routes-route-derive_filter?){: #json_api-routes-route-derive_filter? } | `boolean` | `true` | Whether or not to derive a filter parameter based on the sortable fields of the resource |
+| [`path_param_is_composite_key`](#json_api-routes-route-path_param_is_composite_key){: #json_api-routes-route-path_param_is_composite_key } | `atom` |  | The path parameter that should be parsed as a composite primary key. When specified (e.g., :id), the parameter will be split using the resource's primary key delimiter and mapped to individual primary key fields. This is required for resources with composite primary keys to work correctly with GET, PATCH, and DELETE operations. See the composite primary keys documentation for more details. |
 
 
 

documentation/dsls/DSL-AshJsonApi.Resource.md

@@ -0,0 +1,118 @@
+# Composite Primary Keys
+
+When working with resources that have composite primary keys (multiple fields that together form the unique identifier), AshJsonApi provides special support for encoding and decoding these keys in URLs.
+
+## Defining Composite Primary Keys
+
+First, define your composite primary key in the JSON API configuration:
+
+```elixir
+defmodule MyApp.Bio do
+  use Ash.Resource,
+    extensions: [AshJsonApi.Resource]
+
+  attributes do
+    attribute :author_id, :uuid, primary_key?: true, public?: true
+    attribute :category, :string, primary_key?: true, public?: true
+    attribute :content, :string, public?: true
+  end
+
+  json_api do
+    type "bio"
+    
+    primary_key do
+      keys [:author_id, :category]
+      delimiter "|"  # Use a delimiter that won't conflict with your data
+    end
+  end
+end
+```
+
+### Important Considerations for Delimiters
+
+When choosing a delimiter, ensure it won't appear in your actual data:
+
+- **UUIDs contain dashes (`-`)** - Don't use `-` as a delimiter if any of your composite key fields are UUIDs
+- **Safe alternatives**: `|`, `~`, `::`, or other characters unlikely to appear in your data
+- **Default delimiter**: If not specified, AshJsonApi uses `-` as the default delimiter
+
+## Enabling Composite Key Parsing in Routes
+
+To enable automatic parsing of composite primary keys in URL paths, you must opt-in by specifying the `path_param_is_composite_key` option on your routes:
+
+```elixir
+json_api do
+  type "bio"
+  
+  primary_key do
+    keys [:author_id, :category]
+    delimiter "|"
+  end
+  
+  routes do
+    base "/bios"
+    
+    # Enable composite key parsing for the :id parameter
+    get :read, path_param_is_composite_key: :id
+    patch :update, path_param_is_composite_key: :id
+    delete :destroy, path_param_is_composite_key: :id
+    
+    # Other routes that don't need composite key parsing
+    index :read
+    post :create
+  end
+end
+```
+
+## How It Works
+
+With the above configuration:
+
+1. **URL Format**: `/bios/550e8400-e29b-41d4-a716-446655440000|sports`
+2. **Parsing**: The `:id` parameter `550e8400-e29b-41d4-a716-446655440000|sports` gets split by the `|` delimiter
+3. **Mapping**: The parts are mapped to the primary key fields in order:
+   - `author_id` = `550e8400-e29b-41d4-a716-446655440000`
+   - `category` = `sports`
+4. **Filtering**: The query is filtered to find the record with both `author_id` and `category` matching
+
+## Example Usage
+
+```elixir
+# Creating a bio
+POST /bios
+{
+  "data": {
+    "type": "bio",
+    "attributes": {
+      "author_id": "550e8400-e29b-41d4-a716-446655440000",
+      "category": "sports",
+      "content": "Author bio for sports category"
+    }
+  }
+}
+
+# Retrieving the bio using composite key
+GET /bios/550e8400-e29b-41d4-a716-446655440000|sports
+
+# Updating the bio
+PATCH /bios/550e8400-e29b-41d4-a716-446655440000|sports
+{
+  "data": {
+    "type": "bio", 
+    "attributes": {
+      "content": "Updated bio content"
+    }
+  }
+}
+
+# Deleting the bio
+DELETE /bios/550e8400-e29b-41d4-a716-446655440000|sports
+```
+
+## Without Opt-In Parsing
+
+If you don't specify `path_param_is_composite_key` on a route, the path parameter will be treated as a regular single value, even if your resource has composite primary keys defined. This ensures backward compatibility and prevents unexpected behavior.
+
+## Error Handling
+
+If the composite key format is invalid (wrong number of parts after splitting), AshJsonApi will return a 404 Not Found error with appropriate JSON:API error formatting.