Skip to content

Parse JSON string

parseJsonString parses JSON‑compatible strings into structured data.

It accepts only objects, arrays, or quoted strings and rejects anything that cannot be parsed safely. If the value is not a string, does not begin with a valid JSON container character, or fails JSON parsing, the rule emits no parse result.

Signature

Through the API:

.parse('json');

And internally:

export const parseJsonString: ParseRule<unknown>
(value: unknown, path: FieldPath) => ParseResult<unknown>[]

Events

Event code Description
string.now.json Parsed string into structured JSON.

Design rationale

  • Accepts only JSON‑compatible top‑level forms:
  • Object ({…})
  • Array ([…])
  • Quoted string ("…")
  • Rejects ambiguous or non‑JSON forms such as unquoted text, numbers, booleans, or malformed structures.
  • Ensures contributors can rely on strict, predictable JSON parsing without coercion.
  • Produces a single parse step containing the parsed value and one parseEvent.
  • Never guesses, normalizes, or partially parses — parsing is explicit and opt‑in.

Invoke

parseJsonString runs only when explicitly included in a boundary or pipeline. It is not affected by normalization mode and does not run automatically.

The rule activates when:

  • The value is a string.
  • The trimmed string begins with {, [, or ".
  • JSON.parse succeeds without throwing.

Examples

Valid JSON strings

parseJsonString('{"a": 1}', "$");
// → [
//     {
//       path: "$",
//       nextValue: { a: 1 },
//       events: [
//         JaneEvent{ kind: "info", code: "string.now.json", ... }
//       ]
//     }
//   ]

parseJsonString('["x", "y"]', "$");
// → [
//     {
//       path: "$",
//       nextValue: ["x", "y"],
//       events: [ JaneEvent{ code: "string.now.json", ... } ]
//     }
//   ]

parseJsonString('"hello"', "$");
// → [
//     {
//       path: "$",
//       nextValue: "hello",
//       events: [ JaneEvent{ code: "string.now.json", ... } ]
//     }
//   ]

Invalid formats — no parse

parseJsonString("hello", "$");       // → []
parseJsonString("123", "$");         // → []
parseJsonString("{ bad json }", "$"); // → []
parseJsonString("true", "$");        // → []

Non‑string value

parseJsonString(42, "$"); // → []