diff --git a/schema/kind.go b/schema/kind.go index 44d18e100ffd..e5457420149b 100644 --- a/schema/kind.go +++ b/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 )