From 04cd037ba2b0e9257e37461703cc9716e75d1d4a Mon Sep 17 00:00:00 2001 From: Casper Date: Mon, 17 Oct 2022 17:49:28 -0400 Subject: [PATCH] Fix #7580 by documenting union schema evolution rules (#7585) Co-authored-by: Casper Neo --- docs/source/Schemas.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/docs/source/Schemas.md b/docs/source/Schemas.md index 98831a9da..f049cf40b 100644 --- a/docs/source/Schemas.md +++ b/docs/source/Schemas.md @@ -552,7 +552,7 @@ the world. If this is not practical for you, use explicit field ids, which should always generate a merge conflict if two people try to allocate the same id. -### Schema evolution examples +### Schema evolution examples (tables) Some examples to clarify what happens as you change a schema: @@ -614,6 +614,41 @@ Occasionally ok. You've renamed fields, which will break all code (and JSON files!) that use this schema, but as long as the change is obvious, this is not incompatible with the actual binary buffers, since those only ever address fields by id/offset. + +#### Schema evolution examples (unions) + +Suppose we have the following schema: +``` +union Foo { A, B } +``` +We can add another variant at the end. +``` +union Foo { A, B, another_a: A } +``` +and this will be okay. Old code will not recognize `another_a`. +However if we add `another_a` anywhere but the end, e.g. +``` +union Foo { A, another_a: A, B } +``` +this is not okay. When new code writes `another_a`, old code will +misinterpret it as `B` (and vice versa). However you can explicitly +set the union's "discriminant" value like so: +``` +union Foo { A = 1, another_a: A = 3, B = 2 } +``` +This is okay. + +``` +union Foo { original_a: A = 1, another_a: A = 3, B = 2 } +``` +Renaming fields will break code and any saved human readable representations, +such as json files, but the binary buffers will be the same. + + + + + +
### Testing whether a field is present in a table