Added docs for nullable reference types

Author: Bart Koelman

docs/internals/queries.md

@@ -5,7 +5,7 @@ _since v4.0_
 The query pipeline roughly looks like this:
 
 ```
-HTTP --[ASP.NET Core]--> QueryString --[JADNC:QueryStringParameterReader]--> QueryExpression[] --[JADNC:ResourceService]--> QueryLayer --[JADNC:Repository]--> IQueryable --[EF Core]--> SQL
+HTTP --[ASP.NET]--> QueryString --[JADNC:QueryStringParameterReader]--> QueryExpression[] --[JADNC:ResourceService]--> QueryLayer --[JADNC:Repository]--> IQueryable --[EF Core]--> SQL
 ```
 
 Processing a request involves the following steps:

docs/usage/options.md

@@ -102,7 +102,9 @@ Because we copy resource properties into an intermediate object before serializa
 
 ## Enable ModelState Validation
 
-If you would like to use ASP.NET Core ModelState validation into your controllers when creating / updating resources, set `ValidateModelState` to `true`. By default, no model validation is performed.
+If you would like to use ASP.NET ModelState validation into your controllers when creating / updating resources, set `ValidateModelState` to `true`. By default, no model validation is performed.
+
+How nullability affects ModelState validation is described [here](~/usage/resources/nullability.md).
 
 ```c#
 options.ValidateModelState = true;

docs/usage/resources/nullability.md

@@ -0,0 +1,85 @@
+# Nullability in resources
+
+Properties on a resource class can be declared as nullable or non-nullable. This affects both ASP.NET ModelState validation and the way Entity Framework Core generates database columns.
+
+Note that ModelState validation is turned off by default. It can be enabled in [options](~/usage/options.md#enable-modelstate-validation).
+
+# Value types
+
+When ModelState validation is enabled, non-nullable value types will **not** trigger a validation error when omitted in the request body.
+To make JsonApiDotNetCore return an error when such a property is missing on resource creation, declare it as nullable and annotate it with `[Required]`.
+
+Example:
+
+```c#
+public sealed class User : Identifiable<int>
+{
+    [Attr]
+    [Required]
+    public bool? IsAdministrator { get; set; }
+}
+```
+
+This makes EF Core generate non-nullable columns. And model errors are returned when nullable fields are omitted.
+
+# Reference types
+
+When the [nullable reference types](https://docs.microsoft.com/en-us/dotnet/csharp/nullable-references) (NRT) compiler feature is enabled, it affects both ASP.NET ModelState validation and Entity Framework Core.
+
+## NRT turned off
+
+When NRT is turned off, use `[Required]` on required attributes and relationships. This makes EF Core generate non-nullable columns. And model errors are returned when required fields are omitted.
+
+Example:
+
+```c#
+public sealed class Label : Identifiable<int>
+{
+    [Attr]
+    [Required]
+    public string Name { get; set; }
+
+    [Attr]
+    public string RgbColor { get; set; }
+
+    [HasOne]
+    [Required]
+    public Person Creator { get; set; }
+
+    [HasOne]
+    public Label Parent { get; set; }
+
+    [HasMany]
+    public ISet<TodoItem> TodoItems { get; set; }
+}
+```
+
+## NRT turned on
+
+When NRT is turned on, use nullability annotations (?) on attributes and relationships. This makes EF Core generate non-nullable columns. And model errors are returned when non-nullable fields are omitted.
+
+The [EF Core guidance on NRT](https://docs.microsoft.com/en-us/ef/core/miscellaneous/nullable-reference-types) recommends to use constructor binding to initialize non-nullable properties, but JsonApiDotNetCore does not support that. For required navigation properties, it suggests to use a non-nullable property with a nullable backing field. JsonApiDotNetCore does not support that either. In both cases, just use the null-forgiving operator (!).
+
+When ModelState validation is turned on, to-many relationships must be assigned an empty collection. Otherwise an error is returned when they don't occur in the request body.
+
+Example:
+
+```c#
+public sealed class Label : Identifiable<int>
+{
+    [Attr]
+    public string Name { get; set; } = null!;
+
+    [Attr]
+    public string? RgbColor { get; set; }
+
+    [HasOne]
+    public Person Creator { get; set; } = null!;
+
+    [HasOne]
+    public Label? Parent { get; set; }
+
+    [HasMany]
+    public ISet<TodoItem> TodoItems { get; set; } = new HashSet<TodoItem>();
+}
+```

docs/usage/toc.md

@@ -1,6 +1,7 @@
 # [Resources](resources/index.md)
 ## [Attributes](resources/attributes.md)
 ## [Relationships](resources/relationships.md)
+## [Nullability](resources/nullability.md)
 
 # Reading data
 ## [Filtering](reading/filtering.md)