OpenAPI 3.0と3.1の違いで手が止まるのは、nullの書き方

ネットで見つけた例とAIが書いた例を貼り合わせたスキーマが、読み込みの段階で失敗する。原因を探すと、先頭で3.1.0を宣言しながら、中身に3.0系の書き方が混ざっていた、ということがよくあります。例の多くはどの版の書き方かを名乗っておらず、貼る側も先頭の一行しか見ていないからです。この記事では、OpenAPI 3.0.0と3.1.0の違いを整理したうえで、GPTsのアクションを書く人が実際につまずくのは、nullの書き方のようなデータの形の細部だということを示します。

いちばん大きな違いは、JSON Schemaとの関係です

OpenAPIの仕様書では、リクエストやレスポンスのデータの形を、JSON Schemaという書き方で定義します。3.0.0はJSON Schemaを土台にしながら、完全な互換性はなく、OpenAPI独自のキーワードが標準の書き方と食い違うことがありました。3.1.0は、JSON Schema 2020-12に完全に対応し、食い違いの原因だった独自のキーワード（nullable など）を廃止して、標準の書き方にそろえました。より複雑な検査（バリデーション）も書けるようになり、JSON Schemaの道具や知識をそのまま使いやすくなりました。

物差し	3.0.0	3.1.0
JSON Schema	完全な互換性はない	2020-12に完全対応
独自のキーワード	nullable など標準と食い違うものがある	廃止して標準の書き方に統一
Webhooks	仕様に明確には含まれない	最上位の webhooks の節で定義
components	schemas、responses、parameters など九つ	扱える要素が追加

つまずくのは、nullと範囲の書き方です

たとえば、名前は空でもよい、年齢は0より大きい、という二つの決まりを、二つの版で書き比べます。

# 3.0.0 の書き方
name:
  type: string
  nullable: true
age:
  type: integer
  minimum: 0
  exclusiveMinimum: true

# 3.1.0 の書き方
name:
  type: [string, "null"]
age:
  type: integer
  exclusiveMinimum: 0

3.0.0では、値が空でもよいことを nullable という独自のキーワードで示し、0を含まないことを true か false の印で示していました。3.1.0では、型の一覧に null を加え、exclusiveMinimum には数そのものを書きます。宣言だけ3.1.0にして、中身を3.0.0のまま貼ると、読み込めないか、読み込めても意図と違う決まりとして扱われます。

YAMLで書くときは、もう一つ落とし穴があります。型の一覧に入れる null を、上の例のように引用符で囲まずに書くと、YAMLはそれを、型の名前ではなく、値がないことを表す null として読んでしまいます。ここだけは引用符が要ります。

版の違いを全部覚える必要はありません

版の違いの一覧を見ると、全部覚えなければいけない気がしてきます。けれども、アクションが受け持つのは、GPTsの側から外部を呼び出すことです。相手から呼ばれるための webhooks の定義は中心になりませんし、components に増えた要素を使う場面も限られます。違いの一覧を暗記する前に、自分のスキーマで実際に使っている書き方はどれなのかを数えるほうが早く片づきます。値が空になる項目も、数の範囲の決まりもないスキーマなら、二つの版の差はほとんど表に出ません。

AIにスキーマを書かせるときも、版を指定するだけでは足りないことがあります。AIが学んだ例には二つの版の書き方が混ざっていて、ある書き方がどちらの版のものかを、AIがいつも区別して覚えているとは限らないからです。そして、GPTsのアクションが内部で、どちらの版のどの書き方まで受け付けるのかは、公開されている説明だけでは細部まで分かりません。時期によって変わることもありえます。確かめられるのは、自分のスキーマを実際に読み込ませた結果だけです。

読み込めないときは、宣言と中身を照らします

確かめる順番は、先頭の openapi の版、型の一覧と nullable の書き方、範囲の書き方、の順です。宣言と中身が同じ版の言葉で書かれているかを見るだけで、原因の多くは見つかります。

あなたのスキーマでは、値がないことをどう表しているでしょうか。空の文字列、null、項目そのものを省く、のどれにするかを、誰かが決めたでしょうか。それとも、貼り付けた例が決めたのでしょうか。

この記事の背景にある考え方は、拙著『ChatGPT 誰でも1時間でできる！ はじめてのGPTsのつくり方』の1章5節「GPT利用の前提条件と技術的限界」に書きました。GPTsには利用回数や処理能力などの制約があり、それを知ったうえで計画的に作る、という話です（制約の数字は2024年時点のものです）。そこには「GPTsの開発には、様々な利用制限と技術的制約が伴います。」とあります。この節を読むと、説明書に書かれていない受け付けの範囲のような、道具の側の分からなさを前提に置き、自分の手で確かめる段取りを組めるようになります。