CrystalJson reference

The lookup tables for everyday work: the source generator setup, the attributes you put on a type, the settings you pass to a call, and the build diagnostics you might hit. For the task guides see Working with CrystalJson; for the design see What it is and why. Where a behavior changed between releases, the 7.4.2 to 7.4.3 migration guide carries the full story, and this page links to it rather than repeating it.

Every example uses using SnowBank.Data.Json;.

Setup

CrystalJson's runtime types (JsonValue, CrystalJson, CrystalJsonSettings) live in SnowBank.Core. A project that references SnowBank.Core serializes, parses and uses the DOM through the reflection path with no further setup.

Generated converters and typed proxies need the source generator as well. It ships as a separate package that the compiler runs as a Roslyn analyzer. It is a build-time tool, not part of your shipped application; SnowBank.Core is the only runtime dependency:

<!-- runtime: the JsonValue DOM and the CrystalJson API -->
<PackageReference Include="SnowBank.Core" Version="7.4.6" />
<!-- build-time only: the source generator, a Roslyn analyzer, not redistributed with your app -->
<PackageReference Include="SnowBank.Serialization.Json.CodeGen" Version="7.4.6" />

Give both the same version as your other SnowBank packages, or omit the version under central package management. The generator requires C# 9 or later: below that it reports SYSLIB1221 and emits nothing, JSON included, so set <LangVersion> to 9 or higher (the common trigger is a ported project still pinning a .NET Framework era <LangVersion>7.3</LangVersion>).

A container is a partial class that declares which types it serializes. The generated members land inside it:

[CrystalJsonConverter]
[CrystalSerializable(typeof(Book))]
public static partial class AcmeSerializers { }

string json = AcmeSerializers.Book.ToJsonText(book);
Book back = AcmeSerializers.Book.Deserialize(json);

Container attributes

The container declares three independent things: which class hosts the code, which formats it produces, and which types it registers.

A profile passed to [CrystalJsonOutput(...)] or [CrystalJsonConverter(...)] sets the container's default output form, CrystalJsonSerializerDefaults.Web for camelCase, .DataContractCompat for the legacy DataContractJsonSerializer output. Settings passed at a call site replace the profile for that call.

[CrystalSerializable] replaces the obsolete [CrystalJsonSerializable]; registration is format-neutral now. XML output has its own attributes and its own page, CrystalXml.

Member attributes

Put these on a property or field to change how that one member serializes. All are honored on both the reflection path and the generated path.

[JsonIgnore(Condition = ...)] reads JsonIgnoreCondition, following the System.Text.Json meaning. Note the naming trap: Never means "never ignore".

For [DataContract] types, [DataMember(Name = ...)] renames and [DataMember(IsRequired = true)] makes an absent member throw on read. Generated containers apply the DataContract membership model as of 7.4.3; the migration guide has the details.

Attributes from other serializers

CrystalJson reads the attributes an existing DTO already carries from System.Text.Json and Newtonsoft.Json (JSON.NET), so a ported type serializes without re-annotation, the same on both paths:

When several naming attributes agree, the effective name comes from the highest priority one: CrystalJson [JsonProperty], then [JsonPropertyName], then Newtonsoft [JsonProperty]. Two naming attributes that disagree are a build error (CJSON0011): one type cannot serve two output contracts. A [DataMember] on a [DataContract] type counts as one of them even when it is bare, because it names the member after itself: a [JsonProperty] that renames the same member is the same conflict. A foreign [JsonConverter] naming a type that does not implement the CrystalJson converter contract is ignored, not an error, so a half-ported DTO stays serializable. The migration guide has the full interop rules.

Settings

Pass a CrystalJsonSettings to a Serialize, Parse, or Deserialize call. Start from a preset and add fluent modifiers; each modifier returns a new cached instance.

Presets:

Common modifiers:

JsonStrict does not cover duplicate fields; add .ThrowOnDuplicateFields() when a repeated key must fail. To harden the parser for untrusted input, see Harden parsing for untrusted input.

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

Defaults

• Enums serialize as their name, not their number. Reading accepts names (case-insensitive), numbers, and numeric strings regardless of settings.
• The parser is permissive by default: JavaScript comments and trailing commas are accepted. This is wrong for input you do not control; tighten it with JsonStrict.
• Numbers keep their source literal on the DOM route until you read them as a typed value.

Diagnostics

The CJSON#### codes below are the ones a normal author hits while writing DTOs. Each is reported at the same place by both paths: the generator emits the diagnostic, and the reflection path throws the same message when it builds the type's contract. The migration guide has the full treatment of each.

The self-serializable diagnostics (CJSON0004 to CJSON0007, CJSON0020, CJSON0021) and the XML generator codes (CRYS####, CXML####) are covered in the migration guide and CrystalXml.