Class JsonParser

Parses MOSAIC pipeline configuration JSON into a read-only dictionary of block definitions.

Inheritance
JsonParser
Namespace: MOSAIC.Components.Basics
Assembly: MOSAIC.dll
Syntax
public static class JsonParser
Remarks

A MOSAIC configuration is expected to be a JSON object where each property name is the canonical block name and each property value is a JsonModel describing that block.

Output: Parsing methods return an immutable IReadOnlyDictionary<TKey, TValue> backed by a FrozenDictionary<TKey, TValue> (fast lookups, safe to share across threads).

Validation: The parser enforces a minimal contract:

  • Each block must define a non-empty Type.
  • Block names must be unique (case-insensitive).
  • The dictionary key is treated as the canonical block name; if Name is present it must match the key.

Serializer: Uses System.Text.Json source generation via MosaicJsonContext for speed and AOT-friendliness. The configured options allow comments, trailing commas, and numbers encoded as strings.

Properties

Options

Gets the shared JsonSerializerOptions configured on the source-generated context.

Declaration
private static JsonSerializerOptions Options { get; }
Property Value
Type Description
JsonSerializerOptions

Methods

Parse(string)

Parses a MOSAIC config from a JSON string.

Declaration
public static IReadOnlyDictionary<string, JsonModel> Parse(string json)
Parameters
Type Name Description
string json

JSON string containing a configuration object.

Returns
Type Description
IReadOnlyDictionary<string, JsonModel>

An immutable dictionary mapping canonical block names to their corresponding JsonModel instances.

Remarks

This synchronous overload is useful for unit tests and small configurations where streaming is unnecessary.

Unlike ParseStreamAsync(Stream, CancellationToken), this method does not copy the dictionary key into Name. Callers should set names explicitly if needed.

Exceptions
Type Condition
ArgumentNullException

Thrown if json is null.

FormatException

Thrown if the JSON is invalid or does not match the expected contract.

ParseFileAsync(string, CancellationToken)

Parses a MOSAIC config file into a dictionary mapping block name to JsonModel.

Declaration
public static Task<IReadOnlyDictionary<string, JsonModel>> ParseFileAsync(string filePath, CancellationToken ct = default)
Parameters
Type Name Description
string filePath

Path to the JSON configuration file.

CancellationToken ct

Optional cancellation token used to cancel reading and parsing.

Returns
Type Description
Task<IReadOnlyDictionary<string, JsonModel>>

An immutable dictionary mapping canonical block names to their corresponding JsonModel instances.

Remarks

The file is read asynchronously using a sequential-scan file stream with a 128 KB buffer for efficient streaming of large configurations.

JSON parsing errors are wrapped into a FormatException and, when available, include line and byte position information from the underlying JsonException.

Exceptions
Type Condition
ArgumentNullException

Thrown if filePath is null.

FormatException

Thrown if the JSON is invalid or does not match the expected contract.

IOException

Thrown if the file cannot be read.

ParseStreamAsync(Stream, CancellationToken)

Parses a MOSAIC config from a stream into a dictionary mapping block name to JsonModel.

Declaration
public static Task<IReadOnlyDictionary<string, JsonModel>> ParseStreamAsync(Stream stream, CancellationToken ct = default)
Parameters
Type Name Description
Stream stream

Input stream containing a JSON object mapping block names to models.

CancellationToken ct

Optional cancellation token used to cancel reading and parsing.

Returns
Type Description
Task<IReadOnlyDictionary<string, JsonModel>>

An immutable dictionary mapping canonical block names to their corresponding JsonModel instances.

Remarks

For each entry, the dictionary key is treated as the canonical name and is copied into Name.

The returned dictionary is a FrozenDictionary<TKey, TValue> to provide fast, immutable lookups.

Exceptions
Type Condition
ArgumentNullException

Thrown if stream is null.

FormatException

Thrown if the JSON is invalid or does not match the expected contract.

ValidateDictionary(Dictionary<string, JsonModel>)

Validates the deserialized configuration dictionary.

Declaration
private static void ValidateDictionary(Dictionary<string, JsonModel> dict)
Parameters
Type Name Description
Dictionary<string, JsonModel> dict

Mutable dictionary produced by System.Text.Json deserialization.

Remarks

Validation rules:

  1. Each block must provide a non-empty Type.
  2. Block names must be unique (case-insensitive check).
  3. If Name is present, it must exactly match the dictionary key.
Exceptions
Type Condition
FormatException

Thrown if required fields are missing, names are inconsistent, or duplicates are found.

Search documentation

Start typing to search the documentation.