feat: add field mapping utilities

Author: zachdaniel

.formatter.exs

@@ -5,6 +5,7 @@
 spark_locals_without_parens = [
   action_names_in_schema: 1,
   always_include_linkage: 1,
+  argument_names: 1,
   authorize?: 1,
   base: 1,
   base_route: 1,
@@ -21,6 +22,8 @@ spark_locals_without_parens = [
   derive_filter?: 1,
   derive_sort?: 1,
   description: 1,
+  error_handler: 1,
+  field_names: 1,
   get: 1,
   get: 2,
   get: 3,

documentation/dsls/DSL-AshJsonApi.Domain.md

@@ -61,6 +61,7 @@ end
 | [`authorize?`](#json_api-authorize?){: #json_api-authorize? } | `boolean` | `true` | Whether or not to perform authorization on requests. |
 | [`log_errors?`](#json_api-log_errors?){: #json_api-log_errors? } | `boolean` | `true` | Whether or not to log any errors produced |
 | [`include_nil_values?`](#json_api-include_nil_values?){: #json_api-include_nil_values? } | `boolean` | `true` | Whether or not to include properties for values that are nil in the JSON output |
+| [`error_handler`](#json_api-error_handler){: #json_api-error_handler } | `mfa` |  | Set an MFA to intercept/handle any errors that are generated. The function will be called with a `AshJsonApi.Error` struct and a context map, and should return a modified `AshJsonApi.Error` struct. The context map contains `:domain` and `:resource`. For example: ```elixir defmodule MyApp.ErrorHandler do   def handle_error(error, _context) do     %{error \| detail: "Something went wrong"}   end end ``` And in your domain: ```elixir json_api do   error_handler {MyApp.ErrorHandler, :handle_error, []} end ``` |
 
 
 ### json_api.open_api

documentation/dsls/DSL-AshJsonApi.Resource.md

@@ -69,6 +69,8 @@ end
 | [`default_fields`](#json_api-default_fields){: #json_api-default_fields } | `list(atom)` |  | The fields to include in the object if the `fields` query parameter does not specify. Defaults to all public |
 | [`derive_sort?`](#json_api-derive_sort?){: #json_api-derive_sort? } | `boolean` | `true` | Whether or not to derive a sort parameter based on the sortable fields of the resource |
 | [`derive_filter?`](#json_api-derive_filter?){: #json_api-derive_filter? } | `boolean` | `true` | Whether or not to derive a filter parameter based on the sortable fields of the resource |
+| [`attribute_names`](#json_api-attribute_names){: #json_api-attribute_names } | `keyword \| (any -> any)` |  | Renames attributes (and calculations/aggregates) in the JSON:API output and input. Can be a keyword list of `[ash_name: :json_api_name]` mappings, or a 1-arity function that receives an atom field name and returns the desired JSON:API name (atom or string). The function form is useful for applying a blanket transformation such as camelCase: ```elixir attribute_names fn name ->   name \|> to_string() \|> Macro.camelize() \|> String.downcase_first() end ``` Or with a keyword list: ```elixir attribute_names [   first_name: :firstName,   last_name: :lastName ] ``` Names are applied consistently across serialization, request parsing, sort/filter parameters, field selection, error source pointers, and schema generation. |
+| [`argument_names`](#json_api-argument_names){: #json_api-argument_names } | `keyword \| (any, any -> any)` |  | Renames action arguments in the JSON:API request body and schema. Can be a nested keyword list of `[action_name: [ash_name: :json_api_name]]` mappings, or a 2-arity function that receives `(action_name, argument_name)` atoms and returns the desired JSON:API name (atom or string). ```elixir argument_names [   create: [my_arg: :myArg],   update: [my_arg: :myArg] ] ``` Or with a function: ```elixir argument_names fn _action, name ->   name \|> to_string() \|> Macro.camelize() \|> String.downcase_first() end ``` |
 
 
 ### json_api.routes

documentation/topics/field-names.md

@@ -0,0 +1,131 @@
+<!--
+SPDX-FileCopyrightText: 2020 Zach Daniel
+
+SPDX-License-Identifier: MIT
+-->
+
+# Transforming Field Names
+
+By default, AshJsonApi uses the Ash resource's attribute, relationship, calculation, and aggregate names directly as JSON:API field names. This means a `:first_name` attribute appears as `"first_name"` in requests and responses. The `field_names` and `argument_names` DSL options let you change this — for example, to expose a camelCase API while keeping snake_case internals.
+
+These options affect **every** place a field or argument name appears: serialization output, request body parsing, sort and filter parameters, sparse fieldsets, error source pointers, relationship keys, JSON Schema, and OpenAPI spec generation.
+
+## Renaming fields
+
+### Keyword list
+
+Use a keyword list to rename specific fields:
+
+```elixir
+json_api do
+  type "user"
+
+  field_names first_name: :firstName, last_name: :lastName
+end
+```
+
+A `GET /users/:id` response would then return:
+
+```json
+{
+  "data": {
+    "type": "user",
+    "id": "...",
+    "attributes": {
+      "firstName": "Ada",
+      "lastName": "Lovelace"
+    }
+  }
+}
+```
+
+Fields not listed in the keyword list keep their original names.
+
+### Function
+
+Use a 1-arity function for a blanket transformation. This is useful for converting all field names to camelCase:
+
+```elixir
+json_api do
+  type "user"
+
+  field_names fn name ->
+    camelized = name |> to_string() |> Macro.camelize()
+    {first, rest} = String.split_at(camelized, 1)
+    String.downcase(first) <> rest
+  end
+end
+```
+
+This applies to all public attributes, relationships, calculations, and aggregates on the resource.
+
+## Renaming action arguments
+
+Action arguments (the values sent in the request body under `data.attributes`) can also be renamed with `argument_names`.
+
+### Keyword list
+
+Provide a nested keyword list keyed by action name:
+
+```elixir
+json_api do
+  type "post"
+
+  argument_names [
+    create: [publish_at: :publishAt],
+    update: [publish_at: :publishAt]
+  ]
+end
+```
+
+### Function
+
+Use a 2-arity function that receives `(action_name, argument_name)`:
+
+```elixir
+json_api do
+  type "post"
+
+  argument_names fn _action_name, arg_name ->
+    camelized = arg_name |> to_string() |> Macro.camelize()
+    {first, rest} = String.split_at(camelized, 1)
+    String.downcase(first) <> rest
+  end
+end
+```
+
+The `action_name` parameter lets you apply different mappings per action if needed.
+
+## Where renaming is applied
+
+Once configured, name mapping is applied consistently across:
+
+- **Serialization** — response `attributes` and `relationships` objects use the renamed keys.
+- **Request body parsing** — `data.attributes` keys in POST/PATCH bodies are expected under their renamed forms.
+- **Sort parameters** — `?sort=firstName` works when `:first_name` is renamed to `firstName`.
+- **Filter parameters** — `?filter[firstName]=Ada` maps back to the `:first_name` attribute via a ref transformer passed to `Ash.Filter.parse_input/3`.
+- **Sparse fieldsets** — `?fields[user]=firstName,lastName` selects the renamed fields.
+- **Error source pointers** — validation errors point to `/data/attributes/firstName` instead of `/data/attributes/first_name`.
+- **JSON Schema & OpenAPI** — generated schemas use the renamed property names.
+
+## Combining both options
+
+You can use `field_names` and `argument_names` together. A common pattern is to camelCase everything:
+
+```elixir
+json_api do
+  type "user"
+
+  field_names fn name ->
+    camelized = name |> to_string() |> Macro.camelize()
+    {first, rest} = String.split_at(camelized, 1)
+    String.downcase(first) <> rest
+  end
+
+  argument_names fn _action, name ->
+    camelized = name |> to_string() |> Macro.camelize()
+    {first, rest} = String.split_at(camelized, 1)
+    String.downcase(first) <> rest
+  end
+end
+```

lib/ash_json_api/controllers/helpers.ex

@@ -90,11 +90,19 @@ defmodule AshJsonApi.Controllers.Helpers do
               other
           end
 
-        query =
+        base_query =
           request.resource
           |> Ash.Query.load(request.includes_keyword)
           |> Ash.Query.set_context(request.context)
-          |> Ash.Query.do_filter(filter)
+
+        query =
+          if filter do
+            Ash.Query.filter_input(base_query, filter,
+              ref_transformer: AshJsonApi.Resource.Info.filter_ref_transformer()
+            )
+          else
+            base_query
+          end
           |> Ash.Query.sort(request.sort)
           |> Ash.Query.load(fields(request, request.resource))
           |> Ash.Query.for_read(request.action.name, request.arguments, Request.opts(request))
@@ -690,7 +698,9 @@ defmodule AshJsonApi.Controllers.Helpers do
 
         query =
           if filter do
-            case Ash.Filter.parse_input(resource, filter) do
+            case Ash.Filter.parse_input(resource, filter,
+                   ref_transformer: AshJsonApi.Resource.Info.filter_ref_transformer()
+                 ) do
               {:ok, parsed} ->
                 {:ok, Ash.Query.filter(resource, ^parsed)}
 
@@ -788,7 +798,9 @@ defmodule AshJsonApi.Controllers.Helpers do
 
             query =
               if filter do
-                case Ash.Filter.parse_input(resource, filter) do
+                case Ash.Filter.parse_input(resource, filter,
+                       ref_transformer: AshJsonApi.Resource.Info.filter_ref_transformer()
+                     ) do
                   {:ok, parsed} ->
                     {:ok, Ash.Query.filter(resource, ^parsed)}
 

lib/ash_json_api/error/error.ex

@@ -188,16 +188,18 @@ defmodule AshJsonApi.Error do
     [built_error]
   end
 
-  defp source_pointer(_resource, field, path, :action) do
-    "/data/attributes/#{Enum.join(List.wrap(path) ++ [field], "/")}"
+  defp source_pointer(resource, field, path, :action) do
+    json_key = AshJsonApi.Resource.Info.field_to_json_key(resource, field)
+    "/data/attributes/#{Enum.join(List.wrap(path) ++ [json_key], "/")}"
   end
 
   defp source_pointer(resource, field, path, type)
        when type in [:create, :update] and not is_nil(field) do
     if path == [] && Ash.Resource.Info.public_relationship(resource, field) do
       "/data/relationships/#{field}"
     else
-      "/data/attributes/#{Enum.join(List.wrap(path) ++ [field], "/")}"
+      json_key = AshJsonApi.Resource.Info.field_to_json_key(resource, field)
+      "/data/attributes/#{Enum.join(List.wrap(path) ++ [json_key], "/")}"
     end
   end
 

lib/ash_json_api/json_schema/json_schema.ex

@@ -279,7 +279,7 @@ defmodule AshJsonApi.JsonSchema do
     resource
     |> Ash.Resource.Info.public_attributes()
     |> Enum.reject(&(&1.allow_nil? || AshJsonApi.Resource.only_primary_key?(resource, &1.name)))
-    |> Enum.map(&to_string(&1.name))
+    |> Enum.map(&AshJsonApi.Resource.Info.field_to_json_key(resource, &1.name))
   end
 
   defp resource_attributes(resource) do
@@ -292,7 +292,11 @@ defmodule AshJsonApi.JsonSchema do
     )
     |> Enum.reject(&AshJsonApi.Resource.only_primary_key?(resource, &1.name))
     |> Enum.reduce(%{}, fn attr, acc ->
-      Map.put(acc, to_string(attr.name), resource_attribute_type(attr))
+      Map.put(
+        acc,
+        AshJsonApi.Resource.Info.field_to_json_key(resource, attr.name),
+        resource_attribute_type(attr)
+      )
     end)
   end
 
@@ -735,16 +739,15 @@ defmodule AshJsonApi.JsonSchema do
       action.arguments
       |> Enum.filter(& &1.public?)
       |> Enum.reduce(props, fn argument, props ->
-        Map.put(
-          props,
-          to_string(argument.name),
-          resource_write_attribute_type(argument, argument.type)
-        )
+        json_key =
+          AshJsonApi.Resource.Info.argument_to_json_key(resource, action.name, argument.name)
+
+        Map.put(props, json_key, resource_write_attribute_type(argument, argument.type))
       end),
       action.arguments
       |> Enum.filter(& &1.public?)
       |> Enum.reject(& &1.allow_nil?)
-      |> Enum.map(&"#{&1.name}")
+      |> Enum.map(&AshJsonApi.Resource.Info.argument_to_json_key(resource, action.name, &1.name))
     }
   end
 
@@ -759,7 +762,7 @@ defmodule AshJsonApi.JsonSchema do
   defp sort_format(resource) do
     sorts = sortable_fields(resource)
 
-    "(#{Enum.map_join(sorts, "|", & &1.name)}),*"
+    "(#{Enum.map_join(sorts, "|", &AshJsonApi.Resource.Info.field_to_json_key(resource, &1.name))}),*"
   end
 
   defp page_props(_domain, _resource) do
@@ -972,7 +975,14 @@ defmodule AshJsonApi.JsonSchema do
 
   defp required_write_attributes(resource, arguments, action, route \\ nil) do
     AshJsonApi.OpenApi.required_write_attributes(resource, arguments, action, route)
-    |> Enum.map(&to_string/1)
+    |> Enum.map(fn atom_name ->
+      # Try argument first, then attribute
+      if Enum.any?(arguments, &(&1.name == atom_name)) do
+        AshJsonApi.Resource.Info.argument_to_json_key(resource, action.name, atom_name)
+      else
+        AshJsonApi.Resource.Info.field_to_json_key(resource, atom_name)
+      end
+    end)
   end
 
   defp write_attributes(resource, arguments, action, route \\ nil) do
@@ -986,7 +996,7 @@ defmodule AshJsonApi.JsonSchema do
         |> Enum.reduce(%{}, fn attribute, acc ->
           Map.put(
             acc,
-            to_string(attribute.name),
+            AshJsonApi.Resource.Info.field_to_json_key(resource, attribute.name),
             resource_write_attribute_type(attribute, action.type)
           )
         end)
@@ -997,7 +1007,7 @@ defmodule AshJsonApi.JsonSchema do
     |> Enum.reduce(attributes, fn argument, attributes ->
       Map.put(
         attributes,
-        to_string(argument.name),
+        AshJsonApi.Resource.Info.argument_to_json_key(resource, action.name, argument.name),
         resource_write_attribute_type(argument, :create)
       )
     end)
@@ -1018,11 +1028,11 @@ defmodule AshJsonApi.JsonSchema do
 
   defp without_path_arguments(arguments, _, _), do: arguments
 
-  defp required_relationship_attributes(_resource, relationship_arguments, action) do
+  defp required_relationship_attributes(resource, relationship_arguments, action) do
     action.arguments
     |> Enum.filter(&has_relationship_argument?(relationship_arguments, &1.name))
     |> Enum.reject(& &1.allow_nil?)
-    |> Enum.map(&to_string(&1.name))
+    |> Enum.map(&AshJsonApi.Resource.Info.argument_to_json_key(resource, action.name, &1.name))
   end
 
   defp write_relationships(resource, relationship_arguments, action) do
@@ -1035,7 +1045,7 @@ defmodule AshJsonApi.JsonSchema do
 
       Map.put(
         acc,
-        to_string(argument.name),
+        AshJsonApi.Resource.Info.argument_to_json_key(resource, action.name, argument.name),
         object
       )
     end)