KCIDB Protocol Fundamentals

This defines motivation, principles, and particulars of KCIDB I/O protocol and data format. The protocol is intended for exchanging Linux kernel test result reports between CI systems and databases, and for event notifications.

Principles

1. The canonical message format is JSON accompanied by a schema, with translations to other formats as an option, provided their schema language supports the same or stricter constraints.

2. The schema is versioned. The version consists of two numbers: major and minor. Minor number is increased on backwards-compatible changes. And major number - on backwards-incompatible.

   1. Any data created for a lower minor version would be accepted by the schema with a higher minor version, given the major version number is the same. I.e. it should be possible to simply increase the specified minor version number without changing the data at all, and it would still be valid.
   2. Some data created for a lower major version number will not be accepted by a schema with a higher major version number. I.e. it is impossible to get arbitrary data created for a lower major version number to validate with a higher major version number by simply changing that number in the data.

3. Each submission (or "dataset", or "message") contains the version, and zero or more lists of report objects, one for each object type.

4. Submitters ("origins") generate IDs of objects they submit themselves, and are responsible for their uniqueness.

5. Each origin gets their own namespace for object IDs, using <origin>: prefix.

6. Report objects can be submitted in groups of any size, from one at a time to all at once, regardless of their relation to each other.

7. Every object, including embedded ones, has a misc field accepting an object with arbitrary contents. This field is intended as an "escape hatch" for CI systems to provide data which wouldn't fit into already-formalized fields, and as a way for KCIDB developers to get a sample of such data for eventual formalizing.

8. No field can have null value, except under misc objects. To omit field value simply omit the field altogether.

   This allows direct mapping of missing fields to NULL values in SQL databases without ambiguity between a missing field and the JSON null, reduces submission sizes, disallows multiple ways to present the same data, and simplifies conversion code and processing conditions.

9. Order of submissions doesn't matter.

10. The receiving system guarantees at-least-once delivery.

11. Between two submissions of an object (having the same ID) specified fields will be picked over unspecified, but if a field is specified in both with different values, it's value will be picked non-deterministically. NOTE: misc objects are picked as a whole.

12. The above enables the submitters to gradually populate an object with fields. However, a recipient may specify the maximum time period (e.g. a week) since the first object submission, within which object updates (new fields) will be accepted.

13. Following the above, submissions repeated exactly are a no-op.

14. The schema requires only the absolute minimum set of fields: IDs, origin, and references to other objects. This is required to allow gradual submissions without having to repeat non-essential fields each time.

15. Received data is acted upon only once it is good enough for a particular purpose. Purposes may differ in requirements for the data. E.g.:

    • The condition for a particular notification might not care about some fields (like the command used to build the kernel), and can go out once only the build status is received.
    • A dashboard may require certain fields to meaningfully display an object, but others might be optional.
    • A certain bisection profile would care about some aspects of test results, but not the others, and can be completed without them.

16. The recipient may specify fields required for a particular purpose and notify the submitters about unfit reports, if the fields are not received within a certain time after the first object submission.