🧝

YAMLに入門してみた

2023/12/10に公開

JSON

Overview

Dockerやpubspec.yamlの設定ファイルを書いていると、yamlまたはymlと書くこともある呪文見いたいな言語をよく見ることがある???
文法の基礎がないので深掘りしてみたいと思った。筆者は、昔dot installで少し勉強したぐらいのレベルです。

こんなやつですね

OpenAPIの例だとこんな感じですね。Swaggerともいう。これは、APIの仕様書を設計する技術のことです。

https://www.aeyescan.jp/media/openapi
https://www.openapis.org/

Swaggerの場合

openapi: 3.0.0
info:
  version: 1.0.0
  title: Sample API
  description: >-
    A sample API that uses a sample-site as an example to demonstrate features in
    the OpenAPI 3.0 specification
servers:
  - url: 'http://localhost:8003'
paths:
  /users:
    get:
      description: >
        Returns all users
      operationId: findUsers
      parameters:
        - name: tags
          in: query
          description: tags to filter by
          required: false
          style: form
          schema:
            type: array
            items:
              type: string
        - name: limit
          in: query
          description: maximum number of results to return
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: user response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    User:
      type: "object"
      required:
        - "name"
      properties:
        id:
          type: "integer"
          format: "int64"
          example: 100
        name:
          type: "string"
          example: "👻Jboyさんいた"
        status:
          type: "string"
          description: "user status"
          enum:
            - "pending"
            - "active"
            - "inactive"
    Error:
      type: "object"
      properties:
        code:
          type: "integer"
          format: "int32"
        type:
          type: "string"
        message:
          type: "string"
externalDocs:
  description: "Find out more about Swagger"
  url: "http://swagger.io"

YAML の概要

公式の解説を翻訳

YAML (「YAML Ain't Markup Language」の再帰的頭字語) は、人間に優しく、日常の一般的なタスクで最新のプログラミング言語とうまく連携するように設計されたデータシリアル化言語です。この仕様は、YAML 言語とそれをサポートする概念の入門書です。これは、YAML を処理するアプリケーションを開発するために必要な情報の完全な仕様でもあります。

オープンで相互運用性があり、すぐに理解できるツールにより、コンピューティングが大幅に進歩しました。YAML は、データを扱う人々にとって便利で使いやすいように最初から設計されました。Unicode の印刷可能な文字を使用しており、その一部は構造情報を提供し、残りはデータ自体を含みます。YAML は、構造文字の量を最小限に抑え、データ自体を自然かつ意味のある方法で表示できるようにすることで、独自のクリーンさを実現します。たとえば、インデントを構造に使用したり、コロンでキーと値のペアを区切ったり、ダッシュを使用して「箇条書き」リストを作成したりできます。

データ構造には多くの種類がありますが、それらはすべて、マッピング(ハッシュ/辞書)、シーケンス(配列/リスト)、およびスカラー(文字列/数値)という 3 つの基本的なプリミティブで適切に表現できます。YAML はこれらのプリミティブを活用し、単純な型指定システムとエイリアシングメカニズムを追加して、ネイティブデータ構造をシリアル化するための完全な言語を形成します。ほとんどのプログラミング言語はデータのシリアル化に YAML を使用できますが、YAML は基本的に 3 つの基本プリミティブを中心に構築された言語との連携に優れています。これらには、JavaScript、Perl、PHP、Python、Ruby などの一般的な動的言語が含まれます。

プログラミング用の言語は数百種類ありますが、データの保存と転送用の言語はほんのわずかです。YAML の可能性は事実上無限ですが、構成ファイル、ログファイル、プロセス間メッセージング、言語を超えたデータ共有、オブジェクトの永続化、複雑なデータ構造のデバッグなどの一般的なユースケースでうまく機能するように特別に作成されました。データが見やすくて理解しやすいと、プログラミングがより簡単になります。

summary

YAMLの使い方について

値の書き方に種類がある。とはいえ、バリエーションが多くて全部は紹介するの大変なので、よく見る書き方を解説

Scalars(スカラー型)が、数値、文字、bool型.
Sequence(シーケンス)が、配列・List.
Mapping(マッピング)が、マップ.
コメントをつけるときは、#をつける.

公式の解説

YAML のブロックコレクションはスコープにインデントを使用し、各エントリは独自の行で始まります。ブロックシーケンスは、各エントリをダッシュとスペース (「- 」) で示します。マッピングでは、コロンとスペース (「: 」) を使用して各キーと値のペアをマークします。コメントは、八角形 (「ハッシュ」、「シャープ」、「ポンド」、または「ナンバー記号」とも呼ばれます#) で始まります。

スカラーのシーケンス (ボール選手)

- Mark McGwire
- Sammy Sosa
- Ken Griffey

スカラーからスカラーへのマッピング (プレーヤー統計)

hr:  65    # Home runs
avg: 0.278 # Batting average
rbi: 147   # Runs Batted In

スカラーからシーケンスへのマッピング (各リーグの野球クラブ)

american:
- Boston Red Sox
- Detroit Tigers
- New York Yankees
national:
- New York Mets
- Chicago Cubs
- Atlanta Braves

マッピングのシーケンス (プレーヤーの統計)

-
  name: Mark McGwire
  hr:   65
  avg:  0.278
-
  name: Sammy Sosa
  hr:   63
  avg:  0.288

YAML には、インデントではなく明示的なインジケーターを使用してスコープを示すフロースタイルもあります。フローシーケンスは、角括弧内のカンマ区切りのリストとして記述されます。同様に、フローマッピングでも中括弧を使用します。

シーケンスのシーケンス

- [name        , hr, avg  ]
- [Mark McGwire, 65, 0.278]
- [Sammy Sosa  , 63, 0.288]

マッピングのマッピング

Mark McGwire: {hr: 65, avg: 0.278}
Sammy Sosa: {
    hr: 63,
    avg: 0.288,
 }

thoughts

変数・配列・マップみたいなもので使った例をご紹介しました。わかりやすい例が紹介されているサイトの🔗リンクを載せておきます。
やっと、YAMLの読み方がわかってきました😅

参考になった学習サイト

Playgroundを使うと、YAMLをJSONに変換して、どんなデータの形になるのかを比較するのを試すことができます。

https://eemeli.org/yaml-playground/

スカラー型:

yaml

int: 0
string: "Hello"
bool: true

json

{
  "int": 0,
  "string": "Hello",
  "bool": true
}

シーケンス型:

yaml

# 縦向きで書くなら改行して `-` をつける
array:
 - 1000
 - 2000
 - 3000

# `[]`を使うと、改行しなくても書ける
list: ["hoge", "huge", "taro"]

json

{
  "array": [
    1000,
    2000,
    3000
  ],
  "list": [
    "hoge",
    "huge",
    "taro"
  ]
}

Map型:
yaml

# Mapで書くときは、文字の後に`:`をつけて改行してスペースを開ける。Tabキーは使わない方が良い
person:
 name: "Jboy"
 age: 34
 birthday: 19890310

json

{
  "person": {
    "name": "Jboy",
    "age": 34,
    "birthday": 19890310
  }
}

Overview

summary

thoughts

Discussion