Construct every profile field
Parser_Profile versions syntax, Unicode, and compatibility independently. It also selects BOM, duplicate-name, and top-level policies. The package provides no default or factory.
An application can validate a constructed profile before it creates a parser. Parser initialization also validates the profile before it consumes input.
Know the current strict behavior
The strict family combination follows RFC 8259 syntax and validates Unicode scalar values. Select No_Extensions to reject:
- a UTF-8 BOM and malformed UTF-8;
- unpaired surrogates and raw control characters;
- comments and trailing commas;
- nonstandard or nonfinite number spellings.
The top-level policy accepts any JSON value or requires an object. Neither choice is implicit.
Select extensions independently
Compatibility_Family provides four explicit choices:
| Family | Accepted extension |
|---|---|
No_Extensions | None. |
Comments | // line comments and non-nested /* */ block comments where whitespace is legal. |
Trailing_Commas | One comma after the last item or member in a nonempty container. |
Comments_And_Trailing_Commas | Both behaviors above. |
The parser validates comment text as UTF-8 across chunk boundaries. Comments are trivia, so the parser does not emit comment events. Their octets still contribute to absolute source offsets.
A line comment ends at CR, LF, or final input. A block comment ends at the first */ and does not nest. An unterminated block comment fails as truncated input.
Trailing-comma mode still rejects a leading comma, an empty comma-only container, doubled commas, and a missing value or member.
Choose duplicate handling at instantiation
Reject_Duplicates compares complete decoded names by exact Unicode scalar sequence, without normalization. The parser reports the later name's opening quote after it detects equality at name completion.
Preserve_Unchecked exposes every member in source order. It does not validate uniqueness or select a winner.
Select ordinary output explicitly
Writer_Profile versions syntax, Unicode, and formatting. The current Ordinary_Compact policy is deterministic for the same valid call sequence.
Ordinary output is not canonical JSON. A future canonical profile requires a separate contract and review.
Read the primary diagnostic first
Diagnostic contains a primary error code, coordinate kind, and zero-based offset when that coordinate kind is eligible. Cleanup failure can add a secondary diagnostic without replacing the primary failure.
| Coordinate | Meaning |
|---|---|
No_Coordinate | The error has no eligible offset. |
Source_Byte | Absolute input octet from the start of the JSON document. |
Writer_Token_Byte | Octet in the active name, string, or number input. |
Staged_Output_Byte | Octet in the complete staged output stream. |
JSON_Call_Ordinal | Admitted writer grammar call, counted from zero. |
Malformed input, resource exhaustion, destination failure, and commit failure return statuses. They are not normal exception paths.
Keep physical limits separate from policy
Depth and duplicate-name capacities are caller-selected physical bounds. They do not change which JSON spellings a profile accepts when enough storage exists.
The trusted parser and writer contain no accounting ledger or budget branch. A separately reviewed accounted surface remains future work for untrusted consumers that need aggregate work charging.
A resource failure reports its defined source, writer-token, staged-output, or call-ordinal coordinate.
Choose capacities from application limits, test exact-fit and one-over boundaries, and never describe an example capacity as a library default.