JSON schema for versioned objects

https://blueprints.launchpad.net/oslo?searchtext=json-schema-for-versioned-object

Versioned objects have a well defined schema that is available as python code. This schema can also be expressed in a python independent way for example with JSON Schema. Nova uses versioned objects to define its notification interface. For the consumers of the notifications it would be super awesome to have the schema defined in a easy to process and python independent way.

问题描述

Versioned notifications in nova have a well defined schema implemented with versioned objects. This schema prevents from changing the structure of the notification without communicating the change to the notification consumers. This communication is done via the version number embedded into the notification payload. However this communication is limited and does not contain information about what is changed in the schema or what is the structure of a new notification.

Notification consumers can understand the structure of the notification payload based on notification samples or based on the object model only. If a notification payload is changed then the object model is updated. However this information is hard to consume from software and the consumer shall not depend on the object model of the service directly.

Also the consumer does not have an independent and automatic way to ensure that the received notification has the expected structure without trying to consume it.

用例

我作为通知消费者，希望有一种方法可以在不查看 nova 对象模型或使用人工判断来理解通知示例的情况下查看通知负载的结构，以便进一步自动化新通知或更改通知的消费。

我作为通知消费者，希望能够自动验证接收到的通知是否具有定义的结构，以便确信我的软件可以正确消费该通知，并更早地检测到问题。

提议的变更

通知负载是一个 versioned object，它的线格式是由 oslo.versionedobject 序列化生成的 json blob，因此用 JSON Schema 定义这个 json blob 的结构是自然的。 这样将有一个实现无关、机器可读的 versioned object 描述。

因此，本规范建议向 VersionedObject 基类添加 JSON Schema 生成函数。 该实现将遍历 VersionedObject 类中的 fields 字段中的项目，并使用字段类型来收集 schema 片段。 每个 FieldType 对象都需要有一个新的函数 get_schema(self)，它返回该字段的 schema 片段。 Object 字段类型将进行递归并生成所引用类的 schema。

备选方案

或者，可以将用于定义通知的对象模型外部化，并将其作为 python 库提供给消费者。 但是，这只会帮助能够导入 python 库的消费者，并且会强制消费者依赖 oslo versioned objects。

Impact on Existing APIs

  • 将向 VersionedObject 类添加一个新的类方法 to_json_schema(cls)，该方法返回该类的 JSON schema。

  • 将向 FieldType 基类添加一个新的方法 get_schema(self)。 每个字段类型都应重写它以提供特定于该字段的 schema。

安全影响

无

性能影响

无

Configuration Impact

无

开发人员影响

服务应使用新的类方法来生成 schema，用于验证和文档生成目的。

Testing Impact

除了使用此功能对服务进行单元测试外，还可以使用真实的 versioned objects 添加测试覆盖率。

实现

负责人

主要负责人

balazs-gibizer

里程碑

Newton-2

工作项

  • 更新 FieldType 类以提供 get_schema() 方法

  • 向 VersionedObject 类添加新的类方法

孵化

无

采用

无

库

无

预计 API 稳定

无

文档影响

无

依赖项

无

参考资料

注意

本作品采用知识共享署名 3.0 非移植许可协议授权。 http://creativecommons.org/licenses/by/3.0/legalcode