潜在操作

以下描述了与 https://schema.org/Action 一起使用的一些术语和约定。其目的是为了能够描述在未来执行操作的能力，以及如何行使这种能力。请参阅博客文章 Schema.org Actions（2014 年 4 月）以获取更多背景。早期草稿和替代格式可从 W3C Wiki 获取。

第一部分：操作状态

首先，我们需要一种机制来区分潜在操作与已经发生或仍在进行的操作。期望操作的状态通常基于使用上下文是自明的，因此此属性通常可以省略。然而，在出现歧义的情况下，可能仍需要它来解决歧义。为此，我们引入 Action 的新属性 actionStatus。

属性	预期类型	描述
actionStatus	ActionStatusType	指示 Action 的当前处置。

Thing > Intangible > Enumeration > ActionStatusType

操作的状态。

枚举成员

• ActiveActionStatus - 正在进行的操作（例如，正在观看电影，或开车到某个地点）。
• CompletedActionStatus - 已经发生的操作。
• FailedActionStatus - 未完成的操作。
• PotentialActionStatus - 支持的操作描述。

示例：actionStatus

{
  "@context": "https://schema.org",
  "@type": "WatchAction",
  "actionStatus": "CompletedActionStatus",
  "agent" : {
    "@type": "Person",
    "name": "Kevin Bacon"
  },
  "object" : {
    "@type": "Movie",
    "name": "Footloose"
  },
  "startTime" : "2014-03-01"
}

第二部分：将操作连接到事物

操作经常在对象的上下文中进行或提供（例如，观看这部电影，审查这篇文章，分享此网页等）。我们引入一个名为 potentialAction 的新属性，用于描述可以在该事物上执行的操作的“原型”。

属性	预期类型	描述
potentialAction	Action	指示潜在操作，它描述了该事物将在其中扮演“对象”角色的理想化操作。

示例：Thing.potentialAction

{
  "@context": "https://schema.org",
  "@type": "Movie",
  "name": "Footloose",
  "potentialAction": {
    "@type": "WatchAction"
  }
}

第三部分：操作入口点

潜在操作通过针对操作的目标 EntryPoint 执行来实现。

示例：操作目标 URL

{
  "@context": "https://schema.org",
  "@type": "Movie",
  "name": "Footloose",
  "potentialAction": {
    "@type": "WatchAction",
    "target" : "http://example.com/player?id=123"
  }
}

对于某些平台和用例，简单的 URL 不足以制定请求和/或处理结果，因此我们引入一个新的 EntryPoint 类，用于在必要时指定超出 URL 的附加上下文。

属性	预期类型	描述
target	EntryPoint	用于执行操作的入口点。

Thing > Intangible > EntryPoint

属性	预期类型	描述
urlTemplate	Text	将用于构造操作执行目标的 URL 模板（RFC6570）。
encodingType	Text	请求支持的 MIME 类型。
contentType	Text	响应支持的 MIME 类型。
httpMethod	Text	指定 HTTP 请求适当 HTTP 方法的 HTTP 方法。值是大写字符串，如 HTTP 中使用。
application	SoftwareApplication	主机应用程序。

基于方案的 EntryPoint 编码

理想情况下，简单的“深度链接”用例应该只使用简单的 URL 模板。在某些情况下，甚至可能为某些平台创建新方案，例如：

android-app://{package_id}/{scheme}/{host_path}

示例：多平台 URL

注意：我们期望平台特定绑定的细节通过实施经验演化和澄清。这些示例指示一般方法而不是每个平台的精确信息需求。另请注意，此处显示的示例语法不是严格的 JSON；为了可读性，已添加内联注释。

{
  "@context": "https://schema.org",
  "@type": "Restaurant",
  "name": "Tartine Bakery",
  "potentialAction": {
    "@type": "ViewAction",
    "target": [
      /* Web 深度链接 */
      "http://www.urbanspoon.com/r/6/92204",
      /* 返回 JSON-LD 的 HTTP API */
      {
        "@type": "EntryPoint",
        "urlTemplate": "http://api.urbanspoon.com/r/6/92204",
        "contentType": "application/json+ld"
      },
      /* Android 应用深度链接 */
      "android-app://com.urbanspoon/http/www.urbanspoon.com/r/6/92204",
      /* iOS 深度链接 */
      {
        "@type": "EntryPoint",
        "urlTemplate": "urbanspoon://r/6/92204",
        "application": {
          "@type": "SoftwareApplication",
          "@id": "284708449",
          "name": "Urbanspoon iPhone and iPad App",
          "operatingSystem": "iOS"
        }
      },
      /* Windows Phone 深度链接 */
      {
        "@type": "EntryPoint",
        "urlTemplate": "urbanspoon://r/6/92204",
        "application": {
          "@type": "SoftwareApplication",
          "@id": "5b23b738-bb64-4829-9296-5bcb59bb0d2d",
          "name": "Windows Phone App",
          "operatingSystem": "Windows Phone 8"
        }
      }
    ]
  }
}

第四部分：输入和输出约束

通常需要来自用户或客户端的附加信息来制定完整请求。为了促进此过程，我们需要在潜在操作中描述如何构造这些输入。由于我们需要此功能来填充操作的任何属性，我们引入使用连字符（”-“）分隔符的属性注释概念。例如，通过在潜在操作上指定”location-input”属性，我们指示”location”是完成操作的支持输入。

同样，指示客户端在最终完成的操作版本中将包含什么也是有帮助的，因此我们引入相应的 -output 注释，用于指示哪些属性将在完成的操作中存在。

Thing > Intangible > EntryPoint

注释	预期类型	描述
<property>-input	PropertyValueSpecification	指示在启动操作之前应如何填写属性。
<property>-output	PropertyValueSpecification	指示操作完成时字段将如何填写。

Thing > Intangible > PropertyValueSpecification

属性值规范。

属性	预期类型	描述
valueRequired	Boolean	是否必须填写属性以完成操作。默认值为 false。等同于 HTML 的 input@required。
defaultValue	Thing, DataType	属性的默认值。对于期望 DataType 的属性，它是一个文字值；对于期望对象的属性，它是对当前值之一的 ID 引用。等同于 HTML 的 input@value。
valueName	Text	指示在 URL 模板和表单编码中使用的 PropertyValueSpecification 的名称，类似于 HTML 的 input@name。
readonlyValue	Boolean	属性是否可变。默认值为 false。等同于 HTML 的 input@readonly。为同时具有值的属性指定此项使其行为类似于 HTML 表单中的”隐藏”输入。
multipleValues	Boolean	属性是否允许多个值。默认值为 false。等同于 HTML 的 input@multiple。
valueMinLength	Number	指定文字值中的最小字符数。等同于 HTML 的 input@minlength。
valueMaxLength	Number	指定文字值中的最大字符数。等同于 HTML 的 input@maxlength。
valuePattern	Text	指定用于测试文字值的正则表达式。等同于 HTML 的 input@pattern。
minValue	Number, Date, Time, DateTime	指定文字值的允许范围和间隔。等同于 HTML 的 input@min, max, step。某些特征或属性的较低值。
maxValue	Number, Date, Time, DateTime	某些特征或属性的较高值。等同于 HTML 的 input@min, max, step。
stepValue	Number	step 属性指示预期（和必需）的值的粒度。

minValue、maxValue 和 stepValue 属性指定文字值的允许范围和间隔，并等同于 HTML 的 input@min, max, step。还应注意，如果属性及其 -input 注释都存在，则未注释属性的值应被视为输入的允许选项（类似于 HTML 中的 <select><option>），除非 Input 指示值也是只读的，在这种情况下，所有值应以类似于表单中隐藏输入的方式返回。

输入和输出的文本表示

为了方便，我们还支持这两种类型的文本简写，其格式和命名类似于它们在 HTML 等价物中的外观。例如：

"<property>-input": {
  "@type": "PropertyValueSpecification",
  "valueRequired": true,
  "valueMaxlength": 100,
  "valueName": "q"
}

也可以表示为：

<property>-input: "required maxlength=100 name=q"

URI 模板

最后，我们还允许 URI 模板化（使用 RFC6570），用于将 -input 属性的结果值内联到操作 URL 中。模板中允许的替换引用是填充属性的点状模式路径（相对于 Action 对象）。

示例：带有 -input 的文本搜索深度链接

描述

{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "Example.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "http://example.com/search?q={q}",
    "query-input": "required maxlength=100 name=q"
  }
}

请求

GET http://example.com/search?q=the+search

示例：带有 -output 的产品购买 API 调用

描述

{
  "@type": "Product",
  "url": "http://example.com/products/ipod",
  "potentialAction": {
    "@type": "BuyAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://example.com/products/ipod/buy",
      "encodingType": "application/ld+json",
      "contentType": "application/ld+json"
    },
    "result": {
      "@type": "Order",
      "url-output": "required",
      "confirmationNumber-output": "required",
      "orderNumber-output": "required",
      "orderStatus-output": "required"
    }
  }
}

请求

POST https://example.com/products/ipod/buy

响应

{
  "@type": "BuyAction",
  "actionStatus": "CompletedActionStatus",
  "object": "https://example.com/products/ipod",
  "result": {
    "@type": "Order",
    "url": "http://example.com/orders/1199334",
    "confirmationNumber": "1ABBCDDF23234",
    "orderNumber": "1199334",
    "orderStatus": "PROCESSING"
  }
}

示例：带有 -input 和 -output 的电影评论网站 API

描述

{
  "@context": "https://schema.org",
  "@type": "ReviewAction",
  "target": {
    "@type": "EntryPoint",
    "urlTemplate": "https://api.example.com/review",
    "encodingType": "application/ld+json",
    "contentType": "application/ld+json"
  },
  "object": {
    "@type": "Movie",
    "url-input": "required",
  },
  "result": {
    "@type": "Review",
    "url-output": "required",
    "reviewBody-input": "required",
    "reviewRating": {
      "ratingValue-input": "required"
    }
  }
}

请求

POST https://api.example.com/review

{
  "@context": "https://schema.org",
  "@type": "ReviewAction",
  "object": {
    "@id": "http://example.com/movies/123"
  },
  "result": {
    "@type": "Review",
    "reviewBody": "yada, yada, yada",
    "reviewRating": {
      "ratingValue": "4"
    }
  }
}

响应

{
  "@context": "https://schema.org",
  "@type": "ReviewAction",
  "actionStatus": "CompletedActionStatus",
  "result": {
    "@type": "Review",
    "url": "http://example.com/reviews/abc"
  }
}