AnkiIO.AnkiJsonSerializer Class Reference

Serializes complete deck hierarchies using AnkiIO's deterministic, versioned native JSON format. More...

Static Public Member Functions
static string	Serialize (AnkiDeck deck)
	Serializes a validated deck hierarchy to a culture-invariant JSON string.
static AnkiDeck	Deserialize (string json)
	Deserializes an AnkiIO native JSON document and validates the reconstructed hierarchy.
static async Task	WriteAsync (AnkiDeck deck, Stream destination, CancellationToken cancellationToken=default)
	Asynchronously writes a validated hierarchy as UTF-8 native JSON.
static async Task< AnkiDeck >	ReadAsync (Stream source, CancellationToken cancellationToken=default)
	Asynchronously reads and validates a native JSON hierarchy from a UTF-8 stream.

Static Public Attributes
const int	CurrentFormatVersion = 1
	Identifies the native JSON schema emitted and accepted by this release.

Detailed Description

Serializes complete deck hierarchies using AnkiIO's deterministic, versioned native JSON format.

Native JSON is AnkiIO's loss-minimizing text interchange format for modeled decks, note types, notes, generated cards, scheduling, and review history. It is an AnkiIO format, not an Anki package or CrowdAnki document. Version 1 does not embed media payloads; transfer files from AnkiDeck.Media separately. Unknown properties are retained only on deck objects through AnkiDeck.UnknownData. Unknown document, note-type, note, card, and scheduling properties are ignored during import and are not reproduced.

Definition at line 14 of file AnkiJsonSerializer.cs.

Member Function Documentation

Deserialize()

AnkiDeck AnkiIO.AnkiJsonSerializer.Deserialize ( string json )

inlinestatic

Deserializes an AnkiIO native JSON document and validates the reconstructed hierarchy.

Parameters

json	A complete native JSON document encoded as a .NET string.

Returns

A new, mutable root deck containing the represented hierarchy.

The method accepts only CurrentFormatVersion. Note types are reconstructed first and shared by notes that reference the same ID. Media payloads are not represented by version 1, so the returned root has an empty media collection. Unrecognized deck-object properties are cloned into AnkiDeck.UnknownData for round trips.

Exceptions

ArgumentNullException	json is null.
JsonException	json is empty or malformed, declares an unsupported format version, omits its root deck, references a missing note type, or gives a note a field count inconsistent with its note type.
ArgumentException	The document contains duplicate note-type IDs or values that cannot form valid AnkiIO domain objects.
AnkiValidationException	The reconstructed hierarchy contains error-severity validation diagnostics.

Definition at line 68 of file AnkiJsonSerializer.cs.

ReadAsync()

async Task< AnkiDeck > AnkiIO.AnkiJsonSerializer.ReadAsync ( Stream source, CancellationToken cancellationToken = default )

inlinestatic

Asynchronously reads and validates a native JSON hierarchy from a UTF-8 stream.

Parameters

source	A readable stream positioned at the beginning of a native JSON document.
cancellationToken	A token that can cancel asynchronous JSON parsing and stream reads.

Returns

A task whose result is a new, mutable root deck containing the represented hierarchy.

The caller retains ownership of source . This method neither closes nor rewinds the stream; reading starts at its current position. Only CurrentFormatVersion is accepted. Version 1 returns an empty media collection because it does not embed media payloads.

Exceptions

ArgumentNullException	source is null.
JsonException	The stream is empty, contains malformed JSON, declares an unsupported format version, omits its root deck, references a missing note type, or gives a note a field count inconsistent with its note type.
ArgumentException	The document contains duplicate note-type IDs or values that cannot form valid AnkiIO domain objects.
AnkiValidationException	The reconstructed hierarchy contains error-severity validation diagnostics.
OperationCanceledException	cancellationToken is canceled before the operation completes.
NotSupportedException	source does not support reading.
ObjectDisposedException	source is closed.
IOException	An I/O error occurs while reading the stream.

Definition at line 120 of file AnkiJsonSerializer.cs.

Serialize()

string AnkiIO.AnkiJsonSerializer.Serialize ( AnkiDeck deck )

inlinestatic

Serializes a validated deck hierarchy to a culture-invariant JSON string.

Parameters

deck	The root deck whose entire descendant hierarchy will be serialized.

Returns

Indented UTF-16 JSON using camel-case property names and ending with a single line-feed character.

Note types, notes, tags, review records, subdecks, metadata keys, and extension-data keys are ordered before writing, so an unchanged hierarchy produces stable text. The method does not mutate deck . Media filenames and bytes in AnkiDeck.Media are not included in native JSON version 1.

Exceptions

ArgumentNullException	deck is null.
AnkiValidationException	The hierarchy contains one or more error-severity validation diagnostics.

Definition at line 44 of file AnkiJsonSerializer.cs.

WriteAsync()

async Task AnkiIO.AnkiJsonSerializer.WriteAsync ( AnkiDeck deck, Stream destination, CancellationToken cancellationToken = default )

inlinestatic

Asynchronously writes a validated hierarchy as UTF-8 native JSON.

Parameters

deck	The root deck whose entire descendant hierarchy will be serialized.
destination	A writable stream positioned where the JSON document should begin.
cancellationToken	A token that can cancel asynchronous JSON serialization and stream writes.

Returns

A task that completes after the JSON document has been written.

The caller retains ownership of destination . This method neither closes nor rewinds the stream and does not append the trailing line feed produced by Serialize. It validates before serialization and does not mutate deck . Native JSON version 1 does not include media payloads.

Exceptions

ArgumentNullException	deck or destination is null.
AnkiValidationException	The hierarchy contains one or more error-severity validation diagnostics.
OperationCanceledException	cancellationToken is canceled before the operation completes.
NotSupportedException	destination does not support writing.
ObjectDisposedException	destination is closed.
IOException	An I/O error occurs while writing the stream.

Definition at line 91 of file AnkiJsonSerializer.cs.

Member Data Documentation

CurrentFormatVersion

const int AnkiIO.AnkiJsonSerializer.CurrentFormatVersion = 1

static

Identifies the native JSON schema emitted and accepted by this release.

The value is written to the top-level formatVersion property. Readers reject other versions instead of attempting an implicit migration.

Definition at line 23 of file AnkiJsonSerializer.cs.

---

The documentation for this class was generated from the following file:

• src/AnkiIO/Json/AnkiJsonSerializer.cs