高级JSON表单规范 - 第一章：引言

Don Fizachi

4.97/5 (12投票s)

2016 年 7 月 18 日

LGPL3

9分钟阅读

28755

1118

JSON表单规范。

章节

引言

在这篇 8 章的文章中，我们提出了一种用于定义动态表单的 JSON 规范，这些表单可以在任何理解 JSON 的平台上打开和填写。这些高级 JSON 表单可用于收集从简单的字母数字值到多媒体文件或基于位置的信息等各种数据。可以在这些表单中设置约束，以确保只接受有效值作为输入。这些高级表单中存在允许在必要时跳过输入的特性。此高级表单规范中还包含许多其他特性，最好通过示例来描述。为此，这篇多章节文章将使用一个 Android 应用程序来描述该规范，并演示以下功能（以及其他功能）：

20 种不同的输入屏幕类型
元数据收集
表单屏幕跳过逻辑
重复屏幕
并
多语言支持

请注意，读者熟悉 JSON schema 规范对于理解本文的其余部分非常重要。请在此处参阅快速入门指南。

背景（如果您愿意，可以跳过本节）

设想一个需要进行大规模数据调查的场景。在这种情况下，每个数据收集员或清点员都配备有手持设备，例如手机或平板电脑。这些清点员从远程服务器下载调查表到他们的设备上，然后到现场收集由下载的表单参数定义的数据。当表单的每个实例完成后，会立即将其上传到服务器，或在设备连接建立后尽快上传。调查结束时，将对数据进行分析。上述场景简而言之，就是我过去几年主要关注的问题。

与电子数据收集相关的一系列特性帮助我和我的团队确保了可接受的数据质量。例如，电子表单设置的约束阻止了清点员输入通常被认为无效的数据。我们没有使用纸笔收集数据然后再将其转换为电子格式，这进一步减少了数据中的错误量。

ODK 社区（比其他任何实体都做得更多）在推动大规模电子数据收集领域方面做出了巨大贡献。事实上，直到最近，我们主要的数据收集工具一直是 ODK Collect。这些工具（即 ODK）是开源的，这意味着它们可以被构建或扩展，正如许多人过去所做的那样。

我们需要数据收集工具具备更多功能，当时我们考虑了两种选择：一种是基于 ODK 进行构建，另一种是从头开始。我们决定重新开始，原因如下（除其他外）：

我们希望数据收集的格式与数据存储、传输、呈现、查询和分析的格式相匹配。如本文文章所述，JavaScript 对象表示法（JSON）被选为首选格式。结果发现，在大小方面，JSON 表单比 ODK 在大多数用例中实现的类似 XML 表单要小得多。公平地说，在 ODK 成立之初，JSON 仍处于起步阶段，XML（通过 ODK XForms）是唯一可行的平台无关的表单定义格式。
我们致力于利用 JSON Schema (version 4) 的内置约束参数来进行表单输入验证。
对于需要极高保密性的场景，我们希望在加密操作的核心放置机制，该机制允许使用唯一的临时密钥和强大的对称加密协议对每个已完成的表单实例进行加密。在我们的案例中，Diffie–Hellman (D–H) 密钥交换机制用于计算一次性密钥，而高级加密标准用于加密。

借鉴 ODK 社区的成果，我们在上下文中，着手构建本文 8 章所描述的创新型 JSON 高级表单规范。

使用 Android 应用程序

正如引言部分所述，此高级 JSON 表单规范主要用于在图形用户界面 (GUI) 上显示。我们提供了一个名为 _CCA Mobile_ 的 Android 应用程序（由 CCA System 提供），作为本文的补充，以演示表单如何在 GUI 上显示。

要开始使用，请在 Android 设备上下载并安装该应用程序。此外，请下载名为 _City Census Form.zip_ 的文件。从 ZIP 文件中提取 JSON 表单，然后将其复制到您的 Android 设备。

在应用程序中点击“表单”按钮，然后点击“点击获取新表单”按钮以打开最初复制到设备上的“_City Census.json_”表单。完成此操作后，点击表单开始填写，通过向左或向右滑动并输入值。在到达末尾时保存（或不保存）表单。

要查看已完成表单实例的外观，请返回 **CCA Mobile** 的主屏幕，然后点击“备份”按钮。点击“City Census”表单。选择要备份的已完成实例。点击屏幕底部的备份按钮。选定的实例将写入 SD 卡上的“/CcaMobile/Backup/”目录。现在，使用文本编辑器或其他类似工具打开备份的 JSON 实例文件。

请注意，提供的 Android 应用程序 _CCA Mobile_ 是主应用程序的精简版本。附带的应用程序严格用于演示高级 JSON 表单的功能。此应用程序的所有明示和未明示的权利均归 CCA System 所有。

JSON 高级表单模式

本节假定读者已安装 Android 应用程序并已尝试使用 _City Census_ 表单。

表单的基本结构

下面的代码块显示了表单实例示例的摘录。

/*    
{
"formName": "City Census", 
"formID": "76ce800b-acf9-4bb0-9f9d-b1b41acdb606", 
"formDescription": "This form captures the population of cities in 1950, 
                    2000 and projected population in 2050", 
"canSavePartial": true, 
"formScreens": [
{


...

]
}
*/

从以上内容可以看出，一个表单由多个 JSON 变量组成。这些变量在下面的要点中进行描述：

formName：此变量为 JSON string 类型，其值是表单的可读名称。
formID：这是一个全局唯一的标识表单的值。其值是 JSON string 类型。
formDescription：这是一个人类可读的 string，用于描述表单。其值是 JSON string 类型。
formPublicKey（此处未显示）：这是一个 JSON string 值，以 base 64 字符串格式包含一个公钥。此公钥用于计算对称加密密钥，然后用于加密每个已完成的表单实例。其值是 JSON string 类型，并且在表单中是可选的。此 JSON 变量在第 8 章中进行了讨论。
canSavePartial：这是一个 JSON 布尔值，指示是否可以保存部分完成的表单并在稍后更方便的时间完成。
formScreens：此变量是一个 JSON 数组类型，包含用户必须输入值的表单输入屏幕的定义。表单屏幕的结构在下一节中讨论。

定义有效表单的模式已附加到本文中，即 **Form Schema Verbose** 或 **Form Schema Compact**。这两个文件类似，只是 Form Schema Compact 文件使用 JSON #ref 关键字来减小其大小，从而使其更易读。

有兴趣的读者可以遵循这些演练的表单定义部分，以了解如何使用此 GUI 工具设计表单。

表单输入屏幕的基本结构

上面的图像应该读者应该很熟悉，因为这是 **City Census** 表单中的第三个输入屏幕。请注意，此表单的设计方式是：如果显示设备的语言设置为英语，则显示左侧的屏幕。如果设备的语言设置为法语，则显示右侧的屏幕。为了理解如何定义输入屏幕，请考虑下面的 JSON 代码块。

/*    
{
"mainScreen":  {
"screenID": "City", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "3. What is the name of this city?", 
"screenHint": "Do not leave blank."
}, 
{
"localeCode": "fr", 
"screenLabel": "3. Quel est le nom de cette ville?", 
"screenHint": "Ne pas laisser en blanc."
}], 
"screenwidgetType": "textInput", 
"inputRequired": true, 
"widgetSchema": "
\"City\": {
\"type\": \"string\"
}"
}

*/

上面的示例代码块显示了所有 JSON 输入屏幕通用的参数。这些参数定义如下：

mainScreen：这是一个 JSON object，包含定义表单屏幕如何显示以及输入屏幕必须符合的约束的参数。
screenID：这是一个 JSON string 值，用于唯一标识表单内的屏幕。
screenwidgetType：这是一个 JSON string 值，用于标识输入屏幕的类型，例如文本输入、数字输入、多选选项、单选选项、位置坐标捕获、照片捕获等。
inputRequired：这是一个 JSON 布尔值，指示屏幕输入是必需的还是可选的。
widgetSchema：这是一个 JSON string 值，包含屏幕输入的转义 JSON schema。
screenDisplayArray：这是一个 JSON 数组，其项是一个三元组对象，包含为屏幕显示的说明文本。这些说明指导用户/清点员输入/捕获输入值。此数组的项是一个 JSON 对象，具有以下属性：
- screenLabel：这是一个 JSON string，其值包含要显示的说明。
- screenHint：这是一个可选的 JSON string，包含要显示的附加说明。
- localeCode：这是一个 JSON string，包含 ISO 639-1 两字母语言代码。此代码用于根据设备的语言设置确定是否显示关联的 screenLabel/screenHint。

典型的表单输入屏幕中还包含许多其他参数。这些参数将在本文后续部分的相应章节中进行讨论。

请参阅这些附加文件中的输入屏幕模式：**Form Schema Verbose** 或 **Form Schema Compact**。

在本篇文章的下一章（即第 2 章）中，我们将讨论基本输入屏幕的格式。

历史

2016 年 7 月 18 日：第一个版本
2016 年 11 月 3 日：对此工作进行了更正