JSONとYAMLの違い：APIをJSONからyamlに変換

JSONとyamlもAPIの記述によく利用されている形式です。時には、何らかの原因によって、APIのJSON記述からyaml記述に変換する必要があります。本文では、APIをJSONからyamlに変換する簡単な方法を皆さんに紹介します。

JSONとyamlとの違い

なぜかAPIをJSONからyamlに変換する必要があるのかを理解するには、JSONとyaml形式との違いを理解する必要があります。この部分では、まずJSONとyamlとの違いを皆さんに解説していきたいと思います。YAMLとJSONの主な違いといえば、以下のようなものがあります。

構文の表現力

JSONとYAMLの階層構造の表現方法には大きな違いがあります。JSONは入れ子になったオブジェクト{}と配列[]を使って階層関係を構築します。一方、YAMLはインデント(スペースやタブ)によって階層を表現します。

JSONのデータ構造：

{
  "person": {
    "name": "John",
    "age": 30,
    "addresses": [
      {"country": "USA"},
      {"country": "Japan"} 
    ]
  }
}

yamlのデータ構造：

person:
  name: John
  age: 30
  addresses:
    - country: USA
    - country: Japan

YAMLの方が階層構造が視覚的にわかりやすくなっています。JSONは入れ子になると階層が深くなり、データの構造を把握しづらくなります。

このため、データ構造が複雑になるほど、YAMLのインデントによる表現のメリットが大きくなります。APIの定義など、階層的なデータ構造をもつ文書の記述において、YAMLは適していると言えます。

記述の冗長さ

SONは、データのキーと値を常にダブルクォーテーションで囲む必要があります。また、オブジェクトを表現するためには{}を、配列を表現するためには[]を用いる必要があります。一方、YAMLはこうした記法上の制約が少なく、シンプルな記法でデータを表現できます。

コメントの取り扱い

YAMLではコメントを記述できるため、APIの仕様書やドキュメント記述に向いています。JSONはコメントが利用できないので、機械的なデータ交換に向いています。YAMLのファイルサイズは小さく、JSONよりも配布しやすい特徴があります。

データ型

JSONでは、文字列型の値は必ずダブルクォート(" ")で囲む必要があります。しかしYAMLでは、基本的にキー以外の文字列データをクォートで囲む必要はありません。

例えば以下のように、YAMLではクォートを省略できます。

name: John Smith 
message: Hello World!

一方でJSONでは必ずクォートが必要です。

{
  "name": "John Smith",
  "message": "Hello World!"
}

また、YAMLでは真偽値や日付データもシンプルに記述できます。

registered: true
birthday: 1979-05-27

JSONでは文字列による表現になります。

{
  "registered": "true",
  "birthday": "1979-05-27"
}

このように、YAMLはデータ型の記述において自由度が高く、記述を簡略化できます。JSONではデータ型を明示的に記述する必要があるため、YAMLほどスリムには記述できません。

人間の読み書き

JSONとYAMLのもう1つの大きな違いは、人間が読み書きする上での違いです。

JSONは入れ子構造を使うため、オブジェクトや配列が深くネストされると、データの構造を理解するのが困難になります。

一方、YAMLはインデント(スペースかタブ)によって階層構造を表現します。

例えば、以下のようなJSONデータ:

{
 "person": {
  "name": "John Smith",
  "address": {
   "country": "USA",
   "state": "New York",
   "city": "New York"
  }
 }
}

をYAMLで書くと、次のようになり、一目でデータ構造がわかります：

person:
  name: John Smith
  address: 
    country: USA
    state: New York   
    city: New York

汎用性

汎用性から言うと、JSONは最も普及されたデータ記述言語としていますが、yamlはSwaggerやOpenAPIの仕様として標準化されていますが、JSONほどは普及していません。

APIをJSONをyamlに変換する原因

上記の部分からJSONとyamlとの違いをよく理解すると、なぜかAPIをJSON記述からyaml記述に変換する必要があるのかをも理解できるのでしょう。APIの定義をJSONからYAMLに変換する必要がある理由といえば、以下のような点が考えられるのは一般的です。

• YAMLのほうが記述量が少なく、可読性が高いため。JSONより簡潔に定義できる。
• OpenAPIなどAPI定義の標準仕様がYAMLに対応しているため。標準に沿った定義ができる。
• YAMLではコメント記述ができるため。APIの仕様書として機能させやすい。
• YAMLファイルを配布する方が軽量なため。APIドキュメントと一緒に配布しやすい。
• 開発チーム内でYAMLが標準になっているため。統一された開発環境にするため。
• YAMLに自動生成ツールがあるため。Swaggerなどを使って自動定義が可能。
• YAMLのシリアライズ/デシリアライズが容易なため。プログラム内での変換がしやすい。

このように、YAMLはAPI定義に向いている形式だったり、開発効率面での利点があるため、JSONからYAMLへの変換が必要になることがあります。

APIをJSONからyamlに変換する方法

JSON記述のAPIをyaml形式に変換する方法はたくさんあります。現在、一番簡単な方法は、AIを使って変換することになります。例えば、JSONのコードを直接にClaude（AIツール）に投げて、yaml記述に「Yamlに変換して下さい」と伝えると、すぐにyaml記述に変換することができます。

また、Claude以外、ChatGPTなどのAIツールを使用して変換も実現できますので、自分が使い慣れてきたツールを選択すれば良いのでしょう。

Apidog：JSONとYAMLファイルにも対応

API管理が必要となる場合は、一番使いやすいAPI管理ツールのApidogを使用すると、JSONやyaml形式のAPIを簡単にインポートして、直感的な仕様書を生成したり、APIをテストしたりすることができます。

ApidogはYAMLフォーマットのOpenAPI 3、Swagger 1、2、3のAPIをインポートすることをサポートしているので、YAMLフォーマットのAPIを完全に解析して、APIのデータを完全にApidogにインポートしてテストできます。

ステップ⒈プロジェクトの設定を開き、「データをインポート」をクリックすると、「OpenAPI/Swagger」を選択して、YAMLファイルをApidogにドラッグします。

ステップ⒉ここでYAMLファイルが解析され、データの保存先を選択すると、「確認」ボタンをクリックするだけで、それを簡単にApidogにインポートできます。

そして、ApidogというAPI管理ツールを使って、当該APIをテストしたりすることができるようになりますし、APIリクエストを送信して直ちに内蔵のモックサーバーを使って仮のレスポンスデータを取得することもできます。

yamlやJSONを綺麗なAPI仕様書に生成

また、yamlかJSONファイルをApidogにインポートすると、Apidogは、yaml・JSONファイルで記述されている情報に基づいて、非常に魅力的なAPI仕様書を自動的に生成してくれますし、この仕様書を簡単に他の人に共有することもできるので、非常に便利です。