schema-dts

schema-dts

当工作涉及 Schema.org JSON-LD 的 schema-dts TypeScript 类型时，使用此技能：构建结构化数据对象、注入 <script type="application/ld+json">、多类型节点、@graph 文档、Action 输入／输出约束，或使用 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. 常见页面 Schema、XSS 安全序列化和框架接入，请参阅 patterns-frameworks.md。
6. schema-dts-gen CLI／编程式生成以及 v1→v2 的破坏性变更，请参阅 generator-migration.md。
7. 按照现有项目风格实现：
   • 优先使用 import type { … } from 'schema-dts'。
   • 仅在文档根节点（WithContext 或 Graph）设置 @context: 'https://schema.org'。
   • 添加软件包或运行生成器的命令示例时，优先使用 bun／bunx。

判断

• 仅提供类型。 schema-dts 可在编译时捕获错误的 @type／未知属性，但不会在运行时对照 Google Rich Results 或 Schema.org 进行验证。
• 使用预构建软件包中的 Schema.org 核心内容。待定／实验性层需要通过自定义的 schema-dts-gen 运行生成，不能手写 as 类型断言。
• 顶层 JSON-LD 文档始终使用 WithContext<T>（或 Graph），确保 @context 为必填项且限定为 https://schema.org。
• 优先选择与页面匹配的最窄类型（Product、Article、FAQPage），不要将所有内容都声明为 Thing。
• 仅当 @type 确实是具体类型数组时，才使用 *Leaf + MergeLeafTypes。绝不要将 Product 等联合类型别名传入 MergeLeafTypes。
• 类必须 implements 某种 Schema.org 结构时，使用 *Leaf 接口；联合类型别名无法用于 implements。
• 对任何自定义或第三方本体，运行 schema-dts-gen 2.0.1+。2.0.0 允许 rdfs:comment 文本将代码注入生成的输出中（GHSA-c4f4-pq98-f2p2）。
• 在 Graph 中使用 @id + IdReference 存根交叉链接重复实体，而不是重复嵌套对象。
• 对站内链接搜索框／Action 标记，使用 WithActionConstraints 包装或进行类型断言，使 query-input（以及其他 *-input／*-output）通过类型检查。
• 注入 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 Rich Results Test 或 Schema Markup Validator。
• 升级到 v2 后，重新检查符合 Role 结构的属性、Quantity 赋值、多类型节点，以及任何自定义 schema-dts-gen 输出（现在会导入 schema-dts-lib）。