feat(schema): specify JSON mapping (#21243)

schema/kind.go

@@ -9,81 +9,135 @@ import (
 )
 
 // Kind represents the basic type of a field in an object.
-// Each kind defines the types of go values which should be accepted
-// by listeners and generated by decoders when providing entity updates.
+// Each kind defines the following encodings:
+// Go Encoding: the golang type which should be accepted by listeners and
+// generated by decoders when providing entity updates.
+// JSON Encoding: the JSON encoding which should be used when encoding the field to JSON.
+// When there is some non-determinism in an encoding, kinds should specify what
+// values they accept and also what is the canonical, deterministic encoding which
+// should be preferably emitted by serializers.
 type Kind int
 
 const (
 	// InvalidKind indicates that an invalid type.
 	InvalidKind Kind = iota
 
-	// StringKind is a string type and values of this type must be of the go type string
-	// containing valid UTF-8 and cannot contain null characters.
+	// StringKind is a string type.
+	// Go Encoding: UTF-8 string with no null characters.
+	// JSON Encoding: string
 	StringKind
 
-	// BytesKind is a bytes type and values of this type must be of the go type []byte.
+	// BytesKind is a bytes type.
+	// Go Encoding: []byte
+	// JSON Encoding: base64 encoded string, canonical values should be encoded with standard encoding and padding.
+	// Either standard or URL encoding with or without padding should be accepted.
 	BytesKind
 
-	// Int8Kind is an int8 type and values of this type must be of the go type int8.
+	// Int8Kind represents an 8-bit signed integer.
+	// Go Encoding: int8
+	// JSON Encoding: number
 	Int8Kind
 
-	// Uint8Kind is a uint8 type and values of this type must be of the go type uint8.
+	// Uint8Kind represents an 8-bit unsigned integer.
+	// Go Encoding: uint8
+	// JSON Encoding: number
 	Uint8Kind
 
-	// Int16Kind is an int16 type and values of this type must be of the go type int16.
+	// Int16Kind represents a 16-bit signed integer.
+	// Go Encoding: int16
+	// JSON Encoding: number
 	Int16Kind
 
-	// Uint16Kind is a uint16 type and values of this type must be of the go type uint16.
+	// Uint16Kind represents a 16-bit unsigned integer.
+	// Go Encoding: uint16
+	// JSON Encoding: number
 	Uint16Kind
 
-	// Int32Kind is an int32 type and values of this type must be of the go type int32.
+	// Int32Kind represents a 32-bit signed integer.
+	// Go Encoding: int32
+	// JSON Encoding: number
 	Int32Kind
 
-	// Uint32Kind is a uint32 type and values of this type must be of the go type uint32.
+	// Uint32Kind represents a 32-bit unsigned integer.
+	// Go Encoding: uint32
+	// JSON Encoding: number
 	Uint32Kind
 
-	// Int64Kind is an int64 type and values of this type must be of the go type int64.
+	// Int64Kind represents a 64-bit signed integer.
+	// Go Encoding: int64
+	// JSON Encoding: base10 integer string which matches the IntegerFormat regex
+	// The canonical encoding should include no leading zeros.
 	Int64Kind
 
-	// Uint64Kind is a uint64 type and values of this type must be of the go type uint64.
+	// Uint64Kind represents a 64-bit unsigned integer.
+	// Go Encoding: uint64
+	// JSON Encoding: base10 integer string which matches the IntegerFormat regex
+	// Canonically encoded values should include no leading zeros.
 	Uint64Kind
 
-	// IntegerStringKind represents an arbitrary precision integer number. Values of this type must
-	// be of the go type string and formatted as base10 integers, specifically matching to
-	// the IntegerFormat regex.
+	// IntegerStringKind represents an arbitrary precision integer number.
+	// Go Encoding: string which matches the IntegerFormat regex
+	// JSON Encoding: base10 integer string
+	// Canonically encoded values should include no leading zeros.
 	IntegerStringKind
 
-	// DecimalStringKind represents an arbitrary precision decimal or integer number. Values of this type
-	// must be of the go type string and match the DecimalFormat regex.
+	// DecimalStringKind represents an arbitrary precision decimal or integer number.
+	// Go Encoding: string which matches the DecimalFormat regex
+	// JSON Encoding: base10 decimal string
+	// Canonically encoded values should include no leading zeros or trailing zeros,
+	// and exponential notation with a lowercase 'e' should be used for any numbers
+	// with an absolute value less than or equal to 1e-6 or greater than or equal to 1e6.
 	DecimalStringKind
 
-	// BoolKind is a boolean type and values of this type must be of the go type bool.
+	// BoolKind represents a boolean true or false value.
+	// Go Encoding: bool
+	// JSON Encoding: boolean
 	BoolKind
 
-	// TimeKind is a time type and values of this type must be of the go type time.Time.
+	// TimeKind represents a nanosecond precision UNIX time value (with zero representing January 1, 1970 UTC).
+	// Its valid range is +/- 2^63 (the range of a 64-bit signed integer).
+	// Go Encoding: time.Time
+	// JSON Encoding: Any value IS0 8601 time stamp should be accepted.
+	// Canonical values should be encoded with UTC time zone Z, nanoseconds should
+	// be encoded with no trailing zeros, and T time values should always be present
+	// even at 00:00:00.
 	TimeKind
 
-	// DurationKind is a duration type and values of this type must be of the go type time.Duration.
+	// DurationKind represents the elapsed time between two nanosecond precision time values.
+	// Its valid range is +/- 2^63 (the range of a 64-bit signed integer).
+	// Go Encoding: time.Duration
+	// JSON Encoding: the number of seconds as a decimal string with no trailing zeros followed by
+	// a lowercase 's' character to represent seconds.
 	DurationKind
 
-	// Float32Kind is a float32 type and values of this type must be of the go type float32.
+	// Float32Kind represents an IEEE-754 32-bit floating point number.
+	// Go Encoding: float32
+	// JSON Encoding: number
 	Float32Kind
 
-	// Float64Kind is a float64 type and values of this type must be of the go type float64.
+	// Float64Kind represents an IEEE-754 64-bit floating point number.
+	// Go Encoding: float64
+	// JSON Encoding: number
 	Float64Kind
 
-	// AddressKind represents an account address and must be of type []byte. Addresses usually have a
-	// human-readable rendering, such as bech32, and tooling should provide a way for apps to define a
-	// string encoder for friendly user-facing display.
+	// AddressKind represents an account address which is represented by a variable length array of bytes.
+	// Addresses usually have a human-readable rendering, such as bech32, and tooling should provide
+	// a way for apps to define a string encoder for friendly user-facing display.
+	// Go Encoding: []byte
+	// JSON Encoding: addresses should be encoded as strings using the human-readable address renderer
+	// provided to the JSON encoder.
 	AddressKind
 
-	// EnumKind is an enum type and values of this type must be of the go type string.
+	// EnumKind represents a value of an enum type.
 	// Fields of this type are expected to set the EnumType field in the field definition to the enum
 	// definition.
+	// Go Encoding: string
+	// JSON Encoding: string
 	EnumKind
 
-	// JSONKind is a JSON type and values of this type should be of go type json.RawMessage and represent
-	// valid JSON.
+	// JSONKind represents arbitrary JSON data.
+	// Go Encoding: json.RawMessage
+	// JSON Encoding: any valid JSON value
 	JSONKind
 )