Opening

This group opens JSON data and loads it into the workflow as a document you can then read, modify and save. Each instruction brings JSON in from a different source — a file on disk, a piece of text, a web address, a nested part of a file, or a file whose encoding is detected automatically — and holds it in memory as the loaded document. One instruction in the group is different: Validate JSON Format only checks whether a file is valid JSON and records the answer, without loading anything.

Prerequisite: none. Like the CSV/TSV Reading group, these are entry-point instructions: they don’t need a document to exist beforehand — they create one by reading a source. A workflow that processes existing JSON usually begins with one of these (instead of Create JSON file).

These concepts recur across the instructions in this group; they are explained here once.

• The source to read from: each instruction names where the data comes from — a File path, a piece of JSON text, or a URL. If that source field is left empty, the instruction does nothing — no document is loaded.
• ⚠ Name and Path (the destination to save to) — leaving both empty overwrites the file you opened: where the loaded document will be written when you save it later. For the instructions that read a file, leaving them empty saves over the file you opened and filling them in is a save as: whatever you leave empty is taken from the source. Read From Text and Read From URL have no source file to fall back on, so those two need a Name and a Path to have somewhere to be saved. The file name is inherited whole, extension included: opening notes.log and leaving the destination empty writes over notes.log itself. A File name you type is a name without extension, so that one takes the format’s own.
• Document: the Document key names the loaded document so later instructions can target it. If you leave it empty, the loaded JSON becomes the current document (the one instructions use by default).
• Comments are tolerated: if the JSON source contains // or /* */ comments, they are ignored while reading, so a lightly-commented file still opens.
• Dynamic values @name: the text fields (the source field, Name, Path, Document key, and Nested path where present) accept a saved value: type @ followed by its name and the engine substitutes the value at run time.
• Nothing is written to disk here. These instructions only load the JSON into the workflow (or, for Validate JSON Format, just check it); a later save instruction writes it out.
• Save a result (saveResultKey): only Validate JSON Format produces a value — a yes/no answer saved under the name you type, for later instructions to use with @name. Leave it empty and nothing is saved.

• Detect Encoding And Open .json
• Open JSON File .json
• Read From Text .json
• Read From URL .json
• Read Nested JSON .json
• Validate JSON Format .json

Detect Encoding And Open .json

Opens a JSON file and works out its text encoding automatically from the byte-order mark (BOM) at the start of the file — UTF-8, UTF-16 or UTF-32 — falling back to UTF-8 when there is no mark.

When to use it: when you’re not sure how a JSON file was saved, or you know it isn’t plain UTF-8 (for example a file exported as UTF-16), and want the accented and special characters to come out right.

Parameter	Meaning	Default	Required
File path	The JSON file to read from (accepts @name)	(empty)	Yes
Name	File name the loaded document will be saved under (accepts @name)	(empty)	No
Path	Folder the loaded document will be saved to (accepts @name)	(empty)	No
Document key	Names the loaded document so later instructions can target it. Empty = current document (accepts @name)	(empty)	No

Important behavior: the encoding is taken from the file’s BOM; with no BOM, UTF-8 is assumed. If File path is empty, nothing is loaded.

---

Open JSON File .json

Opens a JSON file from disk (read as UTF-8) and loads it as the document.

When to use it: the normal way to start working from an existing JSON file.

Parameter	Meaning	Default	Required
File path	The JSON file to read from (accepts @name)	(empty)	Yes
Name	File name the loaded document will be saved under (accepts @name)	(empty)	No
Path	Folder the loaded document will be saved to (accepts @name)	(empty)	No
Document key	Names the loaded document so later instructions can target it. Empty = current document (accepts @name)	(empty)	No

Important behavior: the file is read as UTF-8. If File path is empty, nothing is loaded. If the file isn’t valid JSON, the instruction can’t load it — check it first with Validate JSON Format if you’re unsure.

---

Read From Text .json

Loads JSON from a piece of text you provide directly, instead of from a file.

When to use it: when the JSON already lives in a saved value (for example produced by an earlier instruction) or you want to type a small JSON snippet in place — pass it in the JSON text field, usually as @name.

Parameter	Meaning	Default	Required
JSON text	The JSON content to load (accepts @name)	(empty)	Yes
Name	File name the loaded document will be saved under (accepts @name); needed to save the document — this instruction has no source file to take a destination from	(empty)	Yes
Path	Folder the loaded document will be saved to (accepts @name); needed to save the document — this instruction has no source file to take a destination from	(empty)	Yes
Document key	Names the loaded document so later instructions can target it. Empty = current document (accepts @name)	(empty)	No

Important behavior: if JSON text is empty, nothing is loaded. The text must be valid JSON. Unlike the instructions that read a file, this one has no source to inherit the destination from: give it a Name and a Path, or the document has nowhere to be saved.

---

Read From URL .json

Downloads JSON from a web address and loads it as the document.

When to use it: to pull data from an online API or a JSON file published on the web.

Parameter	Meaning	Default	Required
URL	The web address to download the JSON from (accepts @name)	(empty)	Yes
Name	File name the loaded document will be saved under (accepts @name); needed to save the document — this instruction has no source file to take a destination from	(empty)	Yes
Path	Folder the loaded document will be saved to (accepts @name); needed to save the document — this instruction has no source file to take a destination from	(empty)	Yes
Document key	Names the loaded document so later instructions can target it. Empty = current document (accepts @name)	(empty)	No

Important behavior: if URL is empty, nothing is loaded. The download waits up to 30 seconds. The address must be reachable and return valid JSON. Unlike the instructions that read a file, this one has no source to inherit the destination from: give it a Name and a Path, or the document has nowhere to be saved.

---

Read Nested JSON .json

Opens a JSON file but loads only a part inside it — the piece found by following a path of field names and array positions.

When to use it: when a file wraps the data you want inside outer fields (for example the books list inside a store object) and you’d rather work with just that inner piece.

Parameter	Meaning	Default	Required
File path	The JSON file to read from (accepts @name)	(empty)	Yes
Nested path	The path to the inner piece, steps separated by dots — field names and list positions, e.g. store.books or items.1 (accepts @name)	(empty)	No
Name	File name the loaded document will be saved under (accepts @name)	(empty)	No
Path	Folder the loaded document will be saved to (accepts @name)	(empty)	No
Document key	Names the loaded document so later instructions can target it. Empty = current document (accepts @name)	(empty)	No

Important behavior: the Nested path is split on dots; each step is a field name (in an object) or a position in a list, counted from 1 — items.1 is the first item. If any step doesn’t exist, nothing is loaded. If Nested path is left empty, the whole file is loaded, just like Open JSON File. If File path is empty, nothing is loaded.

---

Validate JSON Format .json

Checks whether a file contains well-formed JSON and saves a yes/no answer. Unlike the other instructions in this group, it does not load a document — it only inspects the file.

When to use it: to verify a file is valid before trying to open it, so a later step can branch on the result (for example skip processing when the file is broken).

Parameter	Meaning	Default	Required
File path	The JSON file to check (accepts @name)	(empty)	Yes
Show error details	If yes, prints where the problem is (line and position) when the file is invalid	Yes	No
Show error details (from variable)	Reads the yes/no value from a saved value	(empty)	No
Save result key	Saves the yes/no answer (valid or not) under this name	(empty)	No

Important behavior: if File path is empty, nothing happens and no result is saved. Otherwise the answer (valid / not valid) is saved under Save result key if you provide one. When the file is invalid and Show error details is on, the location of the error is written to the log. This instruction never loads or changes any document.

---