Add require_type_on_create? for JSON:API spec compliance (issue #164) (#414)

* Add require_type_on_create? for JSON:API spec compliance (issue #164)

* mix.lock and test changes

* Shortened require-type-on-create.md

* small fixes to require-type-on-create and md file removed and added small bit to DSL-AshJsonApi.Domain.md

* removed require-type-on-create.md

* mix spark.formatter, mix spark.cheat_sheets, and mix format ran

Author: Dgoz101

.formatter.exs

@@ -65,6 +65,7 @@ spark_locals_without_parens = [
   relationship: 3,
   relationship: 4,
   relationship_arguments: 1,
+  require_type_on_create?: 1,
   resource: 1,
   route: 1,
   route: 3,

documentation/dsls/DSL-AshJsonApi.Domain.md

@@ -3,11 +3,11 @@ This file was generated by Spark. Do not edit it by hand.
 -->
 # AshJsonApi.Domain
 
-The entrypoint for adding JSON:API behavior to an Ash domain
+The entrypoint for adding JSON:API behavior to an Ash domain
 
 
 ## json_api
-Global configuration for JSON:API
+Global configuration for JSON:API
 
 
 ### Nested DSLs
@@ -40,10 +40,10 @@ Global configuration for JSON:API
 
 ### Examples
 ```
-json_api do
-  prefix "/json_api"
-  log_errors? true
-end
+json_api do
+  prefix "/json_api"
+  log_errors? true
+end
 
 ```
 
@@ -61,7 +61,8 @@ 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 ``` |
+| [`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 ``` |
+| [`require_type_on_create?`](#json_api-require_type_on_create?){: #json_api-require_type_on_create? } | `boolean` | `false` | When true, POST create requests MUST include type in data. Default false for backwards compatibility; in a future major version may default to true. |
 
 
 ### json_api.open_api
@@ -71,13 +72,13 @@ OpenAPI configurations
 
 ### Examples
 ```
-json_api do
-  ...
-  open_api do
-    tag "Users"
-    group_by :api
-  end
-end
+json_api do
+  ...
+  open_api do
+    tag "Users"
+    group_by :api
+  end
+end
 
 ```
 
@@ -125,20 +126,20 @@ Configure the routes that will be exposed via the JSON:API
 
 ### Examples
 ```
-routes do
-  base "/posts"
-
-  get :read
-  get :me, route: "/me"
-  index :read
-  post :confirm_name, route: "/confirm_name"
-  patch :update
-  related :comments, :read
-  relationship :comments, :read
-  post_to_relationship :comments
-  patch_relationship :comments
-  delete_from_relationship :comments
-end
+routes do
+  base "/posts"
+
+  get :read
+  get :me, route: "/me"
+  index :read
+  post :confirm_name, route: "/confirm_name"
+  patch :update
+  related :comments, :read
+  relationship :comments, :read
+  post_to_relationship :comments
+  patch_relationship :comments
+  delete_from_relationship :comments
+end
 
 ```
 
@@ -151,7 +152,7 @@ base_route route, resource \\ nil
 ```
 
 
-Sets a prefix for a list of contained routes
+Sets a prefix for a list of contained routes
 
 
 ### Nested DSLs
@@ -170,14 +171,14 @@ Sets a prefix for a list of contained routes
 
 ### Examples
 ```
-base_route "/posts" do
-  index :read
-  get :read
-end
-
-base_route "/comments" do
-  index :read
-end
+base_route "/posts" do
+  index :read
+  get :read
+end
+
+base_route "/comments" do
+  index :read
+end
 
 ```
 

documentation/dsls/DSL-AshJsonApi.Resource.md

@@ -3,7 +3,7 @@ This file was generated by Spark. Do not edit it by hand.
 -->
 # AshJsonApi.Resource
 
-The entrypoint for adding JSON:API behavior to a resource"
+The entrypoint for adding JSON:API behavior to a resource"
 
 
 ## json_api
@@ -27,30 +27,30 @@ Configure the resource's behavior in the JSON:API
 
 ### Examples
 ```
-json_api do
-  type "post"
-  includes [
-    friends: [
-      :comments
-    ],
-    comments: []
-  ]
-
-  routes do
-    base "/posts"
-
-    get :read
-    get :me, route: "/me"
-    index :read
-    post :confirm_name, route: "/confirm_name"
-    patch :update
-    related :comments, :read
-    relationship :comments, :read
-    post_to_relationship :comments
-    patch_relationship :comments
-    delete_from_relationship :comments
-  end
-end
+json_api do
+  type "post"
+  includes [
+    friends: [
+      :comments
+    ],
+    comments: []
+  ]
+
+  routes do
+    base "/posts"
+
+    get :read
+    get :me, route: "/me"
+    index :read
+    post :confirm_name, route: "/confirm_name"
+    patch :update
+    related :comments, :read
+    relationship :comments, :read
+    post_to_relationship :comments
+    patch_relationship :comments
+    delete_from_relationship :comments
+  end
+end
 
 ```
 
@@ -69,9 +69,9 @@ 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 |
-| [`field_names`](#json_api-field_names){: #json_api-field_names } | `:camelize \| :dasherize \| keyword \| (any -> any)` |  | Renames fields (attributes, relationships, calculations, and aggregates) in the JSON:API output and input. Can be one of the atoms `:camelize` or `:dasherize` for automatic conversion, 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). ```elixir field_names :camelize  # first_name → firstName field_names :dasherize # first_name → first-name ``` Or with a keyword list: ```elixir field_names [   first_name: :firstName,   last_name: :lastName ] ``` Or with a function for custom logic: ```elixir field_names fn name ->   camelized = name \|> to_string() \|> Macro.camelize()   {first, rest} = String.split_at(camelized, 1)   String.downcase(first) <> rest end ``` Names are applied consistently across serialization, request parsing, sort/filter parameters, field selection, error source pointers, relationship keys, and schema generation. |
-| [`argument_names`](#json_api-argument_names){: #json_api-argument_names } | `:camelize \| :dasherize \| keyword \| (any, any -> any)` |  | Renames action arguments in the JSON:API request body and schema. Can be one of the atoms `:camelize` or `:dasherize` for automatic conversion, 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 :camelize  # publish_at → publishAt argument_names :dasherize # publish_at → publish-at ``` Or with a keyword list: ```elixir argument_names [   create: [my_arg: :myArg],   update: [my_arg: :myArg] ] ``` Or with a function: ```elixir argument_names fn _action, name ->   camelized = name \|> to_string() \|> Macro.camelize()   {first, rest} = String.split_at(camelized, 1)   String.downcase(first) <> rest end ``` |
-| [`calculation_argument_names`](#json_api-calculation_argument_names){: #json_api-calculation_argument_names } | `:camelize \| :dasherize \| keyword \| (any, any -> any)` |  | Renames calculation arguments in the JSON:API request and schema. Works the same way as `argument_names` but applies to calculation arguments instead of action arguments. The 2-arity function receives `(calculation_name, argument_name)`. Can be one of the atoms `:camelize` or `:dasherize` for automatic conversion, a nested keyword list of `[calc_name: [ash_name: :json_api_name]]` mappings, or a 2-arity function that receives `(calculation_name, argument_name)` atoms and returns the desired JSON:API name (atom or string). ```elixir calculation_argument_names :camelize  # publish_at → publishAt calculation_argument_names :dasherize # publish_at → publish-at ``` Or with a keyword list: ```elixir calculation_argument_names [   full_name: [separator: :sep] ] ``` Or with a function: ```elixir calculation_argument_names fn _calc, name ->   camelized = name \|> to_string() \|> Macro.camelize()   {first, rest} = String.split_at(camelized, 1)   String.downcase(first) <> rest end ``` |
+| [`field_names`](#json_api-field_names){: #json_api-field_names } | `:camelize \| :dasherize \| keyword \| (any -> any)` |  | Renames fields (attributes, relationships, calculations, and aggregates) in the JSON:API output and input.  Can be one of the atoms `:camelize` or `:dasherize` for automatic conversion, 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).  ```elixir field_names :camelize  # first_name → firstName field_names :dasherize # first_name → first-name ```  Or with a keyword list:  ```elixir field_names [   first_name: :firstName,   last_name: :lastName ] ```  Or with a function for custom logic:  ```elixir field_names fn name ->   camelized = name \|> to_string() \|> Macro.camelize()   {first, rest} = String.split_at(camelized, 1)   String.downcase(first) <> rest end ```  Names are applied consistently across serialization, request parsing, sort/filter parameters, field selection, error source pointers, relationship keys, and schema generation. |
+| [`argument_names`](#json_api-argument_names){: #json_api-argument_names } | `:camelize \| :dasherize \| keyword \| (any, any -> any)` |  | Renames action arguments in the JSON:API request body and schema.  Can be one of the atoms `:camelize` or `:dasherize` for automatic conversion, 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 :camelize  # publish_at → publishAt argument_names :dasherize # publish_at → publish-at ```  Or with a keyword list:  ```elixir argument_names [   create: [my_arg: :myArg],   update: [my_arg: :myArg] ] ```  Or with a function:  ```elixir argument_names fn _action, name ->   camelized = name \|> to_string() \|> Macro.camelize()   {first, rest} = String.split_at(camelized, 1)   String.downcase(first) <> rest end ``` |
+| [`calculation_argument_names`](#json_api-calculation_argument_names){: #json_api-calculation_argument_names } | `:camelize \| :dasherize \| keyword \| (any, any -> any)` |  | Renames calculation arguments in the JSON:API request and schema.  Works the same way as `argument_names` but applies to calculation arguments instead of action arguments. The 2-arity function receives `(calculation_name, argument_name)`.  Can be one of the atoms `:camelize` or `:dasherize` for automatic conversion, a nested keyword list of `[calc_name: [ash_name: :json_api_name]]` mappings, or a 2-arity function that receives `(calculation_name, argument_name)` atoms and returns the desired JSON:API name (atom or string).  ```elixir calculation_argument_names :camelize  # publish_at → publishAt calculation_argument_names :dasherize # publish_at → publish-at ```  Or with a keyword list:  ```elixir calculation_argument_names [   full_name: [separator: :sep] ] ```  Or with a function:  ```elixir calculation_argument_names fn _calc, name ->   camelized = name \|> to_string() \|> Macro.camelize()   {first, rest} = String.split_at(camelized, 1)   String.downcase(first) <> rest end ``` |
 
 
 ### json_api.routes
@@ -93,20 +93,20 @@ Configure the routes that will be exposed via the JSON:API
 
 ### Examples
 ```
-routes do
-  base "/posts"
-
-  get :read
-  get :me, route: "/me"
-  index :read
-  post :confirm_name, route: "/confirm_name"
-  patch :update
-  related :comments, :read
-  relationship :comments, :read
-  post_to_relationship :comments
-  patch_relationship :comments
-  delete_from_relationship :comments
-end
+routes do
+  base "/posts"
+
+  get :read
+  get :me, route: "/me"
+  index :read
+  post :confirm_name, route: "/confirm_name"
+  patch :update
+  related :comments, :read
+  relationship :comments, :read
+  post_to_relationship :comments
+  patch_relationship :comments
+  delete_from_relationship :comments
+end
 
 ```
 
@@ -667,10 +667,10 @@ Encode the id of the JSON API response from selected attributes of a resource
 
 ### Examples
 ```
-primary_key do
-  keys [:first_name, :last_name]
-  delimiter "~"
-end
+primary_key do
+  keys [:first_name, :last_name]
+  delimiter "~"
+end
 
 ```
 

lib/ash_json_api/domain/domain.ex

@@ -188,6 +188,12 @@ defmodule AshJsonApi.Domain do
         end
         ```
         """
+      ],
+      require_type_on_create?: [
+        type: :boolean,
+        default: false,
+        doc:
+          "When true, POST create requests MUST include type in data. Default false for backwards compatibility; in a future major version may default to true."
       ]
     ],
     sections: [@open_api, @routes]

lib/ash_json_api/domain/info.ex

@@ -50,4 +50,8 @@ defmodule AshJsonApi.Domain.Info do
   def error_handler(domain) do
     Extension.get_opt(domain, [:json_api], :error_handler, nil, true)
   end
+
+  def require_type_on_create?(domain) do
+    Extension.get_opt(domain, [:json_api], :require_type_on_create?, false, true)
+  end
 end

lib/ash_json_api/error/missing_type_on_create.ex

@@ -0,0 +1,29 @@
+# SPDX-FileCopyrightText: 2019 ash_json_api contributors <https://github.com/ash-project/ash_json_api/graphs/contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule AshJsonApi.Error.MissingTypeOnCreate do
+  @moduledoc """
+  Returned when a POST create request has a data object but no type member,
+  and the domain has require_type_on_create? enabled (JSON:API spec compliance).
+  """
+  use Splode.Error, class: :invalid, fields: []
+
+  def message(_error) do
+    "The resource object MUST contain at least a type member."
+  end
+
+  defimpl AshJsonApi.ToJsonApiError do
+    def to_json_api_error(_error) do
+      %AshJsonApi.Error{
+        id: Ash.UUID.generate(),
+        status_code: 400,
+        code: "missing_type",
+        title: "Invalid resource object",
+        detail: "The resource object MUST contain at least a type member.",
+        source_pointer: "/data",
+        meta: %{}
+      }
+    end
+  end
+end

lib/ash_json_api/request.ex

@@ -15,6 +15,7 @@ defmodule AshJsonApi.Request do
     InvalidQuery,
     InvalidRelationshipInput,
     InvalidType,
+    MissingTypeOnCreate,
     UnacceptableMediaType,
     UnsupportedMediaType
   }
@@ -111,6 +112,7 @@ defmodule AshJsonApi.Request do
     |> validate_href_schema()
     |> validate_req_headers()
     |> validate_body()
+    |> validate_require_type_on_create()
     |> parse_fields()
     |> parse_field_inputs()
     |> parse_filter_included()
@@ -197,6 +199,29 @@ defmodule AshJsonApi.Request do
     end)
   end
 
+  defp validate_require_type_on_create(
+         %{
+           route: %{type: :post},
+           body: %{"data" => data},
+           domain: domain
+         } = request
+       )
+       when is_map(data) do
+    if AshJsonApi.Domain.Info.require_type_on_create?(domain) do
+      type_value = Map.get(data, "type")
+
+      if type_value in [nil, ""] do
+        add_error(request, MissingTypeOnCreate.exception([]), request.route.type)
+      else
+        request
+      end
+    else
+      request
+    end
+  end
+
+  defp validate_require_type_on_create(request), do: request
+
   defp validate_body(%{body: body, schema: %{"schema" => schema}} = request) do
     json_xema = JsonXema.new(schema)
 

lib/ash_json_api/serializer.ex

@@ -383,7 +383,7 @@ defmodule AshJsonApi.Serializer do
 
   defp add_prev_link(links, uri, query, %Ash.Page.Keyset{} = paginator) do
     case paginator do
-      # First page in request, there should be no previous links since its fetching the latest data at the point in time
+      # First page: no previous link (fetching latest data at this point in time)
       %{before: nil, after: nil} ->
         Map.put(links, :prev, nil)