> 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 require a `globalId` linking to a standard document definition. ### File definition schema ## The FileDefinition object ```json {"openapi":"3.2.0","info":{"title":"File Definitions","version":"1.0.0"},"components":{"schemas":{"FileDefinition":{"type":"object","required":["_id","name","version","format","rules","lastModified"],"description":"File definition object as returned by the API.","allOf":[{"$ref":"#/components/schemas/FileDefinitionBase"},{"$ref":"#/components/schemas/ResourceResponse"},{"type":"object","properties":{"_templateId":{"type":"string","format":"objectId","readOnly":true,"description":"Template this file definition was created from."},"_sourceId":{"type":"string","format":"objectId","readOnly":true,"description":"Source identifier for tracking the definition's origin."}}}]},"FileDefinitionBase":{"type":"object","description":"Writable file definition fields shared by the request and response schemas.","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable name for the file definition.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional detailed description of the file definition's purpose and format.\n"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition. Only incremented for breaking changes.\n"},"format":{"type":"string","description":"The file format this definition describes.","enum":["delimited","delimited/x12","delimited/edifact","fixed"]},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents."},"globalId":{"type":"string","description":"Entry in the platform's registry of standard EDI document definitions that this\ndefinition is built from. On an EDI-licensed account an X12 or EDIFACT create without\nit fails with 422 `global_id_not_provided`, and one naming an id the registry doesn't\nhave fails with 422 `invalid_global_id`. No public route lists the registry, so copy the\n`globalId` of an existing definition for the same standard document. Immutable after\ncreation."},"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":"Configuration specific to delimited format files (CSV, EDI, etc.).\n\nUsed when `format` starts with \"delimited\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"colDelimiter":{"type":"string","description":"Character(s) used to delimit columns/fields within a row.\n"},"compositeDelimiter":{"type":"string","description":"Character(s) used to delimit composite elements within a field.\nPrimarily used in EDI formats.\n"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors.\n\nReserved for future use.\n"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters at the end of rows.\n"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows found in the file content during parsing. On a\nfixed-width definition this includes the empty row a trailing line break adds.\n"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters in delimited data.\nPrimarily relevant for EDI EDIFACT format.\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\nrequire a `globalId` linking to a standard document definition.\n\n## File definition schema\n\n{% openapi-schemas spec=\"filedefinition\" schemas=\"FileDefinition\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"Include":{"name":"include","in":"query","required":false,"description":"Comma-separated list of fields to project into each returned record.\nTriggers summary projection: the response contains a minimal identity\nset (`_id`, `name`, plus resource-specific fields) with the requested\nfields added on top. Supports dot notation for nested fields.\nMutually exclusive with `exclude`.","schema":{"type":"string"}},"Exclude":{"name":"exclude","in":"query","required":false,"description":"Comma-separated list of fields to strip from the default response.\nUnlike `include`, does not trigger summary projection — returns the\nfull record with the named fields removed. Protected identity fields\n(e.g. `name`) cannot be stripped. Mutually exclusive with `include`.","schema":{"type":"string"}}},"schemas":{"FileDefinition":{"type":"object","required":["_id","name","version","format","rules","lastModified"],"description":"File definition object as returned by the API.","allOf":[{"$ref":"#/components/schemas/FileDefinitionBase"},{"$ref":"#/components/schemas/ResourceResponse"},{"type":"object","properties":{"_templateId":{"type":"string","format":"objectId","readOnly":true,"description":"Template this file definition was created from."},"_sourceId":{"type":"string","format":"objectId","readOnly":true,"description":"Source identifier for tracking the definition's origin."}}}]},"FileDefinitionBase":{"type":"object","description":"Writable file definition fields shared by the request and response schemas.","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable name for the file definition.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional detailed description of the file definition's purpose and format.\n"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition. Only incremented for breaking changes.\n"},"format":{"type":"string","description":"The file format this definition describes.","enum":["delimited","delimited/x12","delimited/edifact","fixed"]},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents."},"globalId":{"type":"string","description":"Entry in the platform's registry of standard EDI document definitions that this\ndefinition is built from. On an EDI-licensed account an X12 or EDIFACT create without\nit fails with 422 `global_id_not_provided`, and one naming an id the registry doesn't\nhave fails with 422 `invalid_global_id`. No public route lists the registry, so copy the\n`globalId` of an existing definition for the same standard document. Immutable after\ncreation."},"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":"Configuration specific to delimited format files (CSV, EDI, etc.).\n\nUsed when `format` starts with \"delimited\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"colDelimiter":{"type":"string","description":"Character(s) used to delimit columns/fields within a row.\n"},"compositeDelimiter":{"type":"string","description":"Character(s) used to delimit composite elements within a field.\nPrimarily used in EDI formats.\n"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors.\n\nReserved for future use.\n"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters at the end of rows.\n"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows found in the file content during parsing. On a\nfixed-width definition this includes the empty row a trailing line break adds.\n"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters in delimited data.\nPrimarily relevant for EDI EDIFACT format.\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\nrequire a `globalId` linking to a standard document definition.\n\n## File definition schema\n\n{% openapi-schemas spec=\"filedefinition\" schemas=\"FileDefinition\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Request schema for creating or updating a file definition.\n\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":"EDI document type for acknowledgement documents."},"globalId":{"type":"string","description":"Entry in the platform's registry of standard EDI document definitions that this\ndefinition is built from. On an EDI-licensed account an X12 or EDIFACT create without\nit fails with 422 `global_id_not_provided`, and one naming an id the registry doesn't\nhave fails with 422 `invalid_global_id`. No public route lists the registry, so copy the\n`globalId` of an existing definition for the same standard document. Immutable after\ncreation."},"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":"Configuration specific to delimited format files (CSV, EDI, etc.).\n\nUsed when `format` starts with \"delimited\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"colDelimiter":{"type":"string","description":"Character(s) used to delimit columns/fields within a row.\n"},"compositeDelimiter":{"type":"string","description":"Character(s) used to delimit composite elements within a field.\nPrimarily used in EDI formats.\n"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors.\n\nReserved for future use.\n"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters at the end of rows.\n"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows found in the file content during parsing. On a\nfixed-width definition this includes the empty row a trailing line break adds.\n"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters in delimited data.\nPrimarily relevant for EDI EDIFACT format.\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\nrequire a `globalId` linking to a standard document definition.\n\n## File definition schema\n\n{% openapi-schemas spec=\"filedefinition\" schemas=\"FileDefinition\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"FileDefinition":{"type":"object","required":["_id","name","version","format","rules","lastModified"],"description":"File definition object as returned by the API.","allOf":[{"$ref":"#/components/schemas/FileDefinitionBase"},{"$ref":"#/components/schemas/ResourceResponse"},{"type":"object","properties":{"_templateId":{"type":"string","format":"objectId","readOnly":true,"description":"Template this file definition was created from."},"_sourceId":{"type":"string","format":"objectId","readOnly":true,"description":"Source identifier for tracking the definition's origin."}}}]},"FileDefinitionBase":{"type":"object","description":"Writable file definition fields shared by the request and response schemas.","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable name for the file definition.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional detailed description of the file definition's purpose and format.\n"},"version":{"type":"string","enum":["1","2"],"description":"Schema version of the file definition. Only incremented for breaking changes.\n"},"format":{"type":"string","description":"The file format this definition describes.","enum":["delimited","delimited/x12","delimited/edifact","fixed"]},"documentType":{"type":"string","enum":["997","CONTRL"],"description":"EDI document type for acknowledgement documents."},"globalId":{"type":"string","description":"Entry in the platform's registry of standard EDI document definitions that this\ndefinition is built from. On an EDI-licensed account an X12 or EDIFACT create without\nit fails with 422 `global_id_not_provided`, and one naming an id the registry doesn't\nhave fails with 422 `invalid_global_id`. No public route lists the registry, so copy the\n`globalId` of an existing definition for the same standard document. Immutable after\ncreation."},"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":"Configuration specific to delimited format files (CSV, EDI, etc.).\n\nUsed when `format` starts with \"delimited\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"colDelimiter":{"type":"string","description":"Character(s) used to delimit columns/fields within a row.\n"},"compositeDelimiter":{"type":"string","description":"Character(s) used to delimit composite elements within a field.\nPrimarily used in EDI formats.\n"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors.\n\nReserved for future use.\n"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters at the end of rows.\n"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows found in the file content during parsing. On a\nfixed-width definition this includes the empty row a trailing line break adds.\n"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters in delimited data.\nPrimarily relevant for EDI EDIFACT format.\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. ```json {"openapi":"3.2.0","info":{"title":"File Definitions","version":"1.0.0"},"tags":[{"name":"File Definitions","description":"File definitions describe the structure and parsing rules for structured files\n(CSV, fixed-width, EDI X12, EDI EDIFACT). Exports and imports that process\nfile-based data reference a file definition to control how rows, columns,\nsegments, and elements are parsed or generated.\n\nFour formats are supported: `delimited` (CSV/TSV), `delimited/x12` (EDI X12),\n`delimited/edifact` (EDI EDIFACT), and `fixed` (fixed-width). EDI formats\nrequire a `globalId` linking to a standard document definition.\n\n## File definition schema\n\n{% openapi-schemas spec=\"filedefinition\" schemas=\"FileDefinition\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Request schema for creating or updating a file definition.\n\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":"EDI document type for acknowledgement documents."},"globalId":{"type":"string","description":"Entry in the platform's registry of standard EDI document definitions that this\ndefinition is built from. On an EDI-licensed account an X12 or EDIFACT create without\nit fails with 422 `global_id_not_provided`, and one naming an id the registry doesn't\nhave fails with 422 `invalid_global_id`. No public route lists the registry, so copy the\n`globalId` of an existing definition for the same standard document. Immutable after\ncreation."},"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":"Configuration specific to delimited format files (CSV, EDI, etc.).\n\nUsed when `format` starts with \"delimited\".\n","properties":{"rowSuffix":{"type":"string","description":"Character(s) appended after each row during generation.\n"},"rowDelimiter":{"type":"string","description":"Character(s) used to delimit rows during parsing.\n"},"colDelimiter":{"type":"string","description":"Character(s) used to delimit columns/fields within a row.\n"},"compositeDelimiter":{"type":"string","description":"Character(s) used to delimit composite elements within a field.\nPrimarily used in EDI formats.\n"}}},"strict":{"type":"boolean","description":"Whether to fail on all validation errors.\n\nReserved for future use.\n"},"skipEmptyEndColDelimiter":{"type":"boolean","description":"Whether to skip trailing empty column delimiters at the end of rows.\n"},"skipIntermittentEmptyLines":{"type":"boolean","description":"Whether to remove empty rows found in the file content during parsing. On a\nfixed-width definition this includes the empty row a trailing line break adds.\n"},"escapeReleaseChar":{"type":"boolean","description":"Whether to handle escape/release characters in delimited data.\nPrimarily relevant for EDI EDIFACT format.\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.","operationId":"updateFileDefinition","tags":["File Definitions"],"parameters":[{"name":"_id","in":"path","description":"File definition ID.","required":true,"schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"200":{"description":"Updated file definition.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDefinition"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}} ``` ## Delete a file definition > Soft-deletes a file definition. Retained in the recycle bin for 30 days. ```json {"openapi":"3.2.0","info":{"title":"File Definitions","version":"1.0.0"},"tags":[{"name":"File Definitions","description":"File definitions describe the structure and parsing rules for structured files\n(CSV, fixed-width, EDI X12, EDI EDIFACT). Exports and imports that process\nfile-based data reference a file definition to control how rows, columns,\nsegments, and elements are parsed or generated.\n\nFour formats are supported: `delimited` (CSV/TSV), `delimited/x12` (EDI X12),\n`delimited/edifact` (EDI EDIFACT), and `fixed` (fixed-width). EDI formats\nrequire a `globalId` linking to a standard document definition.\n\n## File definition schema\n\n{% openapi-schemas spec=\"filedefinition\" schemas=\"FileDefinition\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/filedefinitions/{_id}":{"delete":{"summary":"Delete a file definition","description":"Soft-deletes a file definition. Retained in the recycle bin for 30 days.","operationId":"deleteFileDefinition","tags":["File Definitions"],"parameters":[{"name":"_id","in":"path","description":"File definition ID.","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"204":{"description":"File definition deleted."},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}} ``` ## List dependencies of a file definition > Returns the set of resources that depend on the specified resource.\ > The response is an object whose keys are dependent-resource types\ > (e.g. \`flows\`, \`imports\`) and whose values are arrays of dependency\ > entries. Returns \`{}\` when no dependents exist, including for\ > well-formatted but nonexistent IDs. ```json {"openapi":"3.2.0","info":{"title":"File Definitions","version":"1.0.0"},"tags":[{"name":"File Definitions","description":"File definitions describe the structure and parsing rules for structured files\n(CSV, fixed-width, EDI X12, EDI EDIFACT). Exports and imports that process\nfile-based data reference a file definition to control how rows, columns,\nsegments, and elements are parsed or generated.\n\nFour formats are supported: `delimited` (CSV/TSV), `delimited/x12` (EDI X12),\n`delimited/edifact` (EDI EDIFACT), and `fixed` (fixed-width). EDI formats\nrequire a `globalId` linking to a standard document definition.\n\n## File definition schema\n\n{% openapi-schemas spec=\"filedefinition\" schemas=\"FileDefinition\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"DependencyResponse":{"type":"object","description":"Map of dependent-resource types to arrays of dependency entries.\nKeys are plural resource type strings (e.g. `flows`, `imports`,\n`connections`). An empty object `{}` means no dependents.\n","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/DependencyEntry"}}},"DependencyEntry":{"type":"object","description":"A single resource that depends on the queried resource.","properties":{"id":{"type":"string","description":"Unique identifier of the dependent resource."},"name":{"type":"string","description":"Display name of the dependent resource."},"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"}}}}}} ```