Skip to content

KCIDB Protocol Fundamentals

Jump to bottom
Nikolai Kondrashov edited this page Apr 4, 2025 · 3 revisions

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 results between CI systems and databases, and for event notifications.

Principles

  1. The canonical message format is JSON accompanied by a schema.
  2. The schema is versioned. Version consists of two numbers: major and minor. Minor number is increased on backwards-compatible changes. And major number - for 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. That is, 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. Submitters ("origins") generate IDs of objects they submit themselves, and are responsible for their uniqueness.
  4. Each origin gets their own namespace for object IDs, using <origin>: prefix.
  5. All results can be submitted in one go, one object per submission, and everything in between.
  6. 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.
  7. No field can have null value, except under misc objects.
  8. Order of submissions doesn't matter.
  9. 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.
  10. Following the above, submissions repeated exactly are a no-op.
  11. Received data is acted upon only once it is good enough for a particular purpose. Purposes may differ in requirements for the data.

Clone this wiki locally