| 1 設計

Spectral の新しい「OR」関数を導入

2025年6月10日

Spectralは、カスタマイズ可能なリンティングルールを通じて品質を強制しようとするAPIチームのガバナンスニーズを満たすために進化し続けています。今回、ルールセットとAPIスタイルガイドにさらなるパワーを追加する新しいコア機能「**or**」を紹介できることを嬉しく思います。

Spectralコア機能とは？

Spectralのコア機能は、Spectralにおけるルールの構成要素です。これらは、プロパティの存在チェック、パターンの評価、値の比較など、再利用可能なロジックをカプセル化します。コア機能とJSONPath式、いくつかのfunctionOptionsを組み合わせて、OpenAPI、Arazzo、またはAsyncAPIドキュメントの強力で宣言的なルールを作成します。

現在のコア機能のリストは以下の通りです。

関数	説明
`alphabetical`	シンプルな配列、またはキーを渡すことでオブジェクトのコンテンツをアルファベット順に強制します。
`enumeration`	フィールド値がこの一連の可能な値に存在するかどうかを確認します。
`falsy`	値は`false`、""、`0`、`null`、または`undefined`である必要があります。
`length`	文字列または配列の長さ、オブジェクト内のプロパティの数、または数値の値をカウントし、最小値および/または最大値を定義します。
`pattern`	正規表現を使用して`match`または`notMatch`します。
`casing`	テキストは`camelCase`や`snake_case`のような特定のケースと一致する必要があります。
`schema`	JSON Schema (ドラフト4, 6, 7, 2019-09, または2020-12) を使用して、$given JSON PathのコンテンツをJSONインスタンスとして扱います。
`truthy`	値は`false`、""、`0`、`null`、または`undefined`であってはなりません。
`defined`	値は定義されている必要があります。つまり、`undefined`以外の何らかの値である必要があります。
`undefined`	値は`undefined`である必要があります。
`unreferencedReusableObject`	この関数は、ドキュメント内の参照されていないオブジェクトを特定します。
`or` 新規	これらのプロパティのいずれか1つ以上が定義されている必要があることを伝えます。
`xor`	これらのプロパティのいずれか1つが必須であり、定義できるのは1つだけであることを伝えます。
`typedEnum`	プロパティに`type`と`enum`の両方が定義されている場合、enum値は型を尊重する必要があります。

「or」機能が役立つ理由

新しいor関数を使用すると、指定された複数のプロパティの**少なくとも1つ**が存在する必要があることをアサートできます。これは、スキーマまたはオブジェクトが複数の方法で検証できる場合に特に役立ち、チームやAPI全体でその柔軟性に対応したい場合に便利です。これにより、高品質なAPIドキュメントの強力な基盤を維持しつつ、分散型の意思決定やユースケースのニュアンスのニーズに対して実用的であり続けることができます。

関数シグネチャ

例1：スキーマに記述テキストが存在する必要がある

APIスキーマ全体でドキュメント/設計プラクティスを強制することを想像してみてください。各スキーマが、消費者や他のAPI設計者にとっての使用（または目的）を表現するために何らかの形で文書化されていることを要求するかもしれませんが、すべてのスキーマ作成者に表現において同じメカニズムを強制する必要はありません。ある人はtitleを、別の人はsummaryを、また別の人はより長いdescriptionを使用するかもしれません。or関数は、その柔軟性を表現することを可能にします。

上記のルールセットは、特定のドキュメントスタイルを強制することなく、すべてのスキーマがその目的を表現するために**ある程度**文書化されていることを保証します。

例2：文字列スキーマに役立つヒントを確保する

別の一般的なケースとして、すべてのtype: stringスキーマに、開発者向けの役立つヒントまたは制約（format、example、またはpatternを介して）が含まれていることを確認したい場合があります。ここでも、複数のものが許容されますが、少なくとも1つは存在する必要があります。

コミュニティ貢献

この機能を追加してくれたClyde Cutting**💛**に感謝します。彼は、Financial Data ExchangeとそのOpen Banking API向けのFDX APIスタイルガイド内で進行中の素晴らしい作業の一環として、この機能の必要性を感じていました。このようなコミュニティの貢献は、Spectralがさらに強力で実用的なツールに成長するのに役立ちます。

試してみる

Spectralの最新バージョンにアップデートし、独自のルールセットでor関数を試してみてください。スキーマのドキュメント、命名規則、構造の柔軟性を強制する場合でも、orはそれを表現するための追加の宣言的な手段を提供します。