Define new schema for Unions

Author: Antoine Pelisse

schema/elements.go

@@ -83,18 +83,15 @@ const (
 
 // Struct represents a type which is composed of a number of different fields.
 // Each field has a name and a type.
-//
-// TODO: in the future, we will add one-of groups (sometimes called unions).
 type Struct struct {
 	// Each struct field appears exactly once in this list. The order in
 	// this list defines the canonical field ordering.
 	Fields []StructField `yaml:"fields,omitempty"`
 
-	// TODO: Implement unions, either this way or by inlining.
-	// Unions are groupings of fields with special rules. They may refer to
+	// Union is a grouping of fields with special rules. It may refer to
 	// one or more fields in the above list. A given field from the above
 	// list may be referenced in exactly 0 or 1 places in the below list.
-	// Unions []Union `yaml:"unions,omitempty"`
+	Union *Union `yaml:"union,omitempty"`
 
 	// ElementRelationship states the relationship between the struct's items.
 	// * `separable` (or unset) implies that each element is 100% independent.
@@ -108,6 +105,45 @@ type Struct struct {
 	ElementRelationship ElementRelationship `yaml:"elementRelationship,omitempty"`
 }
 
+// UnionFields are mapping between the fields that are part of the union and
+// their discriminated value. The discriminated value has to be set, and
+// should not conflict with other discriminated value in the list.
+type UnionField struct {
+	// FieldName is the name of the field that is part of the union. This
+	// is the serialized form of the field.
+	FieldName string `yaml:"fieldName"`
+	// DiscriminatedBy is the value of the discriminator to select that
+	// field.
+	DiscriminatedBy string `yaml:"DiscriminatedBy"`
+}
+
+// Union, or oneof, means that only one of multiple fields of a structure can be
+// set at a time. For backward compatibility reasons, and to help "dumb clients"
+// which are not aware of the union (or can't be aware of it because they
+// don't know what fields are part of the union), the code tolerates multiple
+// fields to be set but will try to detect which fields must be cleared (there
+// should never be more than two though):
+// - If there is a discriminator and its value has changed, clear all fields
+// but the one specified by the discriminator
+// - If there is no discriminator, or it hasn't changed, if new has two of the
+// fields set, remove the one that was set in old.
+// - If there is a discriminator, set it to the value we've kept (if it changed)
+type Union struct {
+	// Discriminator, if present, is the name of the field that
+	// discriminates fields in the union. The mapping between the value of
+	// the discriminator and the field is done by using the Fields list
+	// below.
+	Discriminator *string `yaml:"discriminator,omitempty"`
+
+	// This is the list of fields that belong to this union. This fields are
+	// required to not be part of another union, or be the discriminator for
+	// another union. All the fields present in here have to be part of the
+	// parent structure. Discriminator (if oneOf has one), is NOT included
+	// in this list. The value for field is how we map the name of the field
+	// to actual value for discriminator.
+	Fields []UnionField `yaml:"fields,omitempty"`
+}
+
 // StructField pairs a field name with a field type.
 type StructField struct {
 	// Name is the field name.

schema/schemaschema.go

@@ -84,9 +84,23 @@ var SchemaSchemaYAML = `types:
             namedType: structField
           elementRelationship: associative
           keys: [ "name" ]
+    - name: union
+      type:
+        namedType: union
     - name: elementRelationship
       type:
         scalar: string
+- name: union
+  struct:
+    fields:
+    - name: discriminator
+      type:
+        scalar: string
+    - name: fields
+      type:
+        map:
+          elementType:
+            scalar: string
 - name: structField
   struct:
     fields: