Run update-vendor.sh

vendor/sigs.k8s.io/structured-merge-diff/schema/elements.go

@@ -43,13 +43,12 @@ type TypeRef struct {
 }
 
 // Atom represents the smallest possible pieces of the type system.
+// Each set field in the Atom represents a possible type for the object.
+// If none of the fields are set, any object will fail validation against the atom.
 type Atom struct {
-	// Exactly one of the below must be set.
-	*Scalar  `yaml:"scalar,omitempty"`
-	*Struct  `yaml:"struct,omitempty"`
-	*List    `yaml:"list,omitempty"`
-	*Map     `yaml:"map,omitempty"`
-	*Untyped `yaml:"untyped,omitempty"`
+	*Scalar `yaml:"scalar,omitempty"`
+	*List   `yaml:"list,omitempty"`
+	*Map    `yaml:"map,omitempty"`
 }
 
 // Scalar (AKA "primitive") represents a type which has a single value which is
@@ -65,47 +64,105 @@ const (
 )
 
 // ElementRelationship is an enum of the different possible relationships
-// between the elements of container types (maps, lists, structs, untyped).
+// between the elements of container types (maps, lists).
 type ElementRelationship string
 
 const (
 	// Associative only applies to lists (see the documentation there).
 	Associative = ElementRelationship("associative")
-	// Atomic makes container types (lists, maps, structs, untyped) behave
-	// as scalars / leaf fields (which is the default for untyped data).
+	// Atomic makes container types (lists, maps) behave
+	// as scalars / leaf fields
 	Atomic = ElementRelationship("atomic")
 	// Separable means the items of the container type have no particular
-	// relationship (default behavior for maps and structs).
+	// relationship (default behavior for maps).
 	Separable = ElementRelationship("separable")
 )
 
-// Struct represents a type which is composed of a number of different fields.
-// Each field has a name and a type.
+// Map is a key-value pair. Its default semantics are the same as an
+// associative list, but:
+// * It is serialized differently:
+//     map:  {"k": {"value": "v"}}
+//     list: [{"key": "k", "value": "v"}]
+// * Keys must be string typed.
+// * Keys can't have multiple components.
 //
-// TODO: in the future, we will add one-of groups (sometimes called unions).
-type Struct struct {
+// Optionally, maps may be atomic (for example, imagine representing an RGB
+// color value--it doesn't make sense to have different actors own the R and G
+// values).
+//
+// Maps may also represent a type which is composed of a number of different fields.
+// Each field has a name and a type.
+type Map 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
+	// A 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"`
+	// One can have multiple unions in the same struct, but the fields can't
+	// overlap between unions.
+	Unions []Union `yaml:"unions,omitempty"`
 
-	// ElementRelationship states the relationship between the struct's items.
+	// ElementType is the type of the structs's unknown fields.
+	ElementType TypeRef `yaml:"elementType,omitempty"`
+
+	// ElementRelationship states the relationship between the map's items.
 	// * `separable` (or unset) implies that each element is 100% independent.
 	// * `atomic` implies that all elements depend on each other, and this
 	//   is effectively a scalar / leaf field; it doesn't make sense for
 	//   separate actors to set the elements. Example: an RGB color struct;
 	//   it would never make sense to "own" only one component of the
 	//   color.
-	// The default behavior for structs is `separable`; it's permitted to
+	// The default behavior for maps is `separable`; it's permitted to
 	// leave this unset to get the default behavior.
 	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"`
+	// Discriminatorvalue is the value of the discriminator to
+	// select that field. If the union doesn't have a discriminator,
+	// this field is ignored.
+	DiscriminatorValue string `yaml:"discriminatorValue"`
+}
+
+// Union, or oneof, means that only one of multiple fields of a structure can be
+// set at a time. Setting the discriminator helps clearing oher fields:
+// - If discriminator changed to non-nil, and a new field has been added
+// that doesn't match, an error is returned,
+// - If discriminator hasn't changed and two fields or more are set, an
+// error is returned,
+// - If discriminator changed to non-nil, all other fields but the
+// discriminated one will be cleared,
+// - Otherwise, If only one field is left, update discriminator to that value.
+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"`
+
+	// DeduceInvalidDiscriminator indicates if the discriminator
+	// should be updated automatically based on the fields set. This
+	// typically defaults to false since we don't want to deduce by
+	// default (the behavior exists to maintain compatibility on
+	// existing types and shouldn't be used for new types).
+	DeduceInvalidDiscriminator bool `yaml:"deduceInvalidDiscriminator,omitempty"`
+
+	// This is the list of fields that belong to this 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.
@@ -129,15 +186,14 @@ type List struct {
 	// * `atomic`: the list is treated as a single entity, like a scalar.
 	// * `associative`:
 	//   - If the list element is a scalar, the list is treated as a set.
-	//   - If the list element is a struct, the list is treated as a map.
-	//   - The list element must not be a map or a list itself.
+	//   - If the list element is a map, the list is treated as a map.
 	// There is no default for this value for lists; all schemas must
 	// explicitly state the element relationship for all lists.
 	ElementRelationship ElementRelationship `yaml:"elementRelationship,omitempty"`
 
 	// Iff ElementRelationship is `associative`, and the element type is
-	// struct, then Keys must have non-zero length, and it lists the fields
-	// of the element's struct type which are to be used as the keys of the
+	// map, then Keys must have non-zero length, and it lists the fields
+	// of the element's map type which are to be used as the keys of the
 	// list.
 	//
 	// TODO: change this to "non-atomic struct" above and make the code reflect this.
@@ -146,51 +202,6 @@ type List struct {
 	Keys []string `yaml:"keys,omitempty"`
 }
 
-// Map is a key-value pair. Its default semantics are the same as an
-// associative list, but:
-// * It is serialized differently:
-//     map:  {"k": {"value": "v"}}
-//     list: [{"key": "k", "value": "v"}]
-// * Keys must be string typed.
-// * Keys can't have multiple components.
-//
-// Although serialized the same, maps are different from structs in that each
-// map item must have the same type.
-//
-// Optionally, maps may be atomic (for example, imagine representing an RGB
-// color value--it doesn't make sense to have different actors own the R and G
-// values).
-type Map struct {
-	// ElementType is the type of the list's elements.
-	ElementType TypeRef `yaml:"elementType,omitempty"`
-
-	// ElementRelationship states the relationship between the map's items.
-	// * `separable` implies that each element is 100% independent.
-	// * `atomic` implies that all elements depend on each other, and this
-	//   is effectively a scalar / leaf field; it doesn't make sense for
-	//   separate actors to set the elements.
-	//   TODO: find a simple example.
-	// The default behavior for maps is `separable`; it's permitted to
-	// leave this unset to get the default behavior.
-	ElementRelationship ElementRelationship `yaml:"elementRelationship,omitempty"`
-}
-
-// Untyped represents types that allow arbitrary content. (Think: plugin
-// objects.)
-type Untyped struct {
-	// ElementRelationship states the relationship between the items, if
-	// container-typed data happens to be present here.
-	// * `atomic` implies that all elements depend on each other, and this
-	//   is effectively a scalar / leaf field; it doesn't make sense for
-	//   separate actors to set the elements.
-	// TODO: support "guess" (guesses at associative list keys)
-	// TODO: support "lookup" (calls a lookup function to figure out the
-	//       schema based on the data)
-	// The default behavior for untyped data is `atomic`; it's permitted to
-	// leave this unset to get the default behavior.
-	ElementRelationship ElementRelationship `yaml:"elementRelationship,omitempty"`
-}
-
 // FindNamedType is a convenience function that returns the referenced TypeDef,
 // if it exists, or (nil, false) if it doesn't.
 func (s Schema) FindNamedType(name string) (TypeDef, bool) {