Transform Reference

ODIN as a Canonical Data Model

ODIN serves as the Canonical Data Model (CDM) for all transformations. Regardless of source and target formats, data flows through ODIN as the intermediate representation.

Why ODIN as CDM?

• Type Preservation, ODIN's self-describing types (#, ##, #$, ?, @, ^, ~) preserve semantic meaning
• Modifier Flow, Field modifiers (! critical, * confidential, - deprecated) travel with data
• Canonical Form, Enables hashing, signatures, and deduplication
• Schema Validation, ODIN Schema validates the canonical form

A transform declared as json->json actually executes as json->odin->json.

Document Structure

Transform documents use the .transform.odin extension and include several standard headers. The {$source} section describes the incoming data format, while {$target} controls how the output is rendered.

{$source}
schema = org.odin.auto.policy/1.0.0
format = "json"
discriminator = @.recordType      ; For multi-record-type inputs

{$target}
format = json
encoding = utf-8
indent = ##2

The discriminator enables multi-record processing, when input contains mixed record types, the engine routes each record to the matching segment based on the discriminator field value.

Confidential Field Enforcement

The :confidential modifier flags a field as containing sensitive information, Social Security numbers, API keys, medical records, financial account numbers, or any data subject to privacy regulations. On its own, the modifier does not alter values. It travels with the data as metadata, signaling to downstream systems, loggers, and audit trails that the field requires special handling.

{Customer}
SSN = @.ssn :confidential              ; Flagged, value passes through unchanged
API_Key = @.apiKey :confidential       ; Downstream systems know to mask in logs
Name = @.name                          ; Not confidential, no special handling

When you need the transform itself to protect confidential values before they leave, set enforceConfidential in the header. This activates enforcement -- every field marked :confidential will have its value redacted or masked in the output.

{$}
enforceConfidential = "redact"   ; or "mask"

{Customer}
SSN = @.ssn :confidential          ; Value becomes null (redact) or "***-**-****" (mask)
Name = @.name                      ; Not confidential, passes through normally

This two-layer design lets you flag fields once and control enforcement per transform. A transform feeding an internal data warehouse might leave values intact (just flagged), while a transform generating a partner export redacts them.

Constants & Accumulators

Constants define reusable values that stay fixed throughout the transform. Use them for default values, version strings, or any value referenced in multiple places -- change it once in the header instead of hunting through mappings.

{$const}
DEFAULT_STATE = "TX"
POLICY_VERSION = "2024.1"
MAX_VEHICLES = ##10

; Reference with @$const.NAME
state = @policy.state :default @$const.DEFAULT_STATE

Accumulators are mutable counters that update as the transform processes records. They're useful for running totals, record counts, and summary fields that appear in headers or trailers.

{$accumulator}
record_count = ##0
premium_total = #$0.00

; Update with %accumulate
_ = %accumulate record_count ##1
_ = %accumulate premium_total @coverage.premium

; Read with @$accumulator.name
total_records = @$accumulator.record_count

Lookup Tables

Lookup tables embed reference data directly in the transform, replacing what would otherwise require database joins or external API calls. Define columns in the header, then use %lookup to search by any column and return any other column.

{$table.STATUS[name, code]}
active, "A"
pending, "P"
cancelled, "C"

; Lookup by name, return code
status_code = %lookup STATUS.code @.statusName

; Reverse lookup (same syntax)
status_name = %lookup STATUS.name @.statusCode

{$table.TERRITORY[state, zip_prefix, territory, region]}
TX, 787, "AUSTIN", "CENTRAL"
TX, 750, "DALLAS", "NORTH"

; Match on multiple columns
territory = %lookup TERRITORY.territory @.state @.zipPrefix

Direct Copy

The @ symbol copies a value from the source data to the target field. Use dot notation to navigate nested objects.

policy_number = @policy.number
insured_name = @insured.name.last

Constant Values

Assign literal values directly. Strings use quotes, integers use ##, numbers use #, and currency uses #$.

record_type = "01"
count = ##0
amount = #$100.00

Transformations

The % symbol invokes a built-in verb that transforms the value. Verbs take source paths, literals, or other verb results as arguments.

effective = %formatDate @policy.effective "YYYYMMDD"
name = %concat @name.last ", " @name.first
code = %lookup STATUS @policy.status

Nested verbs evaluate inner-to-outer:

display_name = %upper %concat @first " " @last

Modifiers follow the value expression:

policy_number = @policy.number :pos 0 :len 15 :rightPad " "
state = @policy.state :default "TX"
amount = @premium :required

Positioning Modifiers (Fixed-Width)

policy_number = @policy.number :pos 0 :len 15 :rightPad " "
year = @vehicle.year :pos 15 :len 4 :leftPad "0"

XML Modifiers

{Policy}
id = @policy.id :attr
Number = @policy.number
Description = @policy.description :cdata
Notes = @policy.notes :omitEmpty

JSON Modifiers

year = @vehicle.year :type number           ; "2024" -> 2024
active = @is_active :type boolean           ; "true" -> true
code = @zip :type string                    ; 78701 -> "78701"

contact = :object {name = @insured.name, phone = @insured.phone}

Conditional Modifiers

state = @policy.state :default "TX"
premium = @premium :required
discount = @discount :if hasDiscount
legacy_field = @old_field :unless isNewFormat

Validation Modifiers

email = @contact.email :validate "^[^@]+@[^@]+$"
status = @status :enum "A,P,C"
year = @year :range 1900..2100

JSON is the most common target format. These options control how the output handles whitespace, null values, and empty collections.

{$target}
format = json
indent = ##2           ; Pretty-print with 2-space indentation
nulls = omit           ; Drop fields with null values from output
emptyArrays = include  ; Keep empty arrays ([] ) in output

XML output supports declarations, namespaces, and element-level control. Use field-level :attr and :cdata modifiers (see Field Modifiers above) to control how individual values are rendered.

{$target}
format = xml
declaration = true     ; Include <?xml version="1.0"?> at top
indent = ##2           ; Pretty-print with 2-space indentation
omitEmpty = true       ; Skip elements with no value

{$target.namespace}
ins = http://www.example.org/insurance/xml/

Namespaces are declared in a separate {$target.namespace} section. Each entry maps a prefix to a URI. Fields in the transform can then use :ns prefix to assign elements to a namespace.

CSV output writes one row per record. The field order in the transform determines column order. Use header to control whether a header row with field names is written first.

{$target}
format = csv
delimiter = ","        ; Field separator (comma, pipe, tab, etc.)
quote = "\""          ; Character used to wrap fields containing delimiters
header = true          ; Write a header row with column names
lineEnding = \n       ; Line ending (\n or \r\n)

Fixed-width output produces records where each field occupies an exact number of characters. This format is common in insurance, banking, and government data exchange (ACORD, NACHA, EDI). Use :pos and :len modifiers on individual fields to control positioning.

{$target}
format = fixed-width
lineWidth = ##200      ; Total characters per line
padChar = " "          ; Fill unused positions with spaces
truncate = true        ; Truncate values that exceed :len
lineEnding = \r\n    ; CRLF line endings (common in mainframe formats)

Error Configuration

Error settings control how the transform engine responds to problems during execution. These apply across all formats and determine whether a bad field stops the entire transform, produces a warning, or is silently skipped.

{$target}
onError = fail       ; fail | warn | skip
onMissing = skip     ; fail | warn | skip | default
onValidation = fail  ; fail | warn | skip

Key Interactions

• :required overrides onMissing, always fails if missing
• :default "value" provides fallback when onMissing = default
• :optional explicitly marks field as skippable