Skip to content

Declarative Documents

themarioga edited this page Nov 8, 2026 · 1 revision

Declarative Documents (YAML/JSON)

A definition can be written as a JSON or YAML document with the structure of Integration Definitions in camelCase and version: 1 at the root.

IntegrationDefinition fromYaml = DefinitionLoader.fromYaml(inputStream);   // or a String
IntegrationDefinition fromJson = DefinitionLoader.fromJson(inputStream);

Equivalent JSON and YAML documents produce equal definitions (equals), and both are equal to the same definition built with the Java API.

A complete example

version: 1
id: altas
direction: IMPORT
deliveryStrategy: VALIDATE_THEN_DELIVER
rejectionThreshold: { maxRejected: 50, maxRejectedPercent: 5 }
consumerErrorPolicy: ABORT_FILE
duplicateProtection:
  watermark: true
  postSuccessAction: { type: MOVE, remoteFolder: done }   # or NONE, or DELETE
resultReport:
  mode: REJECTED
  format: XLSX
  channel: { type: LOCAL_DIRECTORY, directory: /data/reports, onExistingFile: SUFFIX }
  namePattern: "{sourceName}_{layout}_result"
inputChannels:
  - type: SFTP
    host: sftp.example.com
    port: 22
    username: tie
    password: ${secret:sftp}
    remoteDirectory: /in
    knownHostsFile: /etc/tie/known_hosts
    timeout: PT30S
  - PROVIDED_STREAM
layouts:
  - name: alta
    fileNamePattern: alta_{tenant}_{timestamp:yyyyMMddHHmmss}
    allowedFormats: [CSV, XLSX]
    formatOptions:
      csv:  { separator: ";", encoding: ISO-8859-1 }
      xlsx: { sheet: Altas }
    columnLocation: HEADER
    fields:
      - name: nif
        textTransforms: [UPPER, { type: PAD_LEFT, length: 9, char: "0" }]
        validations: { regex: "[0-9]{8}[A-Z]" }
      - name: sex
        translations:
          - { from: M, to: Male }
          - { from: F, to: Female }
          - { from: X, to: null, direction: IN }
        onUnmatched: ERROR
      - { name: amount, type: DECIMAL, typeFormat: { decimalSeparator: ",", groupingSeparator: "." } }
      - { name: born, type: DATE, typeFormat: dd/MM/yyyy }
      - { name: active, type: BOOLEAN, typeFormat: { trueLiteral: S, falseLiteral: N } }
      - { name: country, inInput: false, defaultValue: ES }

Writing rules

  • Polymorphic values are objects with type: channels (SFTP, LOCAL_DIRECTORY, PROVIDED_STREAM), post-success actions (NONE, MOVE, DELETE), text transforms (UPPER, LOWER, STRIP_ACCENTS, PAD_LEFT, PAD_RIGHT).
  • A value without parameters can be a plain string: UPPER, DELETE, PROVIDED_STREAM. MOVE and PAD_LEFT need their object form.
  • typeFormat is recognised by its shape: a string is a date pattern; {decimalSeparator, groupingSeparator} a number format; {trueLiteral, falseLiteral} boolean literals.
  • formatOptions is a map per format: csv, xlsx, xml, json.
  • Durations are ISO-8601: timeout: PT30S. A bare number is an error.
  • null is not accepted, except for the to of a translation, where it means "translate to empty".
  • Secrets are written as ${secret:name} and resolved by your SecretProvider when connecting. Literal credentials are accepted, but not recommended.

Errors

Every problem is reported at once, with the path of the property:

layouts[0].fields[0]: unknown property 'colum'
inputChannels[0].port: expected an integer, got '22'
inputChannels[0].timeout: expected an ISO-8601 duration such as PT30S, got 30
layouts[0].allowedFormats[2]: expected one of CSV, XLSX, XML, JSON, got 'TXT'
version: unsupported version 2 (expected 1)

After mapping, the definition goes through the same validation as Tie.validate (minus the SPI checks, which need a Tie). Duplicate keys and trailing content are errors. A syntax error gives its line and column, never an excerpt of the document, so a credential never ends up in a message.

JSON schema

The schema (JSON Schema 2020-12) is in the jar:

try (InputStream schema = DefinitionLoader.schema()) { … }   // /tie-definition.schema.json

Use it in your editor for completion and checks while writing documents. It covers the structure (properties, types, enums, required values); cross-field rules (copy cycles, thresholds and strategies, …) are only checked by the loader.

Clone this wiki locally