• 知识图谱
• 数据

本指南以 Schema.org 开源仓库（schemaorg）为对象，系统讲解其数据目录的格式规范、发布快照体系、词汇提案流程与本地构建运行方式。仓库以data/目录存放全部词汇定义与示例、以software/目录存放支撑网站发布的 Python 工具链；读完本文，你将掌握如何在仓库中定位与解读schema.rdfa/schema.ttl词汇文件、如何运行本地站点构建与调试，以及如何参与 Schema.org 词汇的提议与评审。

仓库定位：词汇、示例与发布软件的统一体

正如仓库根目录的 README.md 所述：这是 Schema.org 项目仓库，它包含发布 Schema.org 所使用的全部词汇（schemas）、示例（examples）与软件（software），而 Schema.org 官方网站本身则是该仓库的产出物。与此对应，data/releases/4.0/README.md 正是随 4.0 正式发布打包的仓库自述文档，它记录了这一版本时代仓库的完整组织方式与协作约定。

在该版本的自述中明确了几项协作基础设施：

• Issue 与提案的管理：由 W3C Schema.org Community Group 的参与者负责，感兴趣者需要加入该社区组并在仓库中查找或提交 Issue。
• 发布规划入口：GitHub 上的 Issue #1 是发布规划的入口点，提供待办工作的总体概览，涵盖主题、具体 Issue 与发布里程碑。
• 持续集成：仓库接入 Travis-CI 对进入的 Pull Request 进行自动检查（当前版本已演进为 GitHub Actions 工作流，见根 README.md 中的 CI 徽章）。
• 发布节奏：每月左右，经过 Schema.org Steering Group 最终评审后进行一次正式发布；每次发布都会把默认分支切换到对应发布代号。

词汇提案机制：如何向 Schema.org 建议新词

Proposing schemas一节是协作规范的核心，它定义了新词汇从提议到被接受的取舍原则，这些原则在今天仍主导着仓库的演进方向。

优先级与证据导向

仓库优先考虑对既有词汇、示例与文档的简单修复和改进，而不是添加全新词汇。是否新增词汇，关键判断标准是：是否存在（最好是大规模的）消费方应用会实际使用这些数据。消费方并不局限于搜索引擎，也可以是开源软件工具、增强标记的 Web 分析方案、浏览器插件或云工具。仅以"搜索引擎一般会使用结构化数据"为由不足以支撑新增词汇，较小的、向后兼容的改动更容易被纳入。

简化哲学与独立扩展

Schema.org 有意不追求捕获 Web 内容的全部细节，它是复杂现实的必要简化。因此很多看似可加入的细节往往不会被采纳，目的是保持词汇对发布者与站长足够简单可用。同时，Schema.org 不是封闭系统，它依托 JSON-LD、Microdata、RDFa 等 Web 标准支持独立扩展，其他倡议（如 Wikidata、GS1 词汇表）的术语可以与 Schema.org 自身定义的术语混用。

对于大规模术语重组，仓库持谨慎态度：若仅出于"优雅""正确建模""本体纯粹性"或"概念统一"等动机，一般不会被接受。项目在规模与性质上要求用"渐进演化 + 务实容忍"替代形式本体的全局一致性，跨领域的基于逻辑的知识结构统一提案更适合提交给其他本体社区。

发布与反馈的实践约定

• 提出改进前请先搜索旧讨论（含已关闭 Issue）；特别欢迎对既有定义、示例与文本的澄清性改进。
• 若提案被标记为 "noted" 后关闭，不必意外——仓库有数百个待讨论 Issue，对暂不深入探索的采用"记录后关闭"的约定。
• Pull Request 应当关联其修复或解决的特定 Issue，让讨论与具体（且易过时的）补丁解耦；任何实质性开发工作需先与项目团队达成一致。
• 改动难度差异很大：定义措辞的调整相对容易，而类型/属性拼写（如Person、startDate）的变更破坏性极强，须格外慎重。
• 新词常先进入 "Pending" 区域，此阶段强烈欢迎全局视角的反馈（新词与其他词的关系、如何与既有模式配合使用等），整合阶段通常体现为措辞微调、示例补充或文档链接修正，而非大规模重构。

数据目录的格式与标准

Formats and standards一节定义了仓库数据文件的组织约定，这些约定直接决定了 4.0 快照与当前主线的目录形态。

文件编码与目录分工

• 全部词汇与示例均位于data/目录，采用 utf-8 编码。
• 4.0 时代的主词汇文件为data/schema.rdfa（utf-8）；开发过程中的词汇可以放在形如data/sdo-somethinghere-schema.rdfa的独立文件中。当前主线已迁移为 Turtle 格式的 data/schema.ttl（根 README.md 已注明主文件为schema.ttl），4.0 快照则完整保留了当时的 RDFa 主文件 data/releases/4.0/schema.rdfa。
• 格式基础：4.0 时代的格式基于 W3C RDFS 的 HTML/RDFa 表示（见 data/releases/4.0/schema.rdfa 首部的说明：使用 RDFa 1.1 初始上下文中声明的简化前缀子集，注释中采用 Markdown 语法便于超文本文档编辑）。
• 示例文件：示例存储在 data/examples.txt 与仓库中其他*examples.txt文件中。与词汇合并进主文件的处理方式不同，示例始终保留在独立文件中，因为这样更契合 git 的文件比较机制。

词汇文件的典型结构

以 data/schema.ttl 为例（当前主线），词汇以 Turtle 三元组表达 RDFS 模型，例如:AboutPage a rdfs:Class声明类型、rdfs:subClassOf :WebPage声明父子关系、rdfs:comment承载带[[编码]]链接语法的自然语言定义。而在 4.0 快照 data/releases/4.0/schema.rdfa 中，同一模型以 HTML/RDFa 呈现：

<div typeof="rdfs:Class" resource="http://schema.org/Thing"> <span class="h" property="rdfs:label">Thing</span> <span property="rdfs:comment">The most generic type of item.</span> </div>

每个术语都以rdfs:label、rdfs:comment及可选的rdfs:subClassOf/dc:source表达；dc:source通常指向影响该术语设计的外部来源（如 rNews）。这种 RDFa 与 Turtle 双格式并存的情况，正是发布快照与主线演进的真实写照。

示例文件的四段式结构

data/examples.txt 中每个示例遵循固定结构：TYPES:行声明涉及的术语列表，随后依次给出PRE-MARKUP（原始网页内容）、MICRODATA、RDFA以及通常还有的JSON-LD各格式标记。例如 Person 示例的 TYPES 声明与 Microdata 片段：

TYPES: #eg-0001 Person, PostalAddress, addressRegion, postalCode, address, streetAddress, extendedAddress, telephone, email, url, addressLocality

<div itemscope itemtype="https://schema.org/Person"> <span itemprop="name">Jane Doe</span> <div itemprop="address" itemscope itemtype="https://schema.org/PostalAddress"> <span itemprop="streetAddress">20341 Whitworth Institute, Suite 123, 405 N. Whitworth</span> <span itemprop="addressLocality">Seattle</span> </div> <span itemprop="telephone">(425) 123-4567</span> </div>

这种多格式并存的示例结构，既服务于网站术语页面的展示，也是测试工具验证"示例确实满足 RDF 中定义的 schema"的输入数据。

发布快照与扩展层级

• data/releases/层级保留发布快照（对应 https://schema.org/version/ 的版本化访问）。每个版本目录存放该发布时刻全套导出文件；以 4.0 快照 data/releases/4.0/ 为例，包含schema.rdfa、schema.ttl、schema.rdf、schema.nq、schema.nt、schema.jsonld、schemaorg.owl、schemaorgcontext.jsonld、各 CSV 属性/类型清单，以及all-layers.*（合并全部扩展层）和各扩展（ext-attic、ext-auto、ext-bib、ext-health-lifesci、ext-meta、ext-pending）的独立导出文件。
• ext/*/层级保留扩展词汇（对应扩展机制）。当前主线下的 data/ext/ 依然沿用attic、auto、bib、health-lifesci、meta、pending等扩展区，与 4.0 快照中的扩展文件一一对应。

本地构建与运行软件

Software一节交代了支撑 Schema.org 网站发布的核心工具链：一个简单的 Python 应用，用于在本地生成 Schema.org 网站的静态镜像，供本地测试或上传至 Google GCloud 供 Web 访问。4.0 时代的部署基于 Python 版 Google App Engine SDK，完整细节见 software/SOFTWARE_README.md。

环境准备

• 需要 Linux 类（含 macOS）环境，Python 3.11 或以上；Windows 用户建议使用 WSL2。
• 建议创建虚拟环境并以可编辑模式安装软件包（software/pyproject.toml 声明了第三方依赖与各 schema.org 包），使本地编辑即时生效：

python3 -m venv .venv source .venv/bin/activate pip install -e software

开发工具（mypy、pytest）可通过pip install -e "software[dev]"一并安装。安装同时会在虚拟环境中生成命令别名（如build_site、build_schema、run_tests、dev_server），与脚本路径形式等价。

初始构建与本地服务

./software/scripts/buildsite.py -a # 全量构建，生成 site/ 目录 ./software/scripts/devserv.py # 本地服务，默认 localhost:8080

首次完整构建需 5–20 分钟（依机器配置而定），仅在初始或重大变更后需要。site/目录是网站镜像，不会提交进仓库；devserv.py支持--host与--port选项改变监听地址，本地开发时改动页面即时生效（浏览器缓存可能需强制刷新）。

增量构建：按需重建术语页与文件

开发阶段无需全量构建，buildsite.py 的initialize()中定义了丰富选项（-a全量、-c清空输出、-d文档页、-e补示例 ID、-f输出文件、-t术语页、-s静态页、-r先跑测试、--shacltests跑 SHACL 验证，以及--release/--buildrelease/--buildsite三档发布构建），常用组合如：

./software/scripts/buildsite.py -t Book sameAs # 重建 Book 与 sameAs 术语页 ./software/scripts/buildsite.py -t All # 重建全部术语页 ./software/scripts/buildsite.py -f Owl # 重建 docs/schemaorg.owl ./software/scripts/buildsite.py -f RDFExport.turtle # 重建 Turtle 格式词汇定义 ./software/scripts/buildsite.py -d PendingHome # 重建 pending 区首页 ./software/scripts/buildsite.py -s # 同步静态文档页与 CSS

测试、版本控制与部署

• 本地测试：software/scripts/buildsite.py -a -r --shacltests会全量构建并断言 schema 自洽、示例满足 RDF 定义的约束（--shacltests执行 Python SHACL 测试）。
• 版本控制：构建脚本以单一配置文件 versions.json 控制所构建的发布版本；修改schemaversion并在releaseLog增加对应条目（未就绪的版本日期以XX占位，如"11.2": "2020-XX-XX"）后，需执行buildsite.py -a全量重建。当前主线schemaversion已到 30.1，而 4.0 对应releaseLog中的"4.0": "2019-10-15"。
• 部署：./software/gcloud/deploy2gcloud.sh可将本地版本部署到 appengine 实例，需提供合法的 appengine 项目名与版本 ID（不必与 Schema 版本号一致），并接受默认的other.yaml；另有面向 webschemas.org 与 schema.org 的专用部署脚本。

发布命名与分支管理

Github Branch naming一节解释了发布代号机制：发布列表按工作代号与发布名双重命名，例如 v1.91 的继任者代号为sdo-venkman，最终成为 v1.92；候选发布说明草稿可在仓库的docs/releases.html中查看。当前主线已不再为进行中的工作使用分支，main分支作为最新候选，虽不保证概念上完全一致，但会在发布候选分发评审前趋于稳定（根 README.md）。

在 4.0 快照中，这一约定体现为随发布同步更新的data/releases/4.0/全套导出文件：从schema.rdfa/schema.ttl等词汇定义、schemaorg.owl本体导出、schemaorgcontext.jsonldJSON-LD 上下文，到*-properties.csv/*-types.csv术语清单，再到all-layers.*合并层与各扩展独立导出，完整构成可独立复现该版本词汇状态的归档。

协作语言与文档定位

Notes一节提醒：仓库文档面向软件代码库而非 schema.org 站点本身；同时，代码与 schema 中的标签、注释与文档应统一使用美式英语，如遇英式/美式选择时以国际通用英语为目标。

从 4.0 快照到当前主线

将 data/releases/4.0/README.md 与根 README.md 对照，可以看到仓库的数处演进：主词汇文件由 RDFa 的schema.rdfa迁移为 Turtle 的data/schema.ttl；部署环境由 Python 版 App Engine SDK 演进为 Python 3.11+ 与 gcloud；持续集成由 Travis-CI 迁移至 GitHub Actions；分支模型从"按发布切换默认分支"演进为main单一候选分支。但核心架构与约定始终如一：词汇与示例分离存放于data/、扩展位于ext/*/、发布快照归档于data/releases/、以versions.json单一配置驱动构建。理解这份 4.0 时代的基础文档，即可顺畅衔接当前主线的构建、测试与发布工作流。

• 知识图谱
• 数据