# Jsons

Custom JSON serialization/deserialization built on `System.Text.Json`'s `Utf8JsonWriter`/`Utf8JsonReader`, optimized for `IId` reference handling and polymorphic types.

## Architecture

- Reference scanning phase (pre-visit) detects multi-referenced objects before serialization.
- Uses `$id`/`$ref` JSON properties for circular reference handling (JSON standard).
- Polymorphic type hints via typename property.
- Context pooling for allocation efficiency.

## Key Files

### Serialization
- **`AcJsonSerializer.cs`** — Main serializer entry point, context pool management.
- **`AcJsonSerializer.JsonSerializationContext.cs`** — Core serialization logic with `Utf8JsonWriter`.
- **`AcJsonSerializer.JsonSerializeTypeMetadata.cs`** — Cached type metadata for serialization.
- **`AcJsonSerializerOptions.cs`** — Configuration and presets.

### Deserialization
- **`AcJsonDeserializer.cs`** — Main deserializer entry point.
- **`AcJsonDeserializer.JsonDeserializationContext.cs`** — Core deserialization logic.
- **`AcJsonDeserializer.JsonDeserializeTypeMetadata.cs`** — Cached type metadata for deserialization.
- **`AcJsonDeserializer.JsonElement.cs`** — `JsonElement` processing.
- **`AcJsonDeserializer.Primitives.cs`** — Primitive type conversions.
- **`AcJsonDeserializer.Utf8Reader.cs`** — `Utf8JsonReader` operations.

### Supporting
- **`AcJsonContextBase.cs`** — Base context shared between serializer and deserializer.
- **`JsonPropertyAccessorBase.cs`** — Property accessor for serialization.
- **`JsonPropertySetterBase.cs`** — Property setter for deserialization.
- **`MergeContractResolver.cs`** — Contract resolution for merge/populate operations.
- **`AcJsonDeserializationException.cs`** — Rich exception with JSON context, type info, and original exception.

## Configuration

| Option | Description |
|---|---|
| `ReferenceHandling` | `All` required — `OnlyId` not fully implemented for JSON |
| `MaxDepth` | Maximum object graph depth |
| `ThrowOnCircularReference` | Throw vs silently handle circular refs |

**Presets:** `Default` (with refs), `FlatCopy`, `WithMaxDepth`, `WithoutReferenceHandling`.

## Dependencies

- Base classes from parent `Serializers/` folder
- `System.Text.Json` (`Utf8JsonWriter`, `Utf8JsonReader`, `JsonElement`)
