Class JsonParser
Parses MOSAIC pipeline configuration JSON into a read-only dictionary of block definitions.
Inherited Members
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 |
| 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 |
| 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 |
| 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:
Exceptions
| Type | Condition |
|---|---|
| FormatException | Thrown if required fields are missing, names are inconsistent, or duplicates are found. |