> 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/b2b-manager/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 carry 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":"Marks the definition as an EDI acknowledgement document. A definition whose rules\ngenerate a functional acknowledgement must carry it: the EDI Activity dashboard's\nacknowledgement status reads it, and an X12 997 definition without it fails every\nrecord of a live run of the import that generates the acknowledgement."},"globalId":{"type":"string","description":"Global identifier mapping to a known EDI standard document definition.\n\nFor EDI formats (`delimited/x12` or `delimited/edifact`) on an account\nwith an EDI license, a create that omits it gets one assigned from the\nEDI catalog, and a supplied value must be a catalog entry (an unknown one\nfails the create with 422 `invalid_global_id`). Immutable after creation:\na PUT that sends a different value, or none, keeps the stored id.\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 list every column in order,\neach element with its `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. A save doesn't parse a sample,\nso a tree that saves can still fail or drop rows when parsed; test\nit against a sample with `POST /v1/processors/structuredFileParser`.\n","items":{"$ref":"#/components/schemas/Rule"}},"fixed":{"type":"object","description":"Configuration specific to fixed-width format files.\n\nUsed when `format` is \"fixed\", which requires `rowDelimiter` and `paddingChar`.\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. Required when `format` is \"fixed\".\n\nA delimiter after the last row is read as one more, empty row: a required row\nrule then fails the parse at that line (\"Required rule must have the respective\nrow in the source file\"), and an optional one adds an empty `{}` record. Set\n`skipIntermittentEmptyLines: true` to drop it.\n"},"paddingChar":{"type":"string","description":"Character used to pad fixed-width fields to their required length. Required when\n`format` is \"fixed\".\n"}}},"delimited":{"type":"object","description":"Delimiters for every `format` that starts with \"delimited\" (CSV, X12, EDIFACT).\nGeneration always writes these saved values. A version \"2\" `delimited/x12` or\n`delimited/edifact` parse instead reads the element separator, component separator\nand segment terminator from the incoming envelope — the ISA segment for X12, the UNB\nsegment for EDIFACT — and uses them for that parse only, so one definition parses\ninterchanges from partners who use different delimiters. The stored definition is\nnot changed. Version \"1\" definitions and plain delimited files always parse with the\nsaved values; check either behavior against a sample with\n`POST /v1/processors/structuredFileParser`.\n","properties":{"rowSuffix":{"type":"string","description":"Segment terminator (X12 `~`, EDIFACT `'`) or other text the generator appends to\nevery row before `rowDelimiter`; rules with `skipRowSuffix: true` omit it. A\nversion \"2\" X12 or EDIFACT parse strips the terminator the envelope declares\ninstead of this value.\n"},"rowDelimiter":{"type":"string","description":"Splits the file into rows when parsing and is written after each row's\n`rowSuffix` when generating. A version \"2\" X12 or EDIFACT parse splits on the\nsegment terminator the envelope declares (plus any line break that follows it),\nso an interchange with no line breaks parses too; generation still writes this\nvalue.\n"},"colDelimiter":{"type":"string","description":"Separates the elements of a row — `,` for CSV, `*` for X12, `+` for EDIFACT — when\nparsing and generating. A version \"2\" X12 or EDIFACT parse uses the element\nseparator found in the incoming ISA (the character after `ISA`) or UNB segment\ninstead, so a partner's `|`-separated interchange parses against a definition\nsaved with `*`; generation always writes this value.\n"},"compositeDelimiter":{"type":"string","description":"Separates the sub-elements of a composite element (a rule element whose `value`\nis an object) that does not set its own `delimiter` — `:` is usual for EDIFACT,\n`>` or `:` for X12. A version \"2\" X12 or EDIFACT parse uses the component\nseparator the envelope declares (ISA16 for X12; the character after the syntax\nidentifier in UNB01 for EDIFACT), so composites split correctly whatever the\npartner sends; generation joins sub-elements with this value.\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. On a\nfixed-width definition this includes the empty row a trailing line break adds.\n"},"escapeReleaseChar":{"type":"boolean","description":"When true, a `?` in front of a delimiter makes that character part of the value\ninstead of a separator (`PO?+W3B` parses as `PO+W3B`); it protects the separators a\nversion \"2\" EDIFACT parse reads from the envelope as well as the saved ones. When\nfalse, `?` is ordinary text and the delimiter after it still splits the element. Set\nit for EDIFACT partners who release characters in their data.\n"},"skipEDIValidation":{"type":"boolean","default":true,"description":"Whether to skip EDI element validation during parsing: element lengths, data types,\ncode lists, mandatory elements and element relationships. Omitted means skipped, so\nthese checks run only when it is `false`. Profile checks (`skipEDIProfileValidation`)\nand missing mandatory segments are separate and still apply.\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`. A loop wrapper\n that produces no row of its own: a group `name`, a\n `maxOccurrence` above `1` and no `elements`, with the repeated\n row's rule under `children`. It is the only shape that repeats\n rows (see `container`).\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. Omit the key on a rule\nwith no elements of its own, such as a container wrapper: an\nempty `elements` array saves, but fails the parse.\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\nPut it on the rule that opens the envelope (ISA, GS, ST, UNB,\nUNH), never on a `container` wrapper. A container's close rule\nsaves and parses without an error, but it consumes the row it\nnames, so the rule meant to read that row comes back empty.\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, and is the only way rows repeat: give the\nwrapper a group `name`, a `maxOccurrence` above `1` and no\n`elements`, and put the repeated row's rule under its\n`children` (for EDI, the `ST` or `UNH` rule with its elements,\nchildren and `closeRule`). Parsed rows come back as an array\nunder the wrapper's `name`; `container: true` on a rule with\nits own `elements` isn't honored as a loop.\n\nA container repeats up to its `maxOccurrence`, which defaults\nto `1`. A container with `1`, or without the key, saves and\nparses but matches a single row: in fixed-width and delimited\nfiles the rows after it are dropped without an error, and an\nX12 parse fails at the next row it can't place, naming a\nmandatory segment as missing (for example `Mandatory segment\n\"SE\" is missing on line: 6`). A rule outside any container\nmatches one row the same way. Give the wrapper the most rows\nthe file can hold, such as `1000`.\n","default":false},"maxOccurrence":{"type":"integer","minimum":1,"description":"Upper bound on how many times this rule may repeat at its\ncurrent position. Rows repeat only under a `container`\nwrapper, so larger values such as `1000` go on the wrapper of\nan `ST` transaction set or a line-item loop; EDI envelopes use\n`1` (one ISA per file, one GS per group).\n\nDefaults to `1`, so a container needs a larger value to repeat\n(see `container`). A value above `1` on any other rule saves,\nbut the parse refuses it with `Max no. of occurrences for\nsegment \"\" is applicable only if it is a\ncontainer/loop.` `0` is refused on save and on parse (`if\npresent, maxOccurrence must be greater than or equal to 1`).\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"},"ignoreIdentifier":{"type":"boolean","description":"Fixed-width: the rule matches rows without looking for a\nrow-type marker. Set it on the row rule of a file whose rows\ncarry no marker, inside a `container` so every row is read.\nWithout it such rows parse to one empty record (`{}`) with no\nerror, wrapped or not.\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** — one element per column, gaps included, each\n with a `length`. Columns are read in element order;\n `startPosition` doesn't move a column.\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` (in a\ncontainer's child rule, a marker whose `name` differs from\nits `value` parses to an empty record without an error).\nNames must be unique within a rule's `elements`: a save or a\nparse with two of the same name is refused (`Sibling element\nnames need to be unique. Duplicate \"\" found in\nelements: [, ]`).\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). A parse refuses a shorter value\n(`Min. length not met for the field \"ISA06\"`). Generation\ndoesn't pad to it; see `maxLength`.\n"},"maxLength":{"type":"integer","minimum":0,"description":"Inclusive maximum string length. See `minLength` for\nusage notes.\n\nGeneration pads a shorter non-empty value with spaces up to\n`maxLength` (`minLength` doesn't pad). An empty value stays\nempty, except on ISA02/ISA04 elements that keep their\nstandard names (`Authorization Information`, `Security\nInformation`), which are written as `maxLength` spaces. So a\ngenerate definition keeps the fixed-width X12 ISA at full\nwidth (ISA02/ISA04 10 characters, ISA06/ISA08 15, 106\ncharacters with the terminator) only with `maxLength` on\nthose elements. Without it, a blank `isa02` comes out empty\nand an unpadded interchange id short, and Celigo's own parser\nrefuses that ISA (`Mandatory element \"ISA02\" is not present`,\n`Min. length not met for the field \"ISA06\"`). A value longer\nthan `maxLength` fails the generation (`Max. length not met\nfor the field \"\"`).\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"},"ignore":{"type":"boolean","description":"When true, the parser reads the element (on a fixed-width row\nit still takes its `length`) but leaves it out of the parsed\nrecord.\n"},"startPosition":{"type":"integer","minimum":1,"description":"Doesn't place the column: fixed-width columns are read in\nelement order, each `length` characters wide, so a definition\nthat skips columns misreads them without an error. Describe a\ngap with a placeholder element of the gap's width instead.\n"},"length":{"type":"integer","minimum":1,"description":"Fixed-width: column width in characters. Every fixed-width\nelement needs one; the parser refuses an element without it\n(`Every fixed width element must provide a \"length\" property\nbetween 1 and 512.`).\n"},"start":{"type":"integer","description":"Legacy fixed-width start offset, paired with `end`. It doesn't\nreplace `length`: an element with `start`/`end` and no\n`length` is refused.\n"},"end":{"type":"integer","description":"Legacy fixed-width end offset, paired with `start`. It doesn't\nreplace `length`: an element with `start`/`end` and no\n`length` is refused.\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\ncarry 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":"Marks the definition as an EDI acknowledgement document. A definition whose rules\ngenerate a functional acknowledgement must carry it: the EDI Activity dashboard's\nacknowledgement status reads it, and an X12 997 definition without it fails every\nrecord of a live run of the import that generates the acknowledgement."},"globalId":{"type":"string","description":"Global identifier mapping to a known EDI standard document definition.\n\nFor EDI formats (`delimited/x12` or `delimited/edifact`) on an account\nwith an EDI license, a create that omits it gets one assigned from the\nEDI catalog, and a supplied value must be a catalog entry (an unknown one\nfails the create with 422 `invalid_global_id`). Immutable after creation:\na PUT that sends a different value, or none, keeps the stored id.\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 list every column in order,\neach element with its `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. A save doesn't parse a sample,\nso a tree that saves can still fail or drop rows when parsed; test\nit against a sample with `POST /v1/processors/structuredFileParser`.\n","items":{"$ref":"#/components/schemas/Rule"}},"fixed":{"type":"object","description":"Configuration specific to fixed-width format files.\n\nUsed when `format` is \"fixed\", which requires `rowDelimiter` and `paddingChar`.\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. Required when `format` is \"fixed\".\n\nA delimiter after the last row is read as one more, empty row: a required row\nrule then fails the parse at that line (\"Required rule must have the respective\nrow in the source file\"), and an optional one adds an empty `{}` record. Set\n`skipIntermittentEmptyLines: true` to drop it.\n"},"paddingChar":{"type":"string","description":"Character used to pad fixed-width fields to their required length. Required when\n`format` is \"fixed\".\n"}}},"delimited":{"type":"object","description":"Delimiters for every `format` that starts with \"delimited\" (CSV, X12, EDIFACT).\nGeneration always writes these saved values. A version \"2\" `delimited/x12` or\n`delimited/edifact` parse instead reads the element separator, component separator\nand segment terminator from the incoming envelope — the ISA segment for X12, the UNB\nsegment for EDIFACT — and uses them for that parse only, so one definition parses\ninterchanges from partners who use different delimiters. The stored definition is\nnot changed. Version \"1\" definitions and plain delimited files always parse with the\nsaved values; check either behavior against a sample with\n`POST /v1/processors/structuredFileParser`.\n","properties":{"rowSuffix":{"type":"string","description":"Segment terminator (X12 `~`, EDIFACT `'`) or other text the generator appends to\nevery row before `rowDelimiter`; rules with `skipRowSuffix: true` omit it. A\nversion \"2\" X12 or EDIFACT parse strips the terminator the envelope declares\ninstead of this value.\n"},"rowDelimiter":{"type":"string","description":"Splits the file into rows when parsing and is written after each row's\n`rowSuffix` when generating. A version \"2\" X12 or EDIFACT parse splits on the\nsegment terminator the envelope declares (plus any line break that follows it),\nso an interchange with no line breaks parses too; generation still writes this\nvalue.\n"},"colDelimiter":{"type":"string","description":"Separates the elements of a row — `,` for CSV, `*` for X12, `+` for EDIFACT — when\nparsing and generating. A version \"2\" X12 or EDIFACT parse uses the element\nseparator found in the incoming ISA (the character after `ISA`) or UNB segment\ninstead, so a partner's `|`-separated interchange parses against a definition\nsaved with `*`; generation always writes this value.\n"},"compositeDelimiter":{"type":"string","description":"Separates the sub-elements of a composite element (a rule element whose `value`\nis an object) that does not set its own `delimiter` — `:` is usual for EDIFACT,\n`>` or `:` for X12. A version \"2\" X12 or EDIFACT parse uses the component\nseparator the envelope declares (ISA16 for X12; the character after the syntax\nidentifier in UNB01 for EDIFACT), so composites split correctly whatever the\npartner sends; generation joins sub-elements with this value.\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. On a\nfixed-width definition this includes the empty row a trailing line break adds.\n"},"escapeReleaseChar":{"type":"boolean","description":"When true, a `?` in front of a delimiter makes that character part of the value\ninstead of a separator (`PO?+W3B` parses as `PO+W3B`); it protects the separators a\nversion \"2\" EDIFACT parse reads from the envelope as well as the saved ones. When\nfalse, `?` is ordinary text and the delimiter after it still splits the element. Set\nit for EDIFACT partners who release characters in their data.\n"},"skipEDIValidation":{"type":"boolean","default":true,"description":"Whether to skip EDI element validation during parsing: element lengths, data types,\ncode lists, mandatory elements and element relationships. Omitted means skipped, so\nthese checks run only when it is `false`. Profile checks (`skipEDIProfileValidation`)\nand missing mandatory segments are separate and still apply.\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`. A loop wrapper\n that produces no row of its own: a group `name`, a\n `maxOccurrence` above `1` and no `elements`, with the repeated\n row's rule under `children`. It is the only shape that repeats\n rows (see `container`).\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. Omit the key on a rule\nwith no elements of its own, such as a container wrapper: an\nempty `elements` array saves, but fails the parse.\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\nPut it on the rule that opens the envelope (ISA, GS, ST, UNB,\nUNH), never on a `container` wrapper. A container's close rule\nsaves and parses without an error, but it consumes the row it\nnames, so the rule meant to read that row comes back empty.\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, and is the only way rows repeat: give the\nwrapper a group `name`, a `maxOccurrence` above `1` and no\n`elements`, and put the repeated row's rule under its\n`children` (for EDI, the `ST` or `UNH` rule with its elements,\nchildren and `closeRule`). Parsed rows come back as an array\nunder the wrapper's `name`; `container: true` on a rule with\nits own `elements` isn't honored as a loop.\n\nA container repeats up to its `maxOccurrence`, which defaults\nto `1`. A container with `1`, or without the key, saves and\nparses but matches a single row: in fixed-width and delimited\nfiles the rows after it are dropped without an error, and an\nX12 parse fails at the next row it can't place, naming a\nmandatory segment as missing (for example `Mandatory segment\n\"SE\" is missing on line: 6`). A rule outside any container\nmatches one row the same way. Give the wrapper the most rows\nthe file can hold, such as `1000`.\n","default":false},"maxOccurrence":{"type":"integer","minimum":1,"description":"Upper bound on how many times this rule may repeat at its\ncurrent position. Rows repeat only under a `container`\nwrapper, so larger values such as `1000` go on the wrapper of\nan `ST` transaction set or a line-item loop; EDI envelopes use\n`1` (one ISA per file, one GS per group).\n\nDefaults to `1`, so a container needs a larger value to repeat\n(see `container`). A value above `1` on any other rule saves,\nbut the parse refuses it with `Max no. of occurrences for\nsegment \"\" is applicable only if it is a\ncontainer/loop.` `0` is refused on save and on parse (`if\npresent, maxOccurrence must be greater than or equal to 1`).\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"},"ignoreIdentifier":{"type":"boolean","description":"Fixed-width: the rule matches rows without looking for a\nrow-type marker. Set it on the row rule of a file whose rows\ncarry no marker, inside a `container` so every row is read.\nWithout it such rows parse to one empty record (`{}`) with no\nerror, wrapped or not.\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** — one element per column, gaps included, each\n with a `length`. Columns are read in element order;\n `startPosition` doesn't move a column.\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` (in a\ncontainer's child rule, a marker whose `name` differs from\nits `value` parses to an empty record without an error).\nNames must be unique within a rule's `elements`: a save or a\nparse with two of the same name is refused (`Sibling element\nnames need to be unique. Duplicate \"\" found in\nelements: [, ]`).\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). A parse refuses a shorter value\n(`Min. length not met for the field \"ISA06\"`). Generation\ndoesn't pad to it; see `maxLength`.\n"},"maxLength":{"type":"integer","minimum":0,"description":"Inclusive maximum string length. See `minLength` for\nusage notes.\n\nGeneration pads a shorter non-empty value with spaces up to\n`maxLength` (`minLength` doesn't pad). An empty value stays\nempty, except on ISA02/ISA04 elements that keep their\nstandard names (`Authorization Information`, `Security\nInformation`), which are written as `maxLength` spaces. So a\ngenerate definition keeps the fixed-width X12 ISA at full\nwidth (ISA02/ISA04 10 characters, ISA06/ISA08 15, 106\ncharacters with the terminator) only with `maxLength` on\nthose elements. Without it, a blank `isa02` comes out empty\nand an unpadded interchange id short, and Celigo's own parser\nrefuses that ISA (`Mandatory element \"ISA02\" is not present`,\n`Min. length not met for the field \"ISA06\"`). A value longer\nthan `maxLength` fails the generation (`Max. length not met\nfor the field \"\"`).\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"},"ignore":{"type":"boolean","description":"When true, the parser reads the element (on a fixed-width row\nit still takes its `length`) but leaves it out of the parsed\nrecord.\n"},"startPosition":{"type":"integer","minimum":1,"description":"Doesn't place the column: fixed-width columns are read in\nelement order, each `length` characters wide, so a definition\nthat skips columns misreads them without an error. Describe a\ngap with a placeholder element of the gap's width instead.\n"},"length":{"type":"integer","minimum":1,"description":"Fixed-width: column width in characters. Every fixed-width\nelement needs one; the parser refuses an element without it\n(`Every fixed width element must provide a \"length\" property\nbetween 1 and 512.`).\n"},"start":{"type":"integer","description":"Legacy fixed-width start offset, paired with `end`. It doesn't\nreplace `length`: an element with `start`/`end` and no\n`length` is refused.\n"},"end":{"type":"integer","description":"Legacy fixed-width end offset, paired with `start`. It doesn't\nreplace `length`: an element with `start`/`end` and no\n`length` is refused.\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\ncarry 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\nA fixed-width definition (`format: fixed`) also needs `fixed.rowDelimiter` and\n`fixed.paddingChar`: a create or full update without either fails with 422\n(\"rowDelimiter is a required field for fixed file definitions.\", \"paddingChar is a\nrequired field for fixed width file definitions.\") and saves nothing.\n","required":["name","version","format","rules"],"allOf":[{"$ref":"#/components/schemas/FileDefinitionBase"}],"if":{"properties":{"format":{"const":"fixed"}},"required":["format"]},"then":{"required":["fixed"],"properties":{"fixed":{"required":["rowDelimiter","paddingChar"]}}}},"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":"Marks the definition as an EDI acknowledgement document. A definition whose rules\ngenerate a functional acknowledgement must carry it: the EDI Activity dashboard's\nacknowledgement status reads it, and an X12 997 definition without it fails every\nrecord of a live run of the import that generates the acknowledgement."},"globalId":{"type":"string","description":"Global identifier mapping to a known EDI standard document definition.\n\nFor EDI formats (`delimited/x12` or `delimited/edifact`) on an account\nwith an EDI license, a create that omits it gets one assigned from the\nEDI catalog, and a supplied value must be a catalog entry (an unknown one\nfails the create with 422 `invalid_global_id`). Immutable after creation:\na PUT that sends a different value, or none, keeps the stored id.\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 list every column in order,\neach element with its `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. A save doesn't parse a sample,\nso a tree that saves can still fail or drop rows when parsed; test\nit against a sample with `POST /v1/processors/structuredFileParser`.\n","items":{"$ref":"#/components/schemas/Rule"}},"fixed":{"type":"object","description":"Configuration specific to fixed-width format files.\n\nUsed when `format` is \"fixed\", which requires `rowDelimiter` and `paddingChar`.\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. Required when `format` is \"fixed\".\n\nA delimiter after the last row is read as one more, empty row: a required row\nrule then fails the parse at that line (\"Required rule must have the respective\nrow in the source file\"), and an optional one adds an empty `{}` record. Set\n`skipIntermittentEmptyLines: true` to drop it.\n"},"paddingChar":{"type":"string","description":"Character used to pad fixed-width fields to their required length. Required when\n`format` is \"fixed\".\n"}}},"delimited":{"type":"object","description":"Delimiters for every `format` that starts with \"delimited\" (CSV, X12, EDIFACT).\nGeneration always writes these saved values. A version \"2\" `delimited/x12` or\n`delimited/edifact` parse instead reads the element separator, component separator\nand segment terminator from the incoming envelope — the ISA segment for X12, the UNB\nsegment for EDIFACT — and uses them for that parse only, so one definition parses\ninterchanges from partners who use different delimiters. The stored definition is\nnot changed. Version \"1\" definitions and plain delimited files always parse with the\nsaved values; check either behavior against a sample with\n`POST /v1/processors/structuredFileParser`.\n","properties":{"rowSuffix":{"type":"string","description":"Segment terminator (X12 `~`, EDIFACT `'`) or other text the generator appends to\nevery row before `rowDelimiter`; rules with `skipRowSuffix: true` omit it. A\nversion \"2\" X12 or EDIFACT parse strips the terminator the envelope declares\ninstead of this value.\n"},"rowDelimiter":{"type":"string","description":"Splits the file into rows when parsing and is written after each row's\n`rowSuffix` when generating. A version \"2\" X12 or EDIFACT parse splits on the\nsegment terminator the envelope declares (plus any line break that follows it),\nso an interchange with no line breaks parses too; generation still writes this\nvalue.\n"},"colDelimiter":{"type":"string","description":"Separates the elements of a row — `,` for CSV, `*` for X12, `+` for EDIFACT — when\nparsing and generating. A version \"2\" X12 or EDIFACT parse uses the element\nseparator found in the incoming ISA (the character after `ISA`) or UNB segment\ninstead, so a partner's `|`-separated interchange parses against a definition\nsaved with `*`; generation always writes this value.\n"},"compositeDelimiter":{"type":"string","description":"Separates the sub-elements of a composite element (a rule element whose `value`\nis an object) that does not set its own `delimiter` — `:` is usual for EDIFACT,\n`>` or `:` for X12. A version \"2\" X12 or EDIFACT parse uses the component\nseparator the envelope declares (ISA16 for X12; the character after the syntax\nidentifier in UNB01 for EDIFACT), so composites split correctly whatever the\npartner sends; generation joins sub-elements with this value.\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. On a\nfixed-width definition this includes the empty row a trailing line break adds.\n"},"escapeReleaseChar":{"type":"boolean","description":"When true, a `?` in front of a delimiter makes that character part of the value\ninstead of a separator (`PO?+W3B` parses as `PO+W3B`); it protects the separators a\nversion \"2\" EDIFACT parse reads from the envelope as well as the saved ones. When\nfalse, `?` is ordinary text and the delimiter after it still splits the element. Set\nit for EDIFACT partners who release characters in their data.\n"},"skipEDIValidation":{"type":"boolean","default":true,"description":"Whether to skip EDI element validation during parsing: element lengths, data types,\ncode lists, mandatory elements and element relationships. Omitted means skipped, so\nthese checks run only when it is `false`. Profile checks (`skipEDIProfileValidation`)\nand missing mandatory segments are separate and still apply.\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`. A loop wrapper\n that produces no row of its own: a group `name`, a\n `maxOccurrence` above `1` and no `elements`, with the repeated\n row's rule under `children`. It is the only shape that repeats\n rows (see `container`).\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. Omit the key on a rule\nwith no elements of its own, such as a container wrapper: an\nempty `elements` array saves, but fails the parse.\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\nPut it on the rule that opens the envelope (ISA, GS, ST, UNB,\nUNH), never on a `container` wrapper. A container's close rule\nsaves and parses without an error, but it consumes the row it\nnames, so the rule meant to read that row comes back empty.\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, and is the only way rows repeat: give the\nwrapper a group `name`, a `maxOccurrence` above `1` and no\n`elements`, and put the repeated row's rule under its\n`children` (for EDI, the `ST` or `UNH` rule with its elements,\nchildren and `closeRule`). Parsed rows come back as an array\nunder the wrapper's `name`; `container: true` on a rule with\nits own `elements` isn't honored as a loop.\n\nA container repeats up to its `maxOccurrence`, which defaults\nto `1`. A container with `1`, or without the key, saves and\nparses but matches a single row: in fixed-width and delimited\nfiles the rows after it are dropped without an error, and an\nX12 parse fails at the next row it can't place, naming a\nmandatory segment as missing (for example `Mandatory segment\n\"SE\" is missing on line: 6`). A rule outside any container\nmatches one row the same way. Give the wrapper the most rows\nthe file can hold, such as `1000`.\n","default":false},"maxOccurrence":{"type":"integer","minimum":1,"description":"Upper bound on how many times this rule may repeat at its\ncurrent position. Rows repeat only under a `container`\nwrapper, so larger values such as `1000` go on the wrapper of\nan `ST` transaction set or a line-item loop; EDI envelopes use\n`1` (one ISA per file, one GS per group).\n\nDefaults to `1`, so a container needs a larger value to repeat\n(see `container`). A value above `1` on any other rule saves,\nbut the parse refuses it with `Max no. of occurrences for\nsegment \"\" is applicable only if it is a\ncontainer/loop.` `0` is refused on save and on parse (`if\npresent, maxOccurrence must be greater than or equal to 1`).\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"},"ignoreIdentifier":{"type":"boolean","description":"Fixed-width: the rule matches rows without looking for a\nrow-type marker. Set it on the row rule of a file whose rows\ncarry no marker, inside a `container` so every row is read.\nWithout it such rows parse to one empty record (`{}`) with no\nerror, wrapped or not.\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** — one element per column, gaps included, each\n with a `length`. Columns are read in element order;\n `startPosition` doesn't move a column.\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` (in a\ncontainer's child rule, a marker whose `name` differs from\nits `value` parses to an empty record without an error).\nNames must be unique within a rule's `elements`: a save or a\nparse with two of the same name is refused (`Sibling element\nnames need to be unique. Duplicate \"\" found in\nelements: [, ]`).\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). A parse refuses a shorter value\n(`Min. length not met for the field \"ISA06\"`). Generation\ndoesn't pad to it; see `maxLength`.\n"},"maxLength":{"type":"integer","minimum":0,"description":"Inclusive maximum string length. See `minLength` for\nusage notes.\n\nGeneration pads a shorter non-empty value with spaces up to\n`maxLength` (`minLength` doesn't pad). An empty value stays\nempty, except on ISA02/ISA04 elements that keep their\nstandard names (`Authorization Information`, `Security\nInformation`), which are written as `maxLength` spaces. So a\ngenerate definition keeps the fixed-width X12 ISA at full\nwidth (ISA02/ISA04 10 characters, ISA06/ISA08 15, 106\ncharacters with the terminator) only with `maxLength` on\nthose elements. Without it, a blank `isa02` comes out empty\nand an unpadded interchange id short, and Celigo's own parser\nrefuses that ISA (`Mandatory element \"ISA02\" is not present`,\n`Min. length not met for the field \"ISA06\"`). A value longer\nthan `maxLength` fails the generation (`Max. length not met\nfor the field \"\"`).\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"},"ignore":{"type":"boolean","description":"When true, the parser reads the element (on a fixed-width row\nit still takes its `length`) but leaves it out of the parsed\nrecord.\n"},"startPosition":{"type":"integer","minimum":1,"description":"Doesn't place the column: fixed-width columns are read in\nelement order, each `length` characters wide, so a definition\nthat skips columns misreads them without an error. Describe a\ngap with a placeholder element of the gap's width instead.\n"},"length":{"type":"integer","minimum":1,"description":"Fixed-width: column width in characters. Every fixed-width\nelement needs one; the parser refuses an element without it\n(`Every fixed width element must provide a \"length\" property\nbetween 1 and 512.`).\n"},"start":{"type":"integer","description":"Legacy fixed-width start offset, paired with `end`. It doesn't\nreplace `length`: an element with `start`/`end` and no\n`length` is refused.\n"},"end":{"type":"integer","description":"Legacy fixed-width end offset, paired with `start`. It doesn't\nreplace `length`: an element with `start`/`end` and no\n`length` is refused.\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\ncarry 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":"Marks the definition as an EDI acknowledgement document. A definition whose rules\ngenerate a functional acknowledgement must carry it: the EDI Activity dashboard's\nacknowledgement status reads it, and an X12 997 definition without it fails every\nrecord of a live run of the import that generates the acknowledgement."},"globalId":{"type":"string","description":"Global identifier mapping to a known EDI standard document definition.\n\nFor EDI formats (`delimited/x12` or `delimited/edifact`) on an account\nwith an EDI license, a create that omits it gets one assigned from the\nEDI catalog, and a supplied value must be a catalog entry (an unknown one\nfails the create with 422 `invalid_global_id`). Immutable after creation:\na PUT that sends a different value, or none, keeps the stored id.\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 list every column in order,\neach element with its `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. A save doesn't parse a sample,\nso a tree that saves can still fail or drop rows when parsed; test\nit against a sample with `POST /v1/processors/structuredFileParser`.\n","items":{"$ref":"#/components/schemas/Rule"}},"fixed":{"type":"object","description":"Configuration specific to fixed-width format files.\n\nUsed when `format` is \"fixed\", which requires `rowDelimiter` and `paddingChar`.\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. Required when `format` is \"fixed\".\n\nA delimiter after the last row is read as one more, empty row: a required row\nrule then fails the parse at that line (\"Required rule must have the respective\nrow in the source file\"), and an optional one adds an empty `{}` record. Set\n`skipIntermittentEmptyLines: true` to drop it.\n"},"paddingChar":{"type":"string","description":"Character used to pad fixed-width fields to their required length. Required when\n`format` is \"fixed\".\n"}}},"delimited":{"type":"object","description":"Delimiters for every `format` that starts with \"delimited\" (CSV, X12, EDIFACT).\nGeneration always writes these saved values. A version \"2\" `delimited/x12` or\n`delimited/edifact` parse instead reads the element separator, component separator\nand segment terminator from the incoming envelope — the ISA segment for X12, the UNB\nsegment for EDIFACT — and uses them for that parse only, so one definition parses\ninterchanges from partners who use different delimiters. The stored definition is\nnot changed. Version \"1\" definitions and plain delimited files always parse with the\nsaved values; check either behavior against a sample with\n`POST /v1/processors/structuredFileParser`.\n","properties":{"rowSuffix":{"type":"string","description":"Segment terminator (X12 `~`, EDIFACT `'`) or other text the generator appends to\nevery row before `rowDelimiter`; rules with `skipRowSuffix: true` omit it. A\nversion \"2\" X12 or EDIFACT parse strips the terminator the envelope declares\ninstead of this value.\n"},"rowDelimiter":{"type":"string","description":"Splits the file into rows when parsing and is written after each row's\n`rowSuffix` when generating. A version \"2\" X12 or EDIFACT parse splits on the\nsegment terminator the envelope declares (plus any line break that follows it),\nso an interchange with no line breaks parses too; generation still writes this\nvalue.\n"},"colDelimiter":{"type":"string","description":"Separates the elements of a row — `,` for CSV, `*` for X12, `+` for EDIFACT — when\nparsing and generating. A version \"2\" X12 or EDIFACT parse uses the element\nseparator found in the incoming ISA (the character after `ISA`) or UNB segment\ninstead, so a partner's `|`-separated interchange parses against a definition\nsaved with `*`; generation always writes this value.\n"},"compositeDelimiter":{"type":"string","description":"Separates the sub-elements of a composite element (a rule element whose `value`\nis an object) that does not set its own `delimiter` — `:` is usual for EDIFACT,\n`>` or `:` for X12. A version \"2\" X12 or EDIFACT parse uses the component\nseparator the envelope declares (ISA16 for X12; the character after the syntax\nidentifier in UNB01 for EDIFACT), so composites split correctly whatever the\npartner sends; generation joins sub-elements with this value.\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. On a\nfixed-width definition this includes the empty row a trailing line break adds.\n"},"escapeReleaseChar":{"type":"boolean","description":"When true, a `?` in front of a delimiter makes that character part of the value\ninstead of a separator (`PO?+W3B` parses as `PO+W3B`); it protects the separators a\nversion \"2\" EDIFACT parse reads from the envelope as well as the saved ones. When\nfalse, `?` is ordinary text and the delimiter after it still splits the element. Set\nit for EDIFACT partners who release characters in their data.\n"},"skipEDIValidation":{"type":"boolean","default":true,"description":"Whether to skip EDI element validation during parsing: element lengths, data types,\ncode lists, mandatory elements and element relationships. Omitted means skipped, so\nthese checks run only when it is `false`. Profile checks (`skipEDIProfileValidation`)\nand missing mandatory segments are separate and still apply.\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`. A loop wrapper\n that produces no row of its own: a group `name`, a\n `maxOccurrence` above `1` and no `elements`, with the repeated\n row's rule under `children`. It is the only shape that repeats\n rows (see `container`).\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. Omit the key on a rule\nwith no elements of its own, such as a container wrapper: an\nempty `elements` array saves, but fails the parse.\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\nPut it on the rule that opens the envelope (ISA, GS, ST, UNB,\nUNH), never on a `container` wrapper. A container's close rule\nsaves and parses without an error, but it consumes the row it\nnames, so the rule meant to read that row comes back empty.\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, and is the only way rows repeat: give the\nwrapper a group `name`, a `maxOccurrence` above `1` and no\n`elements`, and put the repeated row's rule under its\n`children` (for EDI, the `ST` or `UNH` rule with its elements,\nchildren and `closeRule`). Parsed rows come back as an array\nunder the wrapper's `name`; `container: true` on a rule with\nits own `elements` isn't honored as a loop.\n\nA container repeats up to its `maxOccurrence`, which defaults\nto `1`. A container with `1`, or without the key, saves and\nparses but matches a single row: in fixed-width and delimited\nfiles the rows after it are dropped without an error, and an\nX12 parse fails at the next row it can't place, naming a\nmandatory segment as missing (for example `Mandatory segment\n\"SE\" is missing on line: 6`). A rule outside any container\nmatches one row the same way. Give the wrapper the most rows\nthe file can hold, such as `1000`.\n","default":false},"maxOccurrence":{"type":"integer","minimum":1,"description":"Upper bound on how many times this rule may repeat at its\ncurrent position. Rows repeat only under a `container`\nwrapper, so larger values such as `1000` go on the wrapper of\nan `ST` transaction set or a line-item loop; EDI envelopes use\n`1` (one ISA per file, one GS per group).\n\nDefaults to `1`, so a container needs a larger value to repeat\n(see `container`). A value above `1` on any other rule saves,\nbut the parse refuses it with `Max no. of occurrences for\nsegment \"\" is applicable only if it is a\ncontainer/loop.` `0` is refused on save and on parse (`if\npresent, maxOccurrence must be greater than or equal to 1`).\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"},"ignoreIdentifier":{"type":"boolean","description":"Fixed-width: the rule matches rows without looking for a\nrow-type marker. Set it on the row rule of a file whose rows\ncarry no marker, inside a `container` so every row is read.\nWithout it such rows parse to one empty record (`{}`) with no\nerror, wrapped or not.\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** — one element per column, gaps included, each\n with a `length`. Columns are read in element order;\n `startPosition` doesn't move a column.\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` (in a\ncontainer's child rule, a marker whose `name` differs from\nits `value` parses to an empty record without an error).\nNames must be unique within a rule's `elements`: a save or a\nparse with two of the same name is refused (`Sibling element\nnames need to be unique. Duplicate \"\" found in\nelements: [, ]`).\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). A parse refuses a shorter value\n(`Min. length not met for the field \"ISA06\"`). Generation\ndoesn't pad to it; see `maxLength`.\n"},"maxLength":{"type":"integer","minimum":0,"description":"Inclusive maximum string length. See `minLength` for\nusage notes.\n\nGeneration pads a shorter non-empty value with spaces up to\n`maxLength` (`minLength` doesn't pad). An empty value stays\nempty, except on ISA02/ISA04 elements that keep their\nstandard names (`Authorization Information`, `Security\nInformation`), which are written as `maxLength` spaces. So a\ngenerate definition keeps the fixed-width X12 ISA at full\nwidth (ISA02/ISA04 10 characters, ISA06/ISA08 15, 106\ncharacters with the terminator) only with `maxLength` on\nthose elements. Without it, a blank `isa02` comes out empty\nand an unpadded interchange id short, and Celigo's own parser\nrefuses that ISA (`Mandatory element \"ISA02\" is not present`,\n`Min. length not met for the field \"ISA06\"`). A value longer\nthan `maxLength` fails the generation (`Max. length not met\nfor the field \"\"`).\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"},"ignore":{"type":"boolean","description":"When true, the parser reads the element (on a fixed-width row\nit still takes its `length`) but leaves it out of the parsed\nrecord.\n"},"startPosition":{"type":"integer","minimum":1,"description":"Doesn't place the column: fixed-width columns are read in\nelement order, each `length` characters wide, so a definition\nthat skips columns misreads them without an error. Describe a\ngap with a placeholder element of the gap's width instead.\n"},"length":{"type":"integer","minimum":1,"description":"Fixed-width: column width in characters. Every fixed-width\nelement needs one; the parser refuses an element without it\n(`Every fixed width element must provide a \"length\" property\nbetween 1 and 512.`).\n"},"start":{"type":"integer","description":"Legacy fixed-width start offset, paired with `end`. It doesn't\nreplace `length`: an element with `start`/`end` and no\n`length` is refused.\n"},"end":{"type":"integer","description":"Legacy fixed-width end offset, paired with `start`. It doesn't\nreplace `length`: an element with `start`/`end` and no\n`length` is refused.\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: a PUT that sends a\ > different value, or omits it, keeps the stored id. ```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\ncarry 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\nA fixed-width definition (`format: fixed`) also needs `fixed.rowDelimiter` and\n`fixed.paddingChar`: a create or full update without either fails with 422\n(\"rowDelimiter is a required field for fixed file definitions.\", \"paddingChar is a\nrequired field for fixed width file definitions.\") and saves nothing.\n","required":["name","version","format","rules"],"allOf":[{"$ref":"#/components/schemas/FileDefinitionBase"}],"if":{"properties":{"format":{"const":"fixed"}},"required":["format"]},"then":{"required":["fixed"],"properties":{"fixed":{"required":["rowDelimiter","paddingChar"]}}}},"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":"Marks the definition as an EDI acknowledgement document. A definition whose rules\ngenerate a functional acknowledgement must carry it: the EDI Activity dashboard's\nacknowledgement status reads it, and an X12 997 definition without it fails every\nrecord of a live run of the import that generates the acknowledgement."},"globalId":{"type":"string","description":"Global identifier mapping to a known EDI standard document definition.\n\nFor EDI formats (`delimited/x12` or `delimited/edifact`) on an account\nwith an EDI license, a create that omits it gets one assigned from the\nEDI catalog, and a supplied value must be a catalog entry (an unknown one\nfails the create with 422 `invalid_global_id`). Immutable after creation:\na PUT that sends a different value, or none, keeps the stored id.\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 list every column in order,\neach element with its `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. A save doesn't parse a sample,\nso a tree that saves can still fail or drop rows when parsed; test\nit against a sample with `POST /v1/processors/structuredFileParser`.\n","items":{"$ref":"#/components/schemas/Rule"}},"fixed":{"type":"object","description":"Configuration specific to fixed-width format files.\n\nUsed when `format` is \"fixed\", which requires `rowDelimiter` and `paddingChar`.\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. Required when `format` is \"fixed\".\n\nA delimiter after the last row is read as one more, empty row: a required row\nrule then fails the parse at that line (\"Required rule must have the respective\nrow in the source file\"), and an optional one adds an empty `{}` record. Set\n`skipIntermittentEmptyLines: true` to drop it.\n"},"paddingChar":{"type":"string","description":"Character used to pad fixed-width fields to their required length. Required when\n`format` is \"fixed\".\n"}}},"delimited":{"type":"object","description":"Delimiters for every `format` that starts with \"delimited\" (CSV, X12, EDIFACT).\nGeneration always writes these saved values. A version \"2\" `delimited/x12` or\n`delimited/edifact` parse instead reads the element separator, component separator\nand segment terminator from the incoming envelope — the ISA segment for X12, the UNB\nsegment for EDIFACT — and uses them for that parse only, so one definition parses\ninterchanges from partners who use different delimiters. The stored definition is\nnot changed. Version \"1\" definitions and plain delimited files always parse with the\nsaved values; check either behavior against a sample with\n`POST /v1/processors/structuredFileParser`.\n","properties":{"rowSuffix":{"type":"string","description":"Segment terminator (X12 `~`, EDIFACT `'`) or other text the generator appends to\nevery row before `rowDelimiter`; rules with `skipRowSuffix: true` omit it. A\nversion \"2\" X12 or EDIFACT parse strips the terminator the envelope declares\ninstead of this value.\n"},"rowDelimiter":{"type":"string","description":"Splits the file into rows when parsing and is written after each row's\n`rowSuffix` when generating. A version \"2\" X12 or EDIFACT parse splits on the\nsegment terminator the envelope declares (plus any line break that follows it),\nso an interchange with no line breaks parses too; generation still writes this\nvalue.\n"},"colDelimiter":{"type":"string","description":"Separates the elements of a row — `,` for CSV, `*` for X12, `+` for EDIFACT — when\nparsing and generating. A version \"2\" X12 or EDIFACT parse uses the element\nseparator found in the incoming ISA (the character after `ISA`) or UNB segment\ninstead, so a partner's `|`-separated interchange parses against a definition\nsaved with `*`; generation always writes this value.\n"},"compositeDelimiter":{"type":"string","description":"Separates the sub-elements of a composite element (a rule element whose `value`\nis an object) that does not set its own `delimiter` — `:` is usual for EDIFACT,\n`>` or `:` for X12. A version \"2\" X12 or EDIFACT parse uses the component\nseparator the envelope declares (ISA16 for X12; the character after the syntax\nidentifier in UNB01 for EDIFACT), so composites split correctly whatever the\npartner sends; generation joins sub-elements with this value.\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. On a\nfixed-width definition this includes the empty row a trailing line break adds.\n"},"escapeReleaseChar":{"type":"boolean","description":"When true, a `?` in front of a delimiter makes that character part of the value\ninstead of a separator (`PO?+W3B` parses as `PO+W3B`); it protects the separators a\nversion \"2\" EDIFACT parse reads from the envelope as well as the saved ones. When\nfalse, `?` is ordinary text and the delimiter after it still splits the element. Set\nit for EDIFACT partners who release characters in their data.\n"},"skipEDIValidation":{"type":"boolean","default":true,"description":"Whether to skip EDI element validation during parsing: element lengths, data types,\ncode lists, mandatory elements and element relationships. Omitted means skipped, so\nthese checks run only when it is `false`. Profile checks (`skipEDIProfileValidation`)\nand missing mandatory segments are separate and still apply.\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`. A loop wrapper\n that produces no row of its own: a group `name`, a\n `maxOccurrence` above `1` and no `elements`, with the repeated\n row's rule under `children`. It is the only shape that repeats\n rows (see `container`).\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. Omit the key on a rule\nwith no elements of its own, such as a container wrapper: an\nempty `elements` array saves, but fails the parse.\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\nPut it on the rule that opens the envelope (ISA, GS, ST, UNB,\nUNH), never on a `container` wrapper. A container's close rule\nsaves and parses without an error, but it consumes the row it\nnames, so the rule meant to read that row comes back empty.\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, and is the only way rows repeat: give the\nwrapper a group `name`, a `maxOccurrence` above `1` and no\n`elements`, and put the repeated row's rule under its\n`children` (for EDI, the `ST` or `UNH` rule with its elements,\nchildren and `closeRule`). Parsed rows come back as an array\nunder the wrapper's `name`; `container: true` on a rule with\nits own `elements` isn't honored as a loop.\n\nA container repeats up to its `maxOccurrence`, which defaults\nto `1`. A container with `1`, or without the key, saves and\nparses but matches a single row: in fixed-width and delimited\nfiles the rows after it are dropped without an error, and an\nX12 parse fails at the next row it can't place, naming a\nmandatory segment as missing (for example `Mandatory segment\n\"SE\" is missing on line: 6`). A rule outside any container\nmatches one row the same way. Give the wrapper the most rows\nthe file can hold, such as `1000`.\n","default":false},"maxOccurrence":{"type":"integer","minimum":1,"description":"Upper bound on how many times this rule may repeat at its\ncurrent position. Rows repeat only under a `container`\nwrapper, so larger values such as `1000` go on the wrapper of\nan `ST` transaction set or a line-item loop; EDI envelopes use\n`1` (one ISA per file, one GS per group).\n\nDefaults to `1`, so a container needs a larger value to repeat\n(see `container`). A value above `1` on any other rule saves,\nbut the parse refuses it with `Max no. of occurrences for\nsegment \"\" is applicable only if it is a\ncontainer/loop.` `0` is refused on save and on parse (`if\npresent, maxOccurrence must be greater than or equal to 1`).\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"},"ignoreIdentifier":{"type":"boolean","description":"Fixed-width: the rule matches rows without looking for a\nrow-type marker. Set it on the row rule of a file whose rows\ncarry no marker, inside a `container` so every row is read.\nWithout it such rows parse to one empty record (`{}`) with no\nerror, wrapped or not.\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** — one element per column, gaps included, each\n with a `length`. Columns are read in element order;\n `startPosition` doesn't move a column.\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` (in a\ncontainer's child rule, a marker whose `name` differs from\nits `value` parses to an empty record without an error).\nNames must be unique within a rule's `elements`: a save or a\nparse with two of the same name is refused (`Sibling element\nnames need to be unique. Duplicate \"\" found in\nelements: [, ]`).\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). A parse refuses a shorter value\n(`Min. length not met for the field \"ISA06\"`). Generation\ndoesn't pad to it; see `maxLength`.\n"},"maxLength":{"type":"integer","minimum":0,"description":"Inclusive maximum string length. See `minLength` for\nusage notes.\n\nGeneration pads a shorter non-empty value with spaces up to\n`maxLength` (`minLength` doesn't pad). An empty value stays\nempty, except on ISA02/ISA04 elements that keep their\nstandard names (`Authorization Information`, `Security\nInformation`), which are written as `maxLength` spaces. So a\ngenerate definition keeps the fixed-width X12 ISA at full\nwidth (ISA02/ISA04 10 characters, ISA06/ISA08 15, 106\ncharacters with the terminator) only with `maxLength` on\nthose elements. Without it, a blank `isa02` comes out empty\nand an unpadded interchange id short, and Celigo's own parser\nrefuses that ISA (`Mandatory element \"ISA02\" is not present`,\n`Min. length not met for the field \"ISA06\"`). A value longer\nthan `maxLength` fails the generation (`Max. length not met\nfor the field \"\"`).\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"},"ignore":{"type":"boolean","description":"When true, the parser reads the element (on a fixed-width row\nit still takes its `length`) but leaves it out of the parsed\nrecord.\n"},"startPosition":{"type":"integer","minimum":1,"description":"Doesn't place the column: fixed-width columns are read in\nelement order, each `length` characters wide, so a definition\nthat skips columns misreads them without an error. Describe a\ngap with a placeholder element of the gap's width instead.\n"},"length":{"type":"integer","minimum":1,"description":"Fixed-width: column width in characters. Every fixed-width\nelement needs one; the parser refuses an element without it\n(`Every fixed width element must provide a \"length\" property\nbetween 1 and 512.`).\n"},"start":{"type":"integer","description":"Legacy fixed-width start offset, paired with `end`. It doesn't\nreplace `length`: an element with `start`/`end` and no\n`length` is refused.\n"},"end":{"type":"integer","description":"Legacy fixed-width end offset, paired with `start`. It doesn't\nreplace `length`: an element with `start`/`end` and no\n`length` is refused.\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: a PUT that sends a\ndifferent value, or omits it, keeps the stored id.","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\ncarry 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\ncarry 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."},"type":{"type":"string","description":"Sub-type of the dependent resource when its collection distinguishes one, such as\n`stream` for a listener export. Only present for resource types that carry a `type`."},"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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developer.celigo.com/api/api-reference/b2b-manager/file-definitions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.