# Serde / OpenAPI 実装ルール
このドキュメントは、公開型に対して `serde` と `openapi` の実装を行う基準を定める。
## 基本方針
- 外部利用される可能性が高い公開型には、原則として `serde` と `openapi` を実装する。
- ただし、コレクション型や内部集約型、木構造やキャッシュのような実装都合の強い型は対象外とする。
- すでに公開している型でも、シリアライズ表現が不自然になる場合や、内部不変条件を直接露出してしまう場合は実装しない。
## 対象にする型の考え方
- 構造が単純で、フィールドがそのまま意味を表す型を優先する。
- 変換や正規化のロジックを持たず、値を保持すること自体が主目的の型を優先する。
- 利用者が API 境界でそのまま受け渡しやすい型を優先する。
## 実装ルール
- `serde` と `openapi` は feature gate 付きで実装する。
- 型の公開 API とシリアライズ表現が一致するように保つ。
- `openapi` 上で型の実表現がそのまま表せない場合は、`schema(value_type = ...)` などで最も近い表現へ寄せる。
- 追加した型は `cargo check --features serde` と `cargo check --features openapi` で確認する。
## 判断基準
- その型を JSON などの外部境界に載せることが自然か。
- その型の各フィールドが、利用者に見せてもよい安定した意味を持つか。
- その型の保持ロジックが、シリアライズ表現を意識せずに成立するか。
## 例外
- 内部状態、集合構造、索引木、キャッシュ、派生値を主目的とする型は、原則として対象外とする。
- 迷う場合は、まず公開 API としての意味があるかを優先し、必要なら個別に検討する。