JSのコードにYAMLを書きたくなったら、オブジェクトで足りないかを先に確かめる

JavaScriptのコードの中にYAMLをそのまま書いて動かすことはできません。文字列として埋め込み、ライブラリで読み込めば動きますが、そうして手に入るのは、たいてい最初からJavaScriptのオブジェクトで書けば済んだものです。YAMLを分ける利点は、コードを触らずに直せることなのに、コードの中に置いた時点でその利点が消え、読み込みの手間と失敗の可能性だけが残るからです。この記事では、YAMLを読み込む方法を確かめたうえで、YAMLをどこに置くと何が得られるのかを、置き方ごとに比べます。

直接は書けないが、読み込んで使えます

YAMLはデータの書き方で、JavaScriptはプログラミング言語です。文法が違うので、コードの途中にYAMLを書いても、JavaScriptとしては解釈されません。そこで、YAMLを解析（パース）するライブラリを使います。代表的なものが js-yaml で、npm install js-yaml でインストールできます。yaml.load にYAMLを渡すと、JavaScriptのオブジェクトが返ってきます。

ファイルから読み込むのが基本の形です

Node.jsでは、設定をYAMLのファイルに書き、それを読み込んで使う形がよく使われます。

# config.yaml
server:
  port: 8080
  host: 0.0.0.0
database:
  host: localhost
  port: 5432
  username: user

const fs = require('fs');
const yaml = require('js-yaml');

try {
  const config = yaml.load(fs.readFileSync('config.yaml', 'utf8'));
  console.log(`server: ${config.server.host}:${config.server.port}`);
} catch (e) {
  console.error(e);
}

ファイルが見つからない、YAMLの書き方が崩れている、といった失敗に備えて、全体を try と catch で囲んでおきます。

埋め込んだYAMLと、オブジェクトを並べてみます

ファイルを使わず、バッククォートで囲むテンプレートリテラルの中にYAMLを書き、yaml.load に渡すこともできます。同じ設定をオブジェクトで書いた場合と並べます。

// 文字列として埋め込んだYAML
const config1 = yaml.load(`
server:
  port: 8080
`);

// 最初からオブジェクトで書いた場合
const config2 = { server: { port: 8080 } };

どちらも結果は同じオブジェクトです。違うのは、前者にはライブラリの読み込みと解析の手間が加わり、書き方を誤れば実行するまで気づかないことです。しかも、テンプレートリテラルの中では、コードの字下げとYAMLの字下げが混ざります。コードを整形し直しただけでYAMLの親子関係が変わる、という事故は、この置き方に特有のものです。

置き方	得られるもの	向く場面
別のYAMLファイル	コードに触れずに直せる、コメントを残せる	コードを書かない人が設定を直す
コードの中のYAML文字列	ほかから写してきたYAMLをそのまま試せる	一時的な試しや、テストの入力
JavaScriptのオブジェクト	余計な部品がなく、誤りに早く気づける	開発者だけが直す設定

設定をYAMLに分けたので誰でも直せるようになった、という話もよく聞きます。けれども、そのファイルがコードと同じ場所の奥にあり、直すたびにエンジニアの手と確認が要るなら、直せる人は実際には増えていません。分けた効果を決めるのはファイルの形式ではなく、誰がそこまでたどり着けるかです。

どの置き方が正しいかに、一般的な答えはありません。設定を直す人が誰で、どのくらいの頻度で直すのかは、組織ごとに違い、外からは分からないからです。

GPTsでも、定義と処理を分けて考えます

YAMLが受け持つのは、何をどう設定するかという定義で、JavaScriptが受け持つのは、それを使って何をするかという処理です。GPTsのアクションでも同じ分け方が現れます。外部のAPIの呼び出し方を、OpenAPIのスキーマとしてYAMLかJSONで書き、スキーマはどこに何を渡し何が返るかという定義を受け持ちます。実際の処理は、呼び出される側のサーバーのコードが受け持ちます。動かないときに、どちらを疑うべきかは、この分け方で見えてきます。

あなたの手元のYAMLファイルを、この半年でエンジニア以外の誰かが直したことはあるでしょうか。一度もないなら、それをYAMLに分けておく理由は何だったのでしょうか。

この記事の背景にある考え方は、拙著『ChatGPT 誰でも1時間でできる！ はじめてのGPTsのつくり方』の3章1節「専用GPTで業務を効率化しよう」に書きました。専用GPTの真価は内製化にあり、現場の人が自分で作って直せるので、思いついた改善をすぐに試せる、という話です。そこには「組織は新しいアイデアや改善提案を即座に試し、適用することができます。」とあります。この節を読むと、設定を別のファイルに分けるかどうかを、形式の好みではなく、誰がどのくらいの頻度で直すのかという自分の組織の実情から決められるようになります。