入力値を正規化する

全角→半角、トリムなど、保存前に値を整える。

入力された値を整えてから扱いたいときは normalize に変換の名前を並べる。

fields:
  - { field: code, label: コード, type: text, normalize: [toHankaku, trim] }
  - { field: zip,  label: 郵便番号, type: text, normalize: [toHankaku],
      validators: [ { type: postalCode } ] }

検証より先に走る

順番が重要。normalize → validators の順なので、全角で入力されても半角に直してから形式チェックにかかる。上の例なら「１２３－４５６７」と打たれても郵便番号として通る。

逆にすると「全角だから形式違反」で弾かれ、利用者は何が悪いのか分からない。この順序のおかげで「全角で入れないでください」という注意書きが要らなくなる。

並べた順に適用される

配列なので順番がある。[toHankaku, trim] は「半角に直してから前後の空白を取る」。逆順でも結果はだいたい同じだが、変換によっては効き方が変わるので、広い変換から狭い変換の順に書くと考えやすい。

何が使えるか

変換	何をするか	よく使う場面
toHankaku	全角英数字→半角	コード、電話番号、郵便番号、数量
toZenkaku	半角→全角	氏名カナを全角で揃える
hiraToKata / kataToHira	ひらがな⇔カタカナ	カナ検索用の項目
trim	前後の空白を取る	ほぼ全部のテキスト項目
collapseSpaces	連続する空白を1つに	住所、会社名
parseNumber	数字として読める形にする	カンマ付きで入力される金額

業務システムで一番効くのは toHankaku と trim の組み合わせ。コピー&ペーストで入る余計な空白と、全角で打たれた数字は、放っておくとデータが揃わない原因の大半になる。

変換した値が保存される

画面の表示だけを変えるのではなく、変換後の値が実際にデータとして渡る。見せ方だけ変えたいなら normalize ではなく format を使う。

やりたいこと	使うもの
入ってくる値を揃えたい（保存する値が変わる）	normalize
保存する値は変えず、見せ方だけ整えたい	format

同じ変換がバックエンドでも動く

正規化の実装は Dart / TypeScript / Java の3言語に同名で用意されていて、出力が一致することがテストで担保されている。画面を通らずに API を叩かれても、サーバ側で同じ正規化ができる。

足りない変換は足す

normalize の名前も開いた文字列なので、社内のコード整形ルールなどは名前を決めて登録すれば書けるようになる。

書けるキー

キー	書く場所	型	必須	既定値	有効なページ種別	説明
normalize	field	array of string （toHankaku / toZenkaku / hiraToKata / kataToHira / trim / collapseSpaces / parseNumber ほか）	任意	—	crud dashboard detail form master report search wizard	Input converters applied before validation. Built-ins: toHankaku, toZenkaku, hiraToKata, kataToHira, trim, collapseSpaces, parseNumber.

この表は spec/reference.json から生成している（JSON Schema が正）。手元では npx hatake reference <キー名> で同じものが引ける。

近い例

例は丸ごと写して直すのが一番速い。以下は CI で検証済み（そのまま動く形）。

ファイル	種別	画面	どういうときに使うか
customer_form.yaml	form	顧客入力	一覧を持たない単票の入力画面が欲しい（新規と編集を1枚で）
customer_wizard.yaml	wizard	顧客登録	項目が多いので入力をステップに分けて、1ステップずつ検証したい

実物を見る

デモアプリの「顧客マスタ」がこれを使っている。 デモを開く