Transforms

A transform normalises a value as it passes through. Declare them on a field, a type or a trait, and they run in the order written.

fields:
  - name: email
    type: string
    transforms:
      - type: trim
      - type: lowercase

Every transform takes an optional params map, a transform that cannot handle the value it is given returns it unchanged rather than failing, a numeric transform on a string leaves the string alone. That keeps one bad row from failing a whole write, and it means a transform that silently does nothing is usually a type mismatch.

Whitespace

Transform	Params	Effect
trim	—	Removes leading and trailing whitespace
ltrim	—	Leading only
rtrim	—	Trailing only
strip_whitespace	—	Removes all whitespace, not just the ends
collapse_whitespace	—	Runs of whitespace become a single space

Case and wording

Transform	Params	Effect
lowercase	—	hello world
uppercase	—	HELLO WORLD
capitalize	—	First character upper, rest untouched
title	—	First Character Of Each Word
sentencecase	—	First character of the sentence only
camelcase	—	helloWorld
snakecase	—	hello_world
kebabcase	—	hello-world
slug	—	URL-safe: lowercased, non-alphanumerics to hyphens

Editing text

Transform	Params	Effect
prefix	value	Prepends
suffix	value	Appends
replace	find, replace	Replaces every occurrence
regex_replace	expression, replace	Regular-expression replace. An uncompilable pattern leaves the value unchanged
truncate	length, ellipsis	Cuts to length; ellipsis: true appends …
pad_left	length, char	Pads to length
pad_right	length, char	Pads to length
strip_html	—	Removes tags, keeps text
mask_partial	start, end, char	Keeps start leading and end trailing characters, masks the middle

mask_partial is the one to reach for on a stored identifier you still need to recognise, 4111********1111. For hiding a value from a reader rather than changing it, use the mask compliance instead: a transform rewrites what is stored, a compliance governs who sees it.

Nulls and defaults

Transform	Params	Effect
emptyasnull	—	An empty string becomes null
nullasempty	—	Null becomes an empty string
nullasdefault	value	Null becomes value

Useful when a source system disagrees with your schema about which of empty and null means “absent”.

Type coercion

Transform	Params	Effect
tostring	—	To text
tointeger	—	To a whole number; trims first
todouble	—	To a float; trims first
toboolean	—	Case-insensitive; trims first
todate	format	Parses to a date; defaults to RFC 3339

Numbers

Transform	Params	Effect
round	precision	Nearest, to precision decimal places
ceil	precision	Upward
floor	precision	Downward
abs	—	Absolute value
clamp	min, max	Constrains to the range. Either bound may be omitted
format_number	format	Formats for display

Dates

Transform	Params	Effect
format_date	format	Reformats; RFC 3339 in, format out

Encoding

Transform	Params	Effect
base64_encode / base64_decode	—	Base64
url_encode / url_decode	—	Query-string escaping
html_encode / html_decode	—	HTML entity escaping
hex_encode / hex_decode	—	Hexadecimal

Hashing

Transform	Params	Effect
hash	algorithm	Named algorithm
hash_md5, md5	—	MD5
hash_sha1	—	SHA-1
hash_sha256	—	SHA-256
hash_sha512, sha512	—	SHA-512
hmac	algorithm, key	Keyed hash

Caution

A hash transform is one-way and applied on write: the original is not stored. That is the point for a value you must compare but never read back, and a mistake for anything you will need again. For a value that must be recoverable, use the encrypted compliance instead.

MD5 and SHA-1 are present for interoperability with systems that already use them. Do not choose them for anything new.

Identifiers

Transform	Params	Effect
uuid_v4	—	Generates a random UUID
ulid_generate	—	Generates a ULID: time-ordered, so it sorts by creation

JSON

Transform	Params	Effect
json_stringify	—	Value to JSON text
json_parse	—	JSON text to a value
json_extract	path	Pulls one path out of a JSON value

Collections

Transform	Params	Effect
split	separator	Text to a list
join	separator	List to text
distinct	—	Removes duplicates
sort	direction	Sorts; case-insensitive for text
flatten	depth	Flattens nested lists to depth

Custom

Transform	Params	Effect
custom	expression, language	Runs a script against the value

Use this when nothing above fits. Anything you would write more than twice belongs in a shared type or trait rather than repeated inline, see Types and Traits.

Order matters

Transforms run top to bottom, and the wrong order is a real bug rather than a style question:

transforms:
  - type: trim          # " Hello World " → "Hello World"
  - type: lowercase     #                 → "hello world"
  - type: slug          #                 → "hello-world"

Reverse the trim and the slug and the leading space becomes a leading hyphen.

Where to declare them

Level	Applies to	Use when
Field	That field	One-off normalisation
Type	Every field of that type	The rule belongs to the concept, not the column
Trait	Every entity pulling the trait in	The rule travels with a field set

Prefer the highest level that is still true, a lowercase on an email type is applied everywhere an email exists; the same transform copied onto nine fields is eight chances to forget the tenth.

See also

• Fields: declaring fields and their options
• Types: reusable field types
• Field protection: compliances, which govern access rather than content
• Validations: rejecting a value rather than changing it