What do member numbers mean in Microsoft Bond?

Question

Using Microsoft Bond (the C# library in particular), I see that whenever a Bond struct is defined, it looks like this:

struct Name
{
   0: type name;
   5: type name;
   ...
}

What do these numbers (0, 5, ...) mean?

Do they require special treatment in inheritance? (Do I need to make sure that I do not override members with the same number defined in my ancestor?)

Answer 1

The field ordinals are the unique identity of each field. When serializing to tagged binary protocols, these numbers are used to indicate which fields are in the payload. The names of the fields are not used. (Renaming a field in the .bond file does not break serialized binary data compatibility [though, see caveat below about text protocols].) Numbers are smaller than strings, which helps reduce the payload size, but also ends up improving serialization/deserialization time.

You cannot re-use the same field ordinal within the same struct.

There's no special treatment needed when you inherit from a struct (or if you have a struct field inside your struct). Bond keeps the ordinals for the structs separate. Concretely, the following is legal and will work:

namespace inherit_use_same_ordinal;

struct Base {
    0: string field;
}

struct Derived : Base {
    0: bool field;
}

A caveat about text serialization protocols like Simple JSON and Simple XML: these protocols use the field name as the field identifier. So, in these protocols renaming a field breaks serialized data compatibility.

Also, Simple JSON and Simple XML flatten the inheritance hierarchy, so re-using names across Base and Derived will result in clashes. Both have ways to work around this. For Simple XML, the SimpleXml.Settings.UseNamespaces parameter can be set to true to emit fully qualified names.

For Simple JSON, the Bond attribute JsonName can be used to change the name used for Simple JSON serialization, to avoid the conflict:

struct Derived : Base {
    [JsonName("derived_field")]
    0: bool field;
}