Schema Enforcer

Schema Enforcer提供了一种框架，用于使用JSONSchema测试结构化数据与模式定义。

入门指南

安装

Schema Enforcer是一个python库，可在PyPi上找到。它需要3.8或更高版本的python。一旦在您的机器上安装了支持的python版本，就可以使用以下命令使用pip安装工具：python -m pip install schema-enforcer。

python -m pip install schema-enforcer

概述

Schema Enforcer要求用户定义两个不同的元素

• 模式定义文件：这些文件定义了应遵守的特定数据集的模式。
• 结构化数据文件：这些文件包含应遵守在模式定义文件中定义的模式（或多个）的数据。

注意：需要与模式定义进行验证的数据可以以结构化数据文件或Ansible主机变量的形式出现。安装schema-enforcer时，Ansible默认不安装。为了使用Ansible功能，必须在安装时已安装Ansible或将其声明为可选依赖项。为了简洁和简单，本README.md仅讨论结构化数据文件——有关如何使用schema-enforcer与Ansible主机变量一起使用的更多信息，请参阅ansible_command README

当schema-enforcer运行时，它假定目录层次结构，该层次结构应从运行工具的文件夹开始。

• schema-enforcer 将在 ./schema/schemas/ 目录中搜索嵌套的 模式定义文件，这些文件以 .yml、.yaml 或 .json 结尾。
• schema-enforcer 将从当前工作目录（./）开始递归搜索 结构化数据文件。它是通过搜索所有目录（包括当前工作目录）以 .yml、.yaml 或 .json 结尾的文件来实现的。默认情况下，会排除 schema 文件夹及其子目录。

bash$ cd examples/example1
bash$ tree
.
├── chi-beijing-rt1
│   ├── dns.yml
│   └── syslog.yml
├── eng-london-rt1
│   ├── dns.yml
│   └── ntp.yml
└── schema
    └── schemas
        ├── dns.yml
        ├── ntp.yml
        └── syslog.yml

4 directories, 7 files

在上面的示例中，chi-beijing-rt1 是一个包含名为 chi-beijing-rt1 路由的某些配置的结构化数据文件的目录。该文件夹中包含两个结构化数据文件，分别是 dns.yml 和 syslog.yml。同样，eng-london-rt1 目录包含名为 eng-london-rt1 路由的定义文件 — dns.yml 和 ntp.yml。

chi-beijing-rt1/dns.yml 文件定义了 chi-beijing.rt1 应使用的 DNS 服务器。该文件中的数据包括一个简单的哈希类型数据结构，键为 dns_servers，值为一个数组。该数组中的每个元素都是一个具有键 address 的哈希类型对象，其值是一个 IP 地址字符串。

bash$ cat chi-beijing-rt1/dns.yml
# jsonschema: schemas/dns_servers
---
dns_servers:
  - address: "10.1.1.1"
  - address: "10.2.2.2"

注意：行 # jsonschema: schemas/dns_servers 告诉 schema-enforcer 应该验证文件中定义的结构化数据的模式 ID。模式 ID 由模式定义中的顶级键 $id 定义。有关如何将结构化数据映射到应遵守的模式 ID 的更多信息，请参阅 mapping_schemas README

schema/schemas/dns.yml 是一个模式定义文件。它包含用 JSONSchema 编写的 NTP 服务器模式定义。文件 chi-beijing-rt1/dns.yml 和 eng-london-rt1/dns.yml 中的数据应遵循此模式定义文件中的模式。

bash$ cat schema/schemas/dns.yml
---
$schema: "https://json-schema.fullstack.org.cn/draft-07/schema#"
$id: "schemas/dns_servers"
description: "DNS Server Configuration schema."
type: "object"
properties:
  dns_servers:
    type: "array"
    items:
      type: "object"
      properties:
        name:
          type: "string"
        address:
          type: "string"
          format: "ipv4"
        vrf:
          type: "string"
      required:
        - "address"
      uniqueItems: true
required:
  - "dns_servers"

注意：如果您之前没有见过 JSONSchema，该模式定义文件的内容可能看起来有些令人畏惧。如果现在难以解析，请不要担心太多。重要的是要注意，该文件包含一个结构化数据应遵循的模式定义。

基本用法

安装 schema-enforcer 后，可以使用 schema-enforcer validate 命令运行 YAML/JSON 实例文件对定义的模式进行验证。

bash$ schema-enforcer --help
Usage: schema-enforcer [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  ansible        Validate the hostvar for all hosts within an Ansible...
  schema         Manage your schemas
  validate       Validates instance files against defined schema

要运行模式验证，可以运行 schema-enforcer validate 命令。

bash$ schema-enforcer validate
schema-enforcer validate
ALL SCHEMA VALIDATION CHECKS PASSED

要获取特定文件是否通过模式验证的更多上下文信息，可以使用 --show-pass 标志。

bash$ schema-enforcer validate --show-pass
PASS [FILE] ./eng-london-rt1/ntp.yml
PASS [FILE] ./eng-london-rt1/dns.yml
PASS [FILE] ./chi-beijing-rt1/syslog.yml
PASS [FILE] ./chi-beijing-rt1/dns.yml
ALL SCHEMA VALIDATION CHECKS PASSED

如果我们修改 chi-beijing-rt1/dns.yml 文件中的一个地址，使其值为布尔值 true 而不是 IP 地址字符串，然后运行 schema-enforcer 工具，验证将失败并显示错误消息。

bash$ cat chi-beijing-rt1/dns.yml
# jsonschema: schemas/dns_servers
---
dns_servers:
  - address: true
  - address: "10.2.2.2"

bash$ test-schema validate
FAIL | [ERROR] True is not of type 'string' [FILE] ./chi-beijing-rt1/dns.yml [PROPERTY] dns_servers:0:address
bash$ echo $?
1

当结构化数据文件无法通过模式验证时，schema-enforcer 将以代码 1 退出。

配置设置

模式执行器将以默认设置工作，但是可以在 schema-enforcer 运行的路径根目录中放置一个 pyproject.toml 文件，以覆盖默认设置或声明更高级功能的配置。在此 pyproject.toml 文件中，可以使用 tool.schema_enforcer 部分声明模式执行器的设置。例如，请参阅示例 2 中的 pyproject.toml 文件。

bash$ cd examples/example2 && tree -L 2
.
├── README.md
├── hostvars
│   ├── chi-beijing-rt1
│   ├── eng-london-rt1
│   └── ger-berlin-rt1
├── invalid
├── pyproject.toml
└── schema
    ├── definitions
    └── schemas

8 directories, 2 files

在此 toml 文件中，声明了一个模式映射，告诉模式执行器哪些结构化数据文件应由哪些模式 ID 检查。

bash$ cat pyproject.toml
[tool.schema_enforcer.schema_mapping]
# Map structured data filename to schema IDs
'dns_v1.yml' = ['schemas/dns_servers']
'dns_v2.yml' = ['schemas/dns_servers_v2']
'syslog.yml' = ['schemas/syslog_servers']

有关可用配置设置的更多信息，请参阅 configuration README

支持的格式

默认情况下，schema enforcer 安装了 jsonschema format_nongpl 额外扩展（在版本 <1.2.0 中）或 format-nongpl（在版本 >=1.2.0 中）。这个额外扩展允许使用可以在模式定义中使用的格式（例如 ipv4，hostname 等）。format_nongpl 或 format-nongpl 额外扩展只安装不受 GPL 许可的传递依赖项。由 GPL 许可的 rfc3987 传递依赖定义的 iri 和 iri-reference 格式。因此，iri 和 iri-reference 格式不支持 format-nongpl/format_nongpl。如果您需要使用 iri 和/或 iri-reference 格式，可以通过运行以下 pip 命令（或其 poetry 等效命令）来这样做：

pip install 'jsonschema[rfc3987]'

有关更多信息，请参阅 jsonschema 文档中的“验证格式”部分。

下一步去哪里

详细信息可以在 docs/ 目录中的 README.md 文件中找到。

• “介绍 Schema Enforcer”博客文章
• 使用 pyproject.toml 文件进行配置
• 将结构化数据文件映射到模式文件
• 使用 ansible 命令
• 使用 validate 命令
• 使用 schema 命令
• 实现自定义验证器