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.

Problem description

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.

Use Cases

I as a notification consumer want to have a way to see the structure of the notification payload without looking into the nova object model or using human intelligence to understand the notification sample, so that I can further automate the consumption of the new or changed notifications.

I as a notification consumer want to validate that the received notification has the defined structure automatically so that I can be sure my software can consume the notification properly and detect problems earlier.

Proposed change

Notification payload is a versioned object and the wire format of it is a json blob generated by the oslo.versionedobject serialization therefore it is natural to define the structure of this json blob with a JSON Schema. This way there would be a implementation independent, machine readable description of the versioned objects.

Therefore this spec proposes to add JSON Schema generation function to the VersionedObject base class. The implementation would iterate through the items in the fields field of the VersionedObject class and would use the field type to collect the schema pieces. Every FieldType object would need to have a new function get_schema(self) which returns the schema piece of the field. The Object field type will do a recursion and generate the schema of the referred class.

Alternatives

As an alternative it would be possible to externalize the object model used to define the notifications and offer it as a python library to consumers. However this would only help consumer that are capable of import python libraries and it would force the consumers to depend on oslo versioned objects.

Impact on Existing APIs

  • A new class method to_json_schema(cls) will be added to VersionedObject class that returns a JSON schema of the class.

  • A new method get_schema(self) will be added to the FieldType base class. Every field type shall override it to provide the field specific schema.

Security impact

None

Performance Impact

None

Configuration Impact

None

Developer Impact

Service should use the new class method to generate the schema for validation and documentation generation purposes.

Testing Impact

Besides unit testing the service using this feature can add test coverage with real versioned objects.

Implementation

Assignee(s)

Primary assignee:

balazs-gibizer

Milestones

Newton-2

Work Items

  • update the FieldType classes to provide the get_schema() method

  • add the new class method to the VersionedObject class

Incubation

None

Adoption

None

Library

None

Anticipated API Stabilization

None

Documentation Impact

None

Dependencies

None

References

Note

This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode