> ## Documentation Index > Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt > Use this file to discover all available pages before exploring further. # JSON > Parser stage configuration specifications export const schema = { "type": "object", "title": "JSON", "description": "Parses JSON documents with support for nested structures, arrays, JSONPath field mappings, and document splitting. Handles both single JSON objects and JSONL (JSON Lines) format. Extracts specific fields via JSONPath expressions, splits arrays into individual documents, and flattens hierarchical data into indexed fields.", "required": ["type"], "properties": { "id": { "type": "string", "title": "Parser ID", "default": "3d8fdc55-fd79-44a8-8021-b89fe821a07e" }, "label": { "type": "string", "title": "Label", "description": "Human-readable identifier displayed in the Fusion Admin UI, monitoring dashboards, and log messages. Use descriptive labels like `Parse Product PDFs` to aid debugging and team collaboration. Labels appear in performance metrics and error reports, making it easier to identify which stage failed.", "maxLength": 255 }, "enabled": { "type": "boolean", "title": "Enable this Parser Stage", "default": true, "description": "Controls whether this parser stage is active and available for use. When `false`, the stage is completely inactive regardless of other settings. When `true`, the stage runs according to its other configuration options." }, "mediaTypes": { "type": "array", "title": "Media Types to match", "description": "Specifies the media types this parser stage handles. Documents with a matching media type are routed to this stage for parsing. See `inheritMediaTypes` to combine this list with the stage's built-in defaults.", "items": { "type": "string", "pattern": "^[^\\/]+\\/[^\\/]+$", "format": "rfc2646" } }, "inheritMediaTypes": { "type": "boolean", "title": "Match default media types in this Parser Stage", "description": "Controls whether this stage combines its built-in default media types with those in `mediaTypes`. When `true`, both lists are merged. When `false`, only the `mediaTypes` list is used and must contain at least one entry. Set to `false` to override the default media types entirely.", "default": true }, "ignoredMediaTypes": { "type": "array", "title": "Media Types to ignore", "description": "Specifies media types this parser stage excludes from processing. Documents matching an ignored media type are skipped even if they match `mediaTypes`. Use this to carve out exceptions from a broadly matched media type set.", "items": { "type": "string", "pattern": "^[^\\/]+\\/[^\\/]+$", "format": "rfc2646" } }, "pathPatterns": { "type": "array", "title": "File names to parse", "description": "Restricts this parser stage to files whose names match the specified pattern. Use forward slashes (`/`) to join archive names with entry names when matching files inside archives. If no pattern is specified, the stage applies to all matching media types.", "items": { "type": "object", "properties": { "syntax": { "type": "string", "title": "Pattern type", "description": "glob uses bash shell-style wildcards and regex uses Java (PCRE-style) regex.", "enum": ["glob", "regex"], "default": "glob" }, "pattern": { "type": "string", "title": "File name or pattern", "description": "glob examples are \"z.txt\" or \"*.md\" or \"/a/*/b/f.txt\". regex examples are \"z.txt$\" or \".*\\.txt$\" or \"^/a/[^\\/]*/b/f.txt$\"." } } } }, "errorHandling": { "type": "string", "title": "Error Handling", "enum": ["ignore", "log", "fail", "mark"], "default": "mark" }, "outputFieldPrefix": { "type": "string", "title": "Prefix parsed fields with", "description": "Sets a string prefix applied to all fields extracted by this parser, useful for namespacing or avoiding field name collisions. For example, `tika_` produces fields like `tika_title` and `tika_author`. Leave empty to apply no prefix.", "maxLength": 20, "pattern": "^$|^[A-Za-z_][A-Za-z0-9_\\-\\.]+$" }, "rootPath": { "type": "string", "title": "Root path", "description": "Specifies the JSONPath expression that selects the starting point within the JSON structure for document extraction. For example, `$.items` extracts from an array at the `items` key, while `$.data.records` targets a nested array. When set, only the selected portion of the JSON is parsed into documents." }, "includePath": { "type": "boolean", "title": "Include root path", "description": "Controls whether parent field names from the JSON structure are included in the resulting documents when a `rootPath` is set. When `true`, documents include hierarchical path context such as `parent.child.field`. When `false`, only fields from the selected root path level and below are included.", "default": false }, "splitArrays": { "type": "boolean", "title": "Split arrays", "description": "Controls whether each element of a top-level JSON array is created as a separate indexed document. When `true`, each array item is processed independently before applying mappings or other parsing rules. When `false`, the entire array is treated as a single document value.", "default": true }, "expectJsonL": { "type": "boolean", "title": "Expect JSONL", "description": "Enables JSONL (JSON Lines) parsing, where each line contains a complete, independent JSON object. When enabled, each line produces a separate document, allowing large JSON datasets to be processed without loading the entire file into memory. When disabled, the parser expects a single JSON object or array for the entire file.", "default": false }, "maxLineSize": { "type": "integer", "title": "Max line size", "description": "Sets the maximum size in bytes for a single line when parsing JSONL format. Lines exceeding this limit cause a parsing error. Increase this value when processing JSONL files containing large JSON objects per line.", "default": 8192 }, "mappings": { "type": "array", "title": "Mapping rules", "description": "Defines JSONPath-based rules that map specific parts of the JSON structure to named fields in indexed documents. Each mapping specifies a JSONPath expression to locate data and a target field name to store the extracted value. Use this to flatten nested structures, rename fields, or extract specific values from complex JSON.", "items": { "type": "object", "required": ["path", "target"], "properties": { "path": { "type": "string", "title": "JSONPath expression", "description": "File system path, URL path component, or expression path for jsonpath expression. May be absolute path, relative path, or path expression depending on context." }, "target": { "type": "string", "title": "Target field" } } } }, "listHandling": { "type": "string", "title": "JSON List handling", "description": "Determines how JSON arrays are handled when mapping to document fields. Use `multivalued` to store all array items in a single multivalued field, or `index_numbered` to create separate fields for each item with numeric suffixes such as `field_0` and `field_1`. Choose `multivalued` for standard indexing and `index_numbered` when downstream systems require discrete fields.", "enum": ["multivalued", "index_numbered"], "default": "multivalued", "hints": ["advanced"] }, "type": { "type": "string", "enum": ["json"], "default": "json" } }, "additionalProperties": false, "category": "Other", "categoryPriority": 1, "unsafe": false }; export const SchemaParamFields = ({schema}) => { const sanitize = str => { if (typeof str !== "string") return str; return str.replace(/^"(.*)"$/s, "$1").replace(/\\/g, "").replace(/"/g, "'"); }; const renderMd = str => { const s = sanitize(str); const text = (/[.!?]\)*$/).test(s) ? s : `${s}.`; return text.split(/(\*\*[^*]+\*\*|_[^_]+_|`[^`]+`)/g).map((part, i) => { if (part.startsWith("**")) return {part.slice(2, -2)}; if (part.startsWith("_")) return {part.slice(1, -1)}; if (part.startsWith("`")) return {part.slice(1, -1)}; return part; }); }; const {description, properties = {}, required: requiredProps = []} = schema; const visibleProps = useMemo(() => Object.entries(properties).filter(([, prop]) => !prop.hints?.includes("hidden")), [properties]); const renderProp = ([name, prop]) => { const isRequired = requiredProps.includes(name); const hasDefault = prop.default !== undefined; const rawDefault = prop.default; const hints = prop.hints || []; const isComplexDefault = hasDefault && (typeof rawDefault === "object" || typeof rawDefault === "string" && (rawDefault.length > 20 || rawDefault.includes('"'))); const postBadges = []; if (prop.title) { postBadges.push(<>API property: {name}); } const constraints = []; if (prop.minimum !== undefined && prop.maximum !== undefined) { constraints.push(`Range: ${prop.minimum} – ${prop.maximum}`); } else if (prop.minimum !== undefined) { constraints.push(`Min: ${prop.minimum}`); } else if (prop.maximum !== undefined) { constraints.push(`Max: ${prop.maximum}`); } if (prop.minLength !== undefined && prop.maxLength !== undefined) { constraints.push(`Length: ${prop.minLength} – ${prop.maxLength}`); } else if (prop.minLength !== undefined) { constraints.push(`Min length: ${prop.minLength}`); } else if (prop.maxLength !== undefined) { constraints.push(`Max length: ${prop.maxLength}`); } const fieldProps = { key: name, body: prop.title || name, type: prop.type, ...postBadges.length > 0 && ({ post: postBadges }), ...isRequired && ({ required: true }), ...!isComplexDefault && hasDefault ? { default: sanitize(String(rawDefault)) } : {} }; const isObject = prop.type === "object" && prop.properties; const isArrayOfObjects = prop.type === "array" && prop.items?.type === "object" && prop.items.properties; return {prop.description &&

{renderMd(prop.description)}

} {prop.enum &&

Allowed values: {prop.enum.map((v, i) => <>{i > 0 && ", "}{String(v)})}

} {constraints.length > 0 &&

{constraints.join(" · ")}

} {isComplexDefault &&

Default: 

              
                {JSON.stringify(rawDefault, null, 2)}
} {isArrayOfObjects && } {isObject && } ; }; return
{description &&

{renderMd(description)}

} {visibleProps.map(renderProp)}
; }; export const LwTemplate = ({title = "Key questions to get you started", icon = "sparkles", cta = "Powered by Agent Studio", linkHref = "https://lucidworks.com/demo/?utm_source=docs&utm_medium=referral&utm_campaign=docs_cta_ai"}) => { const [isLoaded, setIsLoaded] = useState(false); useEffect(() => { const timer = setTimeout(() => { setIsLoaded(true); }, 500); return () => clearTimeout(timer); }, []); return
{isLoaded && ` }} />} Powered by Lucidworks Agent Studio
; }; [localhost link]: http://localhost:3000/docs/lucidworks-search/09-developer-documentation/config-specs/parsers/json-parser [mintlify link]: https://doc.lucidworks.com/docs/lucidworks-search/09-developer-documentation/config-specs/parsers/json-parser [old doc.lw link]: https://doc.lucidworks.com/managed-fusion/5.9/1cp12w JSON parsing converts JSON content from a single document field into one or more new documents. This parser uses Solr’s [JsonRecordReader](https://lucene.apache.org/solr/5_1_0/solr-solrj/org/apache/solr/common/util/JsonRecordReader.html) to split JSON into sub-documents. If your JSON file contains a column named `id`, this column is consumed to populate the document's unique identifier (Solr's `uniqueKey`) and is not available as a stored field. This behavior occurs because the default value of the parser's **Document ID Source Field** parameter is also `id`. When a CSV column matches this parameter: * The column's value is used to generate the document ID. * The column does not appear in the indexed document as a field. If you need to preserve your `id` column data as a regular field, use one of these options: * Change the column header from `id` to another name such as `record_id` or `item_id`. This is the simplest solution. * In the JSON parser stage configuration, use a mapping rule to map `$.id` to another name such as `record_id` or `item_id`. * In the Index Workbench's parser configuration, set the **Document ID Source Field** to a different column name. This allows `id` to be treated as a normal field, but you must specify a different column to use as the document identifier. See [Parsers Overview](/docs/lucidworks-search/04-move-data-in/parsers/overview) for information about configuring the **Document ID Source Field** parameter. When entering configuration values in the UI, use *unescaped* characters, such as `\t` for the tab character. When entering configuration values in the API, use *escaped* characters, such as `\\t` for the tab character.