add documentation about tuple notation
@@ -4,3 +4,83 @@ fastavro.write
.. autofunction:: fastavro._write_py.writer
.. autofunction:: fastavro._write_py.schemaless_writer
+
+Using the tuple notation to specify which branch of a union to take
+-------------------------------------------------------------------
+
+Since this library uses plain dictionaries to reprensent a record, it is
+possible for that dictionary to fit the definition of two different records.
+
+For example, given a dictionary like this::
+
+ {"name": "My Name"}
+
+It would be valid against both of these records::
+
+ child_schema = {
+ "name": "Child",
+ "type": "record",
+ "fields": [
+ {"name": "name", "type": "string"},
+ {"name": "favorite_color", "type": ["null", "string"]},
+ ]
+ }
+
+ pet_schema = {
+ "name": "Pet",
+ "type": "record",
+ "fields": [
+ {"name": "name", "type": "string"},
+ {"name": "favorite_toy", "type": ["null", "string"]},
+ ]
+ }
+
+This becomes a problem when a schema contains a union of these two similar
+records as it is not clear which record the dictionary represents. For example,
+if you used the previous dictionary with the following schema, it wouldn't be
+clear if the record should be serialized as a `Child` or a `Pet::
+
+ household_schema = {
+ "name": "Household",
+ "type": "record",
+ "fields": [
+ {"name": "address", "type": "string"},
+ {
+ "name": "family_members",
+ "type": {
+ "type": "array", "items": [
+ {
+ "name": "Child",
+ "type": "record",
+ "fields": [
+ {"name": "name", "type": "string"},
+ {"name": "favorite_color", "type": ["null", "string"]},
+ ]
+ }, {
+ "name": "Pet",
+ "type": "record",
+ "fields": [
+ {"name": "name", "type": "string"},
+ {"name": "favorite_toy", "type": ["null", "string"]},
+ ]
+ }
+ ]
+ }
+ },
+ ]
+ }
+
+To resolve this, you can use a tuple notation where the first value of the
+tuple is the fully namespaced record name and the second value is the
+dictionary. For example::
+
+ records = [
+ {
+ "address": "123 Drive Street",
+ "family_members": [
+ ("Child", {"name": "Son"}),
+ ("Child", {"name": "Daughter"}),
+ ("Pet", {"name": "Dog"}),
+ ]
+ }
+ ]
