descriptor.proto revision fbaaef999ba563838ebd00874ed8a1c01fbf286d
1// Protocol Buffers - Google's data interchange format 2// Copyright 2008 Google Inc. All rights reserved. 3// http://code.google.com/p/protobuf/ 4// 5// Redistribution and use in source and binary forms, with or without 6// modification, are permitted provided that the following conditions are 7// met: 8// 9// * Redistributions of source code must retain the above copyright 10// notice, this list of conditions and the following disclaimer. 11// * Redistributions in binary form must reproduce the above 12// copyright notice, this list of conditions and the following disclaimer 13// in the documentation and/or other materials provided with the 14// distribution. 15// * Neither the name of Google Inc. nor the names of its 16// contributors may be used to endorse or promote products derived from 17// this software without specific prior written permission. 18// 19// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31// Author: kenton@google.com (Kenton Varda) 32// Based on original Protocol Buffers design by 33// Sanjay Ghemawat, Jeff Dean, and others. 34// 35// The messages in this file describe the definitions found in .proto files. 36// A valid .proto file can be translated directly to a FileDescriptorProto 37// without any other information (e.g. without reading its imports). 38 39 40 41package google.protobuf; 42option java_package = "com.google.protobuf"; 43option java_outer_classname = "DescriptorProtos"; 44 45// descriptor.proto must be optimized for speed because reflection-based 46// algorithms don't work during bootstrapping. 47option optimize_for = SPEED; 48 49// The protocol compiler can output a FileDescriptorSet containing the .proto 50// files it parses. 51message FileDescriptorSet { 52 repeated FileDescriptorProto file = 1; 53} 54 55// Describes a complete .proto file. 56message FileDescriptorProto { 57 optional string name = 1; // file name, relative to root of source tree 58 optional string package = 2; // e.g. "foo", "foo.bar", etc. 59 60 // Names of files imported by this file. 61 repeated string dependency = 3; 62 63 // All top-level definitions in this file. 64 repeated DescriptorProto message_type = 4; 65 repeated EnumDescriptorProto enum_type = 5; 66 repeated ServiceDescriptorProto service = 6; 67 repeated FieldDescriptorProto extension = 7; 68 69 optional FileOptions options = 8; 70} 71 72// Describes a message type. 73message DescriptorProto { 74 optional string name = 1; 75 76 repeated FieldDescriptorProto field = 2; 77 repeated FieldDescriptorProto extension = 6; 78 79 repeated DescriptorProto nested_type = 3; 80 repeated EnumDescriptorProto enum_type = 4; 81 82 message ExtensionRange { 83 optional int32 start = 1; 84 optional int32 end = 2; 85 } 86 repeated ExtensionRange extension_range = 5; 87 88 optional MessageOptions options = 7; 89} 90 91// Describes a field within a message. 92message FieldDescriptorProto { 93 enum Type { 94 // 0 is reserved for errors. 95 // Order is weird for historical reasons. 96 TYPE_DOUBLE = 1; 97 TYPE_FLOAT = 2; 98 TYPE_INT64 = 3; // Not ZigZag encoded. Negative numbers 99 // take 10 bytes. Use TYPE_SINT64 if negative 100 // values are likely. 101 TYPE_UINT64 = 4; 102 TYPE_INT32 = 5; // Not ZigZag encoded. Negative numbers 103 // take 10 bytes. Use TYPE_SINT32 if negative 104 // values are likely. 105 TYPE_FIXED64 = 6; 106 TYPE_FIXED32 = 7; 107 TYPE_BOOL = 8; 108 TYPE_STRING = 9; 109 TYPE_GROUP = 10; // Tag-delimited aggregate. 110 TYPE_MESSAGE = 11; // Length-delimited aggregate. 111 112 // New in version 2. 113 TYPE_BYTES = 12; 114 TYPE_UINT32 = 13; 115 TYPE_ENUM = 14; 116 TYPE_SFIXED32 = 15; 117 TYPE_SFIXED64 = 16; 118 TYPE_SINT32 = 17; // Uses ZigZag encoding. 119 TYPE_SINT64 = 18; // Uses ZigZag encoding. 120 }; 121 122 enum Label { 123 // 0 is reserved for errors 124 LABEL_OPTIONAL = 1; 125 LABEL_REQUIRED = 2; 126 LABEL_REPEATED = 3; 127 // TODO(sanjay): Should we add LABEL_MAP? 128 }; 129 130 optional string name = 1; 131 optional int32 number = 3; 132 optional Label label = 4; 133 134 // If type_name is set, this need not be set. If both this and type_name 135 // are set, this must be either TYPE_ENUM or TYPE_MESSAGE. 136 optional Type type = 5; 137 138 // For message and enum types, this is the name of the type. If the name 139 // starts with a '.', it is fully-qualified. Otherwise, C++-like scoping 140 // rules are used to find the type (i.e. first the nested types within this 141 // message are searched, then within the parent, on up to the root 142 // namespace). 143 optional string type_name = 6; 144 145 // For extensions, this is the name of the type being extended. It is 146 // resolved in the same manner as type_name. 147 optional string extendee = 2; 148 149 // For numeric types, contains the original text representation of the value. 150 // For booleans, "true" or "false". 151 // For strings, contains the default text contents (not escaped in any way). 152 // For bytes, contains the C escaped value. All bytes >= 128 are escaped. 153 // TODO(kenton): Base-64 encode? 154 optional string default_value = 7; 155 156 optional FieldOptions options = 8; 157} 158 159// Describes an enum type. 160message EnumDescriptorProto { 161 optional string name = 1; 162 163 repeated EnumValueDescriptorProto value = 2; 164 165 optional EnumOptions options = 3; 166} 167 168// Describes a value within an enum. 169message EnumValueDescriptorProto { 170 optional string name = 1; 171 optional int32 number = 2; 172 173 optional EnumValueOptions options = 3; 174} 175 176// Describes a service. 177message ServiceDescriptorProto { 178 optional string name = 1; 179 repeated MethodDescriptorProto method = 2; 180 181 optional ServiceOptions options = 3; 182} 183 184// Describes a method of a service. 185message MethodDescriptorProto { 186 optional string name = 1; 187 188 // Input and output type names. These are resolved in the same way as 189 // FieldDescriptorProto.type_name, but must refer to a message type. 190 optional string input_type = 2; 191 optional string output_type = 3; 192 193 optional MethodOptions options = 4; 194} 195 196// =================================================================== 197// Options 198 199// Each of the definitions above may have "options" attached. These are 200// just annotations which may cause code to be generated slightly differently 201// or may contain hints for code that manipulates protocol messages. 202// 203// Clients may define custom options as extensions of the *Options messages. 204// These extensions may not yet be known at parsing time, so the parser cannot 205// store the values in them. Instead it stores them in a field in the *Options 206// message called uninterpreted_option. This field must have the same name 207// across all *Options messages. We then use this field to populate the 208// extensions when we build a descriptor, at which point all protos have been 209// parsed and so all extensions are known. 210// 211// Extension numbers for custom options may be chosen as follows: 212// * For options which will only be used within a single application or 213// organization, or for experimental options, use field numbers 50000 214// through 99999. It is up to you to ensure that you do not use the 215// same number for multiple options. 216// * For options which will be published and used publicly by multiple 217// independent entities, e-mail kenton@google.com to reserve extension 218// numbers. Simply tell me how many you need and I'll send you back a 219// set of numbers to use -- there's no need to explain how you intend to 220// use them. If this turns out to be popular, a web service will be set up 221// to automatically assign option numbers. 222 223 224message FileOptions { 225 226 // Sets the Java package where classes generated from this .proto will be 227 // placed. By default, the proto package is used, but this is often 228 // inappropriate because proto packages do not normally start with backwards 229 // domain names. 230 optional string java_package = 1; 231 232 233 // If set, all the classes from the .proto file are wrapped in a single 234 // outer class with the given name. This applies to both Proto1 235 // (equivalent to the old "--one_java_file" option) and Proto2 (where 236 // a .proto always translates to a single class, but you may want to 237 // explicitly choose the class name). 238 optional string java_outer_classname = 8; 239 240 // If set true, then the Java code generator will generate a separate .java 241 // file for each top-level message, enum, and service defined in the .proto 242 // file. Thus, these types will *not* be nested inside the outer class 243 // named by java_outer_classname. However, the outer class will still be 244 // generated to contain the file's getDescriptor() method as well as any 245 // top-level extensions defined in the file. 246 optional bool java_multiple_files = 10 [default=false]; 247 248 // Generated classes can be optimized for speed or code size. 249 enum OptimizeMode { 250 SPEED = 1; // Generate complete code for parsing, serialization, 251 // etc. 252 CODE_SIZE = 2; // Use ReflectionOps to implement these methods. 253 LITE_RUNTIME = 3; // Generate code using MessageLite and the lite runtime. 254 } 255 optional OptimizeMode optimize_for = 9 [default=SPEED]; 256 257 258 259 // The parser stores options it doesn't recognize here. See above. 260 repeated UninterpretedOption uninterpreted_option = 999; 261 262 // Clients can define custom options in extensions of this message. See above. 263 extensions 1000 to max; 264} 265 266message MessageOptions { 267 // Set true to use the old proto1 MessageSet wire format for extensions. 268 // This is provided for backwards-compatibility with the MessageSet wire 269 // format. You should not use this for any other reason: It's less 270 // efficient, has fewer features, and is more complicated. 271 // 272 // The message must be defined exactly as follows: 273 // message Foo { 274 // option message_set_wire_format = true; 275 // extensions 4 to max; 276 // } 277 // Note that the message cannot have any defined fields; MessageSets only 278 // have extensions. 279 // 280 // All extensions of your type must be singular messages; e.g. they cannot 281 // be int32s, enums, or repeated messages. 282 // 283 // Because this is an option, the above two restrictions are not enforced by 284 // the protocol compiler. 285 optional bool message_set_wire_format = 1 [default=false]; 286 287 // Disables the generation of the standard "descriptor()" accessor, which can 288 // conflict with a field of the same name. This is meant to make migration 289 // from proto1 easier; new code should avoid fields named "descriptor". 290 optional bool no_standard_descriptor_accessor = 2 [default=false]; 291 292 // The parser stores options it doesn't recognize here. See above. 293 repeated UninterpretedOption uninterpreted_option = 999; 294 295 // Clients can define custom options in extensions of this message. See above. 296 extensions 1000 to max; 297} 298 299message FieldOptions { 300 // The ctype option instructs the C++ code generator to use a different 301 // representation of the field than it normally would. See the specific 302 // options below. This option is not yet implemented in the open source 303 // release -- sorry, we'll try to include it in a future version! 304 optional CType ctype = 1; 305 enum CType { 306 CORD = 1; 307 308 STRING_PIECE = 2; 309 } 310 // The packed option can be enabled for repeated primitive fields to enable 311 // a more efficient representation on the wire. Rather than repeatedly 312 // writing the tag and type for each element, the entire array is encoded as 313 // a single length-delimited blob. 314 optional bool packed = 2; 315 316 // Is this field deprecated? 317 // Depending on the target platform, this can emit Deprecated annotations 318 // for accessors, or it will be completely ignored; in the very least, this 319 // is a formalization for deprecating fields. 320 optional bool deprecated = 3 [default=false]; 321 322 // EXPERIMENTAL. DO NOT USE. 323 // For "map" fields, the name of the field in the enclosed type that 324 // is the key for this map. For example, suppose we have: 325 // message Item { 326 // required string name = 1; 327 // required string value = 2; 328 // } 329 // message Config { 330 // repeated Item items = 1 [experimental_map_key="name"]; 331 // } 332 // In this situation, the map key for Item will be set to "name". 333 // TODO: Fully-implement this, then remove the "experimental_" prefix. 334 optional string experimental_map_key = 9; 335 336 // The parser stores options it doesn't recognize here. See above. 337 repeated UninterpretedOption uninterpreted_option = 999; 338 339 // Clients can define custom options in extensions of this message. See above. 340 extensions 1000 to max; 341} 342 343message EnumOptions { 344 345 // The parser stores options it doesn't recognize here. See above. 346 repeated UninterpretedOption uninterpreted_option = 999; 347 348 // Clients can define custom options in extensions of this message. See above. 349 extensions 1000 to max; 350} 351 352message EnumValueOptions { 353 // The parser stores options it doesn't recognize here. See above. 354 repeated UninterpretedOption uninterpreted_option = 999; 355 356 // Clients can define custom options in extensions of this message. See above. 357 extensions 1000 to max; 358} 359 360message ServiceOptions { 361 362 // Note: Field numbers 1 through 32 are reserved for Google's internal RPC 363 // framework. We apologize for hoarding these numbers to ourselves, but 364 // we were already using them long before we decided to release Protocol 365 // Buffers. 366 367 // The parser stores options it doesn't recognize here. See above. 368 repeated UninterpretedOption uninterpreted_option = 999; 369 370 // Clients can define custom options in extensions of this message. See above. 371 extensions 1000 to max; 372} 373 374message MethodOptions { 375 376 // Note: Field numbers 1 through 32 are reserved for Google's internal RPC 377 // framework. We apologize for hoarding these numbers to ourselves, but 378 // we were already using them long before we decided to release Protocol 379 // Buffers. 380 381 // The parser stores options it doesn't recognize here. See above. 382 repeated UninterpretedOption uninterpreted_option = 999; 383 384 // Clients can define custom options in extensions of this message. See above. 385 extensions 1000 to max; 386} 387 388// A message representing a option the parser does not recognize. This only 389// appears in options protos created by the compiler::Parser class. 390// DescriptorPool resolves these when building Descriptor objects. Therefore, 391// options protos in descriptor objects (e.g. returned by Descriptor::options(), 392// or produced by Descriptor::CopyTo()) will never have UninterpretedOptions 393// in them. 394message UninterpretedOption { 395 // The name of the uninterpreted option. Each string represents a segment in 396 // a dot-separated name. is_extension is true iff a segment represents an 397 // extension (denoted with parentheses in options specs in .proto files). 398 // E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents 399 // "foo.(bar.baz).qux". 400 message NamePart { 401 required string name_part = 1; 402 required bool is_extension = 2; 403 } 404 repeated NamePart name = 2; 405 406 // The value of the uninterpreted option, in whatever type the tokenizer 407 // identified it as during parsing. Exactly one of these should be set. 408 optional string identifier_value = 3; 409 optional uint64 positive_int_value = 4; 410 optional int64 negative_int_value = 5; 411 optional double double_value = 6; 412 optional bytes string_value = 7; 413} 414