EnumCraft.Json 1.0.1

EnumCraft.Json

JSON serialization extensions for EnumCraft TypedEnum and TypedFlag instances

What is EnumCraft.Json?

A lightweight JSON serialization extension package for EnumCraft.Core that provides clean, structured JSON output for TypedEnum and TypedFlag instances.

✅ Simple JSON serialization for TypedEnum
✅ Enhanced serialization for TypedFlag with decomposed flags array
✅ Customizable output with JsonSerializerOptions
✅ Zero configuration — just add the package and use the extensions
✅ Multi-targeted — Works with .NET Framework 4.7.2+ and .NET 8+

Installation

dotnet add package EnumCraft.Core
dotnet add package EnumCraft.Json

Quick Start

TypedEnum Serialization

using EnumCraft;
using EnumCraft.Json;

public class DocumentType : TypedEnumInt<DocumentType>
{
    public static readonly DocumentType Invoice       = new(1, "Invoice",        nameof(Invoice));
    public static readonly DocumentType PurchaseOrder = new(2, "Purchase Order", nameof(PurchaseOrder));
    public static readonly DocumentType CreditMemo    = new(3, "Credit Memo",    nameof(CreditMemo));

    private DocumentType(int id, string description, string code)
      : base(id, description, code) { }
}

// Serialize to object
var type    = DocumentType.Invoice;
var jsonObj = type.AsJsonObject();
// Returns: { id = 1, description = "Invoice", code = "Invoice" }

// Serialize to JSON string
string json = type.AsJsonString();
// Returns: {"id":1,"description":"Invoice","code":"Invoice"}

// With formatting
var options    = new JsonSerializerOptions { WriteIndented = true };
string prettyJson = type.AsJsonString(options);

TypedFlag Serialization

using EnumCraft;
using EnumCraft.Json;

public class Permissions : TypedFlagInt<Permissions>
{
    public static readonly Permissions None    = new(0, "None",    nameof(None));
    public static readonly Permissions Read    = new(1, "Read",    nameof(Read));
    public static readonly Permissions Write   = new(2, "Write",   nameof(Write));
    public static readonly Permissions Execute = new(4, "Execute", nameof(Execute));
    public static readonly Permissions All     = new(7, "All",     nameof(All));

    private Permissions(int id, string description, string code)
      : base(id, description, code) { }
}

// Single flag
var read    = Permissions.Read;
var jsonObj = read.ToJsonObject();
// Returns: { id = 1, description = "Read", code = "Read" }

// Combined flags - includes decomposed flags array
var readWrite    = Permissions.Read | Permissions.Write;
var combinedObj  = readWrite.ToJsonObject();
// Returns:
// {
//   id = 3,
//   description = "Read, Write",
//   code = "Read | Write",
//   flags = [
//     { id = 1, description = "Read", code = "Read" },
//     { id = 2, description = "Write", code = "Write" }
//   ]
// }

// Serialize to JSON string
string json = readWrite.ToJsonString();

API Reference

TypedEnum Extensions

Available on all ITypedEnum<TSelf, TId> instances:

AsJsonObject()

object AsJsonObject<TSelf, TId>(this ITypedEnum<TSelf, TId> typedEnum)

Returns an anonymous object with id, description, and code properties.

Example:

var obj = DocumentType.Invoice.AsJsonObject();
// { id = 1, description = "Invoice", code = "Invoice" }

AsJsonString()

string AsJsonString<TSelf, TId>(this ITypedEnum<TSelf, TId> typedEnum, JsonSerializerOptions? options = null)

Returns a JSON string representation.

Example:

var json = DocumentType.Invoice.AsJsonString();
// {"id":1,"description":"Invoice","code":"Invoice"}

var options   = new JsonSerializerOptions { WriteIndented = true };
var prettyJson = DocumentType.Invoice.AsJsonString(options);

TypedFlag Extensions

Available on all TypedFlag instances — use different method names than TypedEnum to avoid constraint conflicts:

ToJsonObject()

object ToJsonObject<TSelf, TId>(this ITypedEnum<TSelf, TId> typedEnum)

Returns an anonymous object with id, description, and code properties. For combined flags, includes a flags array with decomposed flag objects.

Example — Single Flag:

var obj = Permissions.Read.ToJsonObject();
// { id = 1, description = "Read", code = "Read" }

Example — Combined Flags:

var combo = Permissions.Read | Permissions.Write | Permissions.Execute;
var obj   = combo.ToJsonObject();
// {
//   id = 7,
//   description = "Read, Write, Execute",
//   code = "Read | Write | Execute",
//   flags = [
//     { id = 1, description = "Read", code = "Read" },
//     { id = 2, description = "Write", code = "Write" },
//     { id = 4, description = "Execute", code = "Execute" }
//   ]
// }

ToJsonString()

string ToJsonString<TSelf, TId>(this ITypedEnum<TSelf, TId> typedEnum, JsonSerializerOptions? options = null)

Returns a JSON string representation with flags array for combined flags.

Example:

var combo = Permissions.Read | Permissions.Write;
var json  = combo.ToJsonString();
// {"id":3,"description":"Read, Write","code":"Read | Write","flags":[...]}

Method Names: Why Different?

TypedEnum uses: AsJsonObject() and AsJsonString()
TypedFlag uses: ToJsonObject() and ToJsonString()

Due to .NET Standard 2.0 compatibility constraints with IBitwiseOperators, TypedFlag extensions cannot share the same method names as TypedEnum extensions without causing compilation issues. The different names make the distinction explicit:

• For TypedEnum → use As... methods
• For TypedFlag → use To... methods

Advanced Usage

Custom JSON Options

var options = new JsonSerializerOptions{ WriteIndented        = true,
                                         PropertyNamingPolicy = JsonNamingPolicy.CamelCase };

var json = DocumentType.Invoice.AsJsonString(options);

Using in APIs

[HttpGet("document-types/{id}")]
public IActionResult GetDocumentType(int id)
{
    var type    = DocumentType.GetByID(id);
    var jsonObj = type.AsJsonObject();

    return Ok(jsonObj);
}

[HttpGet("permissions")]
public IActionResult GetPermissions()
{
    var userPerms = Permissions.Read | Permissions.Write;
    var jsonObj   = userPerms.ToJsonObject();

    return Ok(jsonObj);
}

Serializing Collections

var allTypes  = DocumentType.GetAll();
var jsonArray = allTypes.Select(t => t.AsJsonObject()).ToArray();
var json      = JsonSerializer.Serialize(jsonArray);

Logging

var type = DocumentType.Invoice;
_logger.LogInformation("Document type resolved: {Type}", type.AsJsonString());

Best Practices

✅ DO

• Use AsJsonObject() when you need the object for further manipulation
• Use AsJsonString() when you need the final JSON string
• Use ToJsonObject() / ToJsonString() for TypedFlags to get the flags array
• Reuse JsonSerializerOptions instances for performance

❌ DON'T

• Mix As... and To... methods - use As... for TypedEnum, To... for TypedFlag
• Serialize TypedEnum or TypedFlag directly with JsonSerializer.Serialize() - you lose the structured output

Troubleshooting

"Method not found" errors

Make sure you have the correct using directive at the top of your file:

using EnumCraft.Json;

TypedFlag doesn't show flags array

Make sure you're using ToJsonObject() / ToJsonString() - not AsJson...:

// ❌ Wrong — won't include flags array
var json = myFlag.AsJsonString();

// ✅ Correct — includes flags array
var json = myFlag.ToJsonString();

Known Limitations

Additional Properties Not Serialized

AsJsonObject(), AsJsonString(), ToJsonObject(), and ToJsonString() serialize only the base id, description, and code properties. Any additional properties defined on a concrete type are silently ignored.

public class DocumentType : TypedEnumInt<DocumentType>
{
    public bool IsActive { get; }  // ← will NOT appear in JSON output
    // ...
}

DocumentType.Invoice.AsJsonString();
// {"id":1,"description":"Invoice","code":"Invoice"} — IsActive is not included

This is a known limitation - a future release will add a virtual ToJsonProperties() method that concrete types can override to include additional properties in the serialized output.

Framework Support

Dependencies

• EnumCraft.Core (v1.0.0 or later)
• System.Text.Json (v4.7.2 or later)
• Microsoft.CSharp (v4.7.0 or later) - required for .NET Standard 2.0 dynamic support

Related Packages

• EnumCraft.Core - Type-safe enumerations and flags
• EnumCraft.FeatureFlags - Provider-based feature flags built on TypedEnumGuid
• EnumCraft.FeatureFlags.Json - JSON file provider for feature flags

License

MIT — see LICENSE for details.

Author

Randel Bjorkquist — GitHub | NuGet