型、プロパティ、必須フィールド

日常のスキーマの多くはオブジェクトから始まります。JSON オブジェクトは、プロパティを記述し、どのフィールドが必須かを決めると、有用な契約になります。

{
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "profile": {
      "type": "object",
      "properties": {
        "displayName": { "type": "string" }
      },
      "required": ["displayName"]
    }
  },
  "required": ["email", "profile"]
}

type

type キーワードは JSON のプリミティブとコンテナを記述できます。

• object
• array
• string
• number
• integer
• boolean
• null

小数値が無効な場合のみ integer を使います。価格、座標、比率などの小数には number を使います。

properties

properties はフィールド名をスキーマにマップします。各プロパティは独自の型とネスト制約を持てます。

ネストオブジェクトは意図的にモデル化すべきです。ネスト値に意味のあるフィールドがあるなら、汎用 object のままにせず、独自のスキーマブロックを与えてください。

required

required は存在しなければならないプロパティ名の配列です。よくある間違いは、properties に列挙したすべてのプロパティが自動的に必須だと思うことです。そうではありません。

つまり、クライアントに送信を強制せずにオプションフィールドを記述できます。

{
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "subtitle": { "type": "string" }
  },
  "required": ["title"]
}

必須は非空を意味しない

必須の文字列は、minLength を追加しない限り空のままでもよいです。

{ "type": "string", "minLength": 1 }

必須は存在ルール、minLength、minimum、pattern などの制約は値ルールと考えてください。