CrystalJson (SnowBank.Data.Json)

CrystalJson is a high-performance, allocation-conscious JSON stack. It is not System.Text.Json or Newtonsoft - the type names look familiar (JsonObject, JsonArray, ...) but the API is different. The namespace is SnowBank.Data.Json. Add using SnowBank.Data.Json;.

There are two layers, used together:

1. The DOM - JsonValue and its subtypes. A mutable-or-immutable tree you build, parse, navigate, and serialize. Use it for schemaless / dynamic JSON (config, arbitrary documents, change records).
2. The source generator - [CrystalJsonConverter] + [CrystalSerializable(typeof(T))] generate fast, reflection-free, AOT-friendly converters for your POCOs, plus typed read-only / writable proxies over the DOM. Use it for your domain types.

CrystalJson (static class) is the entry point for serialize/parse/deserialize regardless of layer.

---

1. The JsonValue DOM

JsonValue is the abstract base. Concrete types and their JsonType:

Type	JsonType	Notes
JsonObject	Object	key -> value map; mutable or read-only
JsonArray	Array	ordered list; mutable or read-only
JsonString	String	immutable
JsonNumber	Number	immutable; small ints cached
JsonBoolean	Boolean	immutable; only True/False singletons
JsonDateTime	DateTime	immutable; serialized as an ISO string
JsonNull	Null	three distinct singletons (below)

The three nulls - this trips people up:

• JsonNull.Null - an explicit null that was present in the JSON ({"x": null}).
• JsonNull.Missing - a field that was not there (obj["absent"]) or an out-of-range array read.
• JsonNull.Error - result of an invalid access (e.g. indexing a non-array).

All three report value.IsNull == true. Distinguish them with value.IsNullOrMissing(), value.IsMissing(), value.IsError(), or ReferenceEquals(value, JsonNull.Missing). Parsing an empty/whitespace/null input gives JsonNull.Missing; parsing the literal "null" gives JsonNull.Null.

Other useful singletons: JsonBoolean.True/False, JsonNumber.Zero/One, JsonObject.ReadOnly.Empty, JsonArray.ReadOnly.Empty.

---

2. Read-only vs mutable - the core mental model

This is the most important concept. JsonObject and JsonArray can each be mutable or read-only (value.IsReadOnly). Scalars (string/number/bool/null/datetime) are always read-only.

• Mutating a read-only container throws InvalidOperationException ("Cannot mutate ... because it is marked as read-only").
• A read-only value is safe to cache and share across threads.
• Conversions:
  • value.ToReadOnly() - returns self if already read-only, else a deep read-only copy.
  • value.ToMutable() - returns a mutable copy (minimal copying); use before editing a possibly-frozen value.
  • value.Copy(deep: true, readOnly: false) - explicit copy.
  • value.Freeze() - freezes in place (only on values you exclusively own).

Build mutable, then optionally freeze; or build read-only directly with the ReadOnly factory.

using SnowBank.Data.Json;

// mutable, with the Create factories (the default pattern; implicit conversions cover scalars)
var obj = JsonObject.Create([
    ("name", "Alice"),
    ("age", 30),
    ("tags", JsonArray.Create("admin", "user")),
    ("point", JsonObject.Create([ ("x", 1), ("y", 2) ])),
]);
var arr = JsonArray.Create(1, 2, 3);
// (the collection-initializer form `new JsonObject { ["name"] = "Alice" }` compiles too, but the
// factories read identically in their mutable and ReadOnly forms, so prefer them)

// read-only directly (good for cached/shared constants): the ReadOnly twin, same call shape
var ro = JsonObject.ReadOnly.Create([
    ("name", "Alice"),
    ("age", 30),
    ("tags", JsonArray.ReadOnly.Create(["admin", "user"])),
]);

// from a CLR value (POCO, collection, primitive)
JsonValue v   = JsonValue.FromValue(myPoco);              // mutable
JsonValue rov = JsonValue.ReadOnly.FromValue(myPoco);     // read-only

obj.ToReadOnly();   // freeze for caching
ro.ToMutable();     // get a mutable copy to edit

---

3. Reading and navigating

Indexers never throw on a missing key/index - they return JsonNull.Missing (or JsonNull.Error), so you can chain safely:

JsonValue city = obj["user"]["address"]["city"];   // Missing if any hop is absent; no NRE
bool present   = !obj["user"].IsNullOrMissing();

Read + convert in one step (the everyday API):

// Get<T>: optional with default, or required (throws JsonBindingException if null/missing/incompatible)
int    age   = obj.Get<int>("age", 0);          // default if absent
string name  = obj.Get<string>("name");         // throws if absent/null
Guid   id    = obj.Get<Guid>("id");

// TryGet
if (obj.TryGet<string>("email", out var email)) { /* ... */ }

// typed children
JsonObject child = obj.GetObjectOrEmpty("meta");   // never null; empty read-only object if absent
JsonArray  items = obj.GetArray("items");          // throws if not an array
if (obj.TryGetObject("meta", out var meta)) { /* ... */ }

// arrays
int count = items.Count;
string first = items.Get<string>(0);
foreach (var item in items) { /* JsonValue */ }
foreach (var o in items.AsObjects()) { /* JsonObject items only */ }

Convert a JsonValue to a CLR type (when you already hold the value):

string? s = jv.As<string>();          // default(T) (null) if the value is null/missing
int     n = jv.As<int>(-1);           // custom default if null/missing
string  r = jv.Required<string>();    // throws if null/missing

As<T> / Get<T> support primitives, Guid/Uuid*, DateTime/DateTimeOffset/DateOnly/TimeSpan, NodaTime Instant/Duration, Uri, byte[]/Slice, arrays/List<T>, and your POCOs. Numbers/dates use InvariantCulture.

---

4. CrystalJson: serialize / parse / deserialize

using SnowBank.Data.Json;

// SERIALIZE a CLR value -> JSON
string json   = CrystalJson.Serialize(value);                          // formatted, single line
string compact= CrystalJson.Serialize(value, CrystalJsonSettings.JsonCompact);
string pretty = CrystalJson.Serialize(value, CrystalJsonSettings.JsonIndented);
Slice  bytes  = CrystalJson.ToSlice(value, CrystalJsonSettings.JsonCompact);   // UTF-8
byte[] raw    = CrystalJson.ToBytes(value);
CrystalJson.SerializeTo(textWriterOrStream, value);                    // streaming

// PARSE text/bytes -> DOM: parse through the DOM types, not through CrystalJson.*
JsonValue  any = JsonValue.Parse(json);      // string, Slice, ReadOnlySpan<char/byte>
JsonObject o   = JsonObject.Parse(json);     // throws if it is not an object
JsonArray  a   = JsonArray.Parse(json);      // throws if it is not an array
// READ-ONLY (cache-safe) twin of each: the nested ReadOnly class, same entry points
JsonValue roDom = JsonValue.ReadOnly.Parse(json);   // also JsonObject.ReadOnly.Parse, etc.

// DESERIALIZE text/bytes -> POCO (parse + bind)
Book book  = CrystalJson.Deserialize<Book>(json);                      // throws if the JSON is null
Book? maybe= CrystalJson.Deserialize<Book>(json, defaultValue: null);  // null instead of throwing

// Serialize a JsonValue back to text/bytes
string s2 = value.ToJsonText();                  // or ToJsonText(settings)
Slice  b2 = value.ToJsonSlice(CrystalJsonSettings.JsonCompact);

Parse (DOM) vs Deserialize (POCO): Parse returns a JsonValue tree you navigate; Deserialize<T> binds straight to your type. A null/empty/missing input deserializes to null -> throws for a non-nullable T unless you pass a defaultValue.

The intended split: CrystalJson.* serves the POCO route (Serialize, Deserialize, ToSlice), the DOM parses through the DOM types (JsonValue.Parse, JsonObject.Parse, JsonArray.Parse, each a new static returning the derived type, throwing when the payload has another shape). Pick JsonObject.Parse when a non-object payload is a bug (let it throw); pick JsonValue.Parse plus a type test when it is an ordinary case to handle. (CrystalJsonDomWriter.ParseObject(value) is unrelated: it goes the other way, CLR value -> DOM.)

CrystalJsonSettings

Settings are immutable and cached; start from a preset and compose with fluent methods.

Presets: CrystalJsonSettings.Json (default), .JsonCompact, .JsonIndented, .JsonReadOnly (parse a read-only DOM), .JsonStrict, .JsonIgnoreCase (case-insensitive field matching), and JavaScript* variants.

Common fluent options (chainable, e.g. CrystalJsonSettings.Json.Compacted().CamelCased()):

• Layout: .Compacted(), .Indented(), .Formatted()
• Naming: .CamelCased(), .PascalCased()
• Nulls/defaults: .WithoutNullMembers() (default), .WithNullMembers(), .WithoutDefaultValues()
• Enums: .WithEnumAsStrings() (the default since 7.4.3), .WithEnumAsNumbers() - see Enums in the output in section 9 for what changed and the recipes that restore numbers
• Dates: .WithIso8601Dates() (default), .WithMicrosoftDates() (emits "\/Date(ms)\/"; reading that legacy format always works, with or without this setting)
• Durations: .WithNumericDurations() (default: TimeSpan as a number of seconds), .WithIso8601Durations() (emits the legacy "P1DT2H3M4.005S" duration string; reading both forms always works) (7.4.3+)
• Dictionaries: .WithDictionariesAsMaps() (default, {"k":v}), .WithDictionariesAsPairArrays() (emits the legacy [{"Key":k,"Value":v}] shape; again, reading both shapes always works) (7.4.3+)
• Read-only result: .AsReadOnly()

Parsing leniency (deserialization only; none of these change what you emit). The parser is deliberately permissive by default, which is wrong for untrusted input:

Option	Default	Tighten with	Loosen with
JavaScript comments (// ..., /* ... */)	accepted	.WithoutComments()	.WithComments()
trailing commas ([1, 2, ])	accepted	.WithoutTrailingCommas()	.WithTrailingCommas()
content after the top-level value	rejected	.WithoutTrailingData()	.WithTrailingData()
duplicate field names	last one wins	.ThrowOnDuplicateFields()	.FlattenDuplicateFields()

⚠️ The property is settings.AllowTrailingData; the fluent method that sets it is .WithTrailingData(). There is no .AllowTrailingData() method. Same shape for the others: read a bool property, set it with a With* / Without* method.

CrystalJsonSettings.JsonStrict is the shorthand for the first two rows (no comments, no trailing commas). It does not touch duplicate fields, so add .ThrowOnDuplicateFields() yourself if a repeated key must be an error rather than a silent overwrite.

To read several consecutive documents out of one buffer, use CrystalJson.ParseFragment or the streaming reader instead of .WithTrailingData(), which parses the first value and silently drops the rest.

---

5. The source generator (your domain types)

For POCOs, prefer the generator over the DOM: it emits a fast, reflection-free, AOT-friendly converter and typed read-only/writable proxies. (This is how the document-collection layers built on this stack store their documents.)

Declare

Put [CrystalSerializable(typeof(T))] (one per root type) on a public static partial class marked [CrystalJsonConverter]. Nested types are discovered automatically. Use [JsonProperty("name")] to rename a field.

using SnowBank.Data.Json;

public sealed record Book
{
    [JsonProperty("id")]
    public required string Id { get; init; }

    [JsonProperty("title")]
    public required string Title { get; init; }

    [JsonProperty("year")]
    public int Year { get; init; }
    public Author? Author { get; init; }   // nested type: auto-discovered
}

[CrystalJsonConverter]                       // or [CrystalJsonConverter(CrystalJsonSerializerDefaults.Web)] for camelCase + ignore-case
[CrystalSerializable(typeof(Book))]
public static partial class AcmeSerializers { }       // generated members land here

The container vocabulary (7.4.4+)

[CrystalJsonConverter] is a mono-format alias: it means "this class hosts generated code" plus "produce the JSON format, with these parameters". The two halves also exist separately, which is what a container producing several formats needs:

Attribute	Namespace	Role
[CrystalConverter]	SnowBank.Data	the container marker; says nothing about the formats
[CrystalSerializable(typeof(T))]	SnowBank.Data	registers a root type; repeatable; feeds every output format
[CrystalJsonOutput(...)]	SnowBank.Data.Json	requests the JSON format (profile, naming policy, case-insensitivity)
[CrystalXmlOutput(...)]	SnowBank.Data.Xml	requests the XML format (see Documentation/CrystalXml.md)
[CrystalJsonConverter(...)]	SnowBank.Data.Json	alias: [CrystalConverter] + [CrystalJsonOutput], JSON only
[CrystalXmlConverter(...)]	SnowBank.Data.Xml	alias: [CrystalConverter] + [CrystalXmlOutput], XML only

Rules the compiler enforces: a [CrystalConverter] naming no output format is refused (CRYS0001); a mono-format alias next to an output attribute is refused (CRYS0002 - use [CrystalConverter] with explicit output attributes instead); several container markers on one class are refused (CRYS0003).

// a container that produces BOTH formats from one set of registered types
[CrystalConverter]
[CrystalJsonOutput(CrystalJsonSerializerDefaults.Web)]
[CrystalXmlOutput]
[CrystalSerializable(typeof(Book))]
public static partial class CatalogSerializers { }

[CrystalJsonSerializable(typeof(T))] is the former spelling of [CrystalSerializable]: still working and byte-identical, but [Obsolete] (registration never was JSON-specific).

Self-serializable types: the entity IS its own container (7.4.3+)

The container above (AcmeSerializers) is one way to register a type. The other is to let the type carry its own generated code, which is what you want when a layer owns a vocabulary and should not force every consuming application to also declare a JSON container.

[CrystalJsonSelfSerializable] is a meta-attribute: you put it on one of your own attribute classes, and every type decorated with that attribute is opted into generation.

// the layer declares its vocabulary ONCE
[CrystalJsonSelfSerializable]
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)]
public sealed class MyEntityAttribute : Attribute { }

// the application just declares an entity - no container, no [CrystalSerializable]
[MyEntity]
public sealed partial record Widget
{
    public required string Name { get; init; }
    public Author? Author { get; init; }      // referenced types are still picked up
}

Everything generated lands inside one nested static class named Json, so the entity reserves exactly one member name:

Widget.Json.Default          // the converter (the container mode's AcmeSerializers.Widget)
Widget.Json.ReadOnly         // read-only proxy
Widget.Json.Writable         // writable proxy
Widget.Json.PropertyNames    // property-name constants
Widget.Json.GetResolver()    // the per-container resolver, same as the container mode
Widget.Json.ToJsonText(w)    // the static helpers live there too

Referenced types nest inside that same scope under their plain names: Author's converter is Widget.Json.Author.Default. Inside the scope they cannot shadow the referenced type in the entity's own source, which is what the single reserved name buys.

The one-name rule is the design, not an implementation detail: a future generator for another format claims a sibling scope (Widget.Cbor) without renegotiating anything. It also means the Json scope is entirely generated code, so it carries the generated-code attributes (GeneratedCode, DebuggerNonUserCode, ExcludeFromCodeCoverage, DynamicallyAccessedMembers) that could not be put on the entity partial, since that partial is your source.

This is how a document-collection attribute works in a layer built on this stack: the application writes one attribute on the entity, and the JSON converter, both proxies and the layer's own generated schema all fall out of it.

Things to know before you use it:

• The entity must be partial, non-generic, and not nested. The generator rejects the others with CJSON0004 / CJSON0005.
• Your entity may not declare a member named Json. That is CJSON0006, an error, reported at the entity declaration in your own source. The message carries the remedies: rename the member and keep its serialized name with [JsonProperty("json")], or move the type to a [CrystalJsonConverter] container instead.
• A referenced type named like a scope member (Default, ReadOnly, Writable, PropertyNames, …) is CJSON0007, a warning. That type is excluded from generation and falls back to runtime serialization, so it still works, just without a generated converter.
• Hint names are namespace-qualified in this mode, because entity names collide across namespaces far more often than container names do.
• The [CrystalJsonConverter] + [CrystalSerializable] container path is untouched and still correct. Prefer the container when you register third-party types you cannot annotate, or a set of unrelated types; prefer self mode when the type is yours and a layer already marks it.

csproj wiring (the part most often gotten wrong)

Reference the generator project/package as an analyzer, and ensure C# 9+:

<PropertyGroup>
  <LangVersion>latest</LangVersion>
</PropertyGroup>
<ItemGroup>
  <ProjectReference Include="path/to/SnowBank.Serialization.Json.CodeGen.csproj"
                    OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
</ItemGroup>

(If consuming via NuGet, the analyzer ships with SnowBank.Core / its codegen package.)

The language floor is C# 9, and the generator checks it explicitly: below C# 9 it reports SYSLIB1221 ("language version not supported by the source generator") and generates nothing. latest clears the gate with margin, but the actual requirement is only >= 9 — the classic trigger is a ported legacy project still pinning a netfx-era <LangVersion>7.3</LangVersion>. No other project setting is required: the generated files fully qualify every name (they work without ImplicitUsings) and are warning-free under #nullable enable, including for members declared in nullable-oblivious code.

Use

// POCO <-> JSON text
string json = AcmeSerializers.Book.ToJsonText(book);
Book   back = AcmeSerializers.Book.Deserialize(json);

// POCO <-> JsonValue (DOM)
JsonValue packed = AcmeSerializers.Book.Pack(book);
Book      from   = AcmeSerializers.Book.Unpack(jsonObject);

// runtime resolver (pass to CrystalJson APIs and to layers that must resolve your converters)
ICrystalJsonTypeResolver resolver = AcmeSerializers.GetResolver();

Read-only / writable proxies (zero-copy typed views over the DOM)

AcmeSerializers.Book.ReadOnly ro = AcmeSerializers.Book.ToReadOnly(book);   // typed read-only view over a JsonValue
string title = ro.Title;                                  // typed property read
JsonValue dom = ro.ToJsonValue();                         // underlying (read-only) JsonValue
Book poco = ro.ToValue();                                 // materialize the POCO

// edit via copy-on-write: the original proxy is unchanged, you get a new frozen proxy
AcmeSerializers.Book.ReadOnly edited = ro.With(m => { m.Year = 2025; });

// or an explicit mutable proxy
AcmeSerializers.Book.Writable w = ro.ToMutable();
w.Year = 2025;

Absence propagates through a proxy the way it does through the DOM: a chain across a missing inner object keeps navigating (proxy.Metadata.IsNullOrMissing() tells you), an optional member reads as its default, and a required member absent from the document throws JsonBindingException, never a NullReferenceException (pinned by Test_JsonReadOnlyProxy_With_Empty_Object in SnowBank.Serialization.Json.CodeGen.Tests).

(7.4.5+) A type that decides its own format (IJson* interfaces, or a container hook, section 7) gets NO generated proxies, with a CJSON0025 warning: the generator cannot describe a shape it does not produce.

Note: .With(...) (copy-on-write edit) is a method on the GENERATED typed proxies shown here, not on a raw DOM JsonObject/JsonArray. For a plain DOM value there is no .With(...): freeze with value.ToReadOnly() and edit a copy with value.ToMutable() (section 2), then set fields via the indexer.

---

6. Mutating JSON: MutableJsonValue (and ObservableJsonValue)

MutableJsonValue is a mutation proxy used inside "write" closures (document updates in a collection layer, the doc.Write(root => ...) closures of a reactive layer). ObservableJsonValue is the read side that tracks which fields were read (for reactive views). You usually interact via the root handed to a write callback:

doc.Write(root =>
{
    root["status"].Set("online");                 // set a scalar field
    root.Set("count", 42);                         // typed set (auto-converts the CLR value)
    root["point"]["x"].Set(123);                   // nested set (intermediate objects auto-created via GetOrCreateObject)
    root.Set(JsonPath.Create("a.b[0]"), "deep");   // path-based set
    root["items"].Add("newItem");                  // APPEND to the array at root["items"]
});

Footgun - Add means different things on objects vs arrays:

• root.Add("field", value) adds a field to the object (throws if the field already exists).
• root["field"].Add(value) appends to the array at root["field"].

They are not interchangeable. Re-creating an existing field with Add throws; to append, index into the array first.

Don't hold a child proxy across a parent mutation - it goes stale. Re-get it, or do it in one chain:

// stale:
var s = root["settings"]; root["settings"].Set(newSettings); s["k"].Set(v);   // BUG: s is stale
// good:
root["settings"]["k"].Set(v);

---

7. Custom (de)serialization: the IJson* interfaces

When the generator can't cover a type (e.g. a hand-tuned encoding), implement these directly:

public interface IJsonSerializable          { void JsonSerialize(CrystalJsonWriter writer); }
public interface IJsonPackable              { JsonValue JsonPack(CrystalJsonSettings settings, ICrystalJsonTypeResolver resolver); }
public interface IJsonDeserializable<TSelf> { static abstract TSelf JsonDeserialize(JsonValue value, ICrystalJsonTypeResolver? resolver); }

By convention the concrete JsonDeserialize implementation declares the resolver with a default (ICrystalJsonTypeResolver? resolver = null) so callers can omit it; that still satisfies the interface. JsonPack (to DOM) and JsonDeserialize (from DOM) must be inverses - round-trip them in a test. Build values with JsonString.Return(...), JsonNumber.Return(...), JsonArray.ReadOnly.Create(...). Handle null/missing defensively in JsonDeserialize. (Example in the wild: a compact id type packed as a JsonArray of its parts.)

Generated converters call a registered type's own IJson* implementations (7.4.5+)