schema-dts

schema-dts

Schema.org JSON-LD 用の schema-dts TypeScript 型に関わる作業（構造化データオブジェクトの構築、<script type="application/ld+json"> の挿入、複数の型を持つノード、@graph ドキュメント、アクションの入力／出力制約、schema-dts-gen による型定義の再生成）では、このスキルを使用してください。

ワークフロー

1. コードを変更する前に、ローカルの状況を確認します。
   • パッケージ：schema-dts（必要に応じて schema-dts-gen、schema-dts-lib、react-schemaorg も確認します）。
   • バージョン：対象は v2 です（[email protected] = Schema.org v30、[email protected]）。1.x はレガシーとして扱います。
   • 役割：型のみを使ったコンパイル時のチェックです（実行時の Schema.org 検証は行いません）。
   • 形状：単一の WithContext<T> ノード、@id スタブを使う Graph、または MergeLeafTypes による複数の @type のいずれかです。
   • 挿入方法：React／react-schemaorg、Next の Script、Astro の set:html、Svelte の head、または標準 DOM です。
2. ユーザーが最新の動作を求めている場合、インストール済みのメジャーバージョンが不明な場合、または v2 のヘルパー／ジェネレーターの出力に関わる作業では、ドキュメントを更新します。source-map.md から確認を始めてください。
3. インストール、WithContext、Thing の識別、DataTypes、型のみのインポートについては、setup-core.md を参照してください。
4. Graph、IdReference、*Leaf、MergeLeafTypes、WithActionConstraints については、graphs-merge-actions.md を参照してください。
5. 一般的なページスキーマ、XSS に安全なシリアライズ、フレームワークとの連携については、patterns-frameworks.md を参照してください。
6. schema-dts-gen の CLI／プログラムによる生成と、v1 から v2 への変更については、generator-migration.md を参照してください。
7. 既存のプロジェクトのスタイルに合わせて実装します。
   • import type { … } from 'schema-dts' を優先してください。
   • @context: 'https://schema.org' はドキュメントのルート（WithContext または Graph）にのみ指定してください。
   • パッケージを追加したりジェネレーターを実行したりするコマンド例では、bun／bunx を優先してください。

判断基準

• 型のみです。 schema-dts は、誤った @type や不明なプロパティをコンパイル時に検出します。Google リッチリザルトや Schema.org に対する実行時検証は行いません。
• ビルド済みパッケージには Schema.org のコアを使用してください。保留中／実験的なレイヤーには、手作業の as キャストではなく、カスタムの schema-dts-gen の実行が必要です。
• トップレベルの JSON-LD ドキュメントには必ず WithContext<T>（または Graph）を使用し、@context を必須にして https://schema.org に固定してください。
• すべてを Thing として型付けするのではなく、ページに合った 最も具体的な型（Product、Article、FAQPage）を優先してください。
• @type が具体的な型の配列である場合に限り、*Leaf と MergeLeafTypes を使用してください。Product のようなユニオンエイリアスを MergeLeafTypes に渡してはいけません。
• クラスで Schema.org の形状を implements する必要がある場合は、*Leaf インターフェースを使用してください。ユニオンエイリアスは実装できません。
• カスタムまたはサードパーティのオントロジーには、schema-dts-gen 2.0.1 以降を実行してください。2.0.0 では、rdfs:comment のテキストによって生成される出力にコードが注入される可能性がありました（GHSA-c4f4-pq98-f2p2）。
• ネストしたオブジェクトを重複させるのではなく、Graph 内で @id と IdReference スタブを使ってエンティティ同士を相互参照させてください。
• サイトリンク検索ボックス／アクションのマークアップでは、query-input（およびその他の *-input／*-output）を型チェックできるよう、WithActionConstraints でラップするかキャストしてください。
• HTML に挿入する場合は、JSON 文字列内の <、>、&、' を エスケープしてください（または react-schemaorg の JsonLd を使用してください）。
• クローラーが解決する url、image、logo、sameAs、@id の値には、絶対 HTTPS URLを優先してください。

検証

リポジトリに既存のチェックがある場合は、そちらを優先してください。schema-dts に関する重要な作業では、次のうち該当するものを含めてください。

• JSON-LD ビルダーと、フレームワークのラッパーを型チェックします。
• ルートオブジェクトでは WithContext / Graph を使用し、ネストされたノードでは @context を省略していることを確認します。
• ページをスモークレンダリングし、DOM / ソースを表示で application/ld+json スクリプトを確認します。
• SEO の対象となるかが重要な場合は、必要に応じて出力を Google リッチリザルト テスト または Schema Markup Validator に貼り付けます。
• v2 へのアップグレード後は、Role 形式のプロパティ、Quantity の割り当て、複数タイプのノード、およびカスタムの schema-dts-gen 出力（schema-dts-lib をインポートするようになりました）を再確認します。