Implementation Semantics

Thrift is severely underspecified with respect to the handling of required/optional/unspecified-requiredness and default values in various cases such as serialization, deserialization, and new instance creation, and different implementations do different things (see here for a good analysis).

Scrooge attempts to be as rigorous as possible in this regard with consistently applied and, hopefully, easy-to-understand rules.

  1. If neither “required” nor “optional” is declared for a field, it then has the default requiredness of “optional-in/required-out”, or “optInReqOut” for short.

  2. It is invalid for a required field to be null and an exception will be thrown if you attempt to serialize a struct with a null required field.

  3. It is invalid for a required field to be missing during deserialization, and an exception will be thrown in this case.

  4. Optional fields can be set or unset, and the set-state is meaningful state of the struct that should be preserved by serialization/deserialization. Un-set fields are not present in the serialized representation of the struct.

  5. Declared default values will be assigned to any non-required fields that are missing during deserialization. If no default is declared for a field, a default value appropriate for the type will be used (see below).

  6. #4 and #5 imply that optional-with-default-value is not a tenable combination, and will be treated as if “optional” was not specified (optInReqOut-with-default-value).

Default values by type

  • bool = false

  • byte/i16/i32/i64/double = 0

  • string/struct/enum = null

  • list = Seq()

  • set = Set()

  • map = Map()

Missing values

The following “matrix” defines all the scenarios where a value may not be present and how that case is handled:

required, no declared default value:

  • missing in deserialization:

    • throws TProtocolException

  • null in serialization:

    • throws TProtocolException

  • immutable instance instantiation:

    • must be explicitly provided

required, with declared default value:

  • missing in deserialization:

    • throws TProtocolException

  • null in serialization:

    • throws TProtocolException

  • immutable instance instantiation:

    • declared default value

optInReqOut, no declared default value:

  • missing in deserialization:

    • default value for type

  • null in serialization:

    • throws TProtocolException

  • immutable instance instantiation:

    • must be explicitly provided

optInReqOut, with declared default value:

  • missing in deserialization:

    • declared default value

  • null in serialization:

    • throws TProtocolException

  • immutable instance instantiation:

    • declared default value

optional, no declared default value:

  • missing in deserialization:

    • None

  • None in serialization:

    • omitted

  • immutable instance instantiation:

    • None

optional, with declared default value:

  • case not valid, treated as optInReqOut with declared default value