Skip to content

Commit c2be2c1

Browse files
varomodtcopybara-github
varomodt
authored and
copybara-github
committed
Improve accuracy of documentation on any.proto.
PiperOrigin-RevId: 867605540
1 parent 0e4441f commit c2be2c1

File tree

1 file changed

+55
-108
lines changed

1 file changed

+55
-108
lines changed

‎src/google/protobuf/any.proto‎

Lines changed: 55 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -42,121 +42,68 @@ option csharp_namespace = "Google.Protobuf.WellKnownTypes";
4242
// `Any` contains an arbitrary serialized protocol buffer message along with a
4343
// URL that describes the type of the serialized message.
4444
//
45-
// Protobuf library provides support to pack/unpack Any values in the form
46-
// of utility functions or additional generated methods of the Any type.
47-
//
48-
// Example 1: Pack and unpack a message in C++.
49-
//
50-
// Foo foo = ...;
51-
// Any any;
52-
// any.PackFrom(foo);
53-
// ...
54-
// if (any.UnpackTo(&foo)) {
55-
// ...
56-
// }
57-
//
58-
// Example 2: Pack and unpack a message in Java.
59-
//
60-
// Foo foo = ...;
61-
// Any any = Any.pack(foo);
62-
// ...
63-
// if (any.is(Foo.class)) {
64-
// foo = any.unpack(Foo.class);
65-
// }
66-
// // or ...
67-
// if (any.isSameTypeAs(Foo.getDefaultInstance())) {
68-
// foo = any.unpack(Foo.getDefaultInstance());
69-
// }
70-
//
71-
// Example 3: Pack and unpack a message in Python.
72-
//
73-
// foo = Foo(...)
74-
// any = Any()
75-
// any.Pack(foo)
76-
// ...
77-
// if any.Is(Foo.DESCRIPTOR):
78-
// any.Unpack(foo)
79-
// ...
80-
//
81-
// Example 4: Pack and unpack a message in Go
82-
//
83-
// foo := &pb.Foo{...}
84-
// any, err := anypb.New(foo)
85-
// if err != nil {
86-
// ...
87-
// }
88-
// ...
89-
// foo := &pb.Foo{}
90-
// if err := any.UnmarshalTo(foo); err != nil {
91-
// ...
92-
// }
93-
//
94-
// The pack methods provided by protobuf library will by default use
95-
// 'type.googleapis.com/full.type.name' as the type URL and the unpack
96-
// methods only use the fully qualified type name after the last '/'
97-
// in the type URL, for example "foo.bar.com/x/y.z" will yield type
98-
// name "y.z".
99-
//
100-
// JSON
101-
// ====
102-
// The JSON representation of an `Any` value uses the regular
103-
// representation of the deserialized, embedded message, with an
104-
// additional field `@type` which contains the type URL. Example:
105-
//
106-
// package google.profile;
107-
// message Person {
108-
// string first_name = 1;
109-
// string last_name = 2;
110-
// }
111-
//
112-
// {
113-
// "@type": "type.googleapis.com/google.profile.Person",
114-
// "firstName": <string>,
115-
// "lastName": <string>
116-
// }
117-
//
118-
// If the embedded message type is well-known and has a custom JSON
119-
// representation, that representation will be embedded adding a field
120-
// `value` which holds the custom JSON in addition to the `@type`
121-
// field. Example (for message [google.protobuf.Duration][]):
122-
//
123-
// {
124-
// "@type": "type.googleapis.com/google.protobuf.Duration",
125-
// "value": "1.212s"
126-
// }
127-
//
45+
// In its binary encoding, an `Any` is an ordinary message; but in other wire
46+
// forms like JSON, it has a special encoding. The format of the type URL is
47+
// described on the `type_url` field.
48+
//
49+
// Protobuf APIs provide utilities to interact with `Any` values:
50+
//
51+
// - A 'pack' operation accepts a message and constructs a generic `Any` wrapper
52+
// around it.
53+
// - An 'unpack' operation reads the content of an `Any` message, either into an
54+
// existing message or a new one. Unpack operations must check the type of the
55+
// value they unpack against the declared `type_url`.
56+
// - An 'is' operation decides whether an `Any` contains a message of the given
57+
// type, i.e. whether it can `unpack` that type.
58+
//
59+
// The JSON format representation of an `Any` is either:
60+
//
61+
// - For types which serialize to an object and are not `google.protobuf.Any`
62+
// (which is almost everything), the JSON format representation of the `Any`
63+
// is the same as that of the message, with an additional `@type` field which
64+
// contains the type URL.
65+
// - For `google.protobuf.Any` and the types namespaced under `google.protobuf.`
66+
// (typically called 'well-known') which do not serialize to an object, the
67+
// JSON format representation has a key `@type` which contains the type URL
68+
// and a key `value` which contains the JSON-serialized value.
69+
//
70+
// The text format representation of an `Any` is like a message with one field
71+
// whose name is the type URL in brackets. For example, an `Any` containing a
72+
// `foo.Bar` message may be written `[type.googleapis.com/foo.Bar] { a: 2 }`.
12873
message Any {
129-
// A URL/resource name that uniquely identifies the type of the serialized
130-
// protocol buffer message. This string must contain at least
131-
// one "/" character. The last segment of the URL's path must represent
132-
// the fully qualified name of the type (as in
133-
// `path/google.protobuf.Duration`). The name should be in a canonical form
134-
// (e.g., leading "." is not accepted).
74+
// Identifies the type of the serialized Protobuf message with a URI
75+
// relative-path reference consisting of an arbitrary URI prefix and the
76+
// fully-qualified type name.
13577
//
136-
// In practice, teams usually precompile into the binary all types that they
137-
// expect it to use in the context of Any. However, for URLs which use the
138-
// scheme `http`, `https`, or no scheme, one can optionally set up a type
139-
// server that maps type URLs to message definitions as follows:
78+
// Format: <URI relative-path prefix>/<fully-qualified type name>
79+
// Example: type.googleapis.com/google.protobuf.StringValue
14080
//
141-
// * If no scheme is provided, `https` is assumed.
142-
// * An HTTP GET on the URL must yield a [google.protobuf.Type][]
143-
// value in binary format, or produce an error.
144-
// * Applications are allowed to cache lookup results based on the
145-
// URL, or have them precompiled into a binary to avoid any
146-
// lookup. Therefore, binary compatibility needs to be preserved
147-
// on changes to types. (Use versioned type names to manage
148-
// breaking changes.)
81+
// This string must contain at least one `/` character, and the
82+
// content after the last `/` must be the fully-qualified name of the type in
83+
// canonical form, without a leading dot. Do not write a scheme on these URLs
84+
// so that clients do not attempt to contact them.
14985
//
150-
// Note: this functionality is not currently available in the official
151-
// protobuf release, and it is not used for type URLs beginning with
152-
// type.googleapis.com. As of May 2023, there are no widely used type server
153-
// implementations and no plans to implement one.
86+
// The URI prefix is arbitrary and Protobuf implementations are expected to
87+
// simply strip off everything up to and including the last `/` to identify
88+
// the type. `type.googleapis.com/` is a common default prefix but this URL
89+
// does not indicate association with Google and those URLs are not expected
90+
// to respond to any requests. Some legacy implementations may require this
91+
// prefix.
15492
//
155-
// Schemes other than `http`, `https` (or the empty scheme) might be
156-
// used with implementation specific semantics.
93+
// All type URL strings must be legal URI relative-path references with the
94+
// additional restriction (for the text format) that the content of the URL
95+
// must consist of alphanumeric characters, percent-encoded escapes, and
96+
// characters in the following set (not including the outer backticks):
97+
// `/-.~_!$&()*+,;=`. Despite our allowing percent encodings, implementations
98+
// should not unescape them to prevent confusion with existing parsers. For
99+
// example, `type.googleapis.com%2FFoo` should be rejected.
157100
//
101+
// In the original design of `Any` the possibility of launching a type
102+
// resolution service at these type URLs was considered but Protobuf never
103+
// implemented one and considers contacting these URLs to be problematic and
104+
// a potential security issue. Do not attempt to contact type URLs.
158105
string type_url = 1;
159106

160-
// Must be a valid serialized protocol buffer of the above specified type.
107+
// Holds a Protobuf serialization of the type described by type_url.
161108
bytes value = 2;
162109
}

0 commit comments

Comments
 (0)