odata-vocabularies-sync

odata-vocabularies-sync

上流の OData 語彙ソースに合わせて、packages/odata-vocabularies パッケージを同期します。

• 引数なし — 既存のすべての語彙リソースファイルを、公開済みの最新バージョンに更新します。
• URL 引数あり — まず新しい語彙を登録して追加し、その後すべてを更新します。

ファイルの編集はすべて packages/odata-vocabularies/ を基準に行います。

注： com.sap.cds.vocabularies.* ファイル（ObjectModel、AnalyticsDetails）は手動で作成されており、このスキルでは管理されていません。URL を使って追加しようとしないでください。

---

ステップ 1 — 新しい語彙を追加する（URL 引数が指定された場合のみ）

1a. 語彙の JSON を取得して確認する

指定された URL の JSON を取得します（.json で終わる必要があります。XML URL は更新ツールでサポートされていません）。以下を抽出します。

• namespace — 最上位のスキーマオブジェクトのキー（例：Org.OData.NewThing.V1 または com.sap.vocabularies.NewThing.v1）
• alias — スキーマオブジェクト内の $Alias の値（例：NewThing）

namespace から語彙ファミリーを判定します。

• Org.OData. で始まる → OASIS 語彙
• com.sap.vocabularies. で始まる → SAP 語彙
• com.sap.cds. で始まる → CDS 語彙 — 中止してください。 これらのファイルは手動で作成されているため、このスキルでは追加できません。このことをユーザーに説明してください。
• 上記以外 → 中止し、先に進む前にユーザーにファミリーを確認してください。

1b. tools/update.ts を編集する

既存のエントリー内でアルファベット順になるよう、SUPPORTED_VOCABULARIES にエントリーを追加します。

'<namespace>': {
    uri: '<the provided URL>'
},

注： エントリーに update: false を含めると、その語彙を固定し、今後の自動更新の対象から除外できます（例：com.sap.vocabularies.CDS.v1 は手動管理されているため、この設定を使用しています）。通常どおり自動更新する場合は、このフィールドを省略します。

1c. src/resources/index.ts を編集する

6 つの追加をすべて行います。いずれか 1 つでも欠けると、実行時エラーが発生します。

1. インポート — 単一のインポートブロック内で、エイリアスのアルファベット順に挿入します（OASIS と SAP のインポートはファミリー別ではなく、エイリアス順に混在しています）。

   import <Alias> from './<namespace>.js';
   

   JSON の $Alias の値をインポート識別子として使用します。例外： エイリアスが予約済みの JS キーワードまたは組み込み識別子（例：JSON、Map、Error）の場合は、有効な識別子になるよう接頭辞を付けます（例：JSON → ODataJSON）。また、既存のインポートに先例がないか確認してください。一部のエイリアスは簡潔にするため短縮されています（例：Authorization → Auth）。

2. Namespace 共用体型 — 該当するファミリーの型に追加します。

   • OASIS → OasisVocabularyNamespace
   • SAP → SapVocabularyNamespace

   | '<namespace>'
   

3. Alias 共用体型 — 該当するファミリーの型に追加します。

   • OASIS → OasisVocabularyAlias
   • SAP → SapVocabularyAlias

   | '<Alias>'
   

4. NAMESPACE_TO_ALIAS Map：

   ['<namespace>', '<Alias>'],
   

5. ALIAS_TO_NAMESPACE Map：

   ['<Alias>', '<namespace>'],
   

6. vocabularies Record：

   '<namespace>': <Alias>,
   

1d. src/loader.ts を編集する

該当するファミリーブロック内でアルファベット順になるよう、SUPPORTED_VOCABULARY_NAMESPACES に namespace を追加します。

'<namespace>',

1e. README.md を編集する

「Supported Vocabularies」セクションの該当する箇条書きに、エイリアスをアルファベット順に追加します。

• OASIS namespace → OASIS Vocabularies リスト
• SAP namespace → SAP Vocabularies リスト

* <Alias>

---

ステップ 2 — 更新ツールを実行する

登録されているすべての語彙（新たに追加したものも含む）の最新 JSON を取得し、すべての src/resources/*.ts リソースファイルを再生成します。

リポジトリのルートから実行します。

pnpm --filter @sap-ux/odata-vocabularies update:vocabularies

ツールが失敗した場合は、作業を中止し、続行する前にエラー出力全体を報告してください。

---

ステップ 3 — README を監査して修正する

README を登録済みの語彙と照合し、不足している項目を追加します。

1. src/resources/index.ts を読み、NAMESPACE_TO_ALIAS のすべての名前空間を収集し、ファミリーごとに分類します。

   • OASIS：Org.OData. で始まる名前空間
   • SAP：com.sap.vocabularies. で始まる名前空間。ただし com.sap.vocabularies.CDS.v1 は除外します。
   • com.sap.cds. の名前空間はスキップします（手作業で作成されており、README には記載されていません）。

2. 収集した各名前空間について、対応する生成済みリソースファイル src/resources/<namespace>.ts を読み、$Alias の値を抽出します。これは README で表示名として使われる、正式に公開されたエイリアスです。

3. README.md を読み、「Supported Vocabularies」の下にある2つの箇条書きリストを探します。

   • OASIS 語彙のリスト
   • SAP 語彙のリスト

4. 各エイリアスが該当するリストにまだ存在しない場合は、アルファベット順に挿入します。

README がすでに完全な場合は、何も変更しません。

---

ステップ 4 — テストを実行してスナップショットを更新する

pnpm --filter @sap-ux/odata-vocabularies test -- -u

スナップショットに関係しないテストの失敗があれば報告します。スナップショットの更新が想定されるのは、語彙の内容が実際に変更された場合のみです（更新ツールが上流の差分を検出した場合、または新しい語彙が追加された場合）。更新内容を超えてスナップショットに変更がある場合は、受け入れる前に差分を確認してください。リグレッションを示している可能性があります。

---

ステップ 5 — 報告する

実施した内容を要約します。

• 新しい語彙を追加した場合は、名前空間、エイリアス、ファミリー、および変更したすべてのファイルを明記します。
• README に不足していて追加した項目があれば、一覧にします。
• 更新ツールによって再生成された語彙リソースファイルを一覧にします。
• テストがすべて成功したことを確認します。