Enable client-generated IDs per resource type. Obsolete boolean value in favor of enumeration Forbidden/Allowed/Required

Author: bkoelman

JsonApiDotNetCore.sln.DotSettings

@@ -665,6 +665,7 @@ $left$ = $right$;</s:String>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Startups/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=subdirectory/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=unarchive/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Unprocessable/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Workflows/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=xunit/@EntryIndexedValue">True</s:Boolean>
 </wpf:ResourceDictionary>

docs/usage/options.md

@@ -10,16 +10,35 @@ builder.Services.AddJsonApi<AppDbContext>(options =>
 });
 ```
 
-## Client Generated IDs
+## Client-generated IDs
 
 By default, the server will respond with a 403 Forbidden HTTP Status Code if a POST request is received with a client-generated ID.
 
-However, this can be allowed by setting the AllowClientGeneratedIds flag in the options:
+However, this can be allowed or required globally (for all resource types) by setting `ClientIdGeneration` in options:
 
 ```c#
-options.AllowClientGeneratedIds = true;
+options.ClientIdGeneration = ClientIdGenerationMode.Allowed;
 ```
 
+or:
+
+```c#
+options.ClientIdGeneration = ClientIdGenerationMode.Required;
+```
+
+It is possible to overrule this setting per resource type:
+
+```c#
+[Resource(ClientIdGeneration = ClientIdGenerationMode.Required)]
+public class Article : Identifiable<Guid>
+{
+    // ...
+}
+```
+
+> [!NOTE]
+> JsonApiDotNetCore versions before v5.4.0 only provided the global `AllowClientGeneratedIds` boolean property.
+
 ## Pagination
 
 The default page size used for all resources can be overridden in options (10 by default). To disable pagination, set it to `null`.

src/JsonApiDotNetCore.Annotations/Configuration/ClientIdGenerationMode.shared.cs

@@ -0,0 +1,25 @@
+using JetBrains.Annotations;
+
+namespace JsonApiDotNetCore.Configuration;
+
+/// <summary>
+/// Indicates how to handle IDs sent by JSON:API clients when creating resources.
+/// </summary>
+[PublicAPI]
+public enum ClientIdGenerationMode
+{
+    /// <summary>
+    /// Returns an HTTP 403 (Forbidden) response if a client attempts to create a resource with a client-supplied ID.
+    /// </summary>
+    Forbidden,
+
+    /// <summary>
+    /// Allows a client to create a resource with a client-supplied ID, but does not require it.
+    /// </summary>
+    Allowed,
+
+    /// <summary>
+    /// Returns an HTTP 422 (Unprocessable Content) response if a client attempts to create a resource without a client-supplied ID.
+    /// </summary>
+    Required
+}

src/JsonApiDotNetCore.Annotations/Configuration/ResourceType.cs

@@ -18,6 +18,12 @@ public sealed class ResourceType
     /// </summary>
     public string PublicName { get; }
 
+    /// <summary>
+    /// Whether API clients are allowed or required to provide IDs when creating resources of this type. When <c>null</c>, the value from global options
+    /// applies.
+    /// </summary>
+    public ClientIdGenerationMode? ClientIdGeneration { get; }
+
     /// <summary>
     /// The CLR type of the resource.
     /// </summary>
@@ -89,22 +95,24 @@ public sealed class ResourceType
     /// </remarks>
     public LinkTypes RelationshipLinks { get; }
 
-    public ResourceType(string publicName, Type clrType, Type identityClrType, LinkTypes topLevelLinks = LinkTypes.NotConfigured,
-        LinkTypes resourceLinks = LinkTypes.NotConfigured, LinkTypes relationshipLinks = LinkTypes.NotConfigured)
-        : this(publicName, clrType, identityClrType, null, null, null, topLevelLinks, resourceLinks, relationshipLinks)
+    public ResourceType(string publicName, ClientIdGenerationMode? clientIdGeneration, Type clrType, Type identityClrType,
+        LinkTypes topLevelLinks = LinkTypes.NotConfigured, LinkTypes resourceLinks = LinkTypes.NotConfigured,
+        LinkTypes relationshipLinks = LinkTypes.NotConfigured)
+        : this(publicName, clientIdGeneration, clrType, identityClrType, null, null, null, topLevelLinks, resourceLinks, relationshipLinks)
     {
     }
 
-    public ResourceType(string publicName, Type clrType, Type identityClrType, IReadOnlyCollection<AttrAttribute>? attributes,
-        IReadOnlyCollection<RelationshipAttribute>? relationships, IReadOnlyCollection<EagerLoadAttribute>? eagerLoads,
-        LinkTypes topLevelLinks = LinkTypes.NotConfigured, LinkTypes resourceLinks = LinkTypes.NotConfigured,
-        LinkTypes relationshipLinks = LinkTypes.NotConfigured)
+    public ResourceType(string publicName, ClientIdGenerationMode? clientIdGeneration, Type clrType, Type identityClrType,
+        IReadOnlyCollection<AttrAttribute>? attributes, IReadOnlyCollection<RelationshipAttribute>? relationships,
+        IReadOnlyCollection<EagerLoadAttribute>? eagerLoads, LinkTypes topLevelLinks = LinkTypes.NotConfigured,
+        LinkTypes resourceLinks = LinkTypes.NotConfigured, LinkTypes relationshipLinks = LinkTypes.NotConfigured)
     {
         ArgumentGuard.NotNullNorEmpty(publicName);
         ArgumentGuard.NotNull(clrType);
         ArgumentGuard.NotNull(identityClrType);
 
         PublicName = publicName;
+        ClientIdGeneration = clientIdGeneration;
         ClrType = clrType;
         IdentityClrType = identityClrType;
         Attributes = attributes ?? Array.Empty<AttrAttribute>();

src/JsonApiDotNetCore.Annotations/Resources/Annotations/ResourceAttribute.shared.cs

@@ -1,4 +1,5 @@
 using JetBrains.Annotations;
+using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.Controllers;
 
 namespace JsonApiDotNetCore.Resources.Annotations;
@@ -10,11 +11,23 @@ namespace JsonApiDotNetCore.Resources.Annotations;
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)]
 public sealed class ResourceAttribute : Attribute
 {
+    internal ClientIdGenerationMode? NullableClientIdGeneration { get; set; }
+
     /// <summary>
     /// Optional. The publicly exposed name of this resource type.
     /// </summary>
     public string? PublicName { get; set; }
 
+    /// <summary>
+    /// Optional. Whether API clients are allowed or required to provide IDs when creating resources of this type. When not set, the value from global
+    /// options applies.
+    /// </summary>
+    public ClientIdGenerationMode ClientIdGeneration
+    {
+        get => NullableClientIdGeneration.GetValueOrDefault();
+        set => NullableClientIdGeneration = value;
+    }
+
     /// <summary>
     /// The set of endpoints to auto-generate an ASP.NET controller for. Defaults to <see cref="JsonApiEndpoints.All" />. Set to
     /// <see cref="JsonApiEndpoints.None" /> to disable controller generation.

src/JsonApiDotNetCore/Configuration/IJsonApiOptions.cs

@@ -1,5 +1,6 @@
 using System.Data;
 using System.Text.Json;
+using JetBrains.Annotations;
 using JsonApiDotNetCore.Resources.Annotations;
 using JsonApiDotNetCore.Serialization.Objects;
 
@@ -21,37 +22,40 @@ public interface IJsonApiOptions
     string? Namespace { get; }
 
     /// <summary>
-    /// Specifies the default set of allowed capabilities on JSON:API attributes. Defaults to <see cref="AttrCapabilities.All" />.
+    /// Specifies the default set of allowed capabilities on JSON:API attributes. Defaults to <see cref="AttrCapabilities.All" />. This setting can be
+    /// overruled per attribute using <see cref="AttrAttribute.Capabilities" />.
     /// </summary>
     AttrCapabilities DefaultAttrCapabilities { get; }
 
     /// <summary>
-    /// Specifies the default set of allowed capabilities on JSON:API to-one relationships. Defaults to <see cref="HasOneCapabilities.All" />.
+    /// Specifies the default set of allowed capabilities on JSON:API to-one relationships. Defaults to <see cref="HasOneCapabilities.All" />. This setting
+    /// can be overruled per relationship using <see cref="HasOneAttribute.Capabilities" />.
     /// </summary>
     HasOneCapabilities DefaultHasOneCapabilities { get; }
 
     /// <summary>
-    /// Specifies the default set of allowed capabilities on JSON:API to-many relationships. Defaults to <see cref="HasManyCapabilities.All" />.
+    /// Specifies the default set of allowed capabilities on JSON:API to-many relationships. Defaults to <see cref="HasManyCapabilities.All" />. This setting
+    /// can be overruled per relationship using <see cref="HasManyAttribute.Capabilities" />.
     /// </summary>
     HasManyCapabilities DefaultHasManyCapabilities { get; }
 
     /// <summary>
-    /// Indicates whether responses should contain a jsonapi object that contains the highest JSON:API version supported. False by default.
+    /// Whether to include a 'jsonapi' object in responses, which contains the highest JSON:API version supported. <c>false</c> by default.
     /// </summary>
     bool IncludeJsonApiVersion { get; }
 
     /// <summary>
-    /// Whether or not <see cref="Exception" /> stack traces should be included in <see cref="ErrorObject.Meta" />. False by default.
+    /// Whether to include <see cref="Exception" /> stack traces in <see cref="ErrorObject.Meta" /> responses. <c>false</c> by default.
     /// </summary>
     bool IncludeExceptionStackTraceInErrors { get; }
 
     /// <summary>
-    /// Whether or not the request body should be included in <see cref="Document.Meta" /> when it is invalid. False by default.
+    /// Whether to include the request body in <see cref="Document.Meta" /> responses when it is invalid. <c>false</c> by default.
     /// </summary>
     bool IncludeRequestBodyInErrors { get; }
 
     /// <summary>
-    /// Use relative links for all resources. False by default.
+    /// Whether to use relative links for all resources. <c>false</c> by default.
     /// </summary>
     /// <example>
     /// <code><![CDATA[
@@ -94,7 +98,7 @@ public interface IJsonApiOptions
     LinkTypes RelationshipLinks { get; }
 
     /// <summary>
-    /// Whether or not the total resource count should be included in top-level meta objects. This requires an additional database query. False by default.
+    /// Whether to include the total resource count in top-level meta objects. This requires an additional database query. <c>false</c> by default.
     /// </summary>
     bool IncludeTotalResourceCount { get; }
 
@@ -114,28 +118,40 @@ public interface IJsonApiOptions
     PageNumber? MaximumPageNumber { get; }
 
     /// <summary>
-    /// Whether or not to enable ASP.NET ModelState validation. True by default.
+    /// Whether ASP.NET ModelState validation is enabled. <c>true</c> by default.
     /// </summary>
     bool ValidateModelState { get; }
 
     /// <summary>
-    /// Whether or not clients can provide IDs when creating resources. When not allowed, a 403 Forbidden response is returned if a client attempts to create
-    /// a resource with a defined ID. False by default.
+    /// Whether clients are allowed or required to provide IDs when creating resources. <see cref="ClientIdGenerationMode.Forbidden" /> by default. This
+    /// setting can be overruled per resource type using <see cref="ResourceAttribute.ClientIdGeneration" />.
     /// </summary>
+    ClientIdGenerationMode ClientIdGeneration { get; }
+
+    /// <summary>
+    /// Whether clients can provide IDs when creating resources. When not allowed, a 403 Forbidden response is returned if a client attempts to create a
+    /// resource with a defined ID. <c>false</c> by default.
+    /// </summary>
+    /// <remarks>
+    /// Setting this to <c>true</c> corresponds to <see cref="ClientIdGenerationMode.Allowed" />, while <c>false</c> corresponds to
+    /// <see cref="ClientIdGenerationMode.Forbidden" />.
+    /// </remarks>
+    [PublicAPI]
+    [Obsolete("Use ClientIdGeneration instead.")]
     bool AllowClientGeneratedIds { get; }
 
     /// <summary>
-    /// Whether or not to produce an error on unknown query string parameters. False by default.
+    /// Whether to produce an error on unknown query string parameters. <c>false</c> by default.
     /// </summary>
     bool AllowUnknownQueryStringParameters { get; }
 
     /// <summary>
-    /// Whether or not to produce an error on unknown attribute and relationship keys in request bodies. False by default.
+    /// Whether to produce an error on unknown attribute and relationship keys in request bodies. <c>false</c> by default.
     /// </summary>
     bool AllowUnknownFieldsInRequestBody { get; }
 
     /// <summary>
-    /// Determines whether legacy filter notation in query strings, such as =eq:, =like:, and =in: is enabled. False by default.
+    /// Determines whether legacy filter notation in query strings (such as =eq:, =like:, and =in:) is enabled. <c>false</c> by default.
     /// </summary>
     bool EnableLegacyFilterNotation { get; }
 

src/JsonApiDotNetCore/Configuration/JsonApiOptions.cs

@@ -69,7 +69,15 @@ public sealed class JsonApiOptions : IJsonApiOptions
     public bool ValidateModelState { get; set; } = true;
 
     /// <inheritdoc />
-    public bool AllowClientGeneratedIds { get; set; }
+    public ClientIdGenerationMode ClientIdGeneration { get; set; }
+
+    /// <inheritdoc />
+    [Obsolete("Use ClientIdGeneration instead.")]
+    public bool AllowClientGeneratedIds
+    {
+        get => ClientIdGeneration is ClientIdGenerationMode.Allowed or ClientIdGenerationMode.Required;
+        set => ClientIdGeneration = value ? ClientIdGenerationMode.Allowed : ClientIdGenerationMode.Forbidden;
+    }
 
     /// <inheritdoc />
     public bool AllowUnknownQueryStringParameters { get; set; }

src/JsonApiDotNetCore/Configuration/ResourceGraphBuilder.cs

@@ -237,6 +237,8 @@ public ResourceGraphBuilder Add(Type resourceClrType, Type? idClrType = null, st
 
     private ResourceType CreateResourceType(string publicName, Type resourceClrType, Type idClrType)
     {
+        ClientIdGenerationMode? clientIdGeneration = GetClientIdGeneration(resourceClrType);
+
         IReadOnlyCollection<AttrAttribute> attributes = GetAttributes(resourceClrType);
         IReadOnlyCollection<RelationshipAttribute> relationships = GetRelationships(resourceClrType);
         IReadOnlyCollection<EagerLoadAttribute> eagerLoads = GetEagerLoads(resourceClrType);
@@ -246,11 +248,17 @@ private ResourceType CreateResourceType(string publicName, Type resourceClrType,
         var linksAttribute = resourceClrType.GetCustomAttribute<ResourceLinksAttribute>(true);
 
         return linksAttribute == null
-            ? new ResourceType(publicName, resourceClrType, idClrType, attributes, relationships, eagerLoads)
-            : new ResourceType(publicName, resourceClrType, idClrType, attributes, relationships, eagerLoads, linksAttribute.TopLevelLinks,
+            ? new ResourceType(publicName, clientIdGeneration, resourceClrType, idClrType, attributes, relationships, eagerLoads)
+            : new ResourceType(publicName, clientIdGeneration, resourceClrType, idClrType, attributes, relationships, eagerLoads, linksAttribute.TopLevelLinks,
                 linksAttribute.ResourceLinks, linksAttribute.RelationshipLinks);
     }
 
+    private ClientIdGenerationMode? GetClientIdGeneration(Type resourceClrType)
+    {
+        var resourceAttribute = resourceClrType.GetCustomAttribute<ResourceAttribute>(true);
+        return resourceAttribute?.NullableClientIdGeneration;
+    }
+
     private IReadOnlyCollection<AttrAttribute> GetAttributes(Type resourceClrType)
     {
         var attributesByName = new Dictionary<string, AttrAttribute>();

src/JsonApiDotNetCore/Serialization/Request/Adapters/AtomicOperationObjectAdapter.cs

@@ -122,13 +122,10 @@ private WriteOperationKind ConvertOperationCode(AtomicOperationObject atomicOper
 
     private ResourceIdentityRequirements CreateRefRequirements(RequestAdapterState state)
     {
-        JsonElementConstraint? idConstraint = state.Request.WriteOperation == WriteOperationKind.CreateResource
-            ? _options.AllowClientGeneratedIds ? null : JsonElementConstraint.Forbidden
-            : JsonElementConstraint.Required;
-
         return new ResourceIdentityRequirements
         {
-            IdConstraint = idConstraint
+            EvaluateIdConstraint = resourceType =>
+                ResourceIdentityRequirements.DoEvaluateIdConstraint(resourceType, state.Request.WriteOperation, _options.ClientIdGeneration)
         };
     }
 
@@ -137,7 +134,7 @@ private static ResourceIdentityRequirements CreateDataRequirements(AtomicReferen
         return new ResourceIdentityRequirements
         {
             ResourceType = refResult.ResourceType,
-            IdConstraint = refRequirements.IdConstraint,
+            EvaluateIdConstraint = refRequirements.EvaluateIdConstraint,
             IdValue = refResult.Resource.StringId,
             LidValue = refResult.Resource.LocalId,
             RelationshipName = refResult.Relationship?.PublicName

src/JsonApiDotNetCore/Serialization/Request/Adapters/DocumentInResourceOrRelationshipRequestAdapter.cs

@@ -60,14 +60,11 @@ public DocumentInResourceOrRelationshipRequestAdapter(IJsonApiOptions options, I
 
     private ResourceIdentityRequirements CreateIdentityRequirements(RequestAdapterState state)
     {
-        JsonElementConstraint? idConstraint = state.Request.WriteOperation == WriteOperationKind.CreateResource
-            ? _options.AllowClientGeneratedIds ? null : JsonElementConstraint.Forbidden
-            : JsonElementConstraint.Required;
-
         var requirements = new ResourceIdentityRequirements
         {
             ResourceType = state.Request.PrimaryResourceType,
-            IdConstraint = idConstraint,
+            EvaluateIdConstraint = resourceType =>
+                ResourceIdentityRequirements.DoEvaluateIdConstraint(resourceType, state.Request.WriteOperation, _options.ClientIdGeneration),
             IdValue = state.Request.PrimaryId
         };