@celigo/api-specs 0.2.1

package/dist/filedefinition.yml

@@ -0,0 +1,1396 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: File Definitions
+  description: API for managing Celigo file definitions — structure and parsing rules for CSV, fixed-width, and EDI files.
+  x-celigo-ai-guidance:
+    - |-
+      API for managing file definitions in Celigo. File definitions describe the structure
+      and parsing rules for structured files such as CSV, fixed-width, EDI X12, and
+      EDI EDIFACT formats.
+
+      File definitions are referenced by exports and imports that process file-based data.
+      They define how rows, columns, segments, and elements are parsed or generated,
+      including delimiters, padding, and hierarchical rule structures.
+
+      EDI file definitions (X12 and EDIFACT formats) require a valid `globalId` that
+      maps to a known standard document definition, and may require an EDI license.
+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: File Definitions
+    description: |-
+      File definitions describe the structure and parsing rules for structured files
+      (CSV, fixed-width, EDI X12, EDI EDIFACT). Exports and imports that process
+      file-based data reference a file definition to control how rows, columns,
+      segments, and elements are parsed or generated.
+
+      Four formats are supported: `delimited` (CSV/TSV), `delimited/x12` (EDI X12),
+      `delimited/edifact` (EDI EDIFACT), and `fixed` (fixed-width). EDI formats
+      require a `globalId` linking to a standard document definition.
+
+      ## File definition schema
+
+      {% openapi-schemas spec="filedefinition" schemas="FileDefinition" grouped="true" %}
+paths:
+  /v1/filedefinitions:
+    get:
+      x-internal: false
+      summary: List file definitions
+      description: Returns file definitions configured in the account.
+      operationId: listFileDefinitions
+      tags:
+        - File Definitions
+      parameters:
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+        - name: externalId
+          in: query
+          description: Filter to file definitions matching this exact external identifier.
+          schema:
+            type: string
+            examples:
+              - ext-filedef-12345
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of file definitions to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            examples:
+              - 100
+      responses:
+        '200':
+          description: List of file definitions.
+          headers:
+            Link:
+              description: RFC 5988 pagination links. Includes `<...>; rel="next"` when more pages remain.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/FileDefinition'
+              examples:
+                default:
+                  value:
+                    - _id: 69150aa2578417f9fa410317
+                      name: Costco 850
+                      version: '2'
+                      format: delimited/x12
+                      globalId: 525b2a50-b8e5-4d01-b0ae-bf7fa4228ea2
+                      skipEmptyEndColDelimiter: true
+                      skipEDIValidation: true
+                      skipEDIProfileValidation: true
+                      delimited:
+                        rowSuffix: '~'
+                        rowDelimiter: |+
+
+                        colDelimiter: '*'
+                      rules:
+                        - required: true
+                          maxOccurrence: 1
+                          elements:
+                            - name: ISA
+                              value: ISA
+                      lastModified: '2025-11-12T22:30:58.442Z'
+                      sandbox: false
+        '204':
+          description: No file definitions exist in the account.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+      x-celigo-ai-guidance:
+        - |-
+          Returns a list of all file definitions configured in the account.
+          If no file definitions exist, a 204 response with no body will be returned.
+    post:
+      x-internal: false
+      summary: Create a file definition
+      description: Creates a new file definition.
+      operationId: createFileDefinition
+      tags:
+        - File Definitions
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              delimited:
+                summary: Delimited (CSV)
+                value:
+                  name: Customer CSV Import
+                  version: '1'
+                  format: delimited
+                  delimited:
+                    rowDelimiter: |+
+
+                    colDelimiter: ','
+                  rules:
+                    - required: true
+                      maxOccurrence: 1
+                      elements:
+                        - name: customer_id
+                        - name: customer_name
+                        - name: email
+              fixed:
+                summary: Fixed-width
+                value:
+                  name: Fixed-Width Payment File
+                  version: '1'
+                  format: fixed
+                  fixed:
+                    rowDelimiter: |+
+
+                    paddingChar: ' '
+                  rules:
+                    - required: true
+                      maxOccurrence: 1
+                      elements:
+                        - name: record_type
+                          length: 2
+                          value: '01'
+                        - name: account_number
+                          length: 15
+                        - name: amount
+                          length: 10
+      responses:
+        '201':
+          description: File definition created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FileDefinition'
+              examples:
+                delimited:
+                  summary: Created delimited (CSV) definition
+                  value:
+                    _id: 5f8d43a1b9e5a80011a35f2c
+                    name: Customer CSV Import
+                    version: '1'
+                    format: delimited
+                    delimited:
+                      rowDelimiter: |+
+
+                      colDelimiter: ','
+                    rules:
+                      - required: true
+                        maxOccurrence: 1
+                        elements:
+                          - name: customer_id
+                          - name: customer_name
+                          - name: email
+                    lastModified: '2026-06-09T18:05:33.612Z'
+                    sandbox: false
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+      x-celigo-ai-guidance:
+        - |-
+          For EDI formats (`delimited/x12` or `delimited/edifact`), a valid `globalId`
+          is required when the account has an EDI license enabled. The `globalId` must
+          reference a known standard document definition.
+  /v1/filedefinitions/{_id}:
+    get:
+      x-internal: false
+      summary: Get a file definition
+      description: Returns the complete configuration including parsing rules.
+      operationId: getFileDefinitionById
+      tags:
+        - File Definitions
+      parameters:
+        - name: _id
+          in: path
+          description: File definition ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: filedefinitions
+            examples:
+              - 69150aa2578417f9fa410317
+      responses:
+        '200':
+          description: File definition.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FileDefinition'
+              examples:
+                delimited-x12:
+                  value:
+                    _id: 69150aa2578417f9fa410317
+                    name: Costco 850
+                    version: '2'
+                    format: delimited/x12
+                    description: Purchase Order
+                    globalId: 525b2a50-b8e5-4d01-b0ae-bf7fa4228ea2
+                    skipEmptyEndColDelimiter: true
+                    skipEDIValidation: true
+                    skipEDIProfileValidation: true
+                    delimited:
+                      rowSuffix: '~'
+                      rowDelimiter: |+
+
+                      colDelimiter: '*'
+                    rules:
+                      - required: true
+                        maxOccurrence: 1
+                        elements:
+                          - name: ISA
+                            value: ISA
+                    lastModified: '2025-11-12T22:30:58.442Z'
+                    sandbox: false
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update a file definition
+      description: |-
+        Replaces the file definition with the provided configuration. This
+        is a full replace -- include all fields you want to keep. `format`
+        cannot be changed between `fixed` and `delimited` families after
+        creation, and `globalId` is immutable for EDI formats.
+      operationId: updateFileDefinition
+      tags:
+        - File Definitions
+      parameters:
+        - name: _id
+          in: path
+          description: File definition ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: filedefinitions
+            examples:
+              - 69150aa2578417f9fa410317
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              delimited-x12:
+                summary: Full replace re-enabling EDI validation
+                value:
+                  name: Costco 850
+                  version: '2'
+                  format: delimited/x12
+                  description: Purchase Order
+                  globalId: 525b2a50-b8e5-4d01-b0ae-bf7fa4228ea2
+                  skipEmptyEndColDelimiter: true
+                  skipEDIValidation: false
+                  skipEDIProfileValidation: true
+                  delimited:
+                    rowSuffix: '~'
+                    rowDelimiter: |+
+
+                    colDelimiter: '*'
+                  rules:
+                    - required: true
+                      maxOccurrence: 1
+                      elements:
+                        - name: ISA
+                          value: ISA
+      responses:
+        '200':
+          description: Updated file definition.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FileDefinition'
+              examples:
+                delimited-x12:
+                  summary: Updated file definition
+                  value:
+                    _id: 69150aa2578417f9fa410317
+                    name: Costco 850
+                    version: '2'
+                    format: delimited/x12
+                    description: Purchase Order
+                    globalId: 525b2a50-b8e5-4d01-b0ae-bf7fa4228ea2
+                    skipEmptyEndColDelimiter: true
+                    skipEDIValidation: false
+                    skipEDIProfileValidation: true
+                    delimited:
+                      rowSuffix: '~'
+                      rowDelimiter: |+
+
+                      colDelimiter: '*'
+                    rules:
+                      - required: true
+                        maxOccurrence: 1
+                        elements:
+                          - name: ISA
+                            value: ISA
+                    lastModified: '2025-11-20T08:14:27.310Z'
+                    sandbox: false
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    delete:
+      x-internal: false
+      summary: Delete a file definition
+      description: Soft-deletes a file definition. Retained in the recycle bin for 30 days.
+      operationId: deleteFileDefinition
+      tags:
+        - File Definitions
+      parameters:
+        - name: _id
+          in: path
+          description: File definition ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: filedefinitions
+            examples:
+              - 69150aa2578417f9fa410317
+      responses:
+        '204':
+          description: File definition deleted.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/filedefinitions/{_id}/dependencies:
+    get:
+      x-internal: false
+      operationId: listFileDefinitionDependencies
+      tags:
+        - File Definitions
+      summary: List dependencies of a file definition
+      description: |-
+        Returns the set of resources that depend on the specified resource.
+        The response is an object whose keys are dependent-resource types
+        (e.g. `flows`, `imports`) and whose values are arrays of dependency
+        entries. Returns `{}` when no dependents exist, including for
+        well-formatted but nonexistent IDs.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: filedefinitions
+            examples:
+              - 69150aa2578417f9fa410317
+      responses:
+        '200':
+          description: |
+            Dependency map. Keys are resource-type strings; values are arrays
+            of dependency entries. Returns `{}` when no dependents exist.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DependencyResponse'
+              examples:
+                none:
+                  summary: No dependents (also returned for a nonexistent ID)
+                  value: {}
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    Include:
+      name: include
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to project into each returned record.
+        Triggers summary projection: the response contains a minimal identity
+        set (`_id`, `name`, plus resource-specific fields) with the requested
+        fields added on top. Supports dot notation for nested fields.
+        Mutually exclusive with `exclude`.
+      schema:
+        type: string
+      example: _integrationId,disabled,lastModified
+    Exclude:
+      name: exclude
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to strip from the default response.
+        Unlike `include`, does not trigger summary projection — returns the
+        full record with the named fields removed. Protected identity fields
+        (e.g. `name`) cannot be stripped. Mutually exclusive with `include`.
+      schema:
+        type: string
+      example: createdAt,lastModified
+  schemas:
+    Element:
+      type: object
+      additionalProperties: true
+      description: |
+        A single field / segment-element entry inside a `Rule.elements`
+        list.
+
+        **Format-specific usage**
+
+        - **Delimited (CSV / TSV)** — one element per column.  `name` is
+          the human label; `value` is the column id used to address the
+          field downstream (e.g. `orderId`, `customerName`).
+        - **Fixed-width** — adds `startPosition` + `length` (or the
+          legacy `start` / `end` pair) to describe the column's offset
+          within each row.
+        - **EDI X12 / EDIFACT** — element values follow the segmentNN
+          convention (`ISA01`, `BEG03`, `UNB02`).  Segment-element
+          definitions whose value comes from the trading-partner profile
+          use `referenceValue` to bind a Handlebars template such as
+          `{{{ediProfile.isa01}}}` — the runtime fills the value from
+          the profile at parse / generate time.
+
+        **Required fields**
+
+        `name` is required on every element.  `value` is optional: in
+        the canonical delimited row pattern, only the first element of a
+        rule (the row-type marker) carries `value`; subsequent data
+        columns use `name` only and are read by position.  When
+        `value` is set it must be non-empty — the parser uses it as a
+        literal match requirement (`ISA01`, `BEG03`, or the marker
+        string).
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: |
+            Human-readable label or segment-element identifier.  For EDI,
+            descriptive text such as `Authorization Information
+            Qualifier`; for delimited data columns, the output key (the
+            parser uses `name` as the field key in each parsed
+            record); for the row-type marker, equals `value`.
+          examples:
+            - Order ID
+            - Authorization Information Qualifier
+            - orderId
+        value:
+          description: |
+            Machine identifier, row-type matcher, or composite-element
+            definition.  Accepts either:
+
+            - A **string** — EDI elements use it as the segment-element
+              identifier (`ISA01`, `BEG03`).  In the canonical
+              delimited row pattern, only the first element of the row's
+              rule carries `value` — acting as the literal row-type
+              marker the parser matches against column 0 of every row
+              (e.g. `A`, `HDR`, `02`).  Subsequent data columns omit
+              `value` entirely.  When present must be non-empty.
+            - A **composite object** — EDI composite elements (an element
+              whose value is itself a delimited list of sub-elements,
+              e.g. EDIFACT `UNH02` = `S009` or X12 composites split by
+              the component separator) set `value` to an object with a
+              `delimiter` and nested `elements`.  See `CompositeValue`.
+          oneOf:
+            - title: literal
+              type: string
+            - title: composite
+              $ref: '#/components/schemas/CompositeValue'
+          examples:
+            - ISA01
+            - BEG03
+            - A
+            - HDR
+        type:
+          type: string
+          enum:
+            - string
+            - number
+            - decimal
+            - boolean
+          x-enumDescriptions:
+            string: Keeps the parsed value as text; the default when type is omitted.
+            number: Coerces the parsed value to a number, used for EDI control numbers, dates, and numeric fields.
+            decimal: Coerces the parsed value to a decimal number; written for EDI R-type (decimal) elements such as monetary amounts and quantities.
+            boolean: Coerces the parsed value to a boolean.
+          description: |
+            Type coercion applied to the parsed value before it reaches
+            downstream mapping / output.  Defaults to string when omitted.
+            EDI numeric segments (control numbers, dates) typically set
+            `type: number`; decimal-valued EDI elements (monetary
+            amounts, quantities) use `type: decimal`.
+          examples:
+            - string
+            - number
+            - decimal
+            - boolean
+        required:
+          type: boolean
+          default: false
+          description: |
+            Whether the parser should fail when this element is missing
+            or blank.  Defaults to false.  EDI envelope qualifiers and
+            transaction header fields (ISA/GS/ST elements) are
+            conventionally marked required.
+          examples:
+            - true
+            - false
+        minLength:
+          type: integer
+          minimum: 0
+          description: |
+            Inclusive minimum string length.  Used heavily on EDI
+            elements where the X12 / EDIFACT standard fixes the length
+            of envelope qualifiers (e.g. `ISA05` is exactly 2 chars,
+            `ISA13` is exactly 9 chars).
+        maxLength:
+          type: integer
+          minimum: 0
+          description: |
+            Inclusive maximum string length.  See `minLength` for
+            usage notes.
+        referenceValue:
+          type: string
+          description: |
+            Handlebars template that resolves to the element's value at
+            runtime instead of being read from the file.  Most common use
+            is binding EDI envelope fields to the trading-partner
+            profile, e.g. `{{{ediProfile.isa01}}}` or
+            `{{{ediProfile.tpInterchangeId}}}`.
+
+            Use triple-stash (`{{{...}}}`) to avoid HTML escaping for
+            EDI control characters.
+          examples:
+            - '{{{ediProfile.isa01}}}'
+            - '{{{ediProfile.tpInterchangeId}}}'
+        enum:
+          type: array
+          items:
+            type: string
+          description: |
+            Enumerated set of allowed values.  Used to enforce EDI code
+            lists (e.g. BEG01 purpose codes `["00", "06", "22"]`,
+            BEG02 type codes `["PR", "RL", "SA", "ZZ"]`).  When set,
+            the parser rejects values outside the list.
+          examples:
+            - - '00'
+              - '06'
+              - '22'
+            - - PR
+              - RL
+              - SA
+              - ZZ
+        description:
+          type: string
+          description: |
+            Free-text annotation surfaced in the file-definition editor.
+            No functional impact on parsing.
+        tally:
+          type: boolean
+          description: |
+            Marks this element's parsed value as a running tally that the
+            generator accumulates across loop iterations.  The
+            accumulated total is referenced from trailer segments via the
+            `{{_tally.[Element Name]}}` Handlebars helper (e.g. W04
+            "Number of Units Shipped" tallied into the W03 total).
+          examples:
+            - true
+        counter:
+          type: boolean
+          description: |
+            Marks this element as an auto-incrementing counter the
+            generator fills per emitted row / iteration (e.g. LX
+            assigned numbers, HL hierarchical ids).
+          examples:
+            - true
+        startPosition:
+          type: integer
+          minimum: 1
+          description: |
+            Fixed-width: 1-based start column (inclusive).  Pair with
+            `length` to describe the column extent.  Mutually exclusive
+            with the legacy `start` / `end` pair — pick one
+            convention per element.
+        length:
+          type: integer
+          minimum: 1
+          description: |
+            Fixed-width: column width in characters.  Pair with
+            `startPosition`.
+        start:
+          type: integer
+          description: |
+            Legacy fixed-width start offset (kept for backward
+            compatibility).  Pair with `end`.  Prefer
+            `startPosition` + `length` on new definitions.
+        end:
+          type: integer
+          description: |
+            Legacy fixed-width end offset (kept for backward
+            compatibility).  Pair with `start`.  Prefer
+            `startPosition` + `length` on new definitions.
+    CompositeValue:
+      type: object
+      additionalProperties: true
+      required:
+        - elements
+      description: |
+        Composite-element value: an EDI element whose value is itself a
+        delimited list of sub-elements.  Used for EDIFACT composites
+        (e.g. `UNH02` = message identifier `S009`, `DTM01` =
+        date/time/period `C507`) and X12 composites split by the
+        component element separator.
+
+        The parser joins / splits the nested `elements` using
+        `delimiter` (falling back to the file-level
+        `delimited.compositeDelimiter` when omitted).  Sub-elements
+        follow the same `Element` shape as top-level segment elements —
+        typically just `name` + `value` pairs.
+      properties:
+        delimiter:
+          type: string
+          description: |
+            Component separator used between the composite's
+            sub-elements, e.g. `":"` (EDIFACT default) or `">"` /
+            `"="` (X12 component separators).  Optional; when omitted
+            the file-level composite delimiter applies.
+          examples:
+            - ':'
+            - '>'
+            - '='
+        elements:
+          type: array
+          description: |
+            Ordered sub-elements of the composite.  Each entry is an
+            `Element` (recursively — composites may nest), though in
+            practice sub-elements carry only `name` and a literal or
+            Handlebars `value`.
+          items:
+            $ref: '#/components/schemas/Element'
+    Rule:
+      type: object
+      additionalProperties: true
+      description: |
+        A single node in the recursive rules tree.
+
+        A rule may carry any combination of the following — none are
+        required individually, but every rule needs at least one of
+        `elements` (to extract fields) or `children` (to nest deeper
+        rules) to do anything useful.
+
+        **Node roles**
+
+        - **Leaf rule** — has `elements` (and usually no `children`).
+          Describes a single row / segment by enumerating its fields.
+        - **Branch rule** — has `children` (and optionally `elements`).
+          Used to nest loops / sub-segments.  EDI envelopes always nest
+          their inner segments under `children`.
+        - **Container rule** — sets `container: true`.  Acts as a loop
+          wrapper without producing an output row of its own.  When
+          `container` is true, `maxOccurrence` MUST be greater than
+          `1` (the parser rejects `container: true` with `maxOccurrence
+          <= 1`).
+
+        **Envelopes and `closeRule`**
+
+        EDI envelopes (ISA/IEA, GS/GE, ST/SE, UNB/UNZ, UNG/UNE, UNH/UNT)
+        pair an opening rule with a trailing rule:
+
+        - The opening rule lives in `Rules` / `children`.
+        - The matching trailer lives on the opening rule's `closeRule`.
+
+        `closeRule` accepts both an object (single trailer rule) and a
+        one-element array of trailer rules; the parser treats them
+        equivalently.  In practice the **root** envelope (e.g. IEA / UNZ)
+        is written as an object, and **inner** envelopes (e.g. GE / SE /
+        UNE) are written as a one-element array — both shapes are valid
+        against this schema.
+
+        **Additional properties**
+
+        Vendor / runtime extensions (`description`, Celigo-internal
+        flags) flow through unchanged.  Consumers should pass unknown
+        keys back on round-trip rather than dropping them.
+      properties:
+        name:
+          type: string
+          description: |
+            Optional human-readable identifier for the node.  EDI rules use
+            the segment name (`ST`, `GS`); delimited rules typically
+            omit `name` on the root rule.
+          examples:
+            - ST
+            - ISA
+            - OrderHeader
+        elements:
+          type: array
+          description: |
+            Field-level definitions extracted from this rule's row /
+            segment.  See `Element` for the per-field shape.
+
+            EDI segment rules conventionally include a "self" element with
+            `name` and `value` set to the segment id (e.g.
+            `{"name": "ISA", "value": "ISA"}`) followed by one element
+            per segment-element (`ISA01`, `ISA02`, ...).  Delimited
+            rules use one element per column.
+          items:
+            $ref: '#/components/schemas/Element'
+        children:
+          type: array
+          description: |
+            Nested rules.  Used to build EDI envelope → group →
+            transaction → segment trees, or to model repeating
+            sub-segments / loops on any format.
+
+            Recursive: every child is itself a `Rule` (with the same
+            `elements` / `children` / `closeRule` capabilities).
+          items:
+            $ref: '#/components/schemas/Rule'
+        closeRule:
+          description: |
+            Trailer rule that closes the loop / envelope this rule opens.
+
+            Accepts either:
+            - A single `Rule` object (typical at the file root, e.g.
+              IEA / UNZ).
+            - A one-element array of `Rule` objects (typical for inner
+              envelopes, e.g. GE / SE / UNE).
+
+            Both shapes are accepted by the parser; tooling that
+            round-trips file definitions should preserve whichever shape
+            the source document uses.
+
+            For non-EDI / non-loop rules `closeRule` is omitted.
+          oneOf:
+            - title: rule
+              $ref: '#/components/schemas/Rule'
+            - title: array
+              type: array
+              items:
+                $ref: '#/components/schemas/Rule'
+        container:
+          type: boolean
+          description: |
+            Marks this rule as a pure loop wrapper that does not emit a
+            row of its own.  Used on EDI `ST` / `UNH` containers so
+            the parser knows to iterate the inner transaction body up to
+            `maxOccurrence` times without recording the wrapper itself.
+
+            When `container: true` is set, `maxOccurrence` MUST be
+            greater than `1`.  The parser rejects
+            `container: true` paired with `maxOccurrence <= 1` with
+            `Invalid rules: maxOccurences should be greater than '1',
+            when the container is 'true'`.
+          default: false
+          examples:
+            - true
+            - false
+        maxOccurrence:
+          type: integer
+          minimum: 1
+          description: |
+            Upper bound on how many times this rule may repeat at its
+            current position.  EDI envelopes typically use `1` (one
+            ISA per file, one GS per group), while transaction-set
+            loops (`ST` containers, line-item loops) use larger
+            values such as `1000`.
+
+            Required to be greater than `1` when `container` is
+            `true`.
+          examples:
+            - 1
+            - 1000
+        required:
+          type: boolean
+          description: |
+            Whether this rule must be present in the parsed file.  When
+            true and the rule does not match, the parser raises a
+            validation error.  EDI envelope segments (ISA/GS/ST) are
+            always required; optional summary segments are not.
+          examples:
+            - true
+            - false
+        skipRowSuffix:
+          type: boolean
+          description: |
+            Suppresses emission of `delimited.rowSuffix` after this
+            rule's row during generation.  Used on EDI envelope segments
+            (ISA / GS / ST) where the segment terminator is part of the
+            following row's prefix rather than this row's suffix.
+          default: false
+        description:
+          type: string
+          description: |
+            Free-text annotation surfaced in the file-definition editor.
+            No functional impact on parsing.
+        relativeDataPath:
+          type: string
+          description: |
+            JSON path (relative to the parent rule's record context) that
+            this rule's loop iterates over during generation, or that
+            parsed rows are written to during parsing.  Set on repeating
+            rules — line-item loops, N1 address loops, ST transaction
+            containers (e.g. `"Items"`, `"N1"`, `"ST"`).  Omitted on
+            single-occurrence rules.
+          examples:
+            - Items
+            - N1
+            - ST
+        relationship:
+          type: array
+          items:
+            type: string
+          description: |
+            X12 / EDIFACT syntax-note (element relationship) codes for
+            this rule's segment.  Each entry is a condition code followed
+            by the element positions it binds, comma-separated:
+
+            - `C` — conditional: if the first listed element is present,
+              the rest are required (`"C,06,07"`).
+            - `P` — paired: all listed elements must appear together or
+              not at all (`"P,04,05"`).
+            - `R` — required: at least one of the listed elements must be
+              present (`"R,02,03"`).
+            - `E` — exclusion: at most one of the listed elements may be
+              present (`"E,02,07"`).
+            - `L` — list conditional: if the first element is present, at
+              least one of the rest is required (`"L,03,04,05"`).
+
+            Always an array of these code strings (never a plain string).
+            Pass through unchanged when round-tripping; the parser applies
+            the conditions during EDI validation.
+          examples:
+            - - C,06,07
+              - P,04,05
+            - - L,03,04,05,13
+              - R,02,03
+    FileDefinitionBase:
+      type: object
+      description: Writable file definition fields shared by the request and response schemas.
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+          description: |
+            Human-readable name for the file definition.
+          examples:
+            - Invoice EDI 810
+            - Customer CSV Import
+            - Fixed-Width Payment File
+        description:
+          type: string
+          maxLength: 10240
+          description: |
+            Optional detailed description of the file definition's purpose and format.
+          examples:
+            - Defines the structure for parsing incoming EDI 810 invoice documents
+        version:
+          type: string
+          enum:
+            - '1'
+            - '2'
+          x-enumDescriptions:
+            '1': Original file definition schema version.
+            '2': Updated file definition schema version with breaking changes.
+          description: |
+            Schema version of the file definition. Only incremented for breaking changes.
+          examples:
+            - '1'
+            - '2'
+        format:
+          type: string
+          description: The file format this definition describes.
+          enum:
+            - delimited
+            - delimited/x12
+            - delimited/edifact
+            - fixed
+          x-enumDescriptions:
+            delimited: Standard delimited files (CSV, TSV, etc.).
+            delimited/x12: EDI X12 format. Requires `globalId` when EDI license is enabled.
+            delimited/edifact: EDI EDIFACT format. Requires `globalId` when EDI license is enabled.
+            fixed: Fixed-width positional format.
+        documentType:
+          type: string
+          enum:
+            - '997'
+            - CONTRL
+          x-enumDescriptions:
+            '997': X12 functional acknowledgement document type.
+            CONTRL: EDIFACT functional acknowledgement document type.
+          description: EDI document type for acknowledgement documents.
+        globalId:
+          type: string
+          description: |
+            Global identifier mapping to a known EDI standard document definition.
+
+            Required for EDI formats (`delimited/x12` or `delimited/edifact`) when the
+            account has an EDI license enabled. Must reference a valid entry in the
+            standard file definitions metadata. Immutable after creation.
+          examples:
+            - 3c7a8f2e-1234-5678-9abc-def012345678
+        rules:
+          type: array
+          description: |
+            Ordered array of recursive parsing/generation `Rule` nodes that
+            describe the file's structure — segments, elements, loops, and
+            their relationships. The array shape is the same for every
+            `format` (delimited, EDI X12/EDIFACT, and fixed-width): the first
+            element is the file's root rule, EDI envelopes nest through
+            `Rule.children`, and openers pair with trailers via
+            `Rule.closeRule`. Fixed-width rules carry the column offsets on
+            each element (`startPosition`/`length`).
+
+            The cleared / "no rules configured" form is an empty array `[]`.
+            The serialized rules tree must not exceed 20 KB once attached to
+            the parent file definition document.
+          items:
+            $ref: '#/components/schemas/Rule'
+        fixed:
+          type: object
+          description: |
+            Configuration specific to fixed-width format files.
+
+            Used when `format` is "fixed".
+          properties:
+            rowSuffix:
+              type: string
+              description: |
+                Character(s) appended after each row during generation.
+              examples:
+                - \n
+                - \r\n
+            rowDelimiter:
+              type: string
+              description: |
+                Character(s) used to delimit rows during parsing.
+              examples:
+                - \n
+                - \r\n
+            paddingChar:
+              type: string
+              description: |
+                Character used to pad fixed-width fields to their required length.
+              examples:
+                - ' '
+                - '0'
+        delimited:
+          type: object
+          description: |
+            Configuration specific to delimited format files (CSV, EDI, etc.).
+
+            Used when `format` starts with "delimited".
+          properties:
+            rowSuffix:
+              type: string
+              description: |
+                Character(s) appended after each row during generation.
+              examples:
+                - \n
+                - \r\n
+            rowDelimiter:
+              type: string
+              description: |
+                Character(s) used to delimit rows during parsing.
+              examples:
+                - \n
+                - ~\n
+            colDelimiter:
+              type: string
+              description: |
+                Character(s) used to delimit columns/fields within a row.
+              examples:
+                - ','
+                - \t
+                - '*'
+                - '|'
+            compositeDelimiter:
+              type: string
+              description: |
+                Character(s) used to delimit composite elements within a field.
+                Primarily used in EDI formats.
+              examples:
+                - ':'
+                - '>'
+        strict:
+          type: boolean
+          description: |
+            Whether to fail on all validation errors.
+
+            Reserved for future use.
+        skipEmptyEndColDelimiter:
+          type: boolean
+          description: |
+            Whether to skip trailing empty column delimiters at the end of rows.
+        skipIntermittentEmptyLines:
+          type: boolean
+          description: |
+            Whether to remove empty rows found in the file content during parsing.
+        escapeReleaseChar:
+          type: boolean
+          description: |
+            Whether to handle escape/release characters in delimited data.
+            Primarily relevant for EDI EDIFACT format.
+        skipEDIValidation:
+          type: boolean
+          description: |
+            Whether to skip EDI structural validation during parsing.
+        skipEDIProfileValidation:
+          type: boolean
+          default: false
+          description: |
+            Whether to skip EDI profile-level validation during parsing.
+        externalId:
+          type: string
+          description: |
+            External identifier for correlating this file definition with an external system.
+          examples:
+            - ext-filedef-12345
+      x-celigo-ai-guidance:
+        - |-
+          Delimited / EDI shape: an ordered list of root ``Rule`` nodes.
+          For non-EDI delimited files this is typically a single-element
+          array carrying one rule whose ``elements`` describe the
+          columns.  For EDI (X12 / EDIFACT) the array still has one root
+          rule, but that rule's ``children`` build the
+          envelope → group → transaction → segment hierarchy.
+        - |-
+          The rules tree describes how the structuredFileParser walks a file
+          row-by-row (delimited / EDI) or by fixed offsets (fixed-width) and
+          extracts named fields and nested loops/segments.
+
+          ## SHAPE — VARIES BY ``format``
+
+          Two valid top-level shapes, selected by the parent file definition's
+          ``format``:
+
+          - **Array of ``Rule``** — used by every delimited variant
+            (``delimited``, ``delimited/x12``, ``delimited/edifact``, etc.).
+            The first element is the file's root rule; for EDI, deeper
+            envelopes nest through ``Rule.children``.
+
+          - **Single ``Rule`` object** — used by ``format: "fixed"`` (fixed-
+            width).  The whole file is described by one rule whose
+            ``elements`` enumerate the columns by ``startPosition`` /
+            ``length``.
+
+          The ``oneOf`` below documents both shapes.  Tooling that consumes
+          this spec to drive UI rendering or generation should branch on
+          ``format`` to decide which arm applies — there is no
+          discriminator field on the rules tree itself.
+
+          ## EMPTY / CLEARED FORM
+
+          A cleared rules tree is ``[]`` for delimited / EDI and ``{}`` for
+          fixed-width.  Both empty forms are accepted by the parser as
+          "no rules configured" and round-trip cleanly through the
+          structuredFileParser.
+    ResourceResponse:
+      type: object
+      description: Response
+      x-celigo-ai-guidance:
+        - Core response fields shared by all Celigo resources
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the resource. Format is a 24-character hexadecimal string.
+          x-celigo-ai-guidance:
+            - |-
+              The _id is used in:
+              - API endpoints that operate on a specific resource (e.g., GET, PUT, DELETE)
+              - References from other resources (e.g., flows that use this resource)
+              - Job history and error tracking
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was created. Set automatically and cannot be modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix).
+          examples:
+            - '2023-04-01T09:15:32Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was last updated. Changes whenever any property is modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+          examples:
+            - '2023-04-15T14:30:15Z'
+        deletedAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was soft-deleted. When null or absent, the resource is active.
+          x-celigo-ai-guidance:
+            - Non-null means the resource is soft-deleted (in the recycle bin) — recoverable within the retention period before permanent removal.
+          examples:
+            - '2023-05-20T11:45:32Z'
+      required:
+        - _id
+    FileDefinition:
+      type: object
+      required:
+        - _id
+        - name
+        - version
+        - format
+        - rules
+        - lastModified
+      description: File definition object as returned by the API.
+      allOf:
+        - $ref: '#/components/schemas/FileDefinitionBase'
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            _templateId:
+              type: string
+              format: objectId
+              readOnly: true
+              x-celigo-refModel: templates
+              description: Template this file definition was created from.
+              examples:
+                - 5f8d43a1b9e5a80011a35f2c
+            _sourceId:
+              type: string
+              format: objectId
+              readOnly: true
+              description: Source identifier for tracking the definition's origin.
+              examples:
+                - 5f8d43a1b9e5a80011a35f2c
+    Request:
+      type: object
+      description: |
+        Request schema for creating or updating a file definition.
+      required:
+        - name
+        - version
+        - format
+        - rules
+      allOf:
+        - $ref: '#/components/schemas/FileDefinitionBase'
+      x-celigo-ai-guidance:
+        - |-
+          File definitions describe the structure and parsing/generation rules for
+          structured file formats including delimited (CSV), fixed-width, EDI X12,
+          and EDI EDIFACT.
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    DependencyEntry:
+      type: object
+      description: A single resource that depends on the queried resource.
+      properties:
+        id:
+          type: string
+          description: Unique identifier of the dependent resource.
+          examples:
+            - 61f92026dd053843b5d72350
+        name:
+          type: string
+          description: Display name of the dependent resource.
+          examples:
+            - Import Orders to NetSuite
+        paths:
+          type: array
+          description: |-
+            Dot-notation paths within the dependent resource that reference
+            the target resource. `[*]` denotes array elements.
+          items:
+            type: string
+          examples:
+            - - hooks.preSavePage._scriptId
+        accessLevel:
+          type: string
+          description: The caller's access level on the dependent resource.
+          examples:
+            - manage
+        dependencyIds:
+          type: object
+          description: |-
+            Map of resource types to arrays of IDs that this dependent
+            resource references on the target. Keys are singular or plural
+            resource type strings; values are arrays of ID strings.
+          additionalProperties:
+            type: array
+            items:
+              type: string
+          example:
+            script:
+              - 64ff4b21612a134bd2f45531
+      required:
+        - id
+        - name
+        - paths
+        - accessLevel
+        - dependencyIds
+    DependencyResponse:
+      type: object
+      description: |
+        Map of dependent-resource types to arrays of dependency entries.
+        Keys are plural resource type strings (e.g. `flows`, `imports`,
+        `connections`). An empty object `{}` means no dependents.
+      additionalProperties:
+        type: array
+        items:
+          $ref: '#/components/schemas/DependencyEntry'
+      example:
+        exports:
+          - id: 64ff4b21612a134bd2f45534
+            name: Bank FTP Export
+            paths:
+              - hooks.preSavePage._scriptId
+            accessLevel: manage
+            dependencyIds:
+              script:
+                - 64ff4b21612a134bd2f45531
+        flows:
+          - id: 64ff4b22612a134bd2f45538
+            name: CAMT-053 to Celigo CAM Format
+            paths:
+              - pageGenerators[*]._exportId
+            accessLevel: manage
+            dependencyIds:
+              export:
+                - 64ff4b21612a134bd2f45534
+  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
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+x-enable-proxy: true
+x-internal: false