JSONからSmithyモデルへ変換

JSONサンプルからSmithyの型モデル草案を作る

JSONからSmithyモデルへ変換する機能は、入力したJSONサンプルの形を読み取り、対応するSmithy IDLの型定義を組み立てるための出発点です。たとえば、オブジェクトのプロパティや配列の要素をもとに、メンバーや入れ子のshapeを含むテキストを生成します。頂点となる型名は初期値が Root で、用途に合わせて変更できます。出力はコピー、または .smithy ファイルとしてダウンロードできます。

Smithyはサービスのデータモデルやインターフェースを記述する言語です。structure は名前付きメンバーのまとまり、list は順序のある要素列、map はキーと値の対応を表します。入力JSONは実データの一例であり、生成結果はその例から推測したモデルのたたき台です。Smithyのモデル表現にはIDLのほかJSON ASTもあり、両者は別の表現形式です。Smithy 2.0のモデル仕様を参照してください。

サンプルに現れた形と型を読み取る

変換時に見えるのは、入力したサンプルのキー、値、オブジェクトや配列の入れ子です。たとえば注文データに文字列の注文番号と明細の配列が含まれていれば、出力はそれらを表すメンバーと型を含む形になります。複数のサンプルで同じフィールドに異なる値があるなら、すべての実際のパターンを入力に含めてから、推定された型を確認してください。

Smithy IDLでは、shapeを定義する前にnamespaceを宣言する構成が仕様で定められています。生成テキストのnamespaceや型定義を、利用するプロジェクトの命名規則に照らして見直してください。Smithy IDL仕様では、control、metadata、shapeの各セクションや構文を確認できます。

空の値や不足した例は推論を弱める

空配列には要素の例がなく、空オブジェクトにはメンバーの例がありません。そのため、その値だけからリスト要素やオブジェクト構造の意味を確定することはできません。配列を含む場合は代表的な要素を少なくとも入力例に含め、複数の種類がある場合は別のサンプルでも形を示すと、出力を照合しやすくなります。

Smithyの集約shapeには structure、list、map、union などがあります。JSONの見た目だけでは、業務上の意味や許される状態まで決まりません。集約型の定義はSmithyの集約型仕様で確認できます。

生成前にJSONサンプルを整える

1. 代表的なJSONを入力する

   対象のフィールドと値の型が分かるサンプルを入力します。JSONとして解析できるよう、キーと文字列値を二重引用符で囲み、括弧とカンマを確認してください。

2. トップレベルの型名を決める

   Root のままでも始められますが、データを表す名前に変更すると出力を読み返しやすくなります。「型定義のみ」の設定は通常有効です。追加のサービス設計が必要な場合も、この出力だけで補われるわけではありません。

3. 出力を照合して保存する

   入力した各キー、ネスト、配列要素と生成テキストを比較します。必要箇所を編集してからコピーするか、Smithyファイルとしてダウンロードしてください。

推定結果を読むときの疑問

モデル草案としてレビューしてから利用する

この変換は入力サンプルから型構造を推測するもので、Smithy仕様への適合を検証する機能や、完全なサービスAPIを設計する機能ではありません。単一サンプルから必須性、任意性、許容値、互換性、認証や操作の要件を判断できません。空配列・空オブジェクト、値の揺れ、未入力のフィールドがある場合は特に、元の契約を確認して型を手直ししてください。

プロジェクトに組み込む前に、採用するSmithyのバージョンとプロジェクトの検証手順でモデルを確認してください。入力に実データを使う場合は、個人情報、秘密鍵、アクセストークンなどを取り除き、公開してよいサンプルに置き換えてください。