Documented required one-to-one relationships mapping

Author: Bart Koelman

docs/usage/resources/relationships.md

@@ -20,6 +20,84 @@ public class TodoItem : Identifiable<int>
 
 The left side of this relationship is of type `TodoItem` (public name: "todoItems") and the right side is of type `Person` (public name: "persons").
 
+### Required one-to-one relationships in Entity Framework Core
+
+By default, Entity Framework Core generates an identifying foreign key for a required 1-to-1 relationship.
+This means no foreign key column is generated, instead the primary keys point to each other directly.
+
+The next example defines that each car requires an engine, while an engine is optionally linked to a car.
+
+```c#
+public sealed class Car : Identifiable<int>
+{
+    [HasOne]
+    public Engine Engine { get; set; }
+}
+
+public sealed class Engine : Identifiable<int>
+{
+    [HasOne]
+    public Car Car { get; set; }
+}
+
+public sealed class AppDbContext : DbContext
+{
+    protected override void OnModelCreating(ModelBuilder builder)
+    {
+        builder.Entity<Car>()
+            .HasOne(car => car.Engine)
+            .WithOne(engine => engine.Car)
+            .HasForeignKey<Car>()
+            .IsRequired();
+    }
+}
+```
+
+Which results in EF Core generating the next database objects:
+```sql
+CREATE TABLE "Engine" (
+    "Id" integer GENERATED BY DEFAULT AS IDENTITY,
+    CONSTRAINT "PK_Engine" PRIMARY KEY ("Id")
+);
+CREATE TABLE "Cars" (
+    "Id" integer NOT NULL,
+    CONSTRAINT "PK_Cars" PRIMARY KEY ("Id"),
+    CONSTRAINT "FK_Cars_Engine_Id" FOREIGN KEY ("Id") REFERENCES "Engine" ("Id")
+        ON DELETE CASCADE
+);
+```
+
+That mechanism does not make sense for JSON:API, because patching a relationship would result in also
+changing the identity of a resource. Naming the foreign key explicitly fixes the problem by forcing to
+create a foreign key column.
+
+```c#
+protected override void OnModelCreating(ModelBuilder builder)
+{
+    builder.Entity<Car>()
+        .HasOne(car => car.Engine)
+        .WithOne(engine => engine.Car)
+        .HasForeignKey<Car>("EngineId") // Explicit foreign key name added
+        .IsRequired();
+}
+```
+
+Which generates the correct database objects:
+```sql
+CREATE TABLE "Engine" (
+    "Id" integer GENERATED BY DEFAULT AS IDENTITY,
+    CONSTRAINT "PK_Engine" PRIMARY KEY ("Id")
+);
+CREATE TABLE "Cars" (
+    "Id" integer GENERATED BY DEFAULT AS IDENTITY,
+    "EngineId" integer NOT NULL,
+    CONSTRAINT "PK_Cars" PRIMARY KEY ("Id"),
+    CONSTRAINT "FK_Cars_Engine_EngineId" FOREIGN KEY ("EngineId") REFERENCES "Engine" ("Id")
+        ON DELETE CASCADE
+);
+CREATE UNIQUE INDEX "IX_Cars_EngineId" ON "Cars" ("EngineId");
+```
+
 ## HasMany
 
 This exposes a to-many relationship.

test/JsonApiDotNetCoreTests/IntegrationTests/RequiredRelationships/DefaultBehaviorDbContext.cs

@@ -25,8 +25,9 @@ protected override void OnModelCreating(ModelBuilder builder)
 
             // By default, Entity Framework Core generates an identifying foreign key for a required 1-to-1 relationship.
             // This means no foreign key column is generated, instead the primary keys point to each other directly.
-            // That mechanism does not make sense for JSON:API, because patching a relationship would result in
-            // also changing the identity of a resource. Naming the key explicitly forces to create a foreign key column.
+            // That mechanism does not make sense for JSON:API, because patching a relationship would result in also
+            // changing the identity of a resource. Naming the foreign key explicitly fixes the problem by forcing to
+            // create a foreign key column.
             builder.Entity<Order>()
                 .HasOne(order => order.Shipment)
                 .WithOne(shipment => shipment.Order)