@celigo/api-specs 0.2.1

package/dist/processor.yml

@@ -0,0 +1,1253 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Parsers & Generators
+  description: API for one-shot parse/generate calls that convert between raw formats (XML, CSV, EDI) and structured JSON.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: Parsers & Generators
+    description: |-
+      Stateless data transformation processors that convert between raw formats
+      (XML, CSV, EDI) and structured JSON. Parsers accept raw data and return
+      JSON records; generators accept JSON and produce formatted output.
+
+      These are one-shot transformation calls — they do not create or modify
+      any resources. Use them to test parsing rules, preview file definitions,
+      or transform data outside of a flow.
+
+      ## Processor descriptor schema
+
+      {% openapi-schemas spec="processor" schemas="ProcessorDescriptor" grouped="true" %}
+paths:
+  /v1/processors:
+    get:
+      x-internal: false
+      operationId: listProcessorTypes
+      tags:
+        - Parsers & Generators
+      summary: List available flow processor types
+      description: |-
+        Returns the catalog of processor types the flow engine supports — filter,
+        transform, handlebars, javascript, mapper, CSV/XML parser / generator,
+        branch filter, merge, etc. Each entry carries a label, description, and
+        the input/output media types the processor accepts. The response is
+        keyed by processor name (not an array).
+      responses:
+        '200':
+          description: Processor catalog, keyed by processor name.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProcessorsResponse'
+              examples:
+                default:
+                  value:
+                    handlebars:
+                      name: handlebars
+                      label: Handlebars
+                      description: Handlebars template processor.
+                      ruleMediaType: text
+                      dataMediaType: json
+                      resultMediaType: text
+                    javascript:
+                      name: javascript
+                      label: JavaScript
+                      description: JavaScript hook processor.
+                      ruleMediaType: javascript
+                      dataMediaType: json
+                      resultMediaType: json
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/processors/xmlParser:
+    post:
+      x-internal: false
+      operationId: parseXml
+      tags:
+        - Parsers & Generators
+      summary: Convert XML to JSON
+      description: |-
+        Parses XML data into JSON records using the specified parsing rules
+        and resource path.
+
+        **Resource path format** — Use XPath-style slash-separated paths
+        (e.g. `/root/item`). Dot-separated paths (e.g. `root.item`) do not
+        work.
+
+        **Legacy vs modern output** — Without `doc.parsers` configured, or
+        with `V0_json: true`, the parser produces a legacy format where
+        element text appears as `[{"_": "value"}]` arrays and attributes
+        appear under a `$` key. Setting `V0_json: false` produces clean
+        key-value pairs and flattens attributes into the record.
+
+        When `groupByFields` is used the response shape changes: `data`
+        becomes an array of arrays and `dataRecordTraceKeys` /
+        `traceKeysDuplicate` are omitted.
+
+        Invalid XML returns a 422 with code `cannot_parse_xml`.
+        Namespaced XPath expressions (e.g. `ns:element`) return a 422
+        with code `invalid_xpath`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                data:
+                  type: string
+                  examples:
+                    - <orders><order><id>101</id><item>Widget</item></order></orders>
+                  description: The XML data to parse (as a string).
+                rules:
+                  type: object
+                  description: |-
+                    Parsing rules. At minimum, provide `resourcePath` to select
+                    which XML elements become records. Add `doc.parsers` to
+                    control the output format.
+                  properties:
+                    resourcePath:
+                      type: string
+                      examples:
+                        - /orders/order
+                      description: |-
+                        Slash-separated path to the repeating element in the XML
+                        (e.g. `/root/items/item`). Each matching element becomes
+                        one output record.
+                    groupByFields:
+                      type: array
+                      items:
+                        type: string
+                      description: |-
+                        Group parsed records by these field names. Changes the
+                        response `data` to an array of arrays and omits
+                        `dataRecordTraceKeys` and `traceKeysDuplicate`.
+                    sortByFields:
+                      type: array
+                      items:
+                        type: string
+                    doc:
+                      type: object
+                      properties:
+                        fileParser:
+                          type: boolean
+                        parsers:
+                          type: array
+                          description: |-
+                            Array of parser configurations. Typically contains a
+                            single XML parser entry.
+                          items:
+                            type: object
+                            properties:
+                              type:
+                                type: string
+                                enum:
+                                  - xml
+                                x-enumDescriptions:
+                                  xml: XML parser configuration.
+                              version:
+                                type: integer
+                                examples:
+                                  - 1
+                              rules:
+                                type: object
+                                properties:
+                                  V0_json:
+                                    type: boolean
+                                    description: |-
+                                      When `false`, produces clean key-value output
+                                      and flattens XML attributes into the record.
+                                      When `true` (default), uses legacy format with
+                                      `_` and `$` keys.
+                                  trimSpaces:
+                                    type: boolean
+                                    description: Trim leading/trailing whitespace from text nodes.
+                                  stripNewLineChars:
+                                    type: boolean
+                                    description: Remove newline characters from text nodes.
+                                  attributePrefix:
+                                    type: string
+                                    examples:
+                                      - '@'
+                                    description: |-
+                                      Prefix prepended to XML attribute names in the
+                                      JSON output (e.g. `@` produces `@id`). Only
+                                      active when `V0_json` is `false`.
+                                  textNodeName:
+                                    type: string
+                                    examples:
+                                      - '&txt'
+                                    description: |-
+                                      Property name for text content in mixed-content
+                                      elements. Defaults to `&txt`. Only active when
+                                      `V0_json` is `false`.
+                                  listNodes:
+                                    type: array
+                                    items:
+                                      type: string
+                                    description: |-
+                                      Element names that should always be arrays in the
+                                      output, even when containing a single item. Only
+                                      active when `V0_json` is `false`.
+                                  includeNodes:
+                                    type: array
+                                    items:
+                                      type: string
+                                    description: |-
+                                      Only include these element names in the output.
+                                      All other elements are dropped. Only active when
+                                      `V0_json` is `false`.
+                                  excludeNodes:
+                                    type: array
+                                    items:
+                                      type: string
+                                    description: |-
+                                      Exclude these element names from the output. Only
+                                      active when `V0_json` is `false`.
+                                  mixedNodes:
+                                    type: array
+                                    items:
+                                      type: string
+                                    description: |-
+                                      Element names that contain mixed content (text
+                                      interleaved with child elements). Text is
+                                      extracted into the `textNodeName` property. Only
+                                      active when `V0_json` is `false`.
+            examples:
+              modern:
+                summary: Parse XML with clean output (V0_json false)
+                value:
+                  data: <orders><order><id>101</id><item>Widget</item></order><order><id>102</id><item>Gadget</item></order></orders>
+                  rules:
+                    resourcePath: /orders/order
+                    doc:
+                      fileParser: true
+                      parsers:
+                        - type: xml
+                          version: 1
+                          rules:
+                            V0_json: false
+              legacy:
+                summary: Parse XML with legacy output (default)
+                value:
+                  data: <orders><order><id>101</id><item>Widget</item></order></orders>
+                  rules:
+                    resourcePath: /orders/order
+      responses:
+        '200':
+          description: Parsed JSON records.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ParserResponse'
+              examples:
+                modern:
+                  summary: Clean output (V0_json false)
+                  value:
+                    mediaType: json
+                    data:
+                      - id: '101'
+                        item: Widget
+                      - id: '102'
+                        item: Gadget
+                    duration: 1
+                    dataRecordTraceKeys:
+                      - null
+                      - null
+                    traceKeysDuplicate: false
+                legacy:
+                  summary: Legacy output (default)
+                  value:
+                    mediaType: json
+                    data:
+                      - id:
+                          - _: '101'
+                        item:
+                          - _: Widget
+                    duration: 1
+                    dataRecordTraceKeys:
+                      - null
+                    traceKeysDuplicate: false
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: Invalid XPath expression or processing rule error.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                    enum:
+                      - invalid_xpath
+                      - cannot_parse_xml
+                    x-enumDescriptions:
+                      invalid_xpath: The resourcePath contains an invalid or namespaced XPath expression.
+                      cannot_parse_xml: The input data is not well-formed XML.
+                  message:
+                    type: string
+                  source:
+                    type: string
+                  resolved:
+                    type: boolean
+                  occurredAt:
+                    type: integer
+                  path:
+                    type: string
+  /v1/processors/csvParser:
+    post:
+      x-internal: false
+      operationId: parseCsv
+      tags:
+        - Parsers & Generators
+      summary: Convert CSV to JSON
+      description: |-
+        Parses CSV data into JSON records using the specified delimiter and
+        formatting rules.
+
+        Both `data` and `rules` are technically optional — omitting either
+        returns an empty result rather than an error. When `hasHeaderRow` is
+        false, columns are named `Column0`, `Column1`, etc. When
+        `includeEmptyValues` is true, missing values become JSON `null`
+        instead of being omitted from the record.
+
+        When `groupByFields` is used the response shape changes: `data`
+        becomes an array of arrays (grouped records) and the
+        `dataRecordTraceKeys` / `traceKeysDuplicate` fields are omitted.
+        This is a stateless transformation. All values are returned as
+        strings, even numeric CSV columns.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                data:
+                  type: string
+                  examples:
+                    - |-
+                      name,email,age
+                      Alice,alice@example.com,30
+                      Bob,bob@example.com,25
+                  description: The CSV data to parse.
+                rules:
+                  type: object
+                  description: Parsing rules controlling delimiters, headers, and grouping.
+                  properties:
+                    columnDelimiter:
+                      type: string
+                      examples:
+                        - ','
+                      description: Column delimiter character (e.g. `,`, `\t`).
+                    rowDelimiter:
+                      type: string
+                      examples:
+                        - |+
+
+                      description: Row delimiter (e.g. `\n`, `|`).
+                    trimSpaces:
+                      type: boolean
+                      description: When true, trims leading and trailing spaces from parsed values.
+                    hasHeaderRow:
+                      type: boolean
+                      description: |-
+                        When true, the first row is treated as column headers. When false,
+                        columns are named Column0, Column1, etc.
+                    rowsPerRecord:
+                      type: boolean
+                    rowsToSkip:
+                      type: integer
+                      examples:
+                        - 0
+                      description: Number of rows to skip before parsing begins.
+                    multipleRowsPerRecord:
+                      type: boolean
+                    keyColumns:
+                      type: array
+                      items:
+                        type: string
+                      description: |-
+                        Group consecutive rows into multi-row records by
+                        these column names. When a new value appears in a
+                        key column, a new record group starts. Changes the
+                        response `data` to an array of arrays.
+                    disableQuoteAndStripEnclosingQuotes:
+                      type: boolean
+                      description: |-
+                        Disables CSV quote handling and strips enclosing
+                        quotes from values.
+                    groupByFields:
+                      type: array
+                      items:
+                        type: string
+                      description: |-
+                        Group parsed records by these field names. Changes the
+                        response `data` to an array of arrays and omits
+                        `dataRecordTraceKeys` and `traceKeysDuplicate`.
+                    sortByFields:
+                      type: array
+                      items:
+                        type: string
+                options:
+                  type: object
+                  properties:
+                    includeEmptyValues:
+                      type: boolean
+                      description: |-
+                        When true, empty CSV values are returned as JSON `null`.
+                        When false (default), empty values are omitted from the
+                        record.
+            examples:
+              default:
+                summary: Parse a simple CSV with headers
+                value:
+                  data: |-
+                    name,email,age
+                    Alice,alice@example.com,30
+                    Bob,bob@example.com,25
+                  rules:
+                    columnDelimiter: ','
+                    hasHeaderRow: true
+                  options:
+                    includeEmptyValues: false
+      responses:
+        '200':
+          description: Parsed JSON records.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ParserResponse'
+              examples:
+                default:
+                  value:
+                    mediaType: json
+                    data:
+                      - name: Alice
+                        email: alice@example.com
+                        age: '30'
+                      - name: Bob
+                        email: bob@example.com
+                        age: '25'
+                    duration: 0
+                    dataRecordTraceKeys:
+                      - null
+                      - null
+                    traceKeysDuplicate: false
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/processors/csvDataGenerator:
+    post:
+      x-internal: false
+      operationId: generateCsv
+      tags:
+        - Parsers & Generators
+      summary: Generate CSV from JSON
+      description: |-
+        Generates CSV output from JSON records using the specified delimiter
+        and formatting rules.
+
+        The response always has `mediaType: "text"` and does not include
+        `dataRecordTraceKeys` or `traceKeysDuplicate`. This is a stateless
+        transformation.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                data:
+                  description: |-
+                    Records to convert to CSV. Accepts a flat array of objects
+                    (e.g. `[{"a":"1"}, {"a":"2"}]`) or an array of arrays for
+                    batch processing (e.g. `[[{"a":"1"}], [{"a":"2"}]]`). Each
+                    object's keys become column names when `includeHeader` is
+                    true.
+                  oneOf:
+                    - type: array
+                      items:
+                        type: object
+                        additionalProperties: true
+                    - type: array
+                      items:
+                        type: array
+                        items:
+                          type: object
+                          additionalProperties: true
+                rules:
+                  type: object
+                  description: |-
+                    Generation rules controlling delimiters, headers, and
+                    formatting.
+                  properties:
+                    columnDelimiter:
+                      type: string
+                      examples:
+                        - ','
+                      description: Column delimiter character (e.g. `,`, `\t`).
+                    rowDelimiter:
+                      type: string
+                      examples:
+                        - |+
+
+                      description: |-
+                        Row delimiter character (default `\n`). Appended after
+                        each row including the last unless
+                        `truncateLastRowDelimiter` is true.
+                    includeHeader:
+                      type: boolean
+                      description: When true, includes a header row with column names in the output.
+                    truncateLastRowDelimiter:
+                      type: boolean
+                      description: |-
+                        When true, omits the trailing row delimiter after the
+                        last data row.
+                    replaceTabWithSpace:
+                      type: boolean
+                      description: Replace tab characters in values with spaces.
+                    replaceNewlineWithSpace:
+                      type: boolean
+                      description: Replace newline characters in values with spaces.
+                    wrapWithQuotes:
+                      type: boolean
+                      description: Wrap every value (including headers) in double quotes.
+                    customHeaderRows:
+                      type: array
+                      items:
+                        type: string
+                      description: |-
+                        Custom header lines prepended before the column header
+                        row and data rows. Each string becomes one line in the
+                        output.
+            examples:
+              default:
+                summary: Generate CSV with header row
+                value:
+                  data:
+                    - name: Alice
+                      email: alice@example.com
+                    - name: Bob
+                      email: bob@example.com
+                  rules:
+                    columnDelimiter: ','
+                    rowDelimiter: |+
+
+                    includeHeader: true
+      responses:
+        '200':
+          description: Generated CSV data.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GeneratorResponse'
+              examples:
+                default:
+                  value:
+                    mediaType: text
+                    data: |
+                      name,email
+                      Alice,alice@example.com
+                      Bob,bob@example.com
+                    duration: 0
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/processors/structuredFileParser:
+    post:
+      x-internal: false
+      operationId: parseStructuredFile
+      tags:
+        - Parsers & Generators
+      summary: Parse structured file (EDI) to JSON
+      description: |-
+        Parses EDI or other structured/delimited file data into JSON using
+        a file definition (parsing rules). Commonly used for X12 and EDIFACT
+        documents.
+
+        The file definition must be provided inside a `rules.fileDefinition`
+        wrapper object, or referenced by ID via `rules._fileDefinitionId`.
+        This differs from the generator endpoint which places definition
+        fields directly in `rules`.
+
+        The response includes a `recordLevelErrors` array not present on
+        other processor responses. This is a stateless transformation.
+        Provide the file definition inline via `rules.fileDefinition` or
+        reference an existing one via `rules._fileDefinitionId` (not both).
+        The generator endpoint places definition fields directly in `rules`
+        (no `fileDefinition` wrapper).
+
+        **Required file definition fields** — `name`, `version` (string
+        `"1"` or `"2"`), `format` (`delimited`, `delimited/x12`,
+        `delimited/edifact`, or `fixed`), and the corresponding format
+        sub-object (`delimited` or `fixed`) with at least `rowDelimiter`
+        and `colDelimiter` (for delimited) or `rowDelimiter` and
+        `paddingChar` (for fixed). The `rules` property defines the
+        segment/element hierarchy.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - data
+                - rules
+              properties:
+                data:
+                  type: string
+                  examples:
+                    - |-
+                      HDR~John~Doe
+                      DTL~100~USD
+                  description: The raw structured file content to parse.
+                rules:
+                  type: object
+                  description: |-
+                    Provide either a `fileDefinition` object with the full
+                    definition inline, or a `_fileDefinitionId` to reference
+                    an existing file definition resource.
+                  properties:
+                    fileDefinition:
+                      type: object
+                      description: |-
+                        Inline file definition. Must include `name`, `version`,
+                        `format`, the format-specific sub-object, and `rules`.
+                      properties:
+                        name:
+                          type: string
+                          examples:
+                            - simple-delimited
+                        description:
+                          type: string
+                          examples:
+                            - Simple tilde-delimited header/detail file.
+                        version:
+                          type: string
+                          enum:
+                            - '1'
+                            - '2'
+                          x-enumDescriptions:
+                            '1': Original file definition schema version.
+                            '2': Updated file definition schema version with breaking changes.
+                        format:
+                          type: string
+                          description: File format type.
+                          enum:
+                            - delimited
+                            - delimited/x12
+                            - delimited/edifact
+                            - fixed
+                          x-enumDescriptions:
+                            delimited: Generic delimited file (CSV, TSV, pipe-delimited, etc.).
+                            delimited/x12: X12 EDI format with ISA/GS/ST envelope segments.
+                            delimited/edifact: UN/EDIFACT format with UNA/UNB/UNH envelope segments.
+                            fixed: Fixed-width columns padded to defined lengths.
+                        delimited:
+                          type: object
+                          description: Required when `format` starts with `delimited`.
+                          properties:
+                            rowSuffix:
+                              type: string
+                              examples:
+                                - '~'
+                            rowDelimiter:
+                              type: string
+                              examples:
+                                - |+
+
+                              description: Row delimiter (required).
+                            colDelimiter:
+                              type: string
+                              examples:
+                                - '~'
+                              description: Column delimiter (required for delimited).
+                            compositeDelimiter:
+                              type: string
+                              examples:
+                                - ':'
+                              description: Composite element delimiter (EDI formats).
+                        fixed:
+                          type: object
+                          description: Required when `format` is `fixed`.
+                          properties:
+                            rowSuffix:
+                              type: string
+                              examples:
+                                - '~'
+                            rowDelimiter:
+                              type: string
+                              examples:
+                                - |+
+
+                              description: Row delimiter (required).
+                            paddingChar:
+                              type: string
+                              examples:
+                                - ' '
+                              description: Padding character (required, single char).
+                        skipEmptyEndColDelimiter:
+                          type: boolean
+                        skipIntermittentEmptyLines:
+                          type: boolean
+                        skipEDIValidation:
+                          type: boolean
+                        skipEDIProfileValidation:
+                          type: boolean
+                        rules:
+                          description: |-
+                            Segment/element hierarchy. Can be an array of
+                            segment objects or a single root container object
+                            with `children`.
+                          oneOf:
+                            - title: Segment array
+                              type: array
+                              items:
+                                type: object
+                                additionalProperties: true
+                            - title: Root container
+                              type: object
+                              additionalProperties: true
+                      required:
+                        - name
+                        - version
+                        - format
+                        - rules
+                    _fileDefinitionId:
+                      type: string
+                      x-celigo-refModel: filedefinitions
+                      examples:
+                        - 60a2c4e6f321d800129a1a3c
+                      description: |-
+                        Reference an existing file definition by ID instead of
+                        providing an inline definition.
+                    resourcePath:
+                      type: string
+                      examples:
+                        - DTL
+                      description: |-
+                        Dot-separated path into the parsed document to select
+                        which segment's data to return as records.
+                options:
+                  type: object
+                  properties:
+                    ediProfile:
+                      type: object
+                      additionalProperties: true
+                      description: Optional EDI profile for ISA/GS envelope context.
+            examples:
+              inline-definition:
+                summary: Parse with inline file definition
+                value:
+                  data: |-
+                    HDR~John~Doe
+                    DTL~100~USD
+                  rules:
+                    fileDefinition:
+                      name: simple-delimited
+                      version: '1'
+                      format: delimited
+                      delimited:
+                        rowDelimiter: |+
+
+                        colDelimiter: '~'
+                      rules:
+                        - name: HDR
+                          elements:
+                            - name: firstName
+                            - name: lastName
+                        - name: DTL
+                          elements:
+                            - name: amount
+                            - name: currency
+              by-reference:
+                summary: Parse with file definition reference
+                value:
+                  data: HDR~John~Doe
+                  rules:
+                    _fileDefinitionId: 60a2c4e6f321d800129a1a3c
+      responses:
+        '200':
+          description: Parsed JSON records.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StructuredFileParserResponse'
+              examples:
+                default:
+                  value:
+                    mediaType: json
+                    data:
+                      - HDR:
+                          firstName: John
+                          lastName: Doe
+                        DTL:
+                          amount: '100'
+                          currency: USD
+                    recordLevelErrors: []
+                    duration: 1
+                    dataRecordTraceKeys:
+                      - null
+                    traceKeysDuplicate: false
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: File definition validation error or missing required segment.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                  source:
+                    type: string
+                  code:
+                    type: string
+                    description: |-
+                      Error code. Common values: `file_definition_error`,
+                      `missing_row`, `WRONG_MAX_OCCURRENCE`.
+                  resolved:
+                    type: boolean
+                  occurredAt:
+                    type: integer
+                  path:
+                    type: string
+  /v1/processors/structuredFileGenerator:
+    post:
+      x-internal: false
+      operationId: generateStructuredFile
+      tags:
+        - Parsers & Generators
+      summary: Generate structured file (EDI) from JSON
+      description: |-
+        Generates EDI or other structured/delimited file content from JSON
+        records using a file definition (generation rules). Commonly used
+        for producing X12 and EDIFACT documents.
+
+        Unlike the parser endpoint, the generator places file definition
+        fields directly in `rules` (no `fileDefinition` wrapper). Each
+        element in the definition must include a `value` property containing
+        the literal text to output for that field.
+
+        The `data` field must be an array of objects. Each object in the
+        array represents one document to generate. The response has
+        `mediaType: "text"` and does not include `dataRecordTraceKeys` or
+        `traceKeysDuplicate`.
+
+        **Required file definition fields** — `name`, `version` (string
+        `"1"` or `"2"`), `format`, the format sub-object with
+        `rowDelimiter` + `colDelimiter` (and optionally `rowSuffix`), and
+        `rules` defining segments with elements that each have `name` and
+        `value`. This is a stateless transformation. File definition fields
+        go directly in `rules` (no `fileDefinition` wrapper, unlike the
+        parser endpoint).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - data
+                - rules
+              properties:
+                data:
+                  type: array
+                  description: |-
+                    Array of record objects. Each object represents one
+                    document to generate. The generator uses element `value`
+                    properties from the rules, not field values from these
+                    objects.
+                  items:
+                    type: object
+                    additionalProperties: true
+                rules:
+                  type: object
+                  description: |-
+                    File definition placed directly at this level (no
+                    `fileDefinition` wrapper). Must include `name`, `version`,
+                    `format`, the format sub-object, and `rules`.
+                  required:
+                    - name
+                    - version
+                    - format
+                    - rules
+                  properties:
+                    name:
+                      type: string
+                      examples:
+                        - simple-delimited
+                    description:
+                      type: string
+                      examples:
+                        - Simple tilde-delimited header/detail file.
+                    version:
+                      type: string
+                      enum:
+                        - '1'
+                        - '2'
+                      x-enumDescriptions:
+                        '1': Original file definition schema version.
+                        '2': Updated file definition schema version with breaking changes.
+                    format:
+                      type: string
+                      description: File format type.
+                      enum:
+                        - delimited
+                        - delimited/x12
+                        - delimited/edifact
+                        - fixed
+                      x-enumDescriptions:
+                        delimited: Generic delimited file (CSV, TSV, pipe-delimited, etc.).
+                        delimited/x12: X12 EDI format with ISA/GS/ST envelope segments.
+                        delimited/edifact: UN/EDIFACT format with UNA/UNB/UNH envelope segments.
+                        fixed: Fixed-width columns padded to defined lengths.
+                    delimited:
+                      type: object
+                      description: Required when `format` starts with `delimited`.
+                      properties:
+                        rowSuffix:
+                          type: string
+                          examples:
+                            - '~'
+                          description: Appended after each row.
+                        rowDelimiter:
+                          type: string
+                          examples:
+                            - |+
+
+                          description: Row delimiter (required).
+                        colDelimiter:
+                          type: string
+                          examples:
+                            - '~'
+                          description: Column delimiter (required for delimited).
+                        compositeDelimiter:
+                          type: string
+                          examples:
+                            - ':'
+                          description: Composite element delimiter (EDI formats).
+                    fixed:
+                      type: object
+                      description: Required when `format` is `fixed`.
+                      properties:
+                        rowSuffix:
+                          type: string
+                          examples:
+                            - '~'
+                        rowDelimiter:
+                          type: string
+                          examples:
+                            - |+
+
+                          description: Row delimiter (required).
+                        paddingChar:
+                          type: string
+                          examples:
+                            - ' '
+                          description: Padding character (required, single char).
+                    skipEmptyEndColDelimiter:
+                      type: boolean
+                    rules:
+                      type: array
+                      description: |-
+                        Array of segment definitions. Each segment has a `name`
+                        and `elements` array. Each element must have `name` and
+                        `value` (the literal text to output).
+                      items:
+                        type: object
+                        additionalProperties: true
+                  additionalProperties: true
+                options:
+                  type: object
+                  properties:
+                    ediProfile:
+                      type: object
+                      additionalProperties: true
+                      description: Optional EDI profile for ISA/GS envelope context.
+            examples:
+              default:
+                summary: Generate a simple delimited file
+                value:
+                  data:
+                    - {}
+                  rules:
+                    name: simple-delimited
+                    version: '1'
+                    format: delimited
+                    delimited:
+                      rowDelimiter: |+
+
+                      colDelimiter: '~'
+                    rules:
+                      - name: HDR
+                        elements:
+                          - name: firstName
+                            value: John
+                          - name: lastName
+                            value: Doe
+      responses:
+        '200':
+          description: Generated structured file content.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GeneratorResponse'
+              examples:
+                default:
+                  value:
+                    mediaType: text
+                    data: |
+                      HDR~John~Doe
+                    duration: 0
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: File definition validation error.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  source:
+                    type: string
+                  code:
+                    type: string
+                    description: |-
+                      Error code. Typically `INVALID_FILE_DEFINITION` or
+                      `wrong_data_type`.
+                  message:
+                    type: string
+                  details:
+                    type: array
+                    description: Detailed validation errors.
+                    items:
+                      type: object
+                      properties:
+                        path:
+                          type: string
+                        message:
+                          type: string
+                        name:
+                          type: string
+                  path:
+                    type: string
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    ProcessorDescriptor:
+      type: object
+      required:
+        - name
+        - label
+        - description
+        - dataMediaType
+        - resultMediaType
+        - ruleMediaType
+      description: Metadata describing a single processor type.
+      properties:
+        name:
+          type: string
+          examples:
+            - handlebars
+          description: Processor key (matches the enclosing object key).
+        label:
+          type: string
+          examples:
+            - Handlebars
+          description: Human-readable label shown in the UI.
+        description:
+          type: string
+          examples:
+            - Handlebars template processor.
+          description: Short description of the processor's behavior.
+        ruleMediaType:
+          type: string
+          examples:
+            - text
+          description: |-
+            Media type of the processor's rule/template field. Typical values
+            include `text`, `json`, `javascript`.
+        dataMediaType:
+          type: string
+          examples:
+            - json
+          description: Media type the processor expects for the input data.
+        resultMediaType:
+          type: string
+          examples:
+            - text
+          description: Media type the processor emits as its result.
+        ruleJsonSchema:
+          type: object
+          additionalProperties: true
+          description: |-
+            JSON Schema describing the processor's rule structure. Only
+            present on processors with a formal schema (e.g. exportDataConverter).
+        helperFunctions:
+          type: object
+          additionalProperties:
+            type: string
+          description: |-
+            Map of helper function names to usage templates. Only present
+            on the handlebars processor.
+    ProcessorsResponse:
+      type: object
+      description: |-
+        Processor catalog keyed by processor name. Each value describes the
+        processor's label, purpose, and input/output media types.
+      additionalProperties:
+        $ref: '#/components/schemas/ProcessorDescriptor'
+    ParserResponse:
+      type: object
+      description: |-
+        Response from a parser processor (`csvParser`, `xmlParser`).
+
+        When `groupByFields` is used in the request, the `dataRecordTraceKeys`
+        and `traceKeysDuplicate` fields are omitted from the response and `data`
+        becomes an array of arrays (each inner array is one group of records).
+      properties:
+        mediaType:
+          type: string
+          description: Always `json` for parser processors.
+          enum:
+            - json
+          x-enumDescriptions:
+            json: Response data is formatted as JSON.
+        data:
+          description: |-
+            Parsed records. Normally an array of objects. When `groupByFields`
+            is used, becomes an array of arrays (grouped records).
+          oneOf:
+            - type: array
+              items:
+                type: object
+                additionalProperties: true
+            - type: array
+              items:
+                type: array
+                items:
+                  type: object
+                  additionalProperties: true
+        duration:
+          type: integer
+          description: Processing time in milliseconds.
+        dataRecordTraceKeys:
+          type: array
+          items:
+            type:
+              - string
+              - 'null'
+          description: |-
+            Trace keys for each output record (nullable entries). Omitted
+            when `groupByFields` is used.
+        traceKeysDuplicate:
+          type: boolean
+          description: |-
+            Whether any duplicate trace keys were detected. Omitted when
+            `groupByFields` is used.
+    GeneratorResponse:
+      type: object
+      description: Response from a generator processor (`csvDataGenerator`, `structuredFileGenerator`).
+      properties:
+        mediaType:
+          type: string
+          description: Always `text` for generator processors.
+          enum:
+            - text
+          x-enumDescriptions:
+            text: Response data is formatted as plain text.
+        data:
+          type: string
+          description: Generated text output (CSV, EDI, or other structured format).
+        duration:
+          type: integer
+          description: Processing time in milliseconds.
+    StructuredFileParserResponse:
+      type: object
+      description: Response from the `structuredFileParser` processor.
+      properties:
+        mediaType:
+          type: string
+          description: Always `json` for the structured file parser.
+          enum:
+            - json
+          x-enumDescriptions:
+            json: Response data is formatted as JSON.
+        data:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+          description: Parsed records from the structured file.
+        recordLevelErrors:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+          description: |-
+            Per-record errors encountered during parsing (e.g. missing required
+            segments or element validation failures).
+        duration:
+          type: integer
+          description: Processing time in milliseconds.
+        dataRecordTraceKeys:
+          type: array
+          items:
+            type:
+              - string
+              - 'null'
+          description: Trace keys for each output record (nullable entries).
+        traceKeysDuplicate:
+          type: boolean
+          description: When true, duplicate trace keys were detected in the output records.
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+x-enable-proxy: true
+x-internal: false