介绍：Bowtie

这是希望成为 Bowtie 间歇系列的第一个。我在这里说话并不代表 JSON Schema 组织的任何官方身份 - Bowtie 并不是我们 JSON Schema 团队今天“认可”的工具，尽管我个人希望它成为一种官方工具，并且我已经开发了它，希望它以任何意义上的“社区”为拥有者。目前，我只代表我自己作为它的作者发言 :)

JSON Schema

模式

{ "$schema": "https://json-schema.fullstack.org.cn/draft/2020-12/schema", "type": "string", "maxLength": 3}

验证长度最多为 3 的字符串。此行为是规范中所说的应该发生的。在各种编程语言中，规范的每个实现是否都正确遵循规范？对于其他更复杂的模式/实例对呢？这是 Bowtie 试图解决的关键问题 - 我们如何比较 JSON Schema 实现之间的行为差异以及规范之间的差异，希望我们能够更容易地修复实现问题并澄清规范中任何不清楚的部分？

它是什么

Bowtie 是我所说的“元验证器”，我的意思是，一个可以执行其他 JSON Schema 验证实现并收集其结果的程序。

这样做有先例。The JSONPath Comparison project 对 JSONPath 做得非常好，而 Nicolas Seriot's "Parsing JSON is a Minefield" 是 JSON 本身的一个绝佳例子。Bowtie 试图将这些想法带到 JSON Schema。

从现有的 JSON Schema 实现列表 中，Bowtie 已经 支持 9 种编程语言中的12 种实现，允许任何人运行这些实现中的任何一种并查看他们对模式和实例的看法。

它附带了一个 命令行程序，但也许更令人兴奋的是，已经设置了此 CLI 的持续自动化运行，这样 Bowtie 就可以发出一个 所有支持实现的报告。

为了生成此报告，Bowtie 运行 官方 JSON Schema 测试套件，这是我们现有的旨在测试与 JSON Schema 规范一致性的测试集。许多实现已经在 其自己的持续集成中使用此套件，但这是 JSON Schema 用户和实现者第一次能够在同一个地方看到在多个实现中运行此套件的结果。测试套件已经对我们的规范（特别是它们的验证部分）具有很好的覆盖率。该套件当然并不完美，但 Bowtie 的结果因此很好地涵盖了验证规范。

为什么它可能很有趣

Bowtie 使得最显而易见的事情是，一种简单的方法可以比较实现遵循规范的程度。这为实现的用户以及社区提供了透明度，让他们了解哪些领域可能难以实现，或者哪些领域经常被错误实现。我们希望这能带来改进和帮助解决问题的能量，并最终形成更强大的社区！

即使超出测试套件，Bowtie 也能够为其支持的实现提供统一的界面，这意味着您可以快速访问每个实现的结果，而无需学习每个实现提供的特定于语言的 API。如果您有一个模式和实例，并且希望在多个实现中运行它，或者您不熟悉或尚未设置的单个实现，Bowtie 可以提供帮助。

如何运行它？

如果您只对它的输出感兴趣（即测试套件运行的报告），您目前可以在以下链接中找到它们，对应于规范的每个版本

• draft2020-12
• draft2019-09
• draft7
• draft6
• draft4
• draft3

中期目标是将这些链接组合到一个统一的报告中（届时链接可能会更改，但希望我们会设置重定向）。

如果您想超越测试套件报告，您也可以在本地运行 Bowtie，在您想要的任何输入上运行它。Bowtie 用 Python 编写，并在 PyPI 上发布。如果您没有现有的首选设置来安装 Python 应用程序，请 使用适用于您操作系统的特定于平台的说明安装 pipx，然后运行

1$ pipx install bowtie-json-schema

这应该会为您提供一个可用的 Bowtie，您可以通过以下方式检查它

1$ bowtie --help

使用说明在 Bowtie 的文档 中，但肯定需要更多文档，因此如果您遇到无法弄清楚的事情，请告诉我（Julian），这将促使我对此进行记录。

它是如何工作的？

我不会在这篇文章中详细介绍 Bowtie 的实现，但在高层面上，Bowtie 是一个用 Python 编写的命令行程序，它协调着 OCI 容器（在松散的意义上，“Docker 容器”）的启动和关闭。它运行的容器是“测试工具”——一些小的桥接程序，它们接收任何编程语言编写的 JSON Schema 实现，然后允许来自 Bowtie 的传入请求调用被测试的库。为实现添加支持本质上意味着以这种方式实现一个测试工具（这通常很简单），并且一旦测试工具存在，该实现将在 Bowtie 的报告中亮起来，并且任何 Bowtie 用户都将能够通过 Bowtie 的统一 CLI 执行该实现。

如何帮助

有两个领域你可以（作为 JSON Schema 用户、实现作者或社区成员）提供帮助

改进实现

首先也是最明显的是，通过帮助将 Bowtie 发现的任何问题（确认后）反馈给实现方，然后帮助实现方修复这些问题。

找到你喜欢的 JSON Schema 实现以及它失败的测试。实现的 bug 跟踪器上是否存在关于这些失败的已知问题？如果以前没有，那么一个包含最小重现步骤的 issue 票（issue ticket）很可能受到实现者的欢迎，所以你可能想提交一个。如果这些问题是已知的，你可以在 Bowtie 中提交一个 pull request，其中包含有关下游问题的信息，Bowtie 可以在报告中使用这些信息（通过显示该测试被明确跳过）。这里有一个 示例 pull request 展示了如何做到这一点。

在不久的将来，请留意 Bowtie 生成的徽章，你可以用它来展示你的规范合规性（没什么比这更酷了，对吧？）。

改进 Bowtie

第二种方式是帮助改进 Bowtie 本身，我已经有很多想法了，随着越来越多的人开始使用它，这些想法只会越来越多。

为了重复上面的一部分，我自己已经实现了对 许多实现 的支持。如果你维护或使用其中一个实现，请查看我编写的测试程序 - 我可能错误地使用了你的实现（虽然到目前为止还没有发生）。

我还想提一下，我一直尝试在我的 直播中 进行 Bowtie 的工作 - 不吹嘘自己，随时欢迎你过来打个招呼，甚至可以翻看之前的直播，我曾在直播中与各种与 Bowtie 相关的项目斗争，这可能会给你一些关于如何进行工作的提示。

下面是一些关于需要帮助领域的具体指导

这是截至发布这篇文章时的最新内容，但我希望它能迅速过时。如果它看起来仍然适用，请随时联系我！

给我一些容易上手的东西

Bowtie 的 issue 跟踪器上有一份 适合新手解决的 issue 列表，我尝试对其进行整理。它们涵盖了 Bowtie 代码库的各个部分（Python 部分、前端部分以及它周围的基础设施）。该标签并不意味着该 issue 一定很容易修复，尽管很多问题确实如此。但它确实表明相关的功能或修复是“简单直观的”或范围明确的。如果你没有看到任何活动，请随时留下评论，如果你开始着手解决它。

我想学习新的实现或编程语言

这可能是最“有趣”的工作，至少我非常享受这个过程。从 实现列表 中选择一个 Bowtie 尚不支持的实现，然后按照 编写测试程序的教程，该教程将指导你了解 Bowtie 对测试程序的期望。如果教程中存在空白，请提出问题或联系我！但这可以成为一种以一种你以前从未使用过的语言编写简单程序的好方法，以及学习 JSON Schema 实现的一种方法，该实现可能与你已经熟悉的实现做出了不同的选择。

报告很丑，我是一名前端开发者或 UI 设计师，可以提供帮助

这可能是你能提供最大帮助的领域。我自己不是前端开发者，如果你还没有明白这一点，现在你明白了。我用 Bootstrap 构建的东西本质上是展示 Bowtie 发出的结果所需的最低限度。如果你有更多经验或思考如何有效地报告测试结果或比较实现，请帮助我！今天 Bowtie 的所有“前端代码”都集中在一个地方，即 一个被格式化为静态单页面网站的 Jinja2 模板。除了“让它更漂亮、更响应式或更易用”之外，这里还有一些需要关注的具体问题

• 添加客户端端的过滤和排序
• 显示组合的错误和失败计数，或者更一般地，将摘要从“计数表”改进为更直观的图形表示，以显示运行中发生的情况
• 更美观地显示 schema 和实例，或者更一般地，设计一个合适的组件或小部件来表示测试用例、它们的 schema、实例以及（子）测试
• 显示平均合规性数字，或者更一般地，我们应该显示哪些跨实现的摘要统计信息，以及应该如何显示它们？

我开发了 JSON Schema 生态系统中的其他工具

太好了！我希望 Bowtie 能很好地与其他上游或下游工具连接。举个具体的例子，鉴于 Bowtie 为下游实现提供统一的接口，“明显的”补充工具可能是对所有实现进行模糊测试，查找它们意见不一致、崩溃或更一般地产生与规范不符的行为的情况，而这些情况尚未被测试套件中的明确测试覆盖。这样做可能仅仅意味着将这样的工具连接到 Bowtie 并让它运行。请参考 这个 issue，虽然它除了上面提到的内容之外并没有提供更多细节。

其他工具与 Bowtie 相结合也可能具有良好的交互属性，因此如果你有其他想法，请告诉我，或者尝试一下！

我想贡献测试

这绝对也很有帮助。如果它们是针对规范本身的测试，请检查它们是否已存在于官方测试套件中，如果没有，请提交它们。如果它们不是官方测试套件目前覆盖的测试，例如因为它们涵盖了导致实现“崩溃”而不是产生结果的病态案例，那么现在就可以“公开”添加它们（在哪里添加尚待确定），因为 Bowtie 可以“温和地”运行实现并捕获这些错误。Bowtie 还允许进行更广泛的 $ref 相关测试，因为它的协议专门为测试程序配备了一种“注册表”，其中包含预期实现能够引用的 schema。 这个 issue 是相关的，但欢迎大家在这里提出关于我们可以添加哪些测试的想法。

我发现了一个 bug，或者有关于 Bowtie 本身的想法

如果它与实现有关，你可能应该将它提交到实现的 issue 跟踪器。请保持礼貌，因为仍然存在一个很小但非零的概率，即问题是由 Bowtie 本身引起的。即使不是这样，请善待维护者，很多人（包括我自己！）已经意识到 Bowtie 正在标记的问题，并且可能真的希望修复它们，但由于某些原因难以做到。如果你能帮助实现，请帮助它们！

如果是 Bowtie 本身的问题，或者是一个与 Bowtie 相关的新想法，请务必 提交一个 issue、发起讨论，或在 JSON Schema Slack 上发起一个讨论。

我想做一些随机而酷的事情

这个箱子里有一些很酷的想法，甚至已经存在。我想弄清楚我们是否可以利用 Bowtie 来统一地基准测试实现，而不仅仅是测试它们。能够 进入特定于语言的 REPL 也是一个很疯狂的想法，但可能会很有趣。可能还有很多其他想法！

设置 Bowtie 很困难，但我弄明白了/我想帮助进行 CI、"基础设施"或问题分类

这些都是你能够帮助的被低估的领域，因此如果你对这里的内容感兴趣，请告诉我。即使是让 Bowtie 更容易安装（对于那些不使用 Python 的人来说）也是一个很好的帮助！（现在，构建会生成一个 shiv，但不是跨平台的）。

结论

感谢你花时间了解 Bowtie。还要特别感谢 Postman，他们全职雇用我，让我能够代表社区进行这样的工作。没有 Postman，这项工作永远不会实现！我希望未来还有很多工作要做。请分享你的反馈，非常欢迎！如果你想参与进来，我们将不胜感激！

封面照片由 Stable Diffusion 生成。