structpb

package
v1.36.12 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 10, 2026 License: BSD-3-Clause Imports: 10 Imported by: 7,186

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 any, map[string]any, and []any. 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 any, map[string]any, and []any 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]any{
	"firstName": "John",
	"lastName":  "Smith",
	"isAlive":   true,
	"age":       27,
	"address": map[string]any{
		"streetAddress": "21 2nd Street",
		"city":          "New York",
		"state":         "NY",
		"postalCode":    "10021-3100",
	},
	"phoneNumbers": []any{
		map[string]any{
			"type":   "home",
			"number": "212 555-1234",
		},
		map[string]any{
			"type":   "office",
			"number": "646 555-4567",
		},
	},
	"children": []any{},
	"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
}

Represents a JSON array.

func NewList added in v1.25.0 

func NewList(v []any) (*ListValue, error)

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

func (*ListValue) AsSlice added in v1.25.0 

func (x *ListValue) AsSlice() []any

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

func (*ListValue) Descriptor deprecated 

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

Deprecated: Use ListValue.ProtoReflect.Descriptor instead.

func (*ListValue) GetValues 

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

func (*ListValue) MarshalJSON added in v1.25.0 

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 added in v1.25.0 

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

type NullValue 

type NullValue int32

Represents a JSON `null`.

`NullValue` is a sentinel, using an enum with only one value to represent the null value for the `Value` type union.

A field of type `NullValue` with any value other than `0` is considered invalid. Most ProtoJSON serializers will emit a Value with a `null_value` set as a JSON `null` regardless of the integer value, and so will round trip to a `0` value. 

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 deprecated 

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 

func (NullValue) Type() protoreflect.EnumType

type Struct 

type Struct struct {

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

Represents a JSON object.

An unordered key-value map, intending to perfectly capture the semantics of a JSON object. This enables parsing any arbitrary JSON payload as a message field in ProtoJSON format.

This follows RFC 8259 guidelines for interoperable JSON: notably this type cannot represent large Int64 values or `NaN`/`Infinity` numbers, since the JSON format generally does not support those values in its number type.

If you do not intend to parse arbitrary JSON into your message, a custom typed message should be preferred instead of using this type.

func NewStruct added in v1.25.0 

func NewStruct(v map[string]any) (*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 added in v1.25.0 

func (x *Struct) AsMap() map[string]any

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

func (*Struct) Descriptor deprecated 

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

Deprecated: Use Struct.ProtoReflect.Descriptor instead.

func (*Struct) GetFields 

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

func (*Struct) MarshalJSON added in v1.25.0 

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 added in v1.25.0 

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

type Value 

type Value struct {

	// The kind of value.
	//
	// Types that are valid to be assigned 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
}

Represents a JSON value.

`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 these variants. Absence of any variant is an invalid state.

func NewBoolValue added in v1.25.0 

func NewBoolValue(v bool) *Value

NewBoolValue constructs a new boolean Value.

func NewListValue added in v1.25.0 

func NewListValue(v *ListValue) *Value

NewListValue constructs a new list Value.

func NewNullValue added in v1.25.0 

func NewNullValue() *Value

NewNullValue constructs a new null Value.

func NewNumberValue added in v1.25.0 

func NewNumberValue(v float64) *Value

NewNumberValue constructs a new number Value.

func NewStringValue added in v1.25.0 

func NewStringValue(v string) *Value

NewStringValue constructs a new string Value.

func NewStructValue added in v1.25.0 

func NewStructValue(v *Struct) *Value

NewStructValue constructs a new struct Value.

func NewValue added in v1.25.0 

func NewValue(v any) (*Value, error)

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

╔═══════════════════════════════════════╤════════════════════════════════════════════╗
║ Go type                               │ Conversion                                 ║
╠═══════════════════════════════════════╪════════════════════════════════════════════╣
║ nil                                   │ stored as NullValue                        ║
║ bool                                  │ stored as BoolValue                        ║
║ int, int8, int16, int32, int64        │ stored as NumberValue                      ║
║ uint, uint8, uint16, uint32, uint64   │ stored as NumberValue                      ║
║ float32, float64                      │ stored as NumberValue                      ║
║ json.Number                           │ stored as NumberValue                      ║
║ string                                │ stored as StringValue; must be valid UTF-8 ║
║ []byte                                │ stored as StringValue; base64-encoded      ║
║ map[string]any                        │ stored as StructValue                      ║
║ []any                                 │ 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 added in v1.25.0 

func (x *Value) AsInterface() any

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 deprecated 

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

Deprecated: Use Value.ProtoReflect.Descriptor instead.

func (*Value) GetBoolValue 

func (x *Value) GetBoolValue() bool

func (*Value) GetKind 

func (x *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 added in v1.25.0 

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 added in v1.25.0 

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

type Value_BoolValue 

type Value_BoolValue struct {
	// Represents a JSON boolean (`true` or `false` literal in JSON).
	BoolValue bool `protobuf:"varint,4,opt,name=bool_value,json=boolValue,proto3,oneof"`
}

type Value_ListValue 

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

type Value_NullValue 

type Value_NullValue struct {
	// Represents a JSON `null`.
	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 JSON number. Must not be `NaN`, `Infinity` or
	// `-Infinity`, since those are not supported in JSON. This also cannot
	// represent large Int64 values, since JSON format generally does not
	// support them in its number type.
	NumberValue float64 `protobuf:"fixed64,2,opt,name=number_value,json=numberValue,proto3,oneof"`
}

type Value_StringValue 

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

type Value_StructValue 

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.