Schema.org 结构化数据：命名规范与设计原则完全指南

注意：您正在查看 Schema.org 的开发版本。更多详情请参阅我们的工作方式。

Note: You are viewing the development version of Schema.org. For more details, see how we work.

概述

本文档是使用 Schema.org 数据以及设计新的或修订的模式的指南。它包含了模式设计原则、书写和命名规范，以及消费模式时的可用性约定。目前，它不涉及建模设计模式。有关 Schema.org 社区成员分享的更多材料，请参阅项目 GitHub 仓库 的 wiki 区域。

This document serves as a guide for using Schema.org data and for designing new or amended schemas. It contains information on principles of schema design, writing and naming conventions, as well as usability conventions for consuming schemas. It does not currently address modeling design patterns. For further materials shared by Schema.org community members, see the wiki area of the project's GitHub repository.

Schema.org 术语

在 Schema.org 数据模型中，有三种术语：类型、属性和枚举值。所有 Schema.org 数据都以图结构表示，其中实体通过命名的属性相互关联。

There are three kinds of terms in the Schema.org data model: Types, Properties, and Enumerated Values. All Schema.org data is represented in a graph structure where entities are related to each other by named properties.

类型

• 大小写格式：采用首字母大写的驼峰命名法（所有单词首字母大写，并连接成一个字符串）。

  • 例如：FoodEstablishment。
  • Case Format: Use TitleCase (all words capitalized, concatenated into a single string).
    • E.g., FoodEstablishment.

• 关联属性：类型拥有其关联的属性。

  • 例如：FoodEstablishment 拥有属性 servesCuisine。
  • 在技术讨论和机器可读文件中，会使用“域”和“范围”这两个术语，但它们并非供广泛使用。例如，我们说“alumni”的域包括 EducationalOrganization，其范围包括“Person”。
  • Associated Properties: Types have associated properties.
    • E.g., FoodEstablishment has the property servesCuisine.
    • There is technical terminology, "domain" and "range," used during design discussions and in machine-readable files, but it is not intended for widespread use. For example, we say the domain of "alumni" includes EducationalOrganization, and its range includes "Person."

• 继承：类型也会从其父类型（即其超类型）继承关联的属性。

  • 例如：FoodEstablishment 从其父类型 LocalBusiness 继承了属性 openingHours，并从其父类型的父类型 Organization 继承了属性 address。
  • Inheritance: Types also inherit associated properties from their parent types, i.e., their supertypes.
    • E.g., FoodEstablishment has the property openingHours from its parent type(s), LocalBusiness, and has the property address from its parent's parent, Organization.

属性

• 命名格式：属性名称必须使用小写驼峰命名法（第一个单词小写，后续单词首字母大写，并连接成一个字符串）。

  • 例如：servesCuisine。
  • Naming Format: Property names must use lowerCamelCase (first word lowercase, subsequent words capitalized, all concatenated into a single string).
    • E.g., servesCuisine.

• 期望类型：属性必须拥有期望的类型。

  • 例如：属性 servesCuisine 的期望类型是 Text。
  • Expected Types: Properties must have expected types.
    • E.g., the property servesCuisine has the expected type Text.

• 多期望类型：属性可以拥有多个期望类型。

  • 例如：属性 acceptsReservations 的期望类型是 Boolean 或 Text 或 URL。
  • Multiple Expected Types: Properties may have more than one expected type.
    • E.g., the property acceptsReservations has the expected type Boolean or Text or URL.

• 多类型适用：属性可以用于多个类型。

  • 例如：属性 starRating 可以用于 FoodEstablishment 或 LodgingBusiness。
  • Applicable to Multiple Types: Properties may be used on more than one type.
    • E.g., the property starRating can be used on FoodEstablishment OR LodgingBusiness.

• 属性不包含属性：属性本身不能拥有属性。

  • Properties Do Not Have Properties: Properties must not take properties.

枚举

• 待办事项：描述枚举数据模型。
• 待办事项：添加示例。
• TODO: Describe enumeration data model.
• TODO: Add example.

命名规范

• 避免名称冲突：不要给类型和属性起相同的名称。

  • 注意：Schema.org 中存在一些历史遗留案例，过去曾这样做过。应避免这种做法。
  • 例如：避免同时创建 ContactPoint 和 contactPoint。
  • Avoid Name Conflicts: Do not give the same name to a type and a property.
    • Note that Schema.org has some legacy cases where this was done in the past. This practice should be avoided.
    • E.g., Avoid creating both ContactPoint and contactPoint.

• 使用单数形式：术语名称应仅使用单数形式，即使语义上需要复数。

  • 例如：使用 parent 而不是 parents，即使对于每个类型，属性 parent 通常会有多个值。
  • Use Singular Form: Term names should use singular naming only, even if the semantics call for a plural.
    • E.g., parent and not parents, even though for each instance, there may be multiple values for the property parent.

• 介词位置：介词应放在类型或属性名称之后。

  • 例如：reservationFor。
  • Preposition Placement: Prepositions should come after the type or property name.
    • E.g., reservationFor.

• 缩写处理：创建新类型时，应拼写出缩写，除非结果过于冗长。

  • 由于历史遗留条目，Schema.org 中某些单词可能被缩写或未缩写。由于缺乏一致性，在查找模式术语时应同时搜索两种形式。
  • 例如：numTracks 作为遗留属性存在于 Schema.org 中。如果现在创建此属性，它应该是 numberOfTracks（或者更佳的是，命名为 trackCount 以与其他计数属性在语义上保持一致）。
  • Abbreviation Handling: When creating new types, spell out abbreviations, unless the result is painfully verbose.
    • Due to legacy entries, sometimes certain words may be abbreviated, or not, in Schema.org. Due to lack of consistency, you should search for both when looking for a schema term.
    • E.g., numTracks exists in Schema.org as a legacy property. If we were creating this property now, it would be numberOfTracks (or better yet, name it trackCount to be semantically aligned with other counting properties).

• 拼写规则：必须使用美式英语拼写。

  • 例如：color 而不是 colour。
  • Spelling Rules: US English spellings must be used.
    • E.g., color and not colour.

补充说明

• 语义精确性：Schema.org 类型具有超出单词本身可能含义的特定语义；消费应用程序不能仅仅因为名称合适就使用某个类型。

  • 例如：类型 Physician 指的是医生诊所，而不是作为医生的人。
  • Semantic Precision: Schema.org types have a specific semantic meaning beyond what the word itself could mean; consuming applications cannot simply use a type because the name fits.
    • E.g., Physician as a type means a physician's office, not a person who is a physician.

• 避免使用“type”一词：除非指代类型或类的技术概念，否则应避免使用“type”一词。

  • Avoid Using the Word "Type": Avoid using the word "type" unless referring to the technical notion of a type or class.

• 优先复用：当所需语义已存在时，应优先复用现有的 Schema.org 类型和属性。项目通常会调整定义（措辞或类型/属性关联）以促进这一点；有关示例，请参阅发布页面。

  • Prioritize Reuse: Existing Schema.org types and properties should be reused whenever the needed semantics already exist. The project will often adjust definitions (wording or type/property associations) to facilitate this; see the releases page for examples.

• 开放世界假设：Schema.org 采用开放世界哲学：声明的缺失不应被理解为否定。如果未提及某个属性，并不意味着它是假的，而是意味着我们不知道它是真还是假。

  • 例如：对于住宿业务，petsAllowed 是一个布尔属性（真/假）。但如果未设置 petsAllowed，则表示未知是否允许携带宠物。
  • Open World Assumption: Schema.org uses an open-world philosophy: the omission of a claim should not be taken to imply negation. If a property isn't mentioned, this doesn't mean that it is false. Rather, it means that we don't know whether it's true or false.
    • E.g., for a LodgingBusiness, petsAllowed is a boolean property (True/False). But if petsAllowed is not set, then it is unknown whether pets are allowed.