CreateSpecRequest

Payload to create or update a file spec

namestringrequired

Unique human-readable name for the spec

Example: acme-payments-v2

descriptionstring

Optional description of what this spec represents

Default value:

Example: ACME Corp daily payment file, pipe-delimited

versionstring

Semantic version of the spec

Default value: 1.0

Example: 2.0

formatFileFormat (string)required

Supported file formats

Possible values: [CSV, FIXED_WIDTH, XML, JSON, NACHA, ISO20022, SWIFT_MT, DELIMITED, CUSTOM]

Example: DELIMITED

encodingstring

Character encoding of the source file

Default value: UTF-8

Example: UTF-8

hasHeaderboolean

Whether the first data row is a header row (CSV/delimited)

Default value: false

delimiterstring

Field separator character (CSV/DELIMITED only)

Example: |

skipLinesCountinteger

Number of lines to skip at the top of the file (e.g. file-level header)

Default value: 0

Example: 2

fields object[]

Ordered list of field definitions

Array [

namestringrequired

Internal field identifier (snake_case recommended)

Example: account_number

displayNamestring

Human-readable label (defaults to name)

Example: Account Number

typeFieldType (string)required

Data type for a field

Possible values: [STRING, INTEGER, LONG, DECIMAL, AMOUNT, DATE, DATETIME, BOOLEAN, ALPHANUMERIC, ROUTING_NUMBER, ACCOUNT_NUMBER, ABA, ENUM]

Example: AMOUNT

startPositioninteger

1-based character start position (fixed-width only)

Example: 1

lengthinteger

Field length in characters (fixed-width only)

Example: 17

columnIndexinteger

0-based column index (CSV/delimited without header)

Example: 0

columnNamestring

Column header name (CSV/delimited with hasHeader: true)

Example: ACCT_NO

pathstring

XPath (XML) or JSONPath (JSON) expression

Example: $.payment.accountNumber

xmlAttributestring

XML attribute name (XML only)

requiredboolean

Whether the field must be present

Default value: true

nullableboolean

Whether an empty/null value is acceptable

Default value: false

defaultValuestring

Value to use when field is absent or null

formatstring

Date/number format pattern (e.g. yyyyMMdd, #,##0.00)

Example: yyyyMMdd

scaleinteger

Decimal places for AMOUNT/DECIMAL fields

Example: 2

validationRegexstring

Regular expression the field value must match

Example: ^[0-9]{9}$

minLengthinteger

Minimum string length

maxLengthinteger

Maximum string length

Example: 17

allowedValuesstring[]

Whitelist of accepted values

sensitiveboolean

PII flag — value will be masked in logs and traces

Default value: false

descriptionstring

Optional documentation for this field

]

validationRules object[]

Post-parse validation rules

Array [

ruleIdstringrequired

Unique identifier for this rule within the spec

Example: vr-001

fieldstringrequired

Name of the field this rule applies to

Example: amount

ruleTypeRuleType (string)required

Type of validation rule

Possible values: [NOT_NULL, NOT_EMPTY, MIN_LENGTH, MAX_LENGTH, EXACT_LENGTH, REGEX, MIN_VALUE, MAX_VALUE, BETWEEN, ALLOWED_VALUES, CUSTOM_EXPRESSION, CROSS_FIELD]

Example: MIN_VALUE

valuestring

Primary comparison value (e.g. min value, regex pattern, allowed list)

Example: 0

secondaryValuestring

Upper bound for BETWEEN rules

Example: 999999

messagestringrequired

Human-readable error message when the rule fails

Example: Amount must be non-negative

severitySeverity (string)

Severity level of a validation error

Possible values: [INFO, WARNING, ERROR, FATAL]

Example: ERROR

]

correctionRules object[]

Auto-correction rules applied before/after validation

Array [

ruleIdstringrequired

Unique identifier for this rule within the spec

Example: cr-001

fieldstringrequired

Name of the field to correct

Example: account_number

correctionTypeCorrectionType (string)required

Type of auto-correction to apply

Possible values: [TRIM, TRIM_LEADING, TRIM_TRAILING, UPPERCASE, LOWERCASE, TITLE_CASE, DATE_FORMAT_COERCE, NUMBER_FORMAT_COERCE, DEFAULT_IF_NULL, DEFAULT_IF_EMPTY, PAD_LEFT, PAD_RIGHT, REMOVE_SPECIAL_CHARS, REGEX_REPLACE]

Example: TRIM

valuestring

Correction parameter (e.g. default value, replacement string, pad character)

Example: 0

applyOrderinteger

Execution order when multiple corrections apply to the same field (lower = first)

Default value: 0

Example: 1

]

outputSpec object

Describes the output format when transforming from one file format to another

formatFileFormat (string)required

Supported file formats

Possible values: [CSV, FIXED_WIDTH, XML, JSON, NACHA, ISO20022, SWIFT_MT, DELIMITED, CUSTOM]

Example: DELIMITED

delimiterstring

Field delimiter for delimited output formats

Example: ,

encodingstring

Default value: UTF-8

Example: UTF-8

hasHeaderboolean

Whether to write a header row

Default value: false

fieldMappings object[]

Field-level mapping and transformation rules

Array [

sourceFieldstringrequired

Name of the field in the input spec

Example: account_number

targetFieldstringrequired

Name of the field in the output spec

Example: accountNo

transformationstring

Optional SpEL expression to transform the value

Example: #value.substring(0, 9)

]

metadata object

Arbitrary key-value metadata (owner, environment, tags, etc.)

property name*string

CreateSpecRequest

{
  "name": "acme-payments-v2",
  "description": "ACME Corp daily payment file, pipe-delimited",
  "version": "2.0",
  "format": "DELIMITED",
  "encoding": "UTF-8",
  "hasHeader": false,
  "delimiter": "|",
  "skipLinesCount": 2,
  "fields": [
    {
      "name": "account_number",
      "displayName": "Account Number",
      "type": "AMOUNT",
      "startPosition": 1,
      "length": 17,
      "columnIndex": 0,
      "columnName": "ACCT_NO",
      "path": "$.payment.accountNumber",
      "xmlAttribute": "string",
      "required": true,
      "nullable": false,
      "defaultValue": "string",
      "format": "yyyyMMdd",
      "scale": 2,
      "validationRegex": "^[0-9]{9}$",
      "minLength": 0,
      "maxLength": 17,
      "allowedValues": [
        "string"
      ],
      "sensitive": false,
      "description": "string"
    }
  ],
  "validationRules": [
    {
      "ruleId": "vr-001",
      "field": "amount",
      "ruleType": "MIN_VALUE",
      "value": "0",
      "secondaryValue": "999999",
      "message": "Amount must be non-negative",
      "severity": "ERROR"
    }
  ],
  "correctionRules": [
    {
      "ruleId": "cr-001",
      "field": "account_number",
      "correctionType": "TRIM",
      "value": "0",
      "applyOrder": 1
    }
  ],
  "outputSpec": {
    "format": "DELIMITED",
    "delimiter": ",",
    "encoding": "UTF-8",
    "hasHeader": false,
    "fieldMappings": [
      {
        "sourceField": "account_number",
        "targetField": "accountNo",
        "transformation": "#value.substring(0, 9)"
      }
    ]
  },
  "metadata": {
    "owner": "payments-team",
    "environment": "production"
  }
}