> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/api/api-reference/file-definitions.md). # File Definitions 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 ## The FileDefinition object ```json {"openapi":"3.2.0","info":{"title":"File Definitions","version":"1.0.0"},"components":{"schemas":{"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,"description":"Template this file definition was created from."},"_sourceId":{"type":"string","format":"objectId","readOnly":true,"description":"Source identifier for tracking the definition's origin."}}}]},"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.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional detailed description of the file definition's purpose and format.\n"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition. Only incremented for breaking changes.\n"},"format":{"type":"string","description":"The file format this definition describes.","enum":["delimited","delimited/x12","delimited/edifact","fixed"]},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents."},"globalId":{"type":"string","description":"Global identifier mapping to a known EDI standard document definition.\n\nRequired for EDI formats (`delimited/x12` or `delimited/edifact`) when the\naccount has an EDI license enabled. Must reference a valid entry in the\nstandard file definitions metadata. Immutable after creation.\n"},"rules":{"type":"array","description":"Ordered array of recursive parsing/generation `Rule` nodes that\ndescribe the file's structure — segments, elements, loops, and\ntheir relationships. The array shape is the same for every\n`format` (delimited, EDI X12/EDIFACT, and fixed-width): the first\nelement is the file's root rule, EDI envelopes nest through\n`Rule.children`, and openers pair with trailers via\n`Rule.closeRule`. Fixed-width rules carry the column offsets on\neach element (`startPosition`/`length`).\n\nThe cleared / \"no rules configured\" form is an empty array `[]`.\nThe serialized rules tree must not exceed 20 KB once attached to\nthe parent file definition document.\n","items":{"$ref":"#/components/schemas/Rule"}},"fixed":{"type":"object","description":"Configuration specific to fixed-width format files.\n\nUsed when `format` is \"fixed\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"paddingChar":{"type":"string","description":"Character used to pad fixed-width fields to their required length.\n"}}},"delimited":{"type":"object","description":"Configuration specific to delimited format files (CSV, EDI, etc.).\n\nUsed when `format` starts with \"delimited\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"colDelimiter":{"type":"string","description":"Character(s) used to delimit columns/fields within a row.\n"},"compositeDelimiter":{"type":"string","description":"Character(s) used to delimit composite elements within a field.\nPrimarily used in EDI formats.\n"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors.\n\nReserved for future use.\n"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters at the end of rows.\n"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows found in the file content during parsing.\n"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters in delimited data.\nPrimarily relevant for EDI EDIFACT format.\n"},"skipEDIValidation":{"type":"boolean","description":"Whether to skip EDI structural validation during parsing.\n"},"skipEDIProfileValidation":{"type":"boolean","default":false,"description":"Whether to skip EDI profile-level validation during parsing.\n"},"externalId":{"type":"string","description":"External identifier for correlating this file definition with an external system.\n"}}},"Rule":{"type":"object","additionalProperties":true,"description":"A single node in the recursive rules tree.\n\nA rule may carry any combination of the following — none are\nrequired individually, but every rule needs at least one of\n`elements` (to extract fields) or `children` (to nest deeper\nrules) to do anything useful.\n\n**Node roles**\n\n- **Leaf rule** — has `elements` (and usually no `children`).\n Describes a single row / segment by enumerating its fields.\n- **Branch rule** — has `children` (and optionally `elements`).\n Used to nest loops / sub-segments. EDI envelopes always nest\n their inner segments under `children`.\n- **Container rule** — sets `container: true`. Acts as a loop\n wrapper without producing an output row of its own. When\n `container` is true, `maxOccurrence` MUST be greater than\n `1` (the parser rejects `container: true` with `maxOccurrence\n <= 1`).\n\n**Envelopes and `closeRule`**\n\nEDI envelopes (ISA/IEA, GS/GE, ST/SE, UNB/UNZ, UNG/UNE, UNH/UNT)\npair an opening rule with a trailing rule:\n\n- The opening rule lives in `Rules` / `children`.\n- The matching trailer lives on the opening rule's `closeRule`.\n\n`closeRule` accepts both an object (single trailer rule) and a\none-element array of trailer rules; the parser treats them\nequivalently. In practice the **root** envelope (e.g. IEA / UNZ)\nis written as an object, and **inner** envelopes (e.g. GE / SE /\nUNE) are written as a one-element array — both shapes are valid\nagainst this schema.\n\n**Additional properties**\n\nVendor / runtime extensions (`description`, Celigo-internal\nflags) flow through unchanged. Consumers should pass unknown\nkeys back on round-trip rather than dropping them.\n","properties":{"name":{"type":"string","description":"Optional human-readable identifier for the node. EDI rules use\nthe segment name (`ST`, `GS`); delimited rules typically\nomit `name` on the root rule.\n"},"elements":{"type":"array","description":"Field-level definitions extracted from this rule's row /\nsegment. See `Element` for the per-field shape.\n\nEDI segment rules conventionally include a \"self\" element with\n`name` and `value` set to the segment id (e.g.\n`{\"name\": \"ISA\", \"value\": \"ISA\"}`) followed by one element\nper segment-element (`ISA01`, `ISA02`, ...). Delimited\nrules use one element per column.\n","items":{"$ref":"#/components/schemas/Element"}},"children":{"type":"array","description":"Nested rules. Used to build EDI envelope → group →\ntransaction → segment trees, or to model repeating\nsub-segments / loops on any format.\n\nRecursive: every child is itself a `Rule` (with the same\n`elements` / `children` / `closeRule` capabilities).\n","items":{"$ref":"#/components/schemas/Rule"}},"closeRule":{"description":"Trailer rule that closes the loop / envelope this rule opens.\n\nAccepts either:\n- A single `Rule` object (typical at the file root, e.g.\n IEA / UNZ).\n- A one-element array of `Rule` objects (typical for inner\n envelopes, e.g. GE / SE / UNE).\n\nBoth shapes are accepted by the parser; tooling that\nround-trips file definitions should preserve whichever shape\nthe source document uses.\n\nFor non-EDI / non-loop rules `closeRule` is omitted.\n","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\nrow of its own. Used on EDI `ST` / `UNH` containers so\nthe parser knows to iterate the inner transaction body up to\n`maxOccurrence` times without recording the wrapper itself.\n\nWhen `container: true` is set, `maxOccurrence` MUST be\ngreater than `1`. The parser rejects\n`container: true` paired with `maxOccurrence <= 1` with\n`Invalid rules: maxOccurences should be greater than '1',\nwhen the container is 'true'`.\n","default":false},"maxOccurrence":{"type":"integer","minimum":1,"description":"Upper bound on how many times this rule may repeat at its\ncurrent position. EDI envelopes typically use `1` (one\nISA per file, one GS per group), while transaction-set\nloops (`ST` containers, line-item loops) use larger\nvalues such as `1000`.\n\nRequired to be greater than `1` when `container` is\n`true`.\n"},"required":{"type":"boolean","description":"Whether this rule must be present in the parsed file. When\ntrue and the rule does not match, the parser raises a\nvalidation error. EDI envelope segments (ISA/GS/ST) are\nalways required; optional summary segments are not.\n"},"skipRowSuffix":{"type":"boolean","description":"Suppresses emission of `delimited.rowSuffix` after this\nrule's row during generation. Used on EDI envelope segments\n(ISA / GS / ST) where the segment terminator is part of the\nfollowing row's prefix rather than this row's suffix.\n","default":false},"description":{"type":"string","description":"Free-text annotation surfaced in the file-definition editor.\nNo functional impact on parsing.\n"},"relativeDataPath":{"type":"string","description":"JSON path (relative to the parent rule's record context) that\nthis rule's loop iterates over during generation, or that\nparsed rows are written to during parsing. Set on repeating\nrules — line-item loops, N1 address loops, ST transaction\ncontainers (e.g. `\"Items\"`, `\"N1\"`, `\"ST\"`). Omitted on\nsingle-occurrence rules.\n"},"relationship":{"type":"array","items":{"type":"string"},"description":"X12 / EDIFACT syntax-note (element relationship) codes for\nthis rule's segment. Each entry is a condition code followed\nby the element positions it binds, comma-separated:\n\n- `C` — conditional: if the first listed element is present,\n the rest are required (`\"C,06,07\"`).\n- `P` — paired: all listed elements must appear together or\n not at all (`\"P,04,05\"`).\n- `R` — required: at least one of the listed elements must be\n present (`\"R,02,03\"`).\n- `E` — exclusion: at most one of the listed elements may be\n present (`\"E,02,07\"`).\n- `L` — list conditional: if the first element is present, at\n least one of the rest is required (`\"L,03,04,05\"`).\n\nAlways an array of these code strings (never a plain string).\nPass through unchanged when round-tripping; the parser applies\nthe conditions during EDI validation.\n"}}},"Element":{"type":"object","additionalProperties":true,"description":"A single field / segment-element entry inside a `Rule.elements`\nlist.\n\n**Format-specific usage**\n\n- **Delimited (CSV / TSV)** — one element per column. `name` is\n the human label; `value` is the column id used to address the\n field downstream (e.g. `orderId`, `customerName`).\n- **Fixed-width** — adds `startPosition` + `length` (or the\n legacy `start` / `end` pair) to describe the column's offset\n within each row.\n- **EDI X12 / EDIFACT** — element values follow the segmentNN\n convention (`ISA01`, `BEG03`, `UNB02`). Segment-element\n definitions whose value comes from the trading-partner profile\n use `referenceValue` to bind a Handlebars template such as\n `{{{ediProfile.isa01}}}` — the runtime fills the value from\n the profile at parse / generate time.\n\n**Required fields**\n\n`name` is required on every element. `value` is optional: in\nthe canonical delimited row pattern, only the first element of a\nrule (the row-type marker) carries `value`; subsequent data\ncolumns use `name` only and are read by position. When\n`value` is set it must be non-empty — the parser uses it as a\nliteral match requirement (`ISA01`, `BEG03`, or the marker\nstring).\n","required":["name"],"properties":{"name":{"type":"string","description":"Human-readable label or segment-element identifier. For EDI,\ndescriptive text such as `Authorization Information\nQualifier`; for delimited data columns, the output key (the\nparser uses `name` as the field key in each parsed\nrecord); for the row-type marker, equals `value`.\n"},"value":{"description":"Machine identifier, row-type matcher, or composite-element\ndefinition. Accepts either:\n\n- A **string** — EDI elements use it as the segment-element\n identifier (`ISA01`, `BEG03`). In the canonical\n delimited row pattern, only the first element of the row's\n rule carries `value` — acting as the literal row-type\n marker the parser matches against column 0 of every row\n (e.g. `A`, `HDR`, `02`). Subsequent data columns omit\n `value` entirely. When present must be non-empty.\n- A **composite object** — EDI composite elements (an element\n whose value is itself a delimited list of sub-elements,\n e.g. EDIFACT `UNH02` = `S009` or X12 composites split by\n the component separator) set `value` to an object with a\n `delimiter` and nested `elements`. See `CompositeValue`.\n","oneOf":[{"title":"literal","type":"string"},{"title":"composite","$ref":"#/components/schemas/CompositeValue"}]},"type":{"type":"string","enum":["string","number","decimal","boolean"],"description":"Type coercion applied to the parsed value before it reaches\ndownstream mapping / output. Defaults to string when omitted.\nEDI numeric segments (control numbers, dates) typically set\n`type: number`; decimal-valued EDI elements (monetary\namounts, quantities) use `type: decimal`.\n"},"required":{"type":"boolean","default":false,"description":"Whether the parser should fail when this element is missing\nor blank. Defaults to false. EDI envelope qualifiers and\ntransaction header fields (ISA/GS/ST elements) are\nconventionally marked required.\n"},"minLength":{"type":"integer","minimum":0,"description":"Inclusive minimum string length. Used heavily on EDI\nelements where the X12 / EDIFACT standard fixes the length\nof envelope qualifiers (e.g. `ISA05` is exactly 2 chars,\n`ISA13` is exactly 9 chars).\n"},"maxLength":{"type":"integer","minimum":0,"description":"Inclusive maximum string length. See `minLength` for\nusage notes.\n"},"referenceValue":{"type":"string","description":"Handlebars template that resolves to the element's value at\nruntime instead of being read from the file. Most common use\nis binding EDI envelope fields to the trading-partner\nprofile, e.g. `{{{ediProfile.isa01}}}` or\n`{{{ediProfile.tpInterchangeId}}}`.\n\nThe linked EDI profile's fields resolve under\n`ediProfile.*`. X12 profiles: `isa01`, `isa02`, `isa03`,\n`isa04`, `tpIdQualifier`, `tpInterchangeId`, `myIdQualifier`,\n`myInterchangeId`, `isa11`, `isa12`, `isa14`, `isa15`,\n`isa16`, `tpGroupId`, `myGroupId`, `gs07`, `gs08`. EDIFACT\nprofiles: `unb010_0001`, `unb010_0002`, `tpIdQualifier`,\n`myIdQualifier`, `tpInterchangeId`, `myInterchangeId`,\n`versionNumber`, `releaseNumber`, `controllingAgency`. Both\nstandards also expose the profile's `name`, `description`,\n`fileType`, and `controlNumber` (the rolling interchange\ncontrol number — for generate-direction control-number\npositions such as ISA13). There are no `isa05`–`isa08`\nkeys: the sender/receiver qualifier and ID positions bind to\n`tpIdQualifier` / `tpInterchangeId` / `myIdQualifier` /\n`myInterchangeId` (`tp*` is the trading partner's identity,\n`my*` is yours — which pair lands in ISA05/06 vs ISA07/08\ndepends on who sends the document). Field meanings are\ndocumented in the EDI Profiles spec.\n\nUse triple-stash (`{{{...}}}`) to avoid HTML escaping for\nEDI control characters.\n"},"enum":{"type":"array","items":{"type":"string"},"description":"Enumerated set of allowed values. Used to enforce EDI code\nlists (e.g. BEG01 purpose codes `[\"00\", \"06\", \"22\"]`,\nBEG02 type codes `[\"PR\", \"RL\", \"SA\", \"ZZ\"]`). When set,\nthe parser rejects values outside the list.\n"},"description":{"type":"string","description":"Free-text annotation surfaced in the file-definition editor.\nNo functional impact on parsing.\n"},"tally":{"type":"boolean","description":"Marks this element's parsed value as a running tally that the\ngenerator accumulates across loop iterations. The\naccumulated total is referenced from trailer segments via the\n`{{_tally.[Element Name]}}` Handlebars helper (e.g. W04\n\"Number of Units Shipped\" tallied into the W03 total).\n"},"counter":{"type":"boolean","description":"Marks this element as an auto-incrementing counter the\ngenerator fills per emitted row / iteration (e.g. LX\nassigned numbers, HL hierarchical ids).\n"},"startPosition":{"type":"integer","minimum":1,"description":"Fixed-width: 1-based start column (inclusive). Pair with\n`length` to describe the column extent. Mutually exclusive\nwith the legacy `start` / `end` pair — pick one\nconvention per element.\n"},"length":{"type":"integer","minimum":1,"description":"Fixed-width: column width in characters. Pair with\n`startPosition`.\n"},"start":{"type":"integer","description":"Legacy fixed-width start offset (kept for backward\ncompatibility). Pair with `end`. Prefer\n`startPosition` + `length` on new definitions.\n"},"end":{"type":"integer","description":"Legacy fixed-width end offset (kept for backward\ncompatibility). Pair with `start`. Prefer\n`startPosition` + `length` on new definitions.\n"}}},"CompositeValue":{"type":"object","additionalProperties":true,"required":["elements"],"description":"Composite-element value: an EDI element whose value is itself a\ndelimited list of sub-elements. Used for EDIFACT composites\n(e.g. `UNH02` = message identifier `S009`, `DTM01` =\ndate/time/period `C507`) and X12 composites split by the\ncomponent element separator.\n\nThe parser joins / splits the nested `elements` using\n`delimiter` (falling back to the file-level\n`delimited.compositeDelimiter` when omitted). Sub-elements\nfollow the same `Element` shape as top-level segment elements —\ntypically just `name` + `value` pairs.\n","properties":{"delimiter":{"type":"string","description":"Component separator used between the composite's\nsub-elements, e.g. `\":\"` (EDIFACT default) or `\">\"` /\n`\"=\"` (X12 component separators). Optional; when omitted\nthe file-level composite delimiter applies.\n"},"elements":{"type":"array","description":"Ordered sub-elements of the composite. Each entry is an\n`Element` (recursively — composites may nest), though in\npractice sub-elements carry only `name` and a literal or\nHandlebars `value`.\n","items":{"$ref":"#/components/schemas/Element"}}}},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"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."}},"required":["_id"]}}}} ``` ## List file definitions > Returns file definitions configured in the account. ```json {"openapi":"3.2.0","info":{"title":"File Definitions","version":"1.0.0"},"tags":[{"name":"File Definitions","description":"File definitions describe the structure and parsing rules for structured files\n(CSV, fixed-width, EDI X12, EDI EDIFACT). Exports and imports that process\nfile-based data reference a file definition to control how rows, columns,\nsegments, and elements are parsed or generated.\n\nFour formats are supported: `delimited` (CSV/TSV), `delimited/x12` (EDI X12),\n`delimited/edifact` (EDI EDIFACT), and `fixed` (fixed-width). EDI formats\nrequire a `globalId` linking to a standard document definition.\n\n## File definition schema\n\n{% openapi-schemas spec=\"filedefinition\" schemas=\"FileDefinition\" grouped=\"true\" %}"}],"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":[]}],"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.\nTriggers summary projection: the response contains a minimal identity\nset (`_id`, `name`, plus resource-specific fields) with the requested\nfields added on top. Supports dot notation for nested fields.\nMutually exclusive with `exclude`.","schema":{"type":"string"}},"Exclude":{"name":"exclude","in":"query","required":false,"description":"Comma-separated list of fields to strip from the default response.\nUnlike `include`, does not trigger summary projection — returns the\nfull record with the named fields removed. Protected identity fields\n(e.g. `name`) cannot be stripped. Mutually exclusive with `include`.","schema":{"type":"string"}}},"schemas":{"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,"description":"Template this file definition was created from."},"_sourceId":{"type":"string","format":"objectId","readOnly":true,"description":"Source identifier for tracking the definition's origin."}}}]},"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.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional detailed description of the file definition's purpose and format.\n"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition. Only incremented for breaking changes.\n"},"format":{"type":"string","description":"The file format this definition describes.","enum":["delimited","delimited/x12","delimited/edifact","fixed"]},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents."},"globalId":{"type":"string","description":"Global identifier mapping to a known EDI standard document definition.\n\nRequired for EDI formats (`delimited/x12` or `delimited/edifact`) when the\naccount has an EDI license enabled. Must reference a valid entry in the\nstandard file definitions metadata. Immutable after creation.\n"},"rules":{"type":"array","description":"Ordered array of recursive parsing/generation `Rule` nodes that\ndescribe the file's structure — segments, elements, loops, and\ntheir relationships. The array shape is the same for every\n`format` (delimited, EDI X12/EDIFACT, and fixed-width): the first\nelement is the file's root rule, EDI envelopes nest through\n`Rule.children`, and openers pair with trailers via\n`Rule.closeRule`. Fixed-width rules carry the column offsets on\neach element (`startPosition`/`length`).\n\nThe cleared / \"no rules configured\" form is an empty array `[]`.\nThe serialized rules tree must not exceed 20 KB once attached to\nthe parent file definition document.\n","items":{"$ref":"#/components/schemas/Rule"}},"fixed":{"type":"object","description":"Configuration specific to fixed-width format files.\n\nUsed when `format` is \"fixed\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"paddingChar":{"type":"string","description":"Character used to pad fixed-width fields to their required length.\n"}}},"delimited":{"type":"object","description":"Configuration specific to delimited format files (CSV, EDI, etc.).\n\nUsed when `format` starts with \"delimited\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"colDelimiter":{"type":"string","description":"Character(s) used to delimit columns/fields within a row.\n"},"compositeDelimiter":{"type":"string","description":"Character(s) used to delimit composite elements within a field.\nPrimarily used in EDI formats.\n"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors.\n\nReserved for future use.\n"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters at the end of rows.\n"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows found in the file content during parsing.\n"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters in delimited data.\nPrimarily relevant for EDI EDIFACT format.\n"},"skipEDIValidation":{"type":"boolean","description":"Whether to skip EDI structural validation during parsing.\n"},"skipEDIProfileValidation":{"type":"boolean","default":false,"description":"Whether to skip EDI profile-level validation during parsing.\n"},"externalId":{"type":"string","description":"External identifier for correlating this file definition with an external system.\n"}}},"Rule":{"type":"object","additionalProperties":true,"description":"A single node in the recursive rules tree.\n\nA rule may carry any combination of the following — none are\nrequired individually, but every rule needs at least one of\n`elements` (to extract fields) or `children` (to nest deeper\nrules) to do anything useful.\n\n**Node roles**\n\n- **Leaf rule** — has `elements` (and usually no `children`).\n Describes a single row / segment by enumerating its fields.\n- **Branch rule** — has `children` (and optionally `elements`).\n Used to nest loops / sub-segments. EDI envelopes always nest\n their inner segments under `children`.\n- **Container rule** — sets `container: true`. Acts as a loop\n wrapper without producing an output row of its own. When\n `container` is true, `maxOccurrence` MUST be greater than\n `1` (the parser rejects `container: true` with `maxOccurrence\n <= 1`).\n\n**Envelopes and `closeRule`**\n\nEDI envelopes (ISA/IEA, GS/GE, ST/SE, UNB/UNZ, UNG/UNE, UNH/UNT)\npair an opening rule with a trailing rule:\n\n- The opening rule lives in `Rules` / `children`.\n- The matching trailer lives on the opening rule's `closeRule`.\n\n`closeRule` accepts both an object (single trailer rule) and a\none-element array of trailer rules; the parser treats them\nequivalently. In practice the **root** envelope (e.g. IEA / UNZ)\nis written as an object, and **inner** envelopes (e.g. GE / SE /\nUNE) are written as a one-element array — both shapes are valid\nagainst this schema.\n\n**Additional properties**\n\nVendor / runtime extensions (`description`, Celigo-internal\nflags) flow through unchanged. Consumers should pass unknown\nkeys back on round-trip rather than dropping them.\n","properties":{"name":{"type":"string","description":"Optional human-readable identifier for the node. EDI rules use\nthe segment name (`ST`, `GS`); delimited rules typically\nomit `name` on the root rule.\n"},"elements":{"type":"array","description":"Field-level definitions extracted from this rule's row /\nsegment. See `Element` for the per-field shape.\n\nEDI segment rules conventionally include a \"self\" element with\n`name` and `value` set to the segment id (e.g.\n`{\"name\": \"ISA\", \"value\": \"ISA\"}`) followed by one element\nper segment-element (`ISA01`, `ISA02`, ...). Delimited\nrules use one element per column.\n","items":{"$ref":"#/components/schemas/Element"}},"children":{"type":"array","description":"Nested rules. Used to build EDI envelope → group →\ntransaction → segment trees, or to model repeating\nsub-segments / loops on any format.\n\nRecursive: every child is itself a `Rule` (with the same\n`elements` / `children` / `closeRule` capabilities).\n","items":{"$ref":"#/components/schemas/Rule"}},"closeRule":{"description":"Trailer rule that closes the loop / envelope this rule opens.\n\nAccepts either:\n- A single `Rule` object (typical at the file root, e.g.\n IEA / UNZ).\n- A one-element array of `Rule` objects (typical for inner\n envelopes, e.g. GE / SE / UNE).\n\nBoth shapes are accepted by the parser; tooling that\nround-trips file definitions should preserve whichever shape\nthe source document uses.\n\nFor non-EDI / non-loop rules `closeRule` is omitted.\n","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\nrow of its own. Used on EDI `ST` / `UNH` containers so\nthe parser knows to iterate the inner transaction body up to\n`maxOccurrence` times without recording the wrapper itself.\n\nWhen `container: true` is set, `maxOccurrence` MUST be\ngreater than `1`. The parser rejects\n`container: true` paired with `maxOccurrence <= 1` with\n`Invalid rules: maxOccurences should be greater than '1',\nwhen the container is 'true'`.\n","default":false},"maxOccurrence":{"type":"integer","minimum":1,"description":"Upper bound on how many times this rule may repeat at its\ncurrent position. EDI envelopes typically use `1` (one\nISA per file, one GS per group), while transaction-set\nloops (`ST` containers, line-item loops) use larger\nvalues such as `1000`.\n\nRequired to be greater than `1` when `container` is\n`true`.\n"},"required":{"type":"boolean","description":"Whether this rule must be present in the parsed file. When\ntrue and the rule does not match, the parser raises a\nvalidation error. EDI envelope segments (ISA/GS/ST) are\nalways required; optional summary segments are not.\n"},"skipRowSuffix":{"type":"boolean","description":"Suppresses emission of `delimited.rowSuffix` after this\nrule's row during generation. Used on EDI envelope segments\n(ISA / GS / ST) where the segment terminator is part of the\nfollowing row's prefix rather than this row's suffix.\n","default":false},"description":{"type":"string","description":"Free-text annotation surfaced in the file-definition editor.\nNo functional impact on parsing.\n"},"relativeDataPath":{"type":"string","description":"JSON path (relative to the parent rule's record context) that\nthis rule's loop iterates over during generation, or that\nparsed rows are written to during parsing. Set on repeating\nrules — line-item loops, N1 address loops, ST transaction\ncontainers (e.g. `\"Items\"`, `\"N1\"`, `\"ST\"`). Omitted on\nsingle-occurrence rules.\n"},"relationship":{"type":"array","items":{"type":"string"},"description":"X12 / EDIFACT syntax-note (element relationship) codes for\nthis rule's segment. Each entry is a condition code followed\nby the element positions it binds, comma-separated:\n\n- `C` — conditional: if the first listed element is present,\n the rest are required (`\"C,06,07\"`).\n- `P` — paired: all listed elements must appear together or\n not at all (`\"P,04,05\"`).\n- `R` — required: at least one of the listed elements must be\n present (`\"R,02,03\"`).\n- `E` — exclusion: at most one of the listed elements may be\n present (`\"E,02,07\"`).\n- `L` — list conditional: if the first element is present, at\n least one of the rest is required (`\"L,03,04,05\"`).\n\nAlways an array of these code strings (never a plain string).\nPass through unchanged when round-tripping; the parser applies\nthe conditions during EDI validation.\n"}}},"Element":{"type":"object","additionalProperties":true,"description":"A single field / segment-element entry inside a `Rule.elements`\nlist.\n\n**Format-specific usage**\n\n- **Delimited (CSV / TSV)** — one element per column. `name` is\n the human label; `value` is the column id used to address the\n field downstream (e.g. `orderId`, `customerName`).\n- **Fixed-width** — adds `startPosition` + `length` (or the\n legacy `start` / `end` pair) to describe the column's offset\n within each row.\n- **EDI X12 / EDIFACT** — element values follow the segmentNN\n convention (`ISA01`, `BEG03`, `UNB02`). Segment-element\n definitions whose value comes from the trading-partner profile\n use `referenceValue` to bind a Handlebars template such as\n `{{{ediProfile.isa01}}}` — the runtime fills the value from\n the profile at parse / generate time.\n\n**Required fields**\n\n`name` is required on every element. `value` is optional: in\nthe canonical delimited row pattern, only the first element of a\nrule (the row-type marker) carries `value`; subsequent data\ncolumns use `name` only and are read by position. When\n`value` is set it must be non-empty — the parser uses it as a\nliteral match requirement (`ISA01`, `BEG03`, or the marker\nstring).\n","required":["name"],"properties":{"name":{"type":"string","description":"Human-readable label or segment-element identifier. For EDI,\ndescriptive text such as `Authorization Information\nQualifier`; for delimited data columns, the output key (the\nparser uses `name` as the field key in each parsed\nrecord); for the row-type marker, equals `value`.\n"},"value":{"description":"Machine identifier, row-type matcher, or composite-element\ndefinition. Accepts either:\n\n- A **string** — EDI elements use it as the segment-element\n identifier (`ISA01`, `BEG03`). In the canonical\n delimited row pattern, only the first element of the row's\n rule carries `value` — acting as the literal row-type\n marker the parser matches against column 0 of every row\n (e.g. `A`, `HDR`, `02`). Subsequent data columns omit\n `value` entirely. When present must be non-empty.\n- A **composite object** — EDI composite elements (an element\n whose value is itself a delimited list of sub-elements,\n e.g. EDIFACT `UNH02` = `S009` or X12 composites split by\n the component separator) set `value` to an object with a\n `delimiter` and nested `elements`. See `CompositeValue`.\n","oneOf":[{"title":"literal","type":"string"},{"title":"composite","$ref":"#/components/schemas/CompositeValue"}]},"type":{"type":"string","enum":["string","number","decimal","boolean"],"description":"Type coercion applied to the parsed value before it reaches\ndownstream mapping / output. Defaults to string when omitted.\nEDI numeric segments (control numbers, dates) typically set\n`type: number`; decimal-valued EDI elements (monetary\namounts, quantities) use `type: decimal`.\n"},"required":{"type":"boolean","default":false,"description":"Whether the parser should fail when this element is missing\nor blank. Defaults to false. EDI envelope qualifiers and\ntransaction header fields (ISA/GS/ST elements) are\nconventionally marked required.\n"},"minLength":{"type":"integer","minimum":0,"description":"Inclusive minimum string length. Used heavily on EDI\nelements where the X12 / EDIFACT standard fixes the length\nof envelope qualifiers (e.g. `ISA05` is exactly 2 chars,\n`ISA13` is exactly 9 chars).\n"},"maxLength":{"type":"integer","minimum":0,"description":"Inclusive maximum string length. See `minLength` for\nusage notes.\n"},"referenceValue":{"type":"string","description":"Handlebars template that resolves to the element's value at\nruntime instead of being read from the file. Most common use\nis binding EDI envelope fields to the trading-partner\nprofile, e.g. `{{{ediProfile.isa01}}}` or\n`{{{ediProfile.tpInterchangeId}}}`.\n\nThe linked EDI profile's fields resolve under\n`ediProfile.*`. X12 profiles: `isa01`, `isa02`, `isa03`,\n`isa04`, `tpIdQualifier`, `tpInterchangeId`, `myIdQualifier`,\n`myInterchangeId`, `isa11`, `isa12`, `isa14`, `isa15`,\n`isa16`, `tpGroupId`, `myGroupId`, `gs07`, `gs08`. EDIFACT\nprofiles: `unb010_0001`, `unb010_0002`, `tpIdQualifier`,\n`myIdQualifier`, `tpInterchangeId`, `myInterchangeId`,\n`versionNumber`, `releaseNumber`, `controllingAgency`. Both\nstandards also expose the profile's `name`, `description`,\n`fileType`, and `controlNumber` (the rolling interchange\ncontrol number — for generate-direction control-number\npositions such as ISA13). There are no `isa05`–`isa08`\nkeys: the sender/receiver qualifier and ID positions bind to\n`tpIdQualifier` / `tpInterchangeId` / `myIdQualifier` /\n`myInterchangeId` (`tp*` is the trading partner's identity,\n`my*` is yours — which pair lands in ISA05/06 vs ISA07/08\ndepends on who sends the document). Field meanings are\ndocumented in the EDI Profiles spec.\n\nUse triple-stash (`{{{...}}}`) to avoid HTML escaping for\nEDI control characters.\n"},"enum":{"type":"array","items":{"type":"string"},"description":"Enumerated set of allowed values. Used to enforce EDI code\nlists (e.g. BEG01 purpose codes `[\"00\", \"06\", \"22\"]`,\nBEG02 type codes `[\"PR\", \"RL\", \"SA\", \"ZZ\"]`). When set,\nthe parser rejects values outside the list.\n"},"description":{"type":"string","description":"Free-text annotation surfaced in the file-definition editor.\nNo functional impact on parsing.\n"},"tally":{"type":"boolean","description":"Marks this element's parsed value as a running tally that the\ngenerator accumulates across loop iterations. The\naccumulated total is referenced from trailer segments via the\n`{{_tally.[Element Name]}}` Handlebars helper (e.g. W04\n\"Number of Units Shipped\" tallied into the W03 total).\n"},"counter":{"type":"boolean","description":"Marks this element as an auto-incrementing counter the\ngenerator fills per emitted row / iteration (e.g. LX\nassigned numbers, HL hierarchical ids).\n"},"startPosition":{"type":"integer","minimum":1,"description":"Fixed-width: 1-based start column (inclusive). Pair with\n`length` to describe the column extent. Mutually exclusive\nwith the legacy `start` / `end` pair — pick one\nconvention per element.\n"},"length":{"type":"integer","minimum":1,"description":"Fixed-width: column width in characters. Pair with\n`startPosition`.\n"},"start":{"type":"integer","description":"Legacy fixed-width start offset (kept for backward\ncompatibility). Pair with `end`. Prefer\n`startPosition` + `length` on new definitions.\n"},"end":{"type":"integer","description":"Legacy fixed-width end offset (kept for backward\ncompatibility). Pair with `start`. Prefer\n`startPosition` + `length` on new definitions.\n"}}},"CompositeValue":{"type":"object","additionalProperties":true,"required":["elements"],"description":"Composite-element value: an EDI element whose value is itself a\ndelimited list of sub-elements. Used for EDIFACT composites\n(e.g. `UNH02` = message identifier `S009`, `DTM01` =\ndate/time/period `C507`) and X12 composites split by the\ncomponent element separator.\n\nThe parser joins / splits the nested `elements` using\n`delimiter` (falling back to the file-level\n`delimited.compositeDelimiter` when omitted). Sub-elements\nfollow the same `Element` shape as top-level segment elements —\ntypically just `name` + `value` pairs.\n","properties":{"delimiter":{"type":"string","description":"Component separator used between the composite's\nsub-elements, e.g. `\":\"` (EDIFACT default) or `\">\"` /\n`\"=\"` (X12 component separators). Optional; when omitted\nthe file-level composite delimiter applies.\n"},"elements":{"type":"array","description":"Ordered sub-elements of the composite. Each entry is an\n`Element` (recursively — composites may nest), though in\npractice sub-elements carry only `name` and a literal or\nHandlebars `value`.\n","items":{"$ref":"#/components/schemas/Element"}}}},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"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."}},"required":["_id"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot 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:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/filedefinitions":{"get":{"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"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of file definitions to return per page.","schema":{"type":"integer","minimum":1,"maximum":1000}}],"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"}}}}},"204":{"description":"No file definitions exist in the account."},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}} ``` ## Create a file definition > Creates a new file definition. ```json {"openapi":"3.2.0","info":{"title":"File Definitions","version":"1.0.0"},"tags":[{"name":"File Definitions","description":"File definitions describe the structure and parsing rules for structured files\n(CSV, fixed-width, EDI X12, EDI EDIFACT). Exports and imports that process\nfile-based data reference a file definition to control how rows, columns,\nsegments, and elements are parsed or generated.\n\nFour formats are supported: `delimited` (CSV/TSV), `delimited/x12` (EDI X12),\n`delimited/edifact` (EDI EDIFACT), and `fixed` (fixed-width). EDI formats\nrequire a `globalId` linking to a standard document definition.\n\n## File definition schema\n\n{% openapi-schemas spec=\"filedefinition\" schemas=\"FileDefinition\" grouped=\"true\" %}"}],"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":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Request schema for creating or updating a file definition.\n","required":["name","version","format","rules"],"allOf":[{"$ref":"#/components/schemas/FileDefinitionBase"}]},"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.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional detailed description of the file definition's purpose and format.\n"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition. Only incremented for breaking changes.\n"},"format":{"type":"string","description":"The file format this definition describes.","enum":["delimited","delimited/x12","delimited/edifact","fixed"]},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents."},"globalId":{"type":"string","description":"Global identifier mapping to a known EDI standard document definition.\n\nRequired for EDI formats (`delimited/x12` or `delimited/edifact`) when the\naccount has an EDI license enabled. Must reference a valid entry in the\nstandard file definitions metadata. Immutable after creation.\n"},"rules":{"type":"array","description":"Ordered array of recursive parsing/generation `Rule` nodes that\ndescribe the file's structure — segments, elements, loops, and\ntheir relationships. The array shape is the same for every\n`format` (delimited, EDI X12/EDIFACT, and fixed-width): the first\nelement is the file's root rule, EDI envelopes nest through\n`Rule.children`, and openers pair with trailers via\n`Rule.closeRule`. Fixed-width rules carry the column offsets on\neach element (`startPosition`/`length`).\n\nThe cleared / \"no rules configured\" form is an empty array `[]`.\nThe serialized rules tree must not exceed 20 KB once attached to\nthe parent file definition document.\n","items":{"$ref":"#/components/schemas/Rule"}},"fixed":{"type":"object","description":"Configuration specific to fixed-width format files.\n\nUsed when `format` is \"fixed\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"paddingChar":{"type":"string","description":"Character used to pad fixed-width fields to their required length.\n"}}},"delimited":{"type":"object","description":"Configuration specific to delimited format files (CSV, EDI, etc.).\n\nUsed when `format` starts with \"delimited\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"colDelimiter":{"type":"string","description":"Character(s) used to delimit columns/fields within a row.\n"},"compositeDelimiter":{"type":"string","description":"Character(s) used to delimit composite elements within a field.\nPrimarily used in EDI formats.\n"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors.\n\nReserved for future use.\n"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters at the end of rows.\n"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows found in the file content during parsing.\n"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters in delimited data.\nPrimarily relevant for EDI EDIFACT format.\n"},"skipEDIValidation":{"type":"boolean","description":"Whether to skip EDI structural validation during parsing.\n"},"skipEDIProfileValidation":{"type":"boolean","default":false,"description":"Whether to skip EDI profile-level validation during parsing.\n"},"externalId":{"type":"string","description":"External identifier for correlating this file definition with an external system.\n"}}},"Rule":{"type":"object","additionalProperties":true,"description":"A single node in the recursive rules tree.\n\nA rule may carry any combination of the following — none are\nrequired individually, but every rule needs at least one of\n`elements` (to extract fields) or `children` (to nest deeper\nrules) to do anything useful.\n\n**Node roles**\n\n- **Leaf rule** — has `elements` (and usually no `children`).\n Describes a single row / segment by enumerating its fields.\n- **Branch rule** — has `children` (and optionally `elements`).\n Used to nest loops / sub-segments. EDI envelopes always nest\n their inner segments under `children`.\n- **Container rule** — sets `container: true`. Acts as a loop\n wrapper without producing an output row of its own. When\n `container` is true, `maxOccurrence` MUST be greater than\n `1` (the parser rejects `container: true` with `maxOccurrence\n <= 1`).\n\n**Envelopes and `closeRule`**\n\nEDI envelopes (ISA/IEA, GS/GE, ST/SE, UNB/UNZ, UNG/UNE, UNH/UNT)\npair an opening rule with a trailing rule:\n\n- The opening rule lives in `Rules` / `children`.\n- The matching trailer lives on the opening rule's `closeRule`.\n\n`closeRule` accepts both an object (single trailer rule) and a\none-element array of trailer rules; the parser treats them\nequivalently. In practice the **root** envelope (e.g. IEA / UNZ)\nis written as an object, and **inner** envelopes (e.g. GE / SE /\nUNE) are written as a one-element array — both shapes are valid\nagainst this schema.\n\n**Additional properties**\n\nVendor / runtime extensions (`description`, Celigo-internal\nflags) flow through unchanged. Consumers should pass unknown\nkeys back on round-trip rather than dropping them.\n","properties":{"name":{"type":"string","description":"Optional human-readable identifier for the node. EDI rules use\nthe segment name (`ST`, `GS`); delimited rules typically\nomit `name` on the root rule.\n"},"elements":{"type":"array","description":"Field-level definitions extracted from this rule's row /\nsegment. See `Element` for the per-field shape.\n\nEDI segment rules conventionally include a \"self\" element with\n`name` and `value` set to the segment id (e.g.\n`{\"name\": \"ISA\", \"value\": \"ISA\"}`) followed by one element\nper segment-element (`ISA01`, `ISA02`, ...). Delimited\nrules use one element per column.\n","items":{"$ref":"#/components/schemas/Element"}},"children":{"type":"array","description":"Nested rules. Used to build EDI envelope → group →\ntransaction → segment trees, or to model repeating\nsub-segments / loops on any format.\n\nRecursive: every child is itself a `Rule` (with the same\n`elements` / `children` / `closeRule` capabilities).\n","items":{"$ref":"#/components/schemas/Rule"}},"closeRule":{"description":"Trailer rule that closes the loop / envelope this rule opens.\n\nAccepts either:\n- A single `Rule` object (typical at the file root, e.g.\n IEA / UNZ).\n- A one-element array of `Rule` objects (typical for inner\n envelopes, e.g. GE / SE / UNE).\n\nBoth shapes are accepted by the parser; tooling that\nround-trips file definitions should preserve whichever shape\nthe source document uses.\n\nFor non-EDI / non-loop rules `closeRule` is omitted.\n","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\nrow of its own. Used on EDI `ST` / `UNH` containers so\nthe parser knows to iterate the inner transaction body up to\n`maxOccurrence` times without recording the wrapper itself.\n\nWhen `container: true` is set, `maxOccurrence` MUST be\ngreater than `1`. The parser rejects\n`container: true` paired with `maxOccurrence <= 1` with\n`Invalid rules: maxOccurences should be greater than '1',\nwhen the container is 'true'`.\n","default":false},"maxOccurrence":{"type":"integer","minimum":1,"description":"Upper bound on how many times this rule may repeat at its\ncurrent position. EDI envelopes typically use `1` (one\nISA per file, one GS per group), while transaction-set\nloops (`ST` containers, line-item loops) use larger\nvalues such as `1000`.\n\nRequired to be greater than `1` when `container` is\n`true`.\n"},"required":{"type":"boolean","description":"Whether this rule must be present in the parsed file. When\ntrue and the rule does not match, the parser raises a\nvalidation error. EDI envelope segments (ISA/GS/ST) are\nalways required; optional summary segments are not.\n"},"skipRowSuffix":{"type":"boolean","description":"Suppresses emission of `delimited.rowSuffix` after this\nrule's row during generation. Used on EDI envelope segments\n(ISA / GS / ST) where the segment terminator is part of the\nfollowing row's prefix rather than this row's suffix.\n","default":false},"description":{"type":"string","description":"Free-text annotation surfaced in the file-definition editor.\nNo functional impact on parsing.\n"},"relativeDataPath":{"type":"string","description":"JSON path (relative to the parent rule's record context) that\nthis rule's loop iterates over during generation, or that\nparsed rows are written to during parsing. Set on repeating\nrules — line-item loops, N1 address loops, ST transaction\ncontainers (e.g. `\"Items\"`, `\"N1\"`, `\"ST\"`). Omitted on\nsingle-occurrence rules.\n"},"relationship":{"type":"array","items":{"type":"string"},"description":"X12 / EDIFACT syntax-note (element relationship) codes for\nthis rule's segment. Each entry is a condition code followed\nby the element positions it binds, comma-separated:\n\n- `C` — conditional: if the first listed element is present,\n the rest are required (`\"C,06,07\"`).\n- `P` — paired: all listed elements must appear together or\n not at all (`\"P,04,05\"`).\n- `R` — required: at least one of the listed elements must be\n present (`\"R,02,03\"`).\n- `E` — exclusion: at most one of the listed elements may be\n present (`\"E,02,07\"`).\n- `L` — list conditional: if the first element is present, at\n least one of the rest is required (`\"L,03,04,05\"`).\n\nAlways an array of these code strings (never a plain string).\nPass through unchanged when round-tripping; the parser applies\nthe conditions during EDI validation.\n"}}},"Element":{"type":"object","additionalProperties":true,"description":"A single field / segment-element entry inside a `Rule.elements`\nlist.\n\n**Format-specific usage**\n\n- **Delimited (CSV / TSV)** — one element per column. `name` is\n the human label; `value` is the column id used to address the\n field downstream (e.g. `orderId`, `customerName`).\n- **Fixed-width** — adds `startPosition` + `length` (or the\n legacy `start` / `end` pair) to describe the column's offset\n within each row.\n- **EDI X12 / EDIFACT** — element values follow the segmentNN\n convention (`ISA01`, `BEG03`, `UNB02`). Segment-element\n definitions whose value comes from the trading-partner profile\n use `referenceValue` to bind a Handlebars template such as\n `{{{ediProfile.isa01}}}` — the runtime fills the value from\n the profile at parse / generate time.\n\n**Required fields**\n\n`name` is required on every element. `value` is optional: in\nthe canonical delimited row pattern, only the first element of a\nrule (the row-type marker) carries `value`; subsequent data\ncolumns use `name` only and are read by position. When\n`value` is set it must be non-empty — the parser uses it as a\nliteral match requirement (`ISA01`, `BEG03`, or the marker\nstring).\n","required":["name"],"properties":{"name":{"type":"string","description":"Human-readable label or segment-element identifier. For EDI,\ndescriptive text such as `Authorization Information\nQualifier`; for delimited data columns, the output key (the\nparser uses `name` as the field key in each parsed\nrecord); for the row-type marker, equals `value`.\n"},"value":{"description":"Machine identifier, row-type matcher, or composite-element\ndefinition. Accepts either:\n\n- A **string** — EDI elements use it as the segment-element\n identifier (`ISA01`, `BEG03`). In the canonical\n delimited row pattern, only the first element of the row's\n rule carries `value` — acting as the literal row-type\n marker the parser matches against column 0 of every row\n (e.g. `A`, `HDR`, `02`). Subsequent data columns omit\n `value` entirely. When present must be non-empty.\n- A **composite object** — EDI composite elements (an element\n whose value is itself a delimited list of sub-elements,\n e.g. EDIFACT `UNH02` = `S009` or X12 composites split by\n the component separator) set `value` to an object with a\n `delimiter` and nested `elements`. See `CompositeValue`.\n","oneOf":[{"title":"literal","type":"string"},{"title":"composite","$ref":"#/components/schemas/CompositeValue"}]},"type":{"type":"string","enum":["string","number","decimal","boolean"],"description":"Type coercion applied to the parsed value before it reaches\ndownstream mapping / output. Defaults to string when omitted.\nEDI numeric segments (control numbers, dates) typically set\n`type: number`; decimal-valued EDI elements (monetary\namounts, quantities) use `type: decimal`.\n"},"required":{"type":"boolean","default":false,"description":"Whether the parser should fail when this element is missing\nor blank. Defaults to false. EDI envelope qualifiers and\ntransaction header fields (ISA/GS/ST elements) are\nconventionally marked required.\n"},"minLength":{"type":"integer","minimum":0,"description":"Inclusive minimum string length. Used heavily on EDI\nelements where the X12 / EDIFACT standard fixes the length\nof envelope qualifiers (e.g. `ISA05` is exactly 2 chars,\n`ISA13` is exactly 9 chars).\n"},"maxLength":{"type":"integer","minimum":0,"description":"Inclusive maximum string length. See `minLength` for\nusage notes.\n"},"referenceValue":{"type":"string","description":"Handlebars template that resolves to the element's value at\nruntime instead of being read from the file. Most common use\nis binding EDI envelope fields to the trading-partner\nprofile, e.g. `{{{ediProfile.isa01}}}` or\n`{{{ediProfile.tpInterchangeId}}}`.\n\nThe linked EDI profile's fields resolve under\n`ediProfile.*`. X12 profiles: `isa01`, `isa02`, `isa03`,\n`isa04`, `tpIdQualifier`, `tpInterchangeId`, `myIdQualifier`,\n`myInterchangeId`, `isa11`, `isa12`, `isa14`, `isa15`,\n`isa16`, `tpGroupId`, `myGroupId`, `gs07`, `gs08`. EDIFACT\nprofiles: `unb010_0001`, `unb010_0002`, `tpIdQualifier`,\n`myIdQualifier`, `tpInterchangeId`, `myInterchangeId`,\n`versionNumber`, `releaseNumber`, `controllingAgency`. Both\nstandards also expose the profile's `name`, `description`,\n`fileType`, and `controlNumber` (the rolling interchange\ncontrol number — for generate-direction control-number\npositions such as ISA13). There are no `isa05`–`isa08`\nkeys: the sender/receiver qualifier and ID positions bind to\n`tpIdQualifier` / `tpInterchangeId` / `myIdQualifier` /\n`myInterchangeId` (`tp*` is the trading partner's identity,\n`my*` is yours — which pair lands in ISA05/06 vs ISA07/08\ndepends on who sends the document). Field meanings are\ndocumented in the EDI Profiles spec.\n\nUse triple-stash (`{{{...}}}`) to avoid HTML escaping for\nEDI control characters.\n"},"enum":{"type":"array","items":{"type":"string"},"description":"Enumerated set of allowed values. Used to enforce EDI code\nlists (e.g. BEG01 purpose codes `[\"00\", \"06\", \"22\"]`,\nBEG02 type codes `[\"PR\", \"RL\", \"SA\", \"ZZ\"]`). When set,\nthe parser rejects values outside the list.\n"},"description":{"type":"string","description":"Free-text annotation surfaced in the file-definition editor.\nNo functional impact on parsing.\n"},"tally":{"type":"boolean","description":"Marks this element's parsed value as a running tally that the\ngenerator accumulates across loop iterations. The\naccumulated total is referenced from trailer segments via the\n`{{_tally.[Element Name]}}` Handlebars helper (e.g. W04\n\"Number of Units Shipped\" tallied into the W03 total).\n"},"counter":{"type":"boolean","description":"Marks this element as an auto-incrementing counter the\ngenerator fills per emitted row / iteration (e.g. LX\nassigned numbers, HL hierarchical ids).\n"},"startPosition":{"type":"integer","minimum":1,"description":"Fixed-width: 1-based start column (inclusive). Pair with\n`length` to describe the column extent. Mutually exclusive\nwith the legacy `start` / `end` pair — pick one\nconvention per element.\n"},"length":{"type":"integer","minimum":1,"description":"Fixed-width: column width in characters. Pair with\n`startPosition`.\n"},"start":{"type":"integer","description":"Legacy fixed-width start offset (kept for backward\ncompatibility). Pair with `end`. Prefer\n`startPosition` + `length` on new definitions.\n"},"end":{"type":"integer","description":"Legacy fixed-width end offset (kept for backward\ncompatibility). Pair with `start`. Prefer\n`startPosition` + `length` on new definitions.\n"}}},"CompositeValue":{"type":"object","additionalProperties":true,"required":["elements"],"description":"Composite-element value: an EDI element whose value is itself a\ndelimited list of sub-elements. Used for EDIFACT composites\n(e.g. `UNH02` = message identifier `S009`, `DTM01` =\ndate/time/period `C507`) and X12 composites split by the\ncomponent element separator.\n\nThe parser joins / splits the nested `elements` using\n`delimiter` (falling back to the file-level\n`delimited.compositeDelimiter` when omitted). Sub-elements\nfollow the same `Element` shape as top-level segment elements —\ntypically just `name` + `value` pairs.\n","properties":{"delimiter":{"type":"string","description":"Component separator used between the composite's\nsub-elements, e.g. `\":\"` (EDIFACT default) or `\">\"` /\n`\"=\"` (X12 component separators). Optional; when omitted\nthe file-level composite delimiter applies.\n"},"elements":{"type":"array","description":"Ordered sub-elements of the composite. Each entry is an\n`Element` (recursively — composites may nest), though in\npractice sub-elements carry only `name` and a literal or\nHandlebars `value`.\n","items":{"$ref":"#/components/schemas/Element"}}}},"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,"description":"Template this file definition was created from."},"_sourceId":{"type":"string","format":"objectId","readOnly":true,"description":"Source identifier for tracking the definition's origin."}}}]},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"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."}},"required":["_id"]},"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\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand 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.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot 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:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/filedefinitions":{"post":{"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"}}}},"responses":{"201":{"description":"File definition created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDefinition"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}} ``` ## Get a file definition > Returns the complete configuration including parsing rules. ```json {"openapi":"3.2.0","info":{"title":"File Definitions","version":"1.0.0"},"tags":[{"name":"File Definitions","description":"File definitions describe the structure and parsing rules for structured files\n(CSV, fixed-width, EDI X12, EDI EDIFACT). Exports and imports that process\nfile-based data reference a file definition to control how rows, columns,\nsegments, and elements are parsed or generated.\n\nFour formats are supported: `delimited` (CSV/TSV), `delimited/x12` (EDI X12),\n`delimited/edifact` (EDI EDIFACT), and `fixed` (fixed-width). EDI formats\nrequire a `globalId` linking to a standard document definition.\n\n## File definition schema\n\n{% openapi-schemas spec=\"filedefinition\" schemas=\"FileDefinition\" grouped=\"true\" %}"}],"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":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"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,"description":"Template this file definition was created from."},"_sourceId":{"type":"string","format":"objectId","readOnly":true,"description":"Source identifier for tracking the definition's origin."}}}]},"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.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional detailed description of the file definition's purpose and format.\n"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition. Only incremented for breaking changes.\n"},"format":{"type":"string","description":"The file format this definition describes.","enum":["delimited","delimited/x12","delimited/edifact","fixed"]},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents."},"globalId":{"type":"string","description":"Global identifier mapping to a known EDI standard document definition.\n\nRequired for EDI formats (`delimited/x12` or `delimited/edifact`) when the\naccount has an EDI license enabled. Must reference a valid entry in the\nstandard file definitions metadata. Immutable after creation.\n"},"rules":{"type":"array","description":"Ordered array of recursive parsing/generation `Rule` nodes that\ndescribe the file's structure — segments, elements, loops, and\ntheir relationships. The array shape is the same for every\n`format` (delimited, EDI X12/EDIFACT, and fixed-width): the first\nelement is the file's root rule, EDI envelopes nest through\n`Rule.children`, and openers pair with trailers via\n`Rule.closeRule`. Fixed-width rules carry the column offsets on\neach element (`startPosition`/`length`).\n\nThe cleared / \"no rules configured\" form is an empty array `[]`.\nThe serialized rules tree must not exceed 20 KB once attached to\nthe parent file definition document.\n","items":{"$ref":"#/components/schemas/Rule"}},"fixed":{"type":"object","description":"Configuration specific to fixed-width format files.\n\nUsed when `format` is \"fixed\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"paddingChar":{"type":"string","description":"Character used to pad fixed-width fields to their required length.\n"}}},"delimited":{"type":"object","description":"Configuration specific to delimited format files (CSV, EDI, etc.).\n\nUsed when `format` starts with \"delimited\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"colDelimiter":{"type":"string","description":"Character(s) used to delimit columns/fields within a row.\n"},"compositeDelimiter":{"type":"string","description":"Character(s) used to delimit composite elements within a field.\nPrimarily used in EDI formats.\n"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors.\n\nReserved for future use.\n"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters at the end of rows.\n"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows found in the file content during parsing.\n"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters in delimited data.\nPrimarily relevant for EDI EDIFACT format.\n"},"skipEDIValidation":{"type":"boolean","description":"Whether to skip EDI structural validation during parsing.\n"},"skipEDIProfileValidation":{"type":"boolean","default":false,"description":"Whether to skip EDI profile-level validation during parsing.\n"},"externalId":{"type":"string","description":"External identifier for correlating this file definition with an external system.\n"}}},"Rule":{"type":"object","additionalProperties":true,"description":"A single node in the recursive rules tree.\n\nA rule may carry any combination of the following — none are\nrequired individually, but every rule needs at least one of\n`elements` (to extract fields) or `children` (to nest deeper\nrules) to do anything useful.\n\n**Node roles**\n\n- **Leaf rule** — has `elements` (and usually no `children`).\n Describes a single row / segment by enumerating its fields.\n- **Branch rule** — has `children` (and optionally `elements`).\n Used to nest loops / sub-segments. EDI envelopes always nest\n their inner segments under `children`.\n- **Container rule** — sets `container: true`. Acts as a loop\n wrapper without producing an output row of its own. When\n `container` is true, `maxOccurrence` MUST be greater than\n `1` (the parser rejects `container: true` with `maxOccurrence\n <= 1`).\n\n**Envelopes and `closeRule`**\n\nEDI envelopes (ISA/IEA, GS/GE, ST/SE, UNB/UNZ, UNG/UNE, UNH/UNT)\npair an opening rule with a trailing rule:\n\n- The opening rule lives in `Rules` / `children`.\n- The matching trailer lives on the opening rule's `closeRule`.\n\n`closeRule` accepts both an object (single trailer rule) and a\none-element array of trailer rules; the parser treats them\nequivalently. In practice the **root** envelope (e.g. IEA / UNZ)\nis written as an object, and **inner** envelopes (e.g. GE / SE /\nUNE) are written as a one-element array — both shapes are valid\nagainst this schema.\n\n**Additional properties**\n\nVendor / runtime extensions (`description`, Celigo-internal\nflags) flow through unchanged. Consumers should pass unknown\nkeys back on round-trip rather than dropping them.\n","properties":{"name":{"type":"string","description":"Optional human-readable identifier for the node. EDI rules use\nthe segment name (`ST`, `GS`); delimited rules typically\nomit `name` on the root rule.\n"},"elements":{"type":"array","description":"Field-level definitions extracted from this rule's row /\nsegment. See `Element` for the per-field shape.\n\nEDI segment rules conventionally include a \"self\" element with\n`name` and `value` set to the segment id (e.g.\n`{\"name\": \"ISA\", \"value\": \"ISA\"}`) followed by one element\nper segment-element (`ISA01`, `ISA02`, ...). Delimited\nrules use one element per column.\n","items":{"$ref":"#/components/schemas/Element"}},"children":{"type":"array","description":"Nested rules. Used to build EDI envelope → group →\ntransaction → segment trees, or to model repeating\nsub-segments / loops on any format.\n\nRecursive: every child is itself a `Rule` (with the same\n`elements` / `children` / `closeRule` capabilities).\n","items":{"$ref":"#/components/schemas/Rule"}},"closeRule":{"description":"Trailer rule that closes the loop / envelope this rule opens.\n\nAccepts either:\n- A single `Rule` object (typical at the file root, e.g.\n IEA / UNZ).\n- A one-element array of `Rule` objects (typical for inner\n envelopes, e.g. GE / SE / UNE).\n\nBoth shapes are accepted by the parser; tooling that\nround-trips file definitions should preserve whichever shape\nthe source document uses.\n\nFor non-EDI / non-loop rules `closeRule` is omitted.\n","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\nrow of its own. Used on EDI `ST` / `UNH` containers so\nthe parser knows to iterate the inner transaction body up to\n`maxOccurrence` times without recording the wrapper itself.\n\nWhen `container: true` is set, `maxOccurrence` MUST be\ngreater than `1`. The parser rejects\n`container: true` paired with `maxOccurrence <= 1` with\n`Invalid rules: maxOccurences should be greater than '1',\nwhen the container is 'true'`.\n","default":false},"maxOccurrence":{"type":"integer","minimum":1,"description":"Upper bound on how many times this rule may repeat at its\ncurrent position. EDI envelopes typically use `1` (one\nISA per file, one GS per group), while transaction-set\nloops (`ST` containers, line-item loops) use larger\nvalues such as `1000`.\n\nRequired to be greater than `1` when `container` is\n`true`.\n"},"required":{"type":"boolean","description":"Whether this rule must be present in the parsed file. When\ntrue and the rule does not match, the parser raises a\nvalidation error. EDI envelope segments (ISA/GS/ST) are\nalways required; optional summary segments are not.\n"},"skipRowSuffix":{"type":"boolean","description":"Suppresses emission of `delimited.rowSuffix` after this\nrule's row during generation. Used on EDI envelope segments\n(ISA / GS / ST) where the segment terminator is part of the\nfollowing row's prefix rather than this row's suffix.\n","default":false},"description":{"type":"string","description":"Free-text annotation surfaced in the file-definition editor.\nNo functional impact on parsing.\n"},"relativeDataPath":{"type":"string","description":"JSON path (relative to the parent rule's record context) that\nthis rule's loop iterates over during generation, or that\nparsed rows are written to during parsing. Set on repeating\nrules — line-item loops, N1 address loops, ST transaction\ncontainers (e.g. `\"Items\"`, `\"N1\"`, `\"ST\"`). Omitted on\nsingle-occurrence rules.\n"},"relationship":{"type":"array","items":{"type":"string"},"description":"X12 / EDIFACT syntax-note (element relationship) codes for\nthis rule's segment. Each entry is a condition code followed\nby the element positions it binds, comma-separated:\n\n- `C` — conditional: if the first listed element is present,\n the rest are required (`\"C,06,07\"`).\n- `P` — paired: all listed elements must appear together or\n not at all (`\"P,04,05\"`).\n- `R` — required: at least one of the listed elements must be\n present (`\"R,02,03\"`).\n- `E` — exclusion: at most one of the listed elements may be\n present (`\"E,02,07\"`).\n- `L` — list conditional: if the first element is present, at\n least one of the rest is required (`\"L,03,04,05\"`).\n\nAlways an array of these code strings (never a plain string).\nPass through unchanged when round-tripping; the parser applies\nthe conditions during EDI validation.\n"}}},"Element":{"type":"object","additionalProperties":true,"description":"A single field / segment-element entry inside a `Rule.elements`\nlist.\n\n**Format-specific usage**\n\n- **Delimited (CSV / TSV)** — one element per column. `name` is\n the human label; `value` is the column id used to address the\n field downstream (e.g. `orderId`, `customerName`).\n- **Fixed-width** — adds `startPosition` + `length` (or the\n legacy `start` / `end` pair) to describe the column's offset\n within each row.\n- **EDI X12 / EDIFACT** — element values follow the segmentNN\n convention (`ISA01`, `BEG03`, `UNB02`). Segment-element\n definitions whose value comes from the trading-partner profile\n use `referenceValue` to bind a Handlebars template such as\n `{{{ediProfile.isa01}}}` — the runtime fills the value from\n the profile at parse / generate time.\n\n**Required fields**\n\n`name` is required on every element. `value` is optional: in\nthe canonical delimited row pattern, only the first element of a\nrule (the row-type marker) carries `value`; subsequent data\ncolumns use `name` only and are read by position. When\n`value` is set it must be non-empty — the parser uses it as a\nliteral match requirement (`ISA01`, `BEG03`, or the marker\nstring).\n","required":["name"],"properties":{"name":{"type":"string","description":"Human-readable label or segment-element identifier. For EDI,\ndescriptive text such as `Authorization Information\nQualifier`; for delimited data columns, the output key (the\nparser uses `name` as the field key in each parsed\nrecord); for the row-type marker, equals `value`.\n"},"value":{"description":"Machine identifier, row-type matcher, or composite-element\ndefinition. Accepts either:\n\n- A **string** — EDI elements use it as the segment-element\n identifier (`ISA01`, `BEG03`). In the canonical\n delimited row pattern, only the first element of the row's\n rule carries `value` — acting as the literal row-type\n marker the parser matches against column 0 of every row\n (e.g. `A`, `HDR`, `02`). Subsequent data columns omit\n `value` entirely. When present must be non-empty.\n- A **composite object** — EDI composite elements (an element\n whose value is itself a delimited list of sub-elements,\n e.g. EDIFACT `UNH02` = `S009` or X12 composites split by\n the component separator) set `value` to an object with a\n `delimiter` and nested `elements`. See `CompositeValue`.\n","oneOf":[{"title":"literal","type":"string"},{"title":"composite","$ref":"#/components/schemas/CompositeValue"}]},"type":{"type":"string","enum":["string","number","decimal","boolean"],"description":"Type coercion applied to the parsed value before it reaches\ndownstream mapping / output. Defaults to string when omitted.\nEDI numeric segments (control numbers, dates) typically set\n`type: number`; decimal-valued EDI elements (monetary\namounts, quantities) use `type: decimal`.\n"},"required":{"type":"boolean","default":false,"description":"Whether the parser should fail when this element is missing\nor blank. Defaults to false. EDI envelope qualifiers and\ntransaction header fields (ISA/GS/ST elements) are\nconventionally marked required.\n"},"minLength":{"type":"integer","minimum":0,"description":"Inclusive minimum string length. Used heavily on EDI\nelements where the X12 / EDIFACT standard fixes the length\nof envelope qualifiers (e.g. `ISA05` is exactly 2 chars,\n`ISA13` is exactly 9 chars).\n"},"maxLength":{"type":"integer","minimum":0,"description":"Inclusive maximum string length. See `minLength` for\nusage notes.\n"},"referenceValue":{"type":"string","description":"Handlebars template that resolves to the element's value at\nruntime instead of being read from the file. Most common use\nis binding EDI envelope fields to the trading-partner\nprofile, e.g. `{{{ediProfile.isa01}}}` or\n`{{{ediProfile.tpInterchangeId}}}`.\n\nThe linked EDI profile's fields resolve under\n`ediProfile.*`. X12 profiles: `isa01`, `isa02`, `isa03`,\n`isa04`, `tpIdQualifier`, `tpInterchangeId`, `myIdQualifier`,\n`myInterchangeId`, `isa11`, `isa12`, `isa14`, `isa15`,\n`isa16`, `tpGroupId`, `myGroupId`, `gs07`, `gs08`. EDIFACT\nprofiles: `unb010_0001`, `unb010_0002`, `tpIdQualifier`,\n`myIdQualifier`, `tpInterchangeId`, `myInterchangeId`,\n`versionNumber`, `releaseNumber`, `controllingAgency`. Both\nstandards also expose the profile's `name`, `description`,\n`fileType`, and `controlNumber` (the rolling interchange\ncontrol number — for generate-direction control-number\npositions such as ISA13). There are no `isa05`–`isa08`\nkeys: the sender/receiver qualifier and ID positions bind to\n`tpIdQualifier` / `tpInterchangeId` / `myIdQualifier` /\n`myInterchangeId` (`tp*` is the trading partner's identity,\n`my*` is yours — which pair lands in ISA05/06 vs ISA07/08\ndepends on who sends the document). Field meanings are\ndocumented in the EDI Profiles spec.\n\nUse triple-stash (`{{{...}}}`) to avoid HTML escaping for\nEDI control characters.\n"},"enum":{"type":"array","items":{"type":"string"},"description":"Enumerated set of allowed values. Used to enforce EDI code\nlists (e.g. BEG01 purpose codes `[\"00\", \"06\", \"22\"]`,\nBEG02 type codes `[\"PR\", \"RL\", \"SA\", \"ZZ\"]`). When set,\nthe parser rejects values outside the list.\n"},"description":{"type":"string","description":"Free-text annotation surfaced in the file-definition editor.\nNo functional impact on parsing.\n"},"tally":{"type":"boolean","description":"Marks this element's parsed value as a running tally that the\ngenerator accumulates across loop iterations. The\naccumulated total is referenced from trailer segments via the\n`{{_tally.[Element Name]}}` Handlebars helper (e.g. W04\n\"Number of Units Shipped\" tallied into the W03 total).\n"},"counter":{"type":"boolean","description":"Marks this element as an auto-incrementing counter the\ngenerator fills per emitted row / iteration (e.g. LX\nassigned numbers, HL hierarchical ids).\n"},"startPosition":{"type":"integer","minimum":1,"description":"Fixed-width: 1-based start column (inclusive). Pair with\n`length` to describe the column extent. Mutually exclusive\nwith the legacy `start` / `end` pair — pick one\nconvention per element.\n"},"length":{"type":"integer","minimum":1,"description":"Fixed-width: column width in characters. Pair with\n`startPosition`.\n"},"start":{"type":"integer","description":"Legacy fixed-width start offset (kept for backward\ncompatibility). Pair with `end`. Prefer\n`startPosition` + `length` on new definitions.\n"},"end":{"type":"integer","description":"Legacy fixed-width end offset (kept for backward\ncompatibility). Pair with `start`. Prefer\n`startPosition` + `length` on new definitions.\n"}}},"CompositeValue":{"type":"object","additionalProperties":true,"required":["elements"],"description":"Composite-element value: an EDI element whose value is itself a\ndelimited list of sub-elements. Used for EDIFACT composites\n(e.g. `UNH02` = message identifier `S009`, `DTM01` =\ndate/time/period `C507`) and X12 composites split by the\ncomponent element separator.\n\nThe parser joins / splits the nested `elements` using\n`delimiter` (falling back to the file-level\n`delimited.compositeDelimiter` when omitted). Sub-elements\nfollow the same `Element` shape as top-level segment elements —\ntypically just `name` + `value` pairs.\n","properties":{"delimiter":{"type":"string","description":"Component separator used between the composite's\nsub-elements, e.g. `\":\"` (EDIFACT default) or `\">\"` /\n`\"=\"` (X12 component separators). Optional; when omitted\nthe file-level composite delimiter applies.\n"},"elements":{"type":"array","description":"Ordered sub-elements of the composite. Each entry is an\n`Element` (recursively — composites may nest), though in\npractice sub-elements carry only `name` and a literal or\nHandlebars `value`.\n","items":{"$ref":"#/components/schemas/Element"}}}},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"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."}},"required":["_id"]},"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\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand 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.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot 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:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/filedefinitions/{_id}":{"get":{"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"}}],"responses":{"200":{"description":"File definition.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDefinition"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}} ``` ## Update a file definition > 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. ```json {"openapi":"3.2.0","info":{"title":"File Definitions","version":"1.0.0"},"tags":[{"name":"File Definitions","description":"File definitions describe the structure and parsing rules for structured files\n(CSV, fixed-width, EDI X12, EDI EDIFACT). Exports and imports that process\nfile-based data reference a file definition to control how rows, columns,\nsegments, and elements are parsed or generated.\n\nFour formats are supported: `delimited` (CSV/TSV), `delimited/x12` (EDI X12),\n`delimited/edifact` (EDI EDIFACT), and `fixed` (fixed-width). EDI formats\nrequire a `globalId` linking to a standard document definition.\n\n## File definition schema\n\n{% openapi-schemas spec=\"filedefinition\" schemas=\"FileDefinition\" grouped=\"true\" %}"}],"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":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Request schema for creating or updating a file definition.\n","required":["name","version","format","rules"],"allOf":[{"$ref":"#/components/schemas/FileDefinitionBase"}]},"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.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional detailed description of the file definition's purpose and format.\n"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition. Only incremented for breaking changes.\n"},"format":{"type":"string","description":"The file format this definition describes.","enum":["delimited","delimited/x12","delimited/edifact","fixed"]},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents."},"globalId":{"type":"string","description":"Global identifier mapping to a known EDI standard document definition.\n\nRequired for EDI formats (`delimited/x12` or `delimited/edifact`) when the\naccount has an EDI license enabled. Must reference a valid entry in the\nstandard file definitions metadata. Immutable after creation.\n"},"rules":{"type":"array","description":"Ordered array of recursive parsing/generation `Rule` nodes that\ndescribe the file's structure — segments, elements, loops, and\ntheir relationships. The array shape is the same for every\n`format` (delimited, EDI X12/EDIFACT, and fixed-width): the first\nelement is the file's root rule, EDI envelopes nest through\n`Rule.children`, and openers pair with trailers via\n`Rule.closeRule`. Fixed-width rules carry the column offsets on\neach element (`startPosition`/`length`).\n\nThe cleared / \"no rules configured\" form is an empty array `[]`.\nThe serialized rules tree must not exceed 20 KB once attached to\nthe parent file definition document.\n","items":{"$ref":"#/components/schemas/Rule"}},"fixed":{"type":"object","description":"Configuration specific to fixed-width format files.\n\nUsed when `format` is \"fixed\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"paddingChar":{"type":"string","description":"Character used to pad fixed-width fields to their required length.\n"}}},"delimited":{"type":"object","description":"Configuration specific to delimited format files (CSV, EDI, etc.).\n\nUsed when `format` starts with \"delimited\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"colDelimiter":{"type":"string","description":"Character(s) used to delimit columns/fields within a row.\n"},"compositeDelimiter":{"type":"string","description":"Character(s) used to delimit composite elements within a field.\nPrimarily used in EDI formats.\n"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors.\n\nReserved for future use.\n"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters at the end of rows.\n"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows found in the file content during parsing.\n"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters in delimited data.\nPrimarily relevant for EDI EDIFACT format.\n"},"skipEDIValidation":{"type":"boolean","description":"Whether to skip EDI structural validation during parsing.\n"},"skipEDIProfileValidation":{"type":"boolean","default":false,"description":"Whether to skip EDI profile-level validation during parsing.\n"},"externalId":{"type":"string","description":"External identifier for correlating this file definition with an external system.\n"}}},"Rule":{"type":"object","additionalProperties":true,"description":"A single node in the recursive rules tree.\n\nA rule may carry any combination of the following — none are\nrequired individually, but every rule needs at least one of\n`elements` (to extract fields) or `children` (to nest deeper\nrules) to do anything useful.\n\n**Node roles**\n\n- **Leaf rule** — has `elements` (and usually no `children`).\n Describes a single row / segment by enumerating its fields.\n- **Branch rule** — has `children` (and optionally `elements`).\n Used to nest loops / sub-segments. EDI envelopes always nest\n their inner segments under `children`.\n- **Container rule** — sets `container: true`. Acts as a loop\n wrapper without producing an output row of its own. When\n `container` is true, `maxOccurrence` MUST be greater than\n `1` (the parser rejects `container: true` with `maxOccurrence\n <= 1`).\n\n**Envelopes and `closeRule`**\n\nEDI envelopes (ISA/IEA, GS/GE, ST/SE, UNB/UNZ, UNG/UNE, UNH/UNT)\npair an opening rule with a trailing rule:\n\n- The opening rule lives in `Rules` / `children`.\n- The matching trailer lives on the opening rule's `closeRule`.\n\n`closeRule` accepts both an object (single trailer rule) and a\none-element array of trailer rules; the parser treats them\nequivalently. In practice the **root** envelope (e.g. IEA / UNZ)\nis written as an object, and **inner** envelopes (e.g. GE / SE /\nUNE) are written as a one-element array — both shapes are valid\nagainst this schema.\n\n**Additional properties**\n\nVendor / runtime extensions (`description`, Celigo-internal\nflags) flow through unchanged. Consumers should pass unknown\nkeys back on round-trip rather than dropping them.\n","properties":{"name":{"type":"string","description":"Optional human-readable identifier for the node. EDI rules use\nthe segment name (`ST`, `GS`); delimited rules typically\nomit `name` on the root rule.\n"},"elements":{"type":"array","description":"Field-level definitions extracted from this rule's row /\nsegment. See `Element` for the per-field shape.\n\nEDI segment rules conventionally include a \"self\" element with\n`name` and `value` set to the segment id (e.g.\n`{\"name\": \"ISA\", \"value\": \"ISA\"}`) followed by one element\nper segment-element (`ISA01`, `ISA02`, ...). Delimited\nrules use one element per column.\n","items":{"$ref":"#/components/schemas/Element"}},"children":{"type":"array","description":"Nested rules. Used to build EDI envelope → group →\ntransaction → segment trees, or to model repeating\nsub-segments / loops on any format.\n\nRecursive: every child is itself a `Rule` (with the same\n`elements` / `children` / `closeRule` capabilities).\n","items":{"$ref":"#/components/schemas/Rule"}},"closeRule":{"description":"Trailer rule that closes the loop / envelope this rule opens.\n\nAccepts either:\n- A single `Rule` object (typical at the file root, e.g.\n IEA / UNZ).\n- A one-element array of `Rule` objects (typical for inner\n envelopes, e.g. GE / SE / UNE).\n\nBoth shapes are accepted by the parser; tooling that\nround-trips file definitions should preserve whichever shape\nthe source document uses.\n\nFor non-EDI / non-loop rules `closeRule` is omitted.\n","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\nrow of its own. Used on EDI `ST` / `UNH` containers so\nthe parser knows to iterate the inner transaction body up to\n`maxOccurrence` times without recording the wrapper itself.\n\nWhen `container: true` is set, `maxOccurrence` MUST be\ngreater than `1`. The parser rejects\n`container: true` paired with `maxOccurrence <= 1` with\n`Invalid rules: maxOccurences should be greater than '1',\nwhen the container is 'true'`.\n","default":false},"maxOccurrence":{"type":"integer","minimum":1,"description":"Upper bound on how many times this rule may repeat at its\ncurrent position. EDI envelopes typically use `1` (one\nISA per file, one GS per group), while transaction-set\nloops (`ST` containers, line-item loops) use larger\nvalues such as `1000`.\n\nRequired to be greater than `1` when `container` is\n`true`.\n"},"required":{"type":"boolean","description":"Whether this rule must be present in the parsed file. When\ntrue and the rule does not match, the parser raises a\nvalidation error. EDI envelope segments (ISA/GS/ST) are\nalways required; optional summary segments are not.\n"},"skipRowSuffix":{"type":"boolean","description":"Suppresses emission of `delimited.rowSuffix` after this\nrule's row during generation. Used on EDI envelope segments\n(ISA / GS / ST) where the segment terminator is part of the\nfollowing row's prefix rather than this row's suffix.\n","default":false},"description":{"type":"string","description":"Free-text annotation surfaced in the file-definition editor.\nNo functional impact on parsing.\n"},"relativeDataPath":{"type":"string","description":"JSON path (relative to the parent rule's record context) that\nthis rule's loop iterates over during generation, or that\nparsed rows are written to during parsing. Set on repeating\nrules — line-item loops, N1 address loops, ST transaction\ncontainers (e.g. `\"Items\"`, `\"N1\"`, `\"ST\"`). Omitted on\nsingle-occurrence rules.\n"},"relationship":{"type":"array","items":{"type":"string"},"description":"X12 / EDIFACT syntax-note (element relationship) codes for\nthis rule's segment. Each entry is a condition code followed\nby the element positions it binds, comma-separated:\n\n- `C` — conditional: if the first listed element is present,\n the rest are required (`\"C,06,07\"`).\n- `P` — paired: all listed elements must appear together or\n not at all (`\"P,04,05\"`).\n- `R` — required: at least one of the listed elements must be\n present (`\"R,02,03\"`).\n- `E` — exclusion: at most one of the listed elements may be\n present (`\"E,02,07\"`).\n- `L` — list conditional: if the first element is present, at\n least one of the rest is required (`\"L,03,04,05\"`).\n\nAlways an array of these code strings (never a plain string).\nPass through unchanged when round-tripping; the parser applies\nthe conditions during EDI validation.\n"}}},"Element":{"type":"object","additionalProperties":true,"description":"A single field / segment-element entry inside a `Rule.elements`\nlist.\n\n**Format-specific usage**\n\n- **Delimited (CSV / TSV)** — one element per column. `name` is\n the human label; `value` is the column id used to address the\n field downstream (e.g. `orderId`, `customerName`).\n- **Fixed-width** — adds `startPosition` + `length` (or the\n legacy `start` / `end` pair) to describe the column's offset\n within each row.\n- **EDI X12 / EDIFACT** — element values follow the segmentNN\n convention (`ISA01`, `BEG03`, `UNB02`). Segment-element\n definitions whose value comes from the trading-partner profile\n use `referenceValue` to bind a Handlebars template such as\n `{{{ediProfile.isa01}}}` — the runtime fills the value from\n the profile at parse / generate time.\n\n**Required fields**\n\n`name` is required on every element. `value` is optional: in\nthe canonical delimited row pattern, only the first element of a\nrule (the row-type marker) carries `value`; subsequent data\ncolumns use `name` only and are read by position. When\n`value` is set it must be non-empty — the parser uses it as a\nliteral match requirement (`ISA01`, `BEG03`, or the marker\nstring).\n","required":["name"],"properties":{"name":{"type":"string","description":"Human-readable label or segment-element identifier. For EDI,\ndescriptive text such as `Authorization Information\nQualifier`; for delimited data columns, the output key (the\nparser uses `name` as the field key in each parsed\nrecord); for the row-type marker, equals `value`.\n"},"value":{"description":"Machine identifier, row-type matcher, or composite-element\ndefinition. Accepts either:\n\n- A **string** — EDI elements use it as the segment-element\n identifier (`ISA01`, `BEG03`). In the canonical\n delimited row pattern, only the first element of the row's\n rule carries `value` — acting as the literal row-type\n marker the parser matches against column 0 of every row\n (e.g. `A`, `HDR`, `02`). Subsequent data columns omit\n `value` entirely. When present must be non-empty.\n- A **composite object** — EDI composite elements (an element\n whose value is itself a delimited list of sub-elements,\n e.g. EDIFACT `UNH02` = `S009` or X12 composites split by\n the component separator) set `value` to an object with a\n `delimiter` and nested `elements`. See `CompositeValue`.\n","oneOf":[{"title":"literal","type":"string"},{"title":"composite","$ref":"#/components/schemas/CompositeValue"}]},"type":{"type":"string","enum":["string","number","decimal","boolean"],"description":"Type coercion applied to the parsed value before it reaches\ndownstream mapping / output. Defaults to string when omitted.\nEDI numeric segments (control numbers, dates) typically set\n`type: number`; decimal-valued EDI elements (monetary\namounts, quantities) use `type: decimal`.\n"},"required":{"type":"boolean","default":false,"description":"Whether the parser should fail when this element is missing\nor blank. Defaults to false. EDI envelope qualifiers and\ntransaction header fields (ISA/GS/ST elements) are\nconventionally marked required.\n"},"minLength":{"type":"integer","minimum":0,"description":"Inclusive minimum string length. Used heavily on EDI\nelements where the X12 / EDIFACT standard fixes the length\nof envelope qualifiers (e.g. `ISA05` is exactly 2 chars,\n`ISA13` is exactly 9 chars).\n"},"maxLength":{"type":"integer","minimum":0,"description":"Inclusive maximum string length. See `minLength` for\nusage notes.\n"},"referenceValue":{"type":"string","description":"Handlebars template that resolves to the element's value at\nruntime instead of being read from the file. Most common use\nis binding EDI envelope fields to the trading-partner\nprofile, e.g. `{{{ediProfile.isa01}}}` or\n`{{{ediProfile.tpInterchangeId}}}`.\n\nThe linked EDI profile's fields resolve under\n`ediProfile.*`. X12 profiles: `isa01`, `isa02`, `isa03`,\n`isa04`, `tpIdQualifier`, `tpInterchangeId`, `myIdQualifier`,\n`myInterchangeId`, `isa11`, `isa12`, `isa14`, `isa15`,\n`isa16`, `tpGroupId`, `myGroupId`, `gs07`, `gs08`. EDIFACT\nprofiles: `unb010_0001`, `unb010_0002`, `tpIdQualifier`,\n`myIdQualifier`, `tpInterchangeId`, `myInterchangeId`,\n`versionNumber`, `releaseNumber`, `controllingAgency`. Both\nstandards also expose the profile's `name`, `description`,\n`fileType`, and `controlNumber` (the rolling interchange\ncontrol number — for generate-direction control-number\npositions such as ISA13). There are no `isa05`–`isa08`\nkeys: the sender/receiver qualifier and ID positions bind to\n`tpIdQualifier` / `tpInterchangeId` / `myIdQualifier` /\n`myInterchangeId` (`tp*` is the trading partner's identity,\n`my*` is yours — which pair lands in ISA05/06 vs ISA07/08\ndepends on who sends the document). Field meanings are\ndocumented in the EDI Profiles spec.\n\nUse triple-stash (`{{{...}}}`) to avoid HTML escaping for\nEDI control characters.\n"},"enum":{"type":"array","items":{"type":"string"},"description":"Enumerated set of allowed values. Used to enforce EDI code\nlists (e.g. BEG01 purpose codes `[\"00\", \"06\", \"22\"]`,\nBEG02 type codes `[\"PR\", \"RL\", \"SA\", \"ZZ\"]`). When set,\nthe parser rejects values outside the list.\n"},"description":{"type":"string","description":"Free-text annotation surfaced in the file-definition editor.\nNo functional impact on parsing.\n"},"tally":{"type":"boolean","description":"Marks this element's parsed value as a running tally that the\ngenerator accumulates across loop iterations. The\naccumulated total is referenced from trailer segments via the\n`{{_tally.[Element Name]}}` Handlebars helper (e.g. W04\n\"Number of Units Shipped\" tallied into the W03 total).\n"},"counter":{"type":"boolean","description":"Marks this element as an auto-incrementing counter the\ngenerator fills per emitted row / iteration (e.g. LX\nassigned numbers, HL hierarchical ids).\n"},"startPosition":{"type":"integer","minimum":1,"description":"Fixed-width: 1-based start column (inclusive). Pair with\n`length` to describe the column extent. Mutually exclusive\nwith the legacy `start` / `end` pair — pick one\nconvention per element.\n"},"length":{"type":"integer","minimum":1,"description":"Fixed-width: column width in characters. Pair with\n`startPosition`.\n"},"start":{"type":"integer","description":"Legacy fixed-width start offset (kept for backward\ncompatibility). Pair with `end`. Prefer\n`startPosition` + `length` on new definitions.\n"},"end":{"type":"integer","description":"Legacy fixed-width end offset (kept for backward\ncompatibility). Pair with `start`. Prefer\n`startPosition` + `length` on new definitions.\n"}}},"CompositeValue":{"type":"object","additionalProperties":true,"required":["elements"],"description":"Composite-element value: an EDI element whose value is itself a\ndelimited list of sub-elements. Used for EDIFACT composites\n(e.g. `UNH02` = message identifier `S009`, `DTM01` =\ndate/time/period `C507`) and X12 composites split by the\ncomponent element separator.\n\nThe parser joins / splits the nested `elements` using\n`delimiter` (falling back to the file-level\n`delimited.compositeDelimiter` when omitted). Sub-elements\nfollow the same `Element` shape as top-level segment elements —\ntypically just `name` + `value` pairs.\n","properties":{"delimiter":{"type":"string","description":"Component separator used between the composite's\nsub-elements, e.g. `\":\"` (EDIFACT default) or `\">\"` /\n`\"=\"` (X12 component separators). Optional; when omitted\nthe file-level composite delimiter applies.\n"},"elements":{"type":"array","description":"Ordered sub-elements of the composite. Each entry is an\n`Element` (recursively — composites may nest), though in\npractice sub-elements carry only `name` and a literal or\nHandlebars `value`.\n","items":{"$ref":"#/components/schemas/Element"}}}},"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,"description":"Template this file definition was created from."},"_sourceId":{"type":"string","format":"objectId","readOnly":true,"description":"Source identifier for tracking the definition's origin."}}}]},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"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."}},"required":["_id"]},"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\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand 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.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot 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:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/filedefinitions/{_id}":{"put":{"summary":"Update a file definition","description":"Replaces the file definition with the provided configuration. This\nis a full replace -- include all fields you want to keep. `format`\ncannot be changed between `fixed` and `delimited` families after\ncreation, 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"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"200":{"description":"Updated file definition.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDefinition"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}} ``` ## Delete a file definition > Soft-deletes a file definition. Retained in the recycle bin for 30 days. ```json {"openapi":"3.2.0","info":{"title":"File Definitions","version":"1.0.0"},"tags":[{"name":"File Definitions","description":"File definitions describe the structure and parsing rules for structured files\n(CSV, fixed-width, EDI X12, EDI EDIFACT). Exports and imports that process\nfile-based data reference a file definition to control how rows, columns,\nsegments, and elements are parsed or generated.\n\nFour formats are supported: `delimited` (CSV/TSV), `delimited/x12` (EDI X12),\n`delimited/edifact` (EDI EDIFACT), and `fixed` (fixed-width). EDI formats\nrequire a `globalId` linking to a standard document definition.\n\n## File definition schema\n\n{% openapi-schemas spec=\"filedefinition\" schemas=\"FileDefinition\" grouped=\"true\" %}"}],"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":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot 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:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"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\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand 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.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/filedefinitions/{_id}":{"delete":{"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"}}],"responses":{"204":{"description":"File definition deleted."},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}} ``` ## List dependencies of a file definition > 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. ```json {"openapi":"3.2.0","info":{"title":"File Definitions","version":"1.0.0"},"tags":[{"name":"File Definitions","description":"File definitions describe the structure and parsing rules for structured files\n(CSV, fixed-width, EDI X12, EDI EDIFACT). Exports and imports that process\nfile-based data reference a file definition to control how rows, columns,\nsegments, and elements are parsed or generated.\n\nFour formats are supported: `delimited` (CSV/TSV), `delimited/x12` (EDI X12),\n`delimited/edifact` (EDI EDIFACT), and `fixed` (fixed-width). EDI formats\nrequire a `globalId` linking to a standard document definition.\n\n## File definition schema\n\n{% openapi-schemas spec=\"filedefinition\" schemas=\"FileDefinition\" grouped=\"true\" %}"}],"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":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"DependencyResponse":{"type":"object","description":"Map of dependent-resource types to arrays of dependency entries.\nKeys are plural resource type strings (e.g. `flows`, `imports`,\n`connections`). An empty object `{}` means no dependents.\n","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/DependencyEntry"}}},"DependencyEntry":{"type":"object","description":"A single resource that depends on the queried resource.","properties":{"id":{"type":"string","description":"Unique identifier of the dependent resource."},"name":{"type":"string","description":"Display name of the dependent resource."},"paths":{"type":"array","description":"Dot-notation paths within the dependent resource that reference\nthe target resource. `[*]` denotes array elements.","items":{"type":"string"}},"accessLevel":{"type":"string","description":"The caller's access level on the dependent resource."},"dependencyIds":{"type":"object","description":"Map of resource types to arrays of IDs that this dependent\nresource references on the target. Keys are singular or plural\nresource type strings; values are arrays of ID strings.","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["id","name","paths","accessLevel","dependencyIds"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot 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:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/filedefinitions/{_id}/dependencies":{"get":{"operationId":"listFileDefinitionDependencies","tags":["File Definitions"],"summary":"List dependencies of a file definition","description":"Returns the set of resources that depend on the specified resource.\nThe response is an object whose keys are dependent-resource types\n(e.g. `flows`, `imports`) and whose values are arrays of dependency\nentries. Returns `{}` when no dependents exist, including for\nwell-formatted but nonexistent IDs.","parameters":[{"name":"_id","in":"path","required":true,"description":"Resource ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Dependency map. Keys are resource-type strings; values are arrays\nof dependency entries. Returns `{}` when no dependents exist.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DependencyResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.celigo.com/api/api-reference/file-definitions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.