/note/tech

入力チェック仕様の書き方 単項目・相関チェック一覧とテンプレート

要約:

■ 1. 入力チェック仕様の位置づけ

  • 入力チェック仕様とは:
    • 画面やAPIが受け取る値の確認方法を表にまとめた設計書
    • どの項目に、どの条件を、どの順番で、どの層で確かめるかを定める
    • 合わないときにどのメッセージを出すかも定める
  • 1項目1行の表:
    • 型、必須、桁数、文字種、範囲、形式、相関条件、エラーメッセージID、実施層を列に並べる
    • 実装する人とテストする人が同じ表を見て作業できる
  • 本記事の範囲:
    • 仕様書テンプレートと記入例、単項目チェック20種、相関チェック10種の一覧を掲載
    • 各チェックの正規表現と境界値テストケースはすべてPythonで動かした出力を掲載
    • フレームワークごとの実装方法には触れず、仕様の書き方に絞る
    • 確認環境はUbuntu 24.04、Python 3.11.15の標準ライブラリのみ

■ 2. 仕様で決めることの早見表

  • 対象:
    • 画面ID、項目名、物理名を書く(例: R-010 予約登録、利用開始日、start_date)
  • 型:
    • 文字列、整数、小数、日付、時刻、コードのいずれかを書く
  • 必須:
    • 必須、任意、条件付き必須のいずれかを書く(例: 条件付き(C03))
  • 桁数:
    • 最小〜最大を書き、文字数かバイト数かを明記する(例: 1〜50文字)
  • 文字種:
    • 許可する文字の集合を書く(例: 半角英大文字・数字・ハイフン)
  • 範囲:
    • 最小値、最大値と境界を含むかどうかを書く(例: 1以上99以下)
  • 形式:
    • 書式または正規表現を書く(例: YYYY-MM-DD、実在する日付)
  • 相関条件:
    • ほかの項目との関係を書く(例: 利用開始日 ≦ 利用終了日)
  • エラーメッセージID:
    • 文言の一覧と対応づけるIDを書く(例: E-REL-001)
  • 実施層:
    • 画面、サーバー、DB制約のどこで行うかを書く
  • 実行順:
    • 単項目 → 相関 → DB照合の順とし、前の段でエラーなら後ろの段は行わない

■ 3. 入力チェックの3つの段

  • 段の分け方:
    • 見る範囲の広さで3つの段に分けて書くと整理しやすい
  • 単項目チェック:
    • その値だけを見て判定できるもの(必須、桁数、文字種、形式、範囲)
    • 仕様書では項目ごとの行の型〜形式の列に書く
  • 相関チェック:
    • 同じ入力のほかの値がないと判定できないもの(日付の前後、条件付き必須、合計一致)
    • 仕様書では相関条件の列と相関チェック一覧に書く
  • DB照合チェック:
    • 保存済みのデータを読まないと判定できないもの(マスタ存在、重複、予約の重なり)
    • 仕様書ではDB照合チェック一覧に書く
  • 区切りの効果:
    • 上記の基準で区切ると、どの表に書くかで迷わない

■ 4. 項目別チェック仕様のテンプレート

  • 基本ルール:
    • 列は12個とする
    • 空欄にするときは「―」を入れ、書き漏れと区別する
  • 識別系の列:
    • Noは画面の表示順に振る連番
    • 項目名は画面に表示するラベルで、メッセージに埋め込む名前と同じにする
    • 物理名はリクエストの項目名で、APIのキー名やフォームのnameと一致させる
  • 型・必須・桁数の列:
    • 型はDBの型ではなく入力値としての型を書く
    • 条件付き必須の場合は相関チェックIDを書く
    • 桁数の単位(文字・バイト)は表の注記に書く
  • 文字種・範囲・形式の列:
    • 文字種は「半角数字」「全角カタカナ」など一覧の呼び名で統一する
    • 範囲・選択肢は「以上・以下」で境界を含むことを示す
    • 形式は単項目チェック一覧のID(S15など)を書く
  • 相関条件・メッセージ・実施層の列:
    • 相関条件はC01などのIDを書き、内容は相関チェック一覧に書く
    • エラーメッセージIDは複数あるときチェックの順に並べる
    • 実施層は行う層に○を付け、DBは制約名を書く
  • 表計算ソフトへの貼り付け:
    • テンプレートはタブ区切りで提供し、1行目が見出し、2行目以降が記入例

■ 5. 記入例: 備品予約システムの予約登録画面

  • 前提:
    • 架空の社内備品予約システムの予約登録画面(R-010)を題材とする
    • 桁数の単位は文字数とする
    • 前後の空白はチェックの前に取り除く
  • 備品コード(item_code):
    • 必須、6文字固定、英大文字2桁-数字3桁の形式
    • DBでは外部キーで守る
  • 利用開始日・利用終了日(start_date、end_date):
    • 必須、10文字固定、日付形式S15、相関条件はC01とC02
    • 利用開始日は範囲として当日以降を設定する
  • 数量(qty):
    • 必須の整数で1以上99以下、形式はS12とS14、相関条件はC08
  • 利用目的(purpose):
    • 必須のコード値で、選択肢はMEETING、EVENT、OTHER
  • 備考(note):
    • C03による条件付き必須、0〜200文字で制御文字以外を許可
  • 申請者氏名カナ(applicant_kana):
    • 必須、1〜40文字の全角カタカナ
  • 連絡先メールと確認用:
    • C05による条件付き必須、6〜254文字、形式はS17
    • 確認用メールは一致チェック(C06)のみに使い、DBには保存しない
  • 連絡先電話番号(phone):
    • C05による条件付き必須、12〜13文字、形式はS18

■ 6. 相関チェックとDB照合チェックの仕様

  • 書き方:
    • 項目別の表とは別に「1チェック1行」で書く
    • ID、段、対象項目、合格となる条件、表示先、エラーメッセージIDを列にする
  • 表示先の決定:
    • エラーをどの項目に表示するかを必ず決めておく
    • 画面の実装とテストの期待結果がそろう
  • 記入例の相関チェック:
    • C01は利用開始日 ≦ 利用終了日で、表示先は利用終了日
    • C02は開始日と終了日を含めて14日以内で、表示先は利用終了日
    • C03は利用目的がOTHERのとき備考が空でないことで、表示先は備考
    • C05は連絡先メールか電話番号のどちらかが入力されていることで、表示先は連絡先メール
    • C06はメールと確認用メールが完全に一致することで、表示先は確認用メール
  • 記入例のDB照合チェック:
    • D01は備品コードが備品マスタに存在することで、表示先は備品コード
    • D02は同じ備品の予約と期間が重ならないことで、表示先は利用開始日

■ 7. エラーメッセージ一覧

  • IDによる参照:
    • 文言は仕様書の各行に直接書かず、IDで参照する
    • 同じ文言を複数の画面で使い回せる
    • 文言の見直しも1か所で済む
  • 埋め込み値:
    • {0}には項目名、{1}以降には桁数や範囲の値を入れる
  • 文言の例:
    • E-REQ-001は「{0}を入力してください」(必須)
    • E-LEN-001は「{0}は{1}文字以上{2}文字以内で入力してください」(文字数)
    • E-FMT-001は「{0}はYYYY-MM-DD形式の実在する日付で入力してください」(日付)
    • E-RNG-001は「{0}は{1}以上{2}以下で入力してください」(数値範囲)
    • E-REL-001は「{0}は{1}以降の日付を入力してください」(日付の前後)
    • E-DB-002は「指定された期間はすでに予約されています」(期間の重なり)
    • ほかに文字種、整数、個別形式、メール、電話番号、コード値、期間上限、条件付き必須、存在チェック用を用意
  • IDの付け方:
    • 「種別3文字+連番」にすると、IDを見ただけでチェックの種類がわかる
    • REQ=必須、LEN=桁数、CHR=文字種、FMT=形式、RNG=範囲
    • COD=コード値、REL=相関、DB=DB照合

■ 8. 単項目チェック20種の一覧

  • 前提:
    • 仕様書の「形式」列からIDで参照できるよう20種にまとめる
    • 正規表現は文字列全体に一致するか(Pythonのre.fullmatch)で判定する
    • 境界値テストケースは検算スクリプトで実際に判定した値
  • 必須・桁数系:
    • S01 必須は空白を除いて1文字以上で、空文字、半角空白のみ、全角空白のみ、値なしはエラー
    • S02 最大文字数(20)は19文字、20文字、空文字が合格し、21文字がエラー
    • S03 最小文字数(8)は8文字、9文字が合格し、7文字がエラー
    • S04 固定文字数(6)は6文字のみ合格し、5文字と7文字がエラー
    • S05 最大バイト数(30)はUTF-8で判定し、全角10文字(30バイト)は合格、全角10文字+半角1文字はエラー
  • 文字種系:
    • S06 半角数字は[0-9]+で、全角数字、英字混じり、-1、末尾の改行はエラー
    • S07 半角英数字は[0-9A-Za-z]+で、ハイフン、全角英字、空白を含むとエラー
    • S08 パスワードは英小文字、英大文字、数字を各1文字以上含む8〜64文字の半角記号英数字
    • S09 全角カタカナは[ァ-ヶー]+で、ひらがな、半角カナ、空白を含むとエラー
    • S10 コード値は許可した値の一覧に含まれることで、小文字や一覧外の値はエラー
    • S11 制御文字なしはUnicodeカテゴリCcを含まないことで、タブ、改行、NUL文字はエラー
  • 数値系:
    • S12 整数形式は-?(0|[1-9][0-9]*)で、012、1.0、+5、空文字はエラー、-0は合格
    • S13 小数形式は整数5桁・小数2桁までで、100000、1.555、.5、1.はエラー
    • S14 数値範囲(1〜99)は整数形式かつ範囲内で、0と100がエラー
  • 日付・時刻系:
    • S15 日付は[0-9]{4}-[0-9]{2}-[0-9]{2}かつ暦に存在することで、2028-02-29は合格
    • S15では2026-02-29、2026-13-01、2026-04-31、2026/10/05がエラー
    • S16 時刻(HH:MM)は00:00と23:59が合格し、24:00、12:60、9:00がエラー
  • 連絡先・URL系:
    • S17 メールアドレス(簡易)は254文字以内かつ簡易な正規表現に一致すること
    • S18 電話番号はハイフンありで先頭0、数字が10桁か11桁であること
    • S19 郵便番号は[0-9]{3}-[0-9]{4}で、ハイフンなし、桁不足、全角数字はエラー
    • S20 URLはhttp/httpsのみ許可し、ftp://、ホストなし、空白を含むとエラー
  • 形式だけでは決まらない扱い:
    • S12やS14の-0、S15の「当日以降」のような扱いは「範囲」の列で決める
  • メールアドレスの扱い:
    • 形式を厳密に追うほど正規表現が長くなる
    • 仕様には「簡易な形式チェック+確認メールの到達で確かめる」と書くのが扱いやすい
  • 検算結果:
    • Pythonスクリプトで20種109ケースを判定し、期待との不一致は0件

■ 9. 正規表現を仕様に書くときの注意

  • 照合方法の明記:
    • 「どの方法で照合するか」まで決めておくと実装のぶれがなくなる
  • 末尾の改行:
    • Pythonのre.matchで^[0-9]+$を使うと、末尾に改行が付いた「123\n」も一致する
    • 仕様には「文字列全体に一致」と明記し、re.fullmatchで照合する
  • \dの範囲:
    • Pythonの\dは全角数字の「123」にも一致する
    • 半角数字は[0-9]と書く
  • 文字数とバイト数:
    • 「あいう」は3文字でUTF-8では9バイト
    • 「𠮷」は1文字でUTF-8では4バイト、UTF-16では2単位
    • 桁数の単位と、数える側(画面、サーバー、DB)を注記する

■ 10. 相関チェック10種の一覧

  • 書き方:
    • 「合格となる条件」を1文で書き、境界になる組み合わせをテストケースにする
  • 日付・期間系:
    • C01 日付の前後は開始日 ≦ 終了日で、終了日が翌日と同日は合格、前日はエラー
    • C02 期間の上限は両端を含めて14日以内で、13日間と14日間は合格、15日間はエラー
  • 条件付き系:
    • C03 条件付き必須は目的がOTHERなら備考が空でないことで、OTHER+備考なしがエラー
    • C04 条件付き入力不可は利用者区分がGUESTなら部署コードが空であることで、GUEST+部署ありがエラー
    • C05 いずれか必須は電話番号かメールのどちらかが入力されていることで、両方空がエラー
  • 一致・不一致系:
    • C06 一致はメールと確認用メールが完全に一致することで、大文字と小文字の違いもエラー
    • C07 不一致は新しいパスワードが現在のパスワードと異なることで、同じ値がエラー
  • 数量・明細系:
    • C08 合計一致は明細の数量の合計が合計数量と等しいことで、明細0件で合計0も合格
    • C09 大小関係は最小数量 ≦ 最大数量で、同じ値は合格、最小が1大きいとエラー
    • C10 明細の重複なしは明細に同じ備品コードがないことで、同じコードが2行あるとエラー
  • 検算結果:
    • Pythonスクリプトで10種27ケースを判定し、期待との不一致は0件
  • 期間の数え方:
    • 「14日以内」は両端の日を含めるかどうかで1日ずれる
    • 検算スクリプトは「終了日−開始日+1」で数え、10月5日〜18日は14日間で合格、19日までは15日間でエラー
    • 仕様書には「開始日と終了日を含めて」のように数え方を書く

■ 11. チェックの実行順

  • 単項目→相関→DB照合の順:
    • ある段でエラーが出たら後ろの段へは進まないと決めておく
  • この順序の利点:
    • 相関チェックは各項目が正しい型である前提で書ける(日付として読めない値どうしは比べられない)
    • DBへの問い合わせは形式が正しい入力のときだけ行えば済む
    • 同じ段の中のエラーはまとめて返せるので、利用者は一度に直せる
  • 段ごとの扱い:
    • 0段目の前処理として、空白除去や全角・半角変換を行うならここで行うと仕様に書く
    • 単項目は全項目のエラーをまとめて返す
    • 単項目の1項目内では必須→桁数→文字種→形式→範囲の順で最初の1件のみ返す
    • 相関は単項目がすべて合格した前提で、全チェックのエラーをまとめて返す
    • DB照合は相関がすべて合格した前提で、存在チェック→重複・重なりの順で最初の1件を返す
  • SQLiteを使った動作確認:
    • 備品コードが空、開始日が実在しない日付、終了日が空の入力は単項目の段で3件まとめて返り、後ろの段に進まない
    • 開始日が終了日より後の入力と、15日間の入力は相関の段で止まる
    • マスタにない備品コードはDB照合の存在チェックで止まる
    • 予約済み期間(10月10日〜12日)と1日重なる入力はエラー、重ならない入力は通過する
  • 期間の重なりの判定:
    • 「既存の開始日 ≦ 新しい終了日」かつ「既存の終了日 ≧ 新しい開始日」の1つの条件で判定できる
    • 仕様書にもこの形で書くと、同じ日を重なりとみなすかという境界がはっきりする

■ 12. 画面・サーバー・DB制約の分担

  • 複数層で行う理由:
    • 同じチェックを複数の層で行うのは重複ではなく、役割が違う
    • 画面は利用者にすぐ知らせるため
    • サーバーは受け取った値を必ず確かめるため
    • DB制約は保存されるデータの整合性を最後に守るため
  • 必須・桁数:
    • 画面とサーバーで行い、DBではNOT NULLと列の長さで守る
    • 空文字とNULLの扱い、文字数とバイト数の単位をそろえる
  • 文字種・形式:
    • 画面とサーバーで行い、DBは必要な列だけCHECK制約を置く
    • 正規表現は画面とサーバーで同じものを使う
  • 数値範囲:
    • 画面とサーバーで行い、DBはCHECK制約を置く
    • 範囲が変わりやすい値はサーバーだけにする
  • コード値:
    • 選択式の入力でもサーバーで確かめ、DBはCHECKまたは外部キーで守る
  • 相関:
    • 画面とサーバーで行い、同じ行の中で完結するものはDBのCHECKにも置く
    • 複数行にまたがる条件はサーバーで行う
  • 存在チェック・一意・期間の重なり:
    • 存在チェックはサーバーと外部キーで行い、画面は候補から選ぶ形にすると入力が楽になる
    • 一意・重複はサーバーとUNIQUE制約で行い、同時登録時はDB制約が最後に止める
    • 期間の重なりはサーバーで行い、同時登録への対策を別途決める
  • 実施層の判断基準:
    • 入力値だけで判定できるなら画面とサーバーの両方、できないならサーバー(とDB制約)
    • 条件が将来変わりやすいならサーバーだけ、変わりにくいならDB制約にも置く
    • 複数利用者の同時登録で結果が変わるならUNIQUEや外部キーのDB制約を必ず置く
    • バッチや別のAPIなどほかのプログラムも同じ表に書き込むならDB制約を置く

■ 13. レビュー前のチェックリスト

  • 網羅性:
    • 選択式や非表示の項目も含め、すべての入力項目が1行ずつ載っている
    • 空欄がなく、該当なしは「―」になっている
  • 単位と境界:
    • 桁数の単位(文字数、バイト数)が書いてある
    • 範囲は「以上・以下」「より大きい・未満」で境界がわかる
    • 日数や期間は両端を含むかどうかが書いてある
  • 照合と前処理:
    • 正規表現は「文字列全体に一致」と明記してある
    • 前処理(空白除去、全角・半角変換)の有無が書いてある
    • 空文字、空白のみ、値なしの扱いが決まっている
  • 相関とメッセージ:
    • 相関チェックに表示先の項目が書いてある
    • 条件付き必須で、条件を満たさないときに値が入っていた場合の扱いも決まっている
    • すべてのチェックにエラーメッセージIDがあり、メッセージ一覧に文言がある
  • 実施層・実行順・テスト:
    • 実施層(画面、サーバー、DB)が全行に書いてある
    • 実行順と、エラー時に後ろの段へ進むかどうかが書いてある
    • 各チェックに合格とエラーの両方の境界値テストケースがある

■ 14. よくある質問

  • 単項目と相関の線引き:
    • その項目の値だけで判定できれば単項目、同じ入力のほかの項目が必要なら相関
    • 「利用開始日が当日以降」は現在の日付と比べるが、ほかの入力項目を使わないので単項目(範囲)に書く
    • 保存済みのデータを読む必要があるものはDB照合に分ける
  • サーバー側チェックの省略可否:
    • 画面でチェックしていてもサーバー側では必ず行う
    • APIの直接呼び出しなど、画面を通らない経路でも値が届くため
    • 画面のチェックは利用者にすぐ知らせるためと役割を分け、実施層に両方を書く
  • エラーの返し方:
    • 同じ段の中はまとめて返すと、利用者が一度に直せる
    • 本記事の例では単項目の段は全項目分をまとめ、1項目の中では最初の1件だけにする
    • どちらにするかを仕様書の「実行順」に書いておくことが大切
  • 正規表現の記載場所:
    • 一覧表に1か所だけ書き、各項目の行からはID(S06など)で参照する
    • 見直すときに直す場所が1か所で済む
    • 読み手は「半角数字」のような呼び名で内容を把握できる

■ 15. まとめ

  • 入力チェック仕様は「1項目1行」の表にし、型からエラーメッセージID、実施層までを列にする
  • 単項目20種、相関10種の一覧をIDつきで用意し、項目の行からはIDで参照する
  • 実行順は単項目→相関→DB照合とし、前の段でエラーなら後ろの段へ進まない
  • 画面は知らせる役、サーバーは必ず確かめる役、DB制約は整合性を守る役として分担表に書く
  • 正規表現は「文字列全体に一致」で照合し、半角数字は[0-9]と書く
  • 境界値テストケースは合格とエラーの両方を仕様の段階で決め、日数は両端を含むかどうかを書く