describe

为了减少链上数据存储量，方便拓展数据模型，POB 引入了 JSON-Schema 规范，如果您对此不熟悉，请您先对它有个初步的了解。

你会在链上、SDK、API 中经常看到 describe 字段，它是存储在 IPFS 上的 JSON 对象，用于描述数据模型，我们称之为 describe schema。在 POB 中，主要有 Workflow Template 和 Task Template 需要使用到 describe。如果您在使用 POB SDK 创建任务、工作流，提交工作流等，我们会在内部根据不同的 Workflow、Task 模板做数据校验，如果不符合模板中定义的规则，会抛出异常。

我们先来看一个示例：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "POB workflow or task schema title",
  "description": "POB workflow or task schema description",
  "tags": ["your tag"],
  "type": "object",
  "properties": {
    "issuer": {
      "type": "object",
      "description": "Form content for task issuer.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the task"
        },
        "description": {
          "type": "string",
          "description": "Description of the task"
        },
        "tags": {
          "type": "array",
          "description": "Tags of the task",
          "items": {
            "type": "string"
          }
        },
        "project": {
          "type": "string",
          "description": "MetaJam project slug."
        }
      }
    },
    "taker": {
      "type": "object",
      "description": "Form content for task taker.",
      "properties": {
        "content": {
          "type": "string",
          "description": "Content of the task"
        }
      }
    }
  }
}

我们为了更好的描述工作流、任务，我们定义了基本字段，这也是必填字段，下面我们来了解下有哪些基本字段。

基本字段

无论是工作流模板还是任务模板，都有以下基本字段：

{
  "title": "POB workflow or task schema title",
  "description": "POB workflow or task schema description",
  "tags": ["your tag"]
}

title: 表示模板的名称，必填字段。
description: 表示模板的简介，必填字段。
tags: 表示模板的标签，必填字段。

下面我们来看看 describe 是如何在这两个模板中应用的。

工作流模板

工作流模板的 describe schema 相对来说比较简单，它面向的对象只有 issuer。所以一般情况下，我们只需要在 issuer 中定义一些字段，比如：

{
  "issuer": {
    "name": "Your workflow name",
    "description": "Your workflow description",
    "tags": ["Your tag"],
    "project": "Your project slug"
  }
}

当然这只是 schema 中的一部分数据，我们需要结合基本字段和 JSON-Schema 规范提供一个完整的 schema，它看起来像这样：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "POB workflow schema title",
  "description": "POB workflow schema description",
  "tags": ["your tag"],
  "type": "object",
  "properties": {
    "issuer": {
      "type": "object",
      "description": "Form content for workflow issuer.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Your workflow name"
        },
        "description": {
          "type": "string",
          "description": "Your workflow description"
        },
        "tags": {
          "type": "array",
          "description": "Your workflow tags",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}

Ok, 这很棒，我们已经定义了一个完整的 schema，但是还没有提交到 IPFS 上。当您在创建工作流模板时，POB SDK 会自动将上述 schema 提交到 IPFS 上，并且获得一个 hash 值，这个 hash 值就是您的工作流模板的 describe，它将被存储在区块链上。

当 issuer 选择该模板并且想要创建一个工作流时，POB Dapp 会自动解析上述 schema 数据，并且根据字段的类型渲染成一个表单。在完成创建工作流所需的数据后，POB SDK 会自动获取该模板在链上存储的 describe 值并且完成 IPFS 数据解析，然后对 issuer 提交的工作流信息和上面的 schema 进行数据校验，如果校验不通过，则会直接抛出异常。

现在让我们来看看任务模板吧。

任务模板

和工作流模板不同的是，任务模板面向的对象有 issuer、taker 和 reviewer。当我们创建任务模板时，我们需要告知使用该模板（issuer）、提交任务（taker）和审批该任务（reviewer）的用户需要提交哪些信息。

我们为了更清晰的描述这些不同角色用户所需要关注的数据，我们定义了三个字段，分别是：issuer、taker 和 reviewer。

issuer

对于模板创建者来说，您可以在 issuer 字段中定义 issuer 在使用该模板时需要填写哪些信息，这些信息一般对于 taker 和 reviewer 非常有帮助，下面我们以上面的 Schame 示例作为基础来看看如何定义数据：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "POB task Schema",
  "description": "POB task description",
  "tags": ["your tag"],
  "type": "object",
  "properties": {
    "issuer": {
      "type": "object",
      "description": "Form content for task issuer.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the task"
        },
        "description": {
          "type": "string",
          "description": "Description of the task"
        }
      }
    }
  }
}

正如您所看到的，我们在 issuer 字段中定义了两个字段，name 和 description。在 issuer 使用该任务模板时，我们将会显示这两个字段，以便让 issuer 填写。

我们假设 Jack（issuer）使用了该任务模板创建了一个任务，并且 name 和 description 字段分别填写了：Jack's task 和 Jack's task description。在他完成工作流创建之后，所有用户都可以看到在该工作流下有个名为 Jack's task 的任务，并且任务简介是 "Jack's task description"。

那么对于 taker 来说，他需要提交哪些数据呢？这就需要在 taker 字段中描述了。

taker

对于 taker 来说，他需要清晰的知道提交什么数据，这些数据可以在 taker 字段中描述。下面我们结合上面的示例来看看如何定义数据：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "POB task Schema",
  "description": "POB task description",
  "tags": ["your tag"],
  "type": "object",
  "properties": {
    "issuer": {
      "type": "object",
      "description": "Form content for task issuer.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the task"
        },
        "description": {
          "type": "string",
          "description": "Description of the task"
        }
      }
    },
    "taker": {
      "type": "object",
      "description": "Form content for task taker.",
      "properties": {
        "content": {
          "type": "string",
          "description": "Your works."
        }
      }
    }
  }
}

可以看到，上面我们在 taker 字段中定义了一个 content 字段并且类型是 string，当 taker 来提交任务时，他会看到这个字段，并且需要填写。这对于一般任务来说，上面这种定义会非常常见。

reviewer

对于 reviewer 来说，他关注的是 taker 提交了什么内容，自己需要提交什么审批意见。我们可以在 reviewer 字段中定义它，我们结合上面的 schema。例如：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "POB task Schema",
  "description": "POB task description",
  "tags": ["your tag"],
  "type": "object",
  "properties": {
    "issuer": {
      "type": "object",
      "description": "Form content for task issuer.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the task"
        },
        "description": {
          "type": "string",
          "description": "Description of the task"
        }
      }
    },
    "taker": {
      "type": "object",
      "description": "Form content for task taker.",
      "properties": {
        "content": {
          "type": "string",
          "description": "Your works."
        }
      }
    },
    "reviwer": {
      "type": "object",
      "description": "Form content for task issuer.",
      "properties": {
        "content": {
          "type": "string",
          "description": "Your opinion on approval."
        }
      }
    }
  }
}

可以看到，上面我们在 reviewer 字段中定义了一个 content 字段并且类型是 string，当 reviewer 来审批任务时，他会看到这个字段，并且需要填写。例如他可以在这里填写自己的审批意见，这对于普通审批任务，上面这种定义会非常常见。

describe

基本字段#

工作流模板#

任务模板#

issuer#

taker#