Schema检查工具指导

Interface SIG
1

设计背景

Redfish 是一种用于管理现代服务器硬件的开放标准，Redfish 的 Schema 定义了 Redfish 资源的数据模型和结构，这些 Schema 通常以 JSON 格式表示，用于描述 Redfish 中的各种资源和属性。

因此，所有 Redfish 接口与属性均需要有相应的 Schema 描述，针对该项特点，openUBMC 提供了 Schema 检查工具，以确保 Redfish 接口对应的 Schema 能够合理的进行开发与演进。

当前门禁流水线会进行该项检查。

运行方法

在rackmount仓下直接执行python3 interface_config/redfish/schema_check/schema_checker.pypython3 tools/schema_check/schema_checker.py即可运行。

常见错误

[Rule 1-1]: Schema语法检查失败

Schema语法手册参见：Redfish Schema语法手册

错误提示示例：

"definitions": {
    "OemActions": {
        "type": "object",
        "patternProperties": {
            xxx
        },
        "properties": {
            "$ref": "#/definitions/ActionsOem"
        }
    }
}

=============syntax errors found in file: <schema_file_path>
[Rule 1-1]: Schema语法检查失败, 详细信息如下=============
错误信息:  '#/definitions/ActionsOem' is not of type 'object'
语法要求:  object
错误位置:  $.definitions.OemActions.properties.$ref
错误内容:  #/definitions/ActionsOem

问题说明：properties字段下应定义属性，不能直接引用。该处错误可修改为：

"definitions": {
    "OemActions": {
        "type": "object",
        "patternProperties": {
            xxx
        },
        "properties": {
            "ActionsOem": {
                "$ref": "#/definitions/ActionsOem"
            }
        }
    }
}

[Rule 1-2]: 自定义属性语法校验失败

若redfish Schema标准定义文件（DMTF 官网中声明的资源）中

  • Oem下引用了本文件中的定义；
  • Oem下直接原地展开定义；

则会报错。

由于其它子系统的错误定义导致卡在1类检查，可以将schema_checker.py中check_dir_syntax的返回值直接修改为True跳过1类检查。

错误提示示例：

=============constraint errors found in file:
映射器文件: None
Schema文件: /root/iBMC_V3_code/integrated_config/rackmount/interface_config/redfish/static_resource/redfish/v1/schemastore/en/chassis.v1_15_7.json
[Rule 1-2]: 自定义属性语法校验失败, 映射器错误值: #/definitions/OemActions, 错误位置: URI: None, Type: None, 位置: None

问题说明：Oem下字段应定义在部分自定义文件中。该处错误可修改为：

chassis.v1_15_7.json：

"Actions": {
    ...
    "properties": {
        "Oem": {
            - "$ref": "#/definitions/OemActions"
            + "$ref": "oem/huawei_chassis.json#/definitions/OemActions"
        }
    }
}

oem/huawei_chassis.json：

"definitions": {
    + "OemActions": { xxx }
}

[Rule 2-1]: 资源定义完整性检查失败

若

  • 在redfish映射配置中引用的资源，没有找到对应Schema文件；
  • 在redfish映射配置中定义的资源，在Schema中没有定义；

则会报错。

错误提示示例：

=============constraint errors found in file:
映射器文件: /root/tmp/rackmount/interface_config/redfish/mapping_config/PerformanceCollection.json
Schema文件: None
[Rule 2-1]: 资源定义完整性检查失败, 映射器错误值:None, 错误位置: URI:None, Type:None, 位置:hwperformancecollection未定义schema

问题说明：映射器配置资源遵循的schemahwperformancecollection没有找到对应schema文件。

需要注意：

  • redfish资源应添加在资源对应的基文件中，如当前uri对应的Schema文件为resource.v1_0_0.json，则该uri应添加到resource.json中；
  • 映射器配置uri中的动态槽位号在Schema中应去掉动态槽位号前的:，再将动态字段用{}括起来。如映射器配置中的uri为/redfish/v1/:id，在Schema中应为/redfish/v1/{id}

错误提示示例：

=============constraint errors found in file:
映射器文件: /root/tmp/rackmount/interface_config/redfish/mapping_config/v1.json
Schema文件: /root/tmp/rackmount/interface_config/redfish/static_resource/redfish/v1/schemastore/en/serviceroot.json
[Rule 2-1]: 资源定义完整性检查失败, 映射器错误值:/redfish/v1, 错误位置: URI:/redfish/v1, Type:None, 位置:Uri

问题说明：schema文件中definitions/<ResourceType>/uris下没有定义URI/redfish/v1. 该处错误可修改为：

serviceroot.json：

"definitions": {
    "ServiceRoot": {
        "anyOf": { xxx },
      + "uris": [
      +     "redfish/v1"
      + ]
    }
}

[Rule 2-2]：资源方法有效性的检查失败

若

  • Schema中未定义deletable或deletable为false，对应资源的映射配置中提供了delete方法的配置；
  • Schema中未定义insertable或insertable为false，对应资源的映射配置中提供了post方法的配置；
  • Schema中未定义updatable或updatable为false，对应资源的映射配置中提供了patch方法的配置；

则会报错。

错误提示示例：

=============constraint errors found in file:
映射器文件: /root/tmp/rackmount/interface_config/redfish/mapping_config/v1.json
Schema文件: /root/tmp/rackmount/interface_config/redfish/static_resource/redfish/v1/schemastore/en/serviceroot.json
[Rule 2-2]: 资源方法有效性检查失败, 映射器错误值:patch, 错误位置: URI:/redfish/v1, Type:updatable, 位置:Interfaces/Type

问题说明：映射器配置定义了接口，但在schema文件中没有定义或定义该接口类型为false. 该处错误可修改为：

serviceroot.json：

"definitions": {
    "ServiceRoot": {
        "anyOf": { xxx },
      + "updatable": true,
        "deletable": false,
        "insertable": false,
      ...
    }
}

[Rule 2-3]: 属性定义完整性检查失败

若

  • 在接口映射配置中定义的资源条目名，在Schema中未定义；
  • 在接口映射配置中定义的属性，在Schema中未定义；

则会报错。
（PATCH/POST接口若object属性的Schema中定义了additionalProperties为true，则同层级允许有schema定义之外的属性出现在请求体/响应体中）
同层级校验失败则不会再往下层校验，直到同层级存在性和类型定义一致性都通过，才会往下层检查。

错误提示示例：

=============constraint errors found in file:
映射器文件: /root/tmp/rackmount/interface_config/redfish/mapping_config/SystemOverview.json
Schema文件: /root/tmp/rackmount/interface_config/redfish/static_resource/redfish/v1/schemastore/en/systemoverview.v1_0_0.json
[Rule 2-3]: 属性定义完整性检查失败, 映射器错误值:Id, 错误位置: URI:/redfish/v1/SystemOverview, Type:get, 位置:RspBody/Id

问题说明：映射器配置定义了属性Id，但在同层级对应Schema文件中没有找到定义。

[Rule 2-4]: 属性类型定义一致性检查失败

若

  • 属性类型的定义在Schema和接口映射中的定义不一致（只校验映射器配置中请求体中的属性）；
  • 属性类型的定义对取值的限制跟Schema文件中对取值的限制不一致，且更加宽松；

则会报错。
同层级先检查存在性，若存在性检查失败，则不会检查类型一致性。

错误提示示例：

=============constraint errors found in file:
映射器文件: /root/tmp/rackmount/interface_config/redfish/mapping_config/Systems/systems.json
Schema文件: /root/tmp/rackmount/interface_config/redfish/static_resource/redfish/v1/schemastore/en/computersystem.v1_2_0.json
[Rule 2-4]: 属性类型定义一致性检查失败, 映射器错误值: string, 错误位置: URI: /redfish/v1/Systems/:computersystemid, Type: patch, 位置: ReqBody/Boot/BootSourceOverrideMode/Type

问题说明：映射器配置只定义了属性BootSourceOverrideMode的类型为string，但在对应Schema文件中还限制了该属性只能从"Disabled","Once","Continuous"中取值。

[Rule 2-5]: POST请求的requiredOnCreate约束检查失败

若

  • Schema定义中requiredOnCreate下的字段，在该资源映射配置的post方法中不存在

则会报错。

[Rule 2-6]: GET请求的required约束检查失败

若

  • Schema定义中required下的属性，在该资源映射配置的Get请求响应体中不存在

则会报错。

[Rule 2-7]: PATCH请求的readonly约束检查失败

若

  • Schema定义中readonly属性，在该资源映射配置的Patch接口里出现

则会报错。

五、常见问题

1、如何新增Schema文件？

如需要新增resource.v1_2_0.json这个Schema文件，

  1. 在schemastore/en下新增Schema文件，需要注意文件名必须全小写
    （如果是Redfish标准定义的文件，从Redfish标准官网下载最新Redfish Schema Bundle（DSP8010），找到对应文件）

  2. 检查schemastore/en下是否有其基文件resource.json，如果没有也需要补充；有基文件需要检查基文件的引用中是否有新增版本文件的引用；

  3. 在jsonschemas对应目录，此例中在jsonschemas/resource.v1_2_0目录下新增index.json，可以仿照已有文件补充；

  4. 检查映射器配置使用到同样资源模型接口的@odata.type字段是否需要更新版本，@odata.type命名格式为#<ResourceType>.<Version>.<TermName>。

2

在路径interface_config/redfish/下没有schema_check文件夹，这个文件在schema_check/schema_checker.py，但是执行python3 schema_check/schema_checker.py报错

image

3

当前工具已迁移到tools/schema_check/schema_checker.py