Document reader basics

Use a document reader when existing content must become documents for later processing or Vector Store. Add the task matching the source: JSON, Text, HTML, Markdown or YAML. There is no automatic format detection. PDF and Word files are not supported. Text can preserve CSV, XML or YAML as original text without interpreting their structure.

Example

Input

Map existing content into Input Parameters, then enter ${source} as Source expression. The mapping examples below belong to the task definition. Captured task input contains their resolved content or file references, not the expression strings.

Each Reader's collapsed help explains only that format's source, options and result. The shared expression help starts with a short mapping example; open Advanced references only when you need file, user, task-link, Parallel or Map references. For example, an HTTP task can provide its small response body:

{
  "source": "${['Download source'].output.body}"
}

JSON reader accepts a JSON object, such as {"title":"Team procedure"}, or an array of JSON objects, including []. Pass the parsed object or array, not a string containing JSON text. A number, boolean or other primitive value is not a JSON Reader source. Text, HTML, Markdown and YAML readers accept strings. For a fixed value, put that value in Input Parameters and select it with the expression. Do not enter content or a URL directly into Source expression.

All five readers also accept an existing task-file descriptor or a complete ${swf:file:<attachmentId>} reference. Put that complete reference in Input Parameters, for example as the value of source, then enter ${source} in Source expression. Select the descriptor itself, not the surrounding HTTP/Reader output object. Files are checked against the current workflow and task before reading. A URL, local path or storage key is not a file reference. A URL inside inline text stays text; Reader does not fetch it.

Use HTTP first when downloading is needed. Configure its credentials, headers, timeouts and download retries there. Small responses can supply body; file-backed responses can supply swf:file. No special HTTP file mode is needed. When both shapes are supported by the chosen Reader, map both fields into Reader Input Parameters:

{
  "sourceFile": "${['Download source'].output['swf:file']}",
  "sourceBody": "${['Download source'].output.body}"
}

Then use ${jsonata:sourceFile ? sourceFile : sourceBody} as Source expression. This chooses the file when present and nonnull, otherwise the body. It is not a universal YAML fallback: HTTP may already parse a small YAML response body into a JSON object or array. Use JSON Reader for that parsed value. YAML Reader requires raw UTF-8 YAML text or an authorized original YAML file, not the parsed object/array. Check the actual HTTP output before choosing the Reader and mapping. For JSON, Reader preserves the values it receives; it cannot recover original number formatting or precision already changed by an earlier HTTP JSON response conversion. File input reads the retained bytes. Reader-specific options are fixed configuration, not expression fields. Use the documented field names: unknown properties are ignored, not treated as alternative option names. The five task types below are the available document readers.

Shared input, output and limits

See Reader source allowances on Pricing for either input mode. Inline text counts as UTF-8 bytes; inline JSON counts as serialized UTF-8 JSON; file input counts its actual source bytes. Ordinary workflow/task inline-data limits also apply to content in Input Parameters, so the larger Reader allowance does not let you place oversized data there. File input keeps only its descriptor/reference in the saved input, not its contents. It still obeys applicable file and shared-storage allowances. Reduce large sources or divide them into separate reads. Generated JSON can be larger than its source; ordinary result-file and shared-storage allowances apply independently.

Inline strings are already decoded text: leave Text/HTML Character set blank or choose UTF-8. To read another supported encoding, supply a file and choose its character set. An incompatible inline character set fails with correction guidance rather than silently changing the text. A file reference keeps saved task input small; it does not remove the Reader's processing limits.

Output

Every successful read saves documents.json, including for zero or one record. Raw output contains only a nonnull swf:file descriptor, not inline documents, result/resultList or a count. The file contains a bare ordered array of records with id, text and metadata. Zero records is [] inside the file, not null output or a missing attachment. The example IDs, dates and sizes below are illustrative.

The raw task output is a file descriptor, for example:

{
  "swf:file": {
    "id": "3AbCdEfGhIjKlMnOpQrStU",
    "workflowId": "4AbCdEfGhIjKlMnOpQrStU",
    "taskId": "5AbCdEfGhIjKlMnOpQrStU",
    "contentType": "application/json",
    "fileName": "documents.json",
    "sizeInBytes": 254,
    "createdOn": "2026-10-22T00:00:00Z"
  }
}

documents.json file contents

This is an illustrative record inside the file, not a task output object:

[
  {
    "id": "reader-generated-id",
    "text": "Refunds are available within 30 days.",
    "metadata": {}
  }
]

Reader generates IDs and source/structure metadata. Preserve each record's id, text and metadata together. Metadata can include swfSourceId, swfSourceVersion, swfPath, swfOrder, swfNodeKind, swfParentId and swfEmbed, connecting content to its source and surrounding structure. Context records marked swfEmbed:false are not text to embed in Vector Store; keep them when retaining hierarchy for later processing. Full-object JSON can also retain swfSourceJson as JSON text. These records do not themselves create a graph store or perform graph retrieval.

For JSON and YAML records, swfPath uses JSON Pointer locations: "" is the document root, / is an empty-name property, and /0 is the first array item. Nested keys and indexes keep their complete pointer, such as /records/0. IDs also include the record's position in the selected result. Changing which part you select can change its result position and ID.

The same inline bytes identify the same source; file identity uses the authorized attachment. The same source and selection produce stable document IDs. Each attempt uses its resolved input, but a configured retry can evaluate Input Parameters again and read updated workflow variables. Use a stable workflow input or original task output path when every attempt should read the same file. A file deleted before a later attempt cannot be read; deletion does not discard bytes already read by an attempt in progress.

Map a reader's attachment into Vector Store Input Parameters:

{
  "docs": "${['Read source'].output['swf:file']}"
}

Then use ${docs} in Documents expression. Replace Read source with your task's name. Select the descriptor, not the complete reader output object. Selecting it does not load a file; Store's supported file-input path reads the document array.

If reading fails, correct the expression, source-file access, format, encoding or selected content before retrying. For size/storage failures, reduce source/generated content or make room in storage. A failed read has no partial successful output to consume. A syntactically valid expression can still select a missing value, wrong type or unavailable file at runtime.