Documentation

Overview

Package structpb contains generated types for google/protobuf/struct.proto.

The messages (i.e., Value, Struct, and ListValue) defined in struct.proto are used to represent arbitrary JSON. The Value message represents a JSON value, the Struct message represents a JSON object, and the ListValue message represents a JSON array. See https://json.org for more information.

The Value, Struct, and ListValue types have generated MarshalJSON and UnmarshalJSON methods such that they serialize JSON equivalent to what the messages themselves represent. Use of these types with the "google.golang.org/protobuf/encoding/protojson" package ensures that they will be serialized as their JSON equivalent.

Conversion to and from a Go interface

The standard Go "encoding/json" package has functionality to serialize arbitrary types to a large degree. The Value.AsInterface, Struct.AsMap, and ListValue.AsSlice methods can convert the protobuf message representation into a form represented by interface{}, map[string]interface{}, and []interface{}. This form can be used with other packages that operate on such data structures and also directly with the standard json package.

In order to convert the interface{}, map[string]interface{}, and []interface{} forms back as Value, Struct, and ListValue messages, use the NewStruct, NewList, and NewValue constructor functions.

Example usage

Consider the following example JSON object:

{
	"firstName": "John",
	"lastName": "Smith",
	"isAlive": true,
	"age": 27,
	"address": {
		"streetAddress": "21 2nd Street",
		"city": "New York",
		"state": "NY",
		"postalCode": "10021-3100"
	},
	"phoneNumbers": [
		{
			"type": "home",
			"number": "212 555-1234"
		},
		{
			"type": "office",
			"number": "646 555-4567"
		}
	],
	"children": [],
	"spouse": null
}

To construct a Value message representing the above JSON object:

m, err := structpb.NewValue(map[string]interface{}{
	"firstName": "John",
	"lastName":  "Smith",
	"isAlive":   true,
	"age":       27,
	"address": map[string]interface{}{
		"streetAddress": "21 2nd Street",
		"city":          "New York",
		"state":         "NY",
		"postalCode":    "10021-3100",
	},
	"phoneNumbers": []interface{}{
		map[string]interface{}{
			"type":   "home",
			"number": "212 555-1234",
		},
		map[string]interface{}{
			"type":   "office",
			"number": "646 555-4567",
		},
	},
	"children": []interface{}{},
	"spouse":   nil,
})
if err != nil {
	... // handle error
}
... // make use of m as a *structpb.Value

Index

Constants

This section is empty.

Variables

View Source
var (
	NullValue_name = map[int32]string{
		0: "NULL_VALUE",
	}
	NullValue_value = map[string]int32{
		"NULL_VALUE": 0,
	}
)

    Enum value maps for NullValue.

    View Source
    var File_google_protobuf_struct_proto protoreflect.FileDescriptor

    Functions

    This section is empty.

    Types

    type ListValue

    type ListValue struct {
    
    	// Repeated field of dynamically typed values.
    	Values []*Value `protobuf:"bytes,1,rep,name=values,proto3" json:"values,omitempty"`
    	// contains filtered or unexported fields
    }

      `ListValue` is a wrapper around a repeated field of values.

      The JSON representation for `ListValue` is JSON array.

      func NewList

      func NewList(v []interface{}) (*ListValue, error)

        NewList constructs a ListValue from a general-purpose Go slice. The slice elements are converted using NewValue.

        func (*ListValue) AsSlice

        func (x *ListValue) AsSlice() []interface{}

          AsSlice converts x to a general-purpose Go slice. The slice elements are converted by calling Value.AsInterface.

          func (*ListValue) Descriptor

          func (*ListValue) Descriptor() ([]byte, []int)

            Deprecated: Use ListValue.ProtoReflect.Descriptor instead.

            func (*ListValue) GetValues

            func (x *ListValue) GetValues() []*Value

            func (*ListValue) MarshalJSON

            func (x *ListValue) MarshalJSON() ([]byte, error)

            func (*ListValue) ProtoMessage

            func (*ListValue) ProtoMessage()

            func (*ListValue) ProtoReflect

            func (x *ListValue) ProtoReflect() protoreflect.Message

            func (*ListValue) Reset

            func (x *ListValue) Reset()

            func (*ListValue) String

            func (x *ListValue) String() string

            func (*ListValue) UnmarshalJSON

            func (x *ListValue) UnmarshalJSON(b []byte) error

            type NullValue

            type NullValue int32

              `NullValue` is a singleton enumeration to represent the null value for the `Value` type union.

              The JSON representation for `NullValue` is JSON `null`.
              
              const (
              	// Null value.
              	NullValue_NULL_VALUE NullValue = 0
              )

              func (NullValue) Descriptor

              func (NullValue) Descriptor() protoreflect.EnumDescriptor

              func (NullValue) Enum

              func (x NullValue) Enum() *NullValue

              func (NullValue) EnumDescriptor

              func (NullValue) EnumDescriptor() ([]byte, []int)

                Deprecated: Use NullValue.Descriptor instead.

                func (NullValue) Number

                func (x NullValue) Number() protoreflect.EnumNumber

                func (NullValue) String

                func (x NullValue) String() string

                func (NullValue) Type

                type Struct

                type Struct struct {
                
                	// Unordered map of dynamically typed values.
                	Fields map[string]*Value `` /* 153-byte string literal not displayed */
                	// contains filtered or unexported fields
                }

                  `Struct` represents a structured data value, consisting of fields which map to dynamically typed values. In some languages, `Struct` might be supported by a native representation. For example, in scripting languages like JS a struct is represented as an object. The details of that representation are described together with the proto support for the language.

                  The JSON representation for `Struct` is JSON object.

                  func NewStruct

                  func NewStruct(v map[string]interface{}) (*Struct, error)

                    NewStruct constructs a Struct from a general-purpose Go map. The map keys must be valid UTF-8. The map values are converted using NewValue.

                    func (*Struct) AsMap

                    func (x *Struct) AsMap() map[string]interface{}

                      AsMap converts x to a general-purpose Go map. The map values are converted by calling Value.AsInterface.

                      func (*Struct) Descriptor

                      func (*Struct) Descriptor() ([]byte, []int)

                        Deprecated: Use Struct.ProtoReflect.Descriptor instead.

                        func (*Struct) GetFields

                        func (x *Struct) GetFields() map[string]*Value

                        func (*Struct) MarshalJSON

                        func (x *Struct) MarshalJSON() ([]byte, error)

                        func (*Struct) ProtoMessage

                        func (*Struct) ProtoMessage()

                        func (*Struct) ProtoReflect

                        func (x *Struct) ProtoReflect() protoreflect.Message

                        func (*Struct) Reset

                        func (x *Struct) Reset()

                        func (*Struct) String

                        func (x *Struct) String() string

                        func (*Struct) UnmarshalJSON

                        func (x *Struct) UnmarshalJSON(b []byte) error

                        type Value

                        type Value struct {
                        
                        	// The kind of value.
                        	//
                        	// Types that are assignable to Kind:
                        	//	*Value_NullValue
                        	//	*Value_NumberValue
                        	//	*Value_StringValue
                        	//	*Value_BoolValue
                        	//	*Value_StructValue
                        	//	*Value_ListValue
                        	Kind isValue_Kind `protobuf_oneof:"kind"`
                        	// contains filtered or unexported fields
                        }

                          `Value` represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values. A producer of value is expected to set one of that variants, absence of any variant indicates an error.

                          The JSON representation for `Value` is JSON value.

                          func NewBoolValue

                          func NewBoolValue(v bool) *Value

                            NewBoolValue constructs a new boolean Value.

                            func NewListValue

                            func NewListValue(v *ListValue) *Value

                              NewListValue constructs a new list Value.

                              func NewNullValue

                              func NewNullValue() *Value

                                NewNullValue constructs a new null Value.

                                func NewNumberValue

                                func NewNumberValue(v float64) *Value

                                  NewNumberValue constructs a new number Value.

                                  func NewStringValue

                                  func NewStringValue(v string) *Value

                                    NewStringValue constructs a new string Value.

                                    func NewStructValue

                                    func NewStructValue(v *Struct) *Value

                                      NewStructValue constructs a new struct Value.

                                      func NewValue

                                      func NewValue(v interface{}) (*Value, error)

                                        NewValue constructs a Value from a general-purpose Go interface.

                                        ╔════════════════════════╤════════════════════════════════════════════╗
                                        ║ Go type                │ Conversion                                 ║
                                        ╠════════════════════════╪════════════════════════════════════════════╣
                                        ║ nil                    │ stored as NullValue                        ║
                                        ║ bool                   │ stored as BoolValue                        ║
                                        ║ int, int32, int64      │ stored as NumberValue                      ║
                                        ║ uint, uint32, uint64   │ stored as NumberValue                      ║
                                        ║ float32, float64       │ stored as NumberValue                      ║
                                        ║ string                 │ stored as StringValue; must be valid UTF-8 ║
                                        ║ []byte                 │ stored as StringValue; base64-encoded      ║
                                        ║ map[string]interface{} │ stored as StructValue                      ║
                                        ║ []interface{}          │ stored as ListValue                        ║
                                        ╚════════════════════════╧════════════════════════════════════════════╝
                                        

                                        When converting an int64 or uint64 to a NumberValue, numeric precision loss is possible since they are stored as a float64.

                                        func (*Value) AsInterface

                                        func (x *Value) AsInterface() interface{}

                                          AsInterface converts x to a general-purpose Go interface.

                                          Calling Value.MarshalJSON and "encoding/json".Marshal on this output produce semantically equivalent JSON (assuming no errors occur).

                                          Floating-point values (i.e., "NaN", "Infinity", and "-Infinity") are converted as strings to remain compatible with MarshalJSON.

                                          func (*Value) Descriptor

                                          func (*Value) Descriptor() ([]byte, []int)

                                            Deprecated: Use Value.ProtoReflect.Descriptor instead.

                                            func (*Value) GetBoolValue

                                            func (x *Value) GetBoolValue() bool

                                            func (*Value) GetKind

                                            func (m *Value) GetKind() isValue_Kind

                                            func (*Value) GetListValue

                                            func (x *Value) GetListValue() *ListValue

                                            func (*Value) GetNullValue

                                            func (x *Value) GetNullValue() NullValue

                                            func (*Value) GetNumberValue

                                            func (x *Value) GetNumberValue() float64

                                            func (*Value) GetStringValue

                                            func (x *Value) GetStringValue() string

                                            func (*Value) GetStructValue

                                            func (x *Value) GetStructValue() *Struct

                                            func (*Value) MarshalJSON

                                            func (x *Value) MarshalJSON() ([]byte, error)

                                            func (*Value) ProtoMessage

                                            func (*Value) ProtoMessage()

                                            func (*Value) ProtoReflect

                                            func (x *Value) ProtoReflect() protoreflect.Message

                                            func (*Value) Reset

                                            func (x *Value) Reset()

                                            func (*Value) String

                                            func (x *Value) String() string

                                            func (*Value) UnmarshalJSON

                                            func (x *Value) UnmarshalJSON(b []byte) error

                                            type Value_BoolValue

                                            type Value_BoolValue struct {
                                            	// Represents a boolean value.
                                            	BoolValue bool `protobuf:"varint,4,opt,name=bool_value,json=boolValue,proto3,oneof"`
                                            }

                                            type Value_ListValue

                                            type Value_ListValue struct {
                                            	// Represents a repeated `Value`.
                                            	ListValue *ListValue `protobuf:"bytes,6,opt,name=list_value,json=listValue,proto3,oneof"`
                                            }

                                            type Value_NullValue

                                            type Value_NullValue struct {
                                            	// Represents a null value.
                                            	NullValue NullValue `protobuf:"varint,1,opt,name=null_value,json=nullValue,proto3,enum=google.protobuf.NullValue,oneof"`
                                            }

                                            type Value_NumberValue

                                            type Value_NumberValue struct {
                                            	// Represents a double value.
                                            	NumberValue float64 `protobuf:"fixed64,2,opt,name=number_value,json=numberValue,proto3,oneof"`
                                            }

                                            type Value_StringValue

                                            type Value_StringValue struct {
                                            	// Represents a string value.
                                            	StringValue string `protobuf:"bytes,3,opt,name=string_value,json=stringValue,proto3,oneof"`
                                            }

                                            type Value_StructValue

                                            type Value_StructValue struct {
                                            	// Represents a structured value.
                                            	StructValue *Struct `protobuf:"bytes,5,opt,name=struct_value,json=structValue,proto3,oneof"`
                                            }

                                            Source Files