Built-in support for free-format client-generated IDs (#14)

Bart Koelman · web-flow · commit 9f8ae9d40263 · 2021-12-20T14:58:47.000+01:00
* Rename MongoIdentifiable to HexStringMongoIdentifiable, extract interface IMongoIdentifiable

* Added FreeStringMongoIdentifiable, updated tests for client-generated IDs

* Updated documentation
diff --git a/README.md b/README.md
@@ -18,7 +18,7 @@ dotnet add package JsonApiDotNetCore.MongoDb
 #nullable enable
 
 [Resource]
-public class Book : MongoIdentifiable
+public class Book : HexStringMongoIdentifiable
 {
     [Attr]
     public string Name { get; set; } = null!;
@@ -70,9 +70,19 @@ builder.Services.AddJsonApiMongoDb();
 builder.Services.AddScoped(typeof(IResourceReadRepository<,>), typeof(MongoRepository<,>));
 builder.Services.AddScoped(typeof(IResourceWriteRepository<,>), typeof(MongoRepository<,>));
 builder.Services.AddScoped(typeof(IResourceRepository<,>), typeof(MongoRepository<,>));
-
 ```
 
+## Using client-generated IDs
+Resources that inherit from `HexStringMongoIdentifiable` use auto-generated (performant) 12-byte hexadecimal
+[Object IDs](https://docs.mongodb.com/manual/reference/bson-types/#objectid).
+You can assign an ID manually, but it must match the 12-byte hexadecimal pattern.
+
+To assign free-format string IDs manually, make your resources inherit from `FreeStringMongoIdentifiable` instead.
+When creating a resource without assigning an ID, a 12-byte hexadecimal ID will be auto-generated.
+
+Set `options.AllowClientGeneratedIds` to `true` in Program.cs to allow API clients to assign IDs. This can be combined
+with both base classes, but `FreeStringMongoIdentifiable` probably makes the most sense.
+
 ## Limitations
 
 - JSON:API relationships are currently not supported. You can use complex object graphs though, which are stored in a single document.
diff --git a/src/Examples/GettingStarted/Models/Book.cs b/src/Examples/GettingStarted/Models/Book.cs
@@ -6,7 +6,7 @@ namespace GettingStarted.Models;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource]
-public sealed class Book : MongoIdentifiable
+public sealed class Book : HexStringMongoIdentifiable
 {
     [Attr]
     public string Title { get; set; } = null!;
diff --git a/src/Examples/JsonApiDotNetCoreMongoDbExample/Models/TodoItem.cs b/src/Examples/JsonApiDotNetCoreMongoDbExample/Models/TodoItem.cs
@@ -7,7 +7,7 @@ namespace JsonApiDotNetCoreMongoDbExample.Models;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource]
-public sealed class TodoItem : MongoIdentifiable
+public sealed class TodoItem : HexStringMongoIdentifiable
 {
     [Attr]
     public string Description { get; set; } = null!;
diff --git a/src/JsonApiDotNetCore.MongoDb/Queries/Internal/HideRelationshipsSparseFieldSetCache.cs b/src/JsonApiDotNetCore.MongoDb/Queries/Internal/HideRelationshipsSparseFieldSetCache.cs
@@ -1,5 +1,6 @@
 using System.Collections.Immutable;
 using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.MongoDb.Resources;
 using JsonApiDotNetCore.Queries;
 using JsonApiDotNetCore.Queries.Internal;
 using JsonApiDotNetCore.Resources;
@@ -38,6 +39,11 @@ public IImmutableSet<ResourceFieldAttribute> GetSparseFieldSetForSerializer(Reso
     {
         IImmutableSet<ResourceFieldAttribute> fieldSet = _innerCache.GetSparseFieldSetForSerializer(resourceType);
 
+        return resourceType.ClrType.IsAssignableTo(typeof(IMongoIdentifiable)) ? RemoveRelationships(fieldSet) : fieldSet;
+    }
+
+    private static IImmutableSet<ResourceFieldAttribute> RemoveRelationships(IImmutableSet<ResourceFieldAttribute> fieldSet)
+    {
         ResourceFieldAttribute[] relationships = fieldSet.Where(field => field is RelationshipAttribute).ToArray();
         return fieldSet.Except(relationships);
     }
diff --git a/src/JsonApiDotNetCore.MongoDb/Repositories/MongoRepository.cs b/src/JsonApiDotNetCore.MongoDb/Repositories/MongoRepository.cs
@@ -5,6 +5,7 @@
 using JsonApiDotNetCore.Middleware;
 using JsonApiDotNetCore.MongoDb.Errors;
 using JsonApiDotNetCore.MongoDb.Queries.Internal.QueryableBuilding;
+using JsonApiDotNetCore.MongoDb.Resources;
 using JsonApiDotNetCore.Queries;
 using JsonApiDotNetCore.Queries.Expressions;
 using JsonApiDotNetCore.Queries.Internal.QueryableBuilding;
@@ -52,9 +53,9 @@ public MongoRepository(IMongoDataAccess mongoDataAccess, ITargetedFields targete
         _constraintProviders = constraintProviders;
         _resourceDefinitionAccessor = resourceDefinitionAccessor;
 
-        if (typeof(TId) != typeof(string))
+        if (!typeof(TResource).IsAssignableTo(typeof(IMongoIdentifiable)))
         {
-            throw new InvalidConfigurationException("MongoDB can only be used for resources with an 'Id' property of type 'string'.");
+            throw new InvalidConfigurationException("MongoDB can only be used with resources that implement 'IMongoIdentifiable'.");
         }
     }
 
diff --git a/src/JsonApiDotNetCore.MongoDb/Resources/FreeStringMongoIdentifiable.cs b/src/JsonApiDotNetCore.MongoDb/Resources/FreeStringMongoIdentifiable.cs
@@ -0,0 +1,27 @@
+using MongoDB.Bson.Serialization.Attributes;
+using MongoDB.Bson.Serialization.IdGenerators;
+
+namespace JsonApiDotNetCore.MongoDb.Resources;
+
+/// <summary>
+/// Basic implementation of a JSON:API resource whose Id is stored as a free-format string in MongoDB. Useful for resources that are created using
+/// client-generated IDs.
+/// </summary>
+public abstract class FreeStringMongoIdentifiable : IMongoIdentifiable
+{
+    /// <inheritdoc />
+    [BsonId(IdGenerator = typeof(StringObjectIdGenerator))]
+    public virtual string? Id { get; set; }
+
+    /// <inheritdoc />
+    [BsonIgnore]
+    public string? StringId
+    {
+        get => Id;
+        set => Id = value;
+    }
+
+    /// <inheritdoc />
+    [BsonIgnore]
+    public string? LocalId { get; set; }
+}
diff --git a/src/JsonApiDotNetCore.MongoDb/Resources/HexStringMongoIdentifiable.cs b/src/JsonApiDotNetCore.MongoDb/Resources/HexStringMongoIdentifiable.cs
@@ -1,13 +1,12 @@
-using JsonApiDotNetCore.Resources;
 using MongoDB.Bson;
 using MongoDB.Bson.Serialization.Attributes;
 
 namespace JsonApiDotNetCore.MongoDb.Resources;
 
 /// <summary>
-/// A convenient basic implementation of <see cref="IIdentifiable" /> for use with MongoDB models.
+/// Basic implementation of a JSON:API resource whose Id is stored as a 12-byte hexadecimal ObjectId in MongoDB.
 /// </summary>
-public abstract class MongoIdentifiable : IIdentifiable<string?>
+public abstract class HexStringMongoIdentifiable : IMongoIdentifiable
 {
     /// <inheritdoc />
     [BsonId]
diff --git a/src/JsonApiDotNetCore.MongoDb/Resources/IMongoIdentifiable.cs b/src/JsonApiDotNetCore.MongoDb/Resources/IMongoIdentifiable.cs
@@ -0,0 +1,10 @@
+using JsonApiDotNetCore.Resources;
+
+namespace JsonApiDotNetCore.MongoDb.Resources;
+
+/// <summary>
+/// Marker interface to indicate a resource that is stored in MongoDB.
+/// </summary>
+public interface IMongoIdentifiable : IIdentifiable<string?>
+{
+}
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/Creating/AtomicCreateResourceWithClientGeneratedIdTests.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/Creating/AtomicCreateResourceWithClientGeneratedIdTests.cs
@@ -3,7 +3,6 @@
 using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.Serialization.Objects;
 using Microsoft.Extensions.DependencyInjection;
-using MongoDB.Bson;
 using TestBuildingBlocks;
 using Xunit;
 
@@ -28,7 +27,7 @@ public async Task Can_create_resource_with_client_generated_string_ID_having_sid
     {
         // Arrange
         TextLanguage newLanguage = _fakers.TextLanguage.Generate();
-        newLanguage.Id = ObjectId.GenerateNewId().ToString();
+        newLanguage.Id = "free-format-client-generated-id";
 
         var requestBody = new
         {
@@ -82,8 +81,8 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>
     public async Task Can_create_resource_with_client_generated_string_ID_having_no_side_effects()
     {
         // Arrange
-        MusicTrack newTrack = _fakers.MusicTrack.Generate();
-        newTrack.Id = ObjectId.GenerateNewId().ToString();
+        Playlist newPlaylist = _fakers.Playlist.Generate();
+        newPlaylist.Id = "free-format-client-generated-id";
 
         var requestBody = new
         {
@@ -94,13 +93,11 @@ public async Task Can_create_resource_with_client_generated_string_ID_having_no_
                     op = "add",
                     data = new
                     {
-                        type = "musicTracks",
-                        id = newTrack.StringId,
+                        type = "playlists",
+                        id = newPlaylist.StringId,
                         attributes = new
                         {
-                            title = newTrack.Title,
-                            lengthInSeconds = newTrack.LengthInSeconds,
-                            releasedAt = newTrack.ReleasedAt
+                            name = newPlaylist.Name
                         }
                     }
                 }
@@ -119,10 +116,9 @@ public async Task Can_create_resource_with_client_generated_string_ID_having_no_
 
         await _testContext.RunOnDatabaseAsync(async dbContext =>
         {
-            MusicTrack trackInDatabase = await dbContext.MusicTracks.FirstWithIdAsync(newTrack.Id);
+            Playlist playlistInDatabase = await dbContext.Playlists.FirstWithIdAsync(newPlaylist.Id);
 
-            trackInDatabase.Title.Should().Be(newTrack.Title);
-            trackInDatabase.LengthInSeconds.Should().BeApproximately(newTrack.LengthInSeconds);
+            playlistInDatabase.Name.Should().Be(newPlaylist.Name);
         });
     }
 
@@ -131,7 +127,7 @@ public async Task Cannot_create_resource_for_existing_client_generated_ID()
     {
         // Arrange
         TextLanguage existingLanguage = _fakers.TextLanguage.Generate();
-        existingLanguage.Id = ObjectId.GenerateNewId().ToString();
+        existingLanguage.Id = "existing-free-format-client-generated-id";
 
         string newIsoCode = _fakers.TextLanguage.Generate().IsoCode!;
 
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/Lyric.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/Lyric.cs
@@ -7,7 +7,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations")]
-public sealed class Lyric : MongoIdentifiable
+public sealed class Lyric : HexStringMongoIdentifiable
 {
     [Attr]
     public string? Format { get; set; }
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/MusicTrack.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/MusicTrack.cs
@@ -8,7 +8,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations")]
-public sealed class MusicTrack : MongoIdentifiable
+public sealed class MusicTrack : HexStringMongoIdentifiable
 {
     [RegularExpression(@"^[a-fA-F\d]{24}$")]
     public override string? Id { get; set; }
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/Performer.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/Performer.cs
@@ -6,7 +6,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations")]
-public sealed class Performer : MongoIdentifiable
+public sealed class Performer : HexStringMongoIdentifiable
 {
     [Attr]
     public string? ArtistName { get; set; }
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/Playlist.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/Playlist.cs
@@ -7,7 +7,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations")]
-public sealed class Playlist : MongoIdentifiable
+public sealed class Playlist : FreeStringMongoIdentifiable
 {
     [Attr]
     public string Name { get; set; } = null!;
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/RecordCompany.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/RecordCompany.cs
@@ -7,7 +7,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations")]
-public sealed class RecordCompany : MongoIdentifiable
+public sealed class RecordCompany : HexStringMongoIdentifiable
 {
     [Attr]
     public string Name { get; set; } = null!;
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/TextLanguage.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/AtomicOperations/TextLanguage.cs
@@ -7,7 +7,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations")]
-public sealed class TextLanguage : MongoIdentifiable
+public sealed class TextLanguage : FreeStringMongoIdentifiable
 {
     [Attr]
     public string? IsoCode { get; set; }
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/Meta/SupportTicket.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/Meta/SupportTicket.cs
@@ -6,7 +6,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.Meta;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.Meta")]
-public sealed class SupportTicket : MongoIdentifiable
+public sealed class SupportTicket : HexStringMongoIdentifiable
 {
     [Attr]
     public string Description { get; set; } = null!;
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/AccountPreferences.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/AccountPreferences.cs
@@ -5,7 +5,7 @@
 namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
-public sealed class AccountPreferences : MongoIdentifiable
+public sealed class AccountPreferences : HexStringMongoIdentifiable
 {
     [Attr]
     public bool UseDarkTheme { get; set; }
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/Blog.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/Blog.cs
@@ -7,7 +7,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings")]
-public sealed class Blog : MongoIdentifiable
+public sealed class Blog : HexStringMongoIdentifiable
 {
     [Attr]
     public string Title { get; set; } = null!;
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/BlogPost.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/BlogPost.cs
@@ -7,7 +7,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings")]
-public sealed class BlogPost : MongoIdentifiable
+public sealed class BlogPost : HexStringMongoIdentifiable
 {
     [Attr]
     public string Caption { get; set; } = null!;
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/Comment.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/Comment.cs
@@ -7,7 +7,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings")]
-public sealed class Comment : MongoIdentifiable
+public sealed class Comment : HexStringMongoIdentifiable
 {
     [Attr]
     public string Text { get; set; } = null!;
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/Filtering/FilterableResource.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/Filtering/FilterableResource.cs
@@ -7,7 +7,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings.Filtering;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings.Filtering")]
-public sealed class FilterableResource : MongoIdentifiable
+public sealed class FilterableResource : HexStringMongoIdentifiable
 {
     [Attr]
     public string SomeString { get; set; } = string.Empty;
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/Label.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/Label.cs
@@ -6,7 +6,7 @@
 namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
-public sealed class Label : MongoIdentifiable
+public sealed class Label : HexStringMongoIdentifiable
 {
     [Attr]
     public string Name { get; set; } = null!;
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/LoginAttempt.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/LoginAttempt.cs
@@ -5,7 +5,7 @@
 namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
-public sealed class LoginAttempt : MongoIdentifiable
+public sealed class LoginAttempt : HexStringMongoIdentifiable
 {
     [Attr]
     public DateTimeOffset TriedAt { get; set; }
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/WebAccount.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/QueryStrings/WebAccount.cs
@@ -7,7 +7,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 [Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings")]
-public sealed class WebAccount : MongoIdentifiable
+public sealed class WebAccount : HexStringMongoIdentifiable
 {
     [Attr]
     public string UserName { get; set; } = null!;
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/Creating/CreateResourceTests.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/Creating/CreateResourceTests.cs
@@ -98,7 +98,7 @@ public async Task Cannot_create_resource_with_int_ID()
         ErrorObject error = responseDocument.Errors[0];
         error.StatusCode.Should().Be(HttpStatusCode.InternalServerError);
         error.Title.Should().Be("An unhandled error occurred while processing this request.");
-        error.Detail.Should().Be("MongoDB can only be used for resources with an 'Id' property of type 'string'.");
+        error.Detail.Should().Be("MongoDB can only be used with resources that implement 'IMongoIdentifiable'.");
     }
 
     [Fact]
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/Creating/CreateResourceWithClientGeneratedIdTests.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/Creating/CreateResourceWithClientGeneratedIdTests.cs
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/RgbColor.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/RgbColor.cs
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/UserAccount.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/UserAccount.cs
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/WorkItem.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/WorkItem.cs
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/WorkItemGroup.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/WorkItemGroup.cs
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/WorkTag.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ReadWrite/WorkTag.cs
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ResourceDefinitions/Reading/Moon.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ResourceDefinitions/Reading/Moon.cs
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ResourceDefinitions/Reading/Planet.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ResourceDefinitions/Reading/Planet.cs
diff --git a/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ResourceDefinitions/Reading/Star.cs b/test/JsonApiDotNetCoreMongoDbTests/IntegrationTests/ResourceDefinitions/Reading/Star.cs
diff --git a/test/TestBuildingBlocks/MongoDbContextShim.cs b/test/TestBuildingBlocks/MongoDbContextShim.cs
diff --git a/test/TestBuildingBlocks/MongoDbSetShim.cs b/test/TestBuildingBlocks/MongoDbSetShim.cs

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ namespace GettingStarted.Models;`
`6`	`6`
`7`	`7`	`[UsedImplicitly(ImplicitUseTargetFlags.Members)]`
`8`	`8`	`[Resource]`
`9`		`-public sealed class Book : MongoIdentifiable`
	`9`	`+public sealed class Book : HexStringMongoIdentifiable`
`10`	`10`	`{`
`11`	`11`	`[Attr]`
`12`	`12`	`public string Title { get; set; } = null!;`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@ namespace JsonApiDotNetCoreMongoDbExample.Models;`
`7`	`7`
`8`	`8`	`[UsedImplicitly(ImplicitUseTargetFlags.Members)]`
`9`	`9`	`[Resource]`
`10`		`-public sealed class TodoItem : MongoIdentifiable`
	`10`	`+public sealed class TodoItem : HexStringMongoIdentifiable`
`11`	`11`	`{`
`12`	`12`	`[Attr]`
`13`	`13`	`public string Description { get; set; } = null!;`
Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,7 @@`
`5`	`5`	`using JsonApiDotNetCore.Middleware;`
`6`	`6`	`using JsonApiDotNetCore.MongoDb.Errors;`
`7`	`7`	`using JsonApiDotNetCore.MongoDb.Queries.Internal.QueryableBuilding;`
	`8`	`+using JsonApiDotNetCore.MongoDb.Resources;`
`8`	`9`	`using JsonApiDotNetCore.Queries;`
`9`	`10`	`using JsonApiDotNetCore.Queries.Expressions;`
`10`	`11`	`using JsonApiDotNetCore.Queries.Internal.QueryableBuilding;`
`@@ -52,9 +53,9 @@ public MongoRepository(IMongoDataAccess mongoDataAccess, ITargetedFields targete`
`52`	`53`	`_constraintProviders = constraintProviders;`
`53`	`54`	`_resourceDefinitionAccessor = resourceDefinitionAccessor;`
`54`	`55`
`55`		`- if (typeof(TId) != typeof(string))`
	`56`	`+ if (!typeof(TResource).IsAssignableTo(typeof(IMongoIdentifiable)))`
`56`	`57`	`{`
`57`		`- throw new InvalidConfigurationException("MongoDB can only be used for resources with an 'Id' property of type 'string'.");`
	`58`	`+ throw new InvalidConfigurationException("MongoDB can only be used with resources that implement 'IMongoIdentifiable'.");`
`58`	`59`	`}`
`59`	`60`	`}`
`60`	`61`
Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,6 @@`
`3`	`3`	`using JsonApiDotNetCore.Configuration;`
`4`	`4`	`using JsonApiDotNetCore.Serialization.Objects;`
`5`	`5`	`using Microsoft.Extensions.DependencyInjection;`
`6`		`-using MongoDB.Bson;`
`7`	`6`	`using TestBuildingBlocks;`
`8`	`7`	`using Xunit;`
`9`	`8`
`@@ -28,7 +27,7 @@ public async Task Can_create_resource_with_client_generated_string_ID_having_sid`
`28`	`27`	`{`
`29`	`28`	`// Arrange`
`30`	`29`	`TextLanguage newLanguage = _fakers.TextLanguage.Generate();`
`31`		`- newLanguage.Id = ObjectId.GenerateNewId().ToString();`
	`30`	`+ newLanguage.Id = "free-format-client-generated-id";`
`32`	`31`
`33`	`32`	`var requestBody = new`
`34`	`33`	`{`
`@@ -82,8 +81,8 @@ await _testContext.RunOnDatabaseAsync(async dbContext =>`
`82`	`81`	`public async Task Can_create_resource_with_client_generated_string_ID_having_no_side_effects()`
`83`	`82`	`{`
`84`	`83`	`// Arrange`
`85`		`- MusicTrack newTrack = _fakers.MusicTrack.Generate();`
`86`		`- newTrack.Id = ObjectId.GenerateNewId().ToString();`
	`84`	`+ Playlist newPlaylist = _fakers.Playlist.Generate();`
	`85`	`+ newPlaylist.Id = "free-format-client-generated-id";`
`87`	`86`
`88`	`87`	`var requestBody = new`
`89`	`88`	`{`
`@@ -94,13 +93,11 @@ public async Task Can_create_resource_with_client_generated_string_ID_having_no_`
`94`	`93`	`op = "add",`
`95`	`94`	`data = new`
`96`	`95`	`{`
`97`		`- type = "musicTracks",`
`98`		`- id = newTrack.StringId,`
	`96`	`+ type = "playlists",`
	`97`	`+ id = newPlaylist.StringId,`
`99`	`98`	`attributes = new`
`100`	`99`	`{`
`101`		`- title = newTrack.Title,`
`102`		`- lengthInSeconds = newTrack.LengthInSeconds,`
`103`		`- releasedAt = newTrack.ReleasedAt`
	`100`	`+ name = newPlaylist.Name`
`104`	`101`	`}`
`105`	`102`	`}`
`106`	`103`	`}`
`@@ -119,10 +116,9 @@ public async Task Can_create_resource_with_client_generated_string_ID_having_no_`
`119`	`116`
`120`	`117`	`await _testContext.RunOnDatabaseAsync(async dbContext =>`
`121`	`118`	`{`
`122`		`- MusicTrack trackInDatabase = await dbContext.MusicTracks.FirstWithIdAsync(newTrack.Id);`
	`119`	`+ Playlist playlistInDatabase = await dbContext.Playlists.FirstWithIdAsync(newPlaylist.Id);`
`123`	`120`
`124`		`- trackInDatabase.Title.Should().Be(newTrack.Title);`
`125`		`- trackInDatabase.LengthInSeconds.Should().BeApproximately(newTrack.LengthInSeconds);`
	`121`	`+ playlistInDatabase.Name.Should().Be(newPlaylist.Name);`
`126`	`122`	`});`
`127`	`123`	`}`
`128`	`124`
`@@ -131,7 +127,7 @@ public async Task Cannot_create_resource_for_existing_client_generated_ID()`
`131`	`127`	`{`
`132`	`128`	`// Arrange`
`133`	`129`	`TextLanguage existingLanguage = _fakers.TextLanguage.Generate();`
`134`		`- existingLanguage.Id = ObjectId.GenerateNewId().ToString();`
	`130`	`+ existingLanguage.Id = "existing-free-format-client-generated-id";`
`135`	`131`
`136`	`132`	`string newIsoCode = _fakers.TextLanguage.Generate().IsoCode!;`
`137`	`133`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations;`
`7`	`7`
`8`	`8`	`[UsedImplicitly(ImplicitUseTargetFlags.Members)]`
`9`	`9`	`[Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations")]`
`10`		`-public sealed class Lyric : MongoIdentifiable`
	`10`	`+public sealed class Lyric : HexStringMongoIdentifiable`
`11`	`11`	`{`
`12`	`12`	`[Attr]`
`13`	`13`	`public string? Format { get; set; }`
Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations;`
`8`	`8`
`9`	`9`	`[UsedImplicitly(ImplicitUseTargetFlags.Members)]`
`10`	`10`	`[Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations")]`
`11`		`-public sealed class MusicTrack : MongoIdentifiable`
	`11`	`+public sealed class MusicTrack : HexStringMongoIdentifiable`
`12`	`12`	`{`
`13`	`13`	`[RegularExpression(@"^[a-fA-F\d]{24}$")]`
`14`	`14`	`public override string? Id { get; set; }`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations;`
`6`	`6`
`7`	`7`	`[UsedImplicitly(ImplicitUseTargetFlags.Members)]`
`8`	`8`	`[Resource(ControllerNamespace = "JsonApiDotNetCoreMongoDbTests.IntegrationTests.AtomicOperations")]`
`9`		`-public sealed class Performer : MongoIdentifiable`
	`9`	`+public sealed class Performer : HexStringMongoIdentifiable`
`10`	`10`	`{`
`11`	`11`	`[Attr]`
`12`	`12`	`public string? ArtistName { get; set; }`
Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@`
`5`	`5`	`namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings;`
`6`	`6`
`7`	`7`	`[UsedImplicitly(ImplicitUseTargetFlags.Members)]`
`8`		`-public sealed class AccountPreferences : MongoIdentifiable`
	`8`	`+public sealed class AccountPreferences : HexStringMongoIdentifiable`
`9`	`9`	`{`
`10`	`10`	`[Attr]`
`11`	`11`	`public bool UseDarkTheme { get; set; }`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`	`namespace JsonApiDotNetCoreMongoDbTests.IntegrationTests.QueryStrings;`
`7`	`7`
`8`	`8`	`[UsedImplicitly(ImplicitUseTargetFlags.Members)]`
`9`		`-public sealed class Label : MongoIdentifiable`
	`9`	`+public sealed class Label : HexStringMongoIdentifiable`
`10`	`10`	`{`
`11`	`11`	`[Attr]`
`12`	`12`	`public string Name { get; set; } = null!;`
Original file line number	Diff line number	Diff line change
`@@ -98,7 +98,7 @@ public async Task Cannot_create_resource_with_int_ID()`
`98`	`98`	`ErrorObject error = responseDocument.Errors[0];`
`99`	`99`	`error.StatusCode.Should().Be(HttpStatusCode.InternalServerError);`
`100`	`100`	`error.Title.Should().Be("An unhandled error occurred while processing this request.");`
`101`		`- error.Detail.Should().Be("MongoDB can only be used for resources with an 'Id' property of type 'string'.");`
	`101`	`+ error.Detail.Should().Be("MongoDB can only be used with resources that implement 'IMongoIdentifiable'.");`
`102`	`102`	`}`
`103`	`103`
`104`	`104`	`[Fact]`