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 // Indexes of the public imported files in the dependency list above. 63 repeated int32 public_dependency = 10; 64 // Indexes of the weak imported files in the dependency list. 65 // For Google-internal migration only. Do not use. 66 repeated int32 weak_dependency = 11; 67 68 // All top-level definitions in this file. 69 repeated DescriptorProto message_type = 4; 70 repeated EnumDescriptorProto enum_type = 5; 71 repeated ServiceDescriptorProto service = 6; 72 repeated FieldDescriptorProto extension = 7; 73 74 optional FileOptions options = 8; 75 76 // This field contains optional information about the original source code. 77 // You may safely remove this entire field whithout harming runtime 78 // functionality of the descriptors -- the information is needed only by 79 // development tools. 80 optional SourceCodeInfo source_code_info = 9; 81} 82 83// Describes a message type. 84message DescriptorProto { 85 optional string name = 1; 86 87 repeated FieldDescriptorProto field = 2; 88 repeated FieldDescriptorProto extension = 6; 89 90 repeated DescriptorProto nested_type = 3; 91 repeated EnumDescriptorProto enum_type = 4; 92 93 message ExtensionRange { 94 optional int32 start = 1; 95 optional int32 end = 2; 96 } 97 repeated ExtensionRange extension_range = 5; 98 99 optional MessageOptions options = 7; 100} 101 102// Describes a field within a message. 103message FieldDescriptorProto { 104 enum Type { 105 // 0 is reserved for errors. 106 // Order is weird for historical reasons. 107 TYPE_DOUBLE = 1; 108 TYPE_FLOAT = 2; 109 // Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT64 if 110 // negative values are likely. 111 TYPE_INT64 = 3; 112 TYPE_UINT64 = 4; 113 // Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT32 if 114 // negative values are likely. 115 TYPE_INT32 = 5; 116 TYPE_FIXED64 = 6; 117 TYPE_FIXED32 = 7; 118 TYPE_BOOL = 8; 119 TYPE_STRING = 9; 120 TYPE_GROUP = 10; // Tag-delimited aggregate. 121 TYPE_MESSAGE = 11; // Length-delimited aggregate. 122 123 // New in version 2. 124 TYPE_BYTES = 12; 125 TYPE_UINT32 = 13; 126 TYPE_ENUM = 14; 127 TYPE_SFIXED32 = 15; 128 TYPE_SFIXED64 = 16; 129 TYPE_SINT32 = 17; // Uses ZigZag encoding. 130 TYPE_SINT64 = 18; // Uses ZigZag encoding. 131 }; 132 133 enum Label { 134 // 0 is reserved for errors 135 LABEL_OPTIONAL = 1; 136 LABEL_REQUIRED = 2; 137 LABEL_REPEATED = 3; 138 // TODO(sanjay): Should we add LABEL_MAP? 139 }; 140 141 optional string name = 1; 142 optional int32 number = 3; 143 optional Label label = 4; 144 145 // If type_name is set, this need not be set. If both this and type_name 146 // are set, this must be either TYPE_ENUM or TYPE_MESSAGE. 147 optional Type type = 5; 148 149 // For message and enum types, this is the name of the type. If the name 150 // starts with a '.', it is fully-qualified. Otherwise, C++-like scoping 151 // rules are used to find the type (i.e. first the nested types within this 152 // message are searched, then within the parent, on up to the root 153 // namespace). 154 optional string type_name = 6; 155 156 // For extensions, this is the name of the type being extended. It is 157 // resolved in the same manner as type_name. 158 optional string extendee = 2; 159 160 // For numeric types, contains the original text representation of the value. 161 // For booleans, "true" or "false". 162 // For strings, contains the default text contents (not escaped in any way). 163 // For bytes, contains the C escaped value. All bytes >= 128 are escaped. 164 // TODO(kenton): Base-64 encode? 165 optional string default_value = 7; 166 167 optional FieldOptions options = 8; 168} 169 170// Describes an enum type. 171message EnumDescriptorProto { 172 optional string name = 1; 173 174 repeated EnumValueDescriptorProto value = 2; 175 176 optional EnumOptions options = 3; 177} 178 179// Describes a value within an enum. 180message EnumValueDescriptorProto { 181 optional string name = 1; 182 optional int32 number = 2; 183 184 optional EnumValueOptions options = 3; 185} 186 187// Describes a service. 188message ServiceDescriptorProto { 189 optional string name = 1; 190 repeated MethodDescriptorProto method = 2; 191 192 optional ServiceOptions options = 3; 193} 194 195// Describes a method of a service. 196message MethodDescriptorProto { 197 optional string name = 1; 198 199 // Input and output type names. These are resolved in the same way as 200 // FieldDescriptorProto.type_name, but must refer to a message type. 201 optional string input_type = 2; 202 optional string output_type = 3; 203 204 optional MethodOptions options = 4; 205} 206 207 208// =================================================================== 209// Options 210 211// Each of the definitions above may have "options" attached. These are 212// just annotations which may cause code to be generated slightly differently 213// or may contain hints for code that manipulates protocol messages. 214// 215// Clients may define custom options as extensions of the *Options messages. 216// These extensions may not yet be known at parsing time, so the parser cannot 217// store the values in them. Instead it stores them in a field in the *Options 218// message called uninterpreted_option. This field must have the same name 219// across all *Options messages. We then use this field to populate the 220// extensions when we build a descriptor, at which point all protos have been 221// parsed and so all extensions are known. 222// 223// Extension numbers for custom options may be chosen as follows: 224// * For options which will only be used within a single application or 225// organization, or for experimental options, use field numbers 50000 226// through 99999. It is up to you to ensure that you do not use the 227// same number for multiple options. 228// * For options which will be published and used publicly by multiple 229// independent entities, e-mail protobuf-global-extension-registry@google.com 230// to reserve extension numbers. Simply provide your project name (e.g. 231// Object-C plugin) and your porject website (if available) -- there's no need 232// to explain how you intend to use them. Usually you only need one extension 233// number. You can declare multiple options with only one extension number by 234// putting them in a sub-message. See the Custom Options section of the docs 235// for examples: 236// http://code.google.com/apis/protocolbuffers/docs/proto.html#options 237// If this turns out to be popular, a web service will be set up 238// to automatically assign option numbers. 239 240 241message FileOptions { 242 243 // Sets the Java package where classes generated from this .proto will be 244 // placed. By default, the proto package is used, but this is often 245 // inappropriate because proto packages do not normally start with backwards 246 // domain names. 247 optional string java_package = 1; 248 249 250 // If set, all the classes from the .proto file are wrapped in a single 251 // outer class with the given name. This applies to both Proto1 252 // (equivalent to the old "--one_java_file" option) and Proto2 (where 253 // a .proto always translates to a single class, but you may want to 254 // explicitly choose the class name). 255 optional string java_outer_classname = 8; 256 257 // If set true, then the Java code generator will generate a separate .java 258 // file for each top-level message, enum, and service defined in the .proto 259 // file. Thus, these types will *not* be nested inside the outer class 260 // named by java_outer_classname. However, the outer class will still be 261 // generated to contain the file's getDescriptor() method as well as any 262 // top-level extensions defined in the file. 263 optional bool java_multiple_files = 10 [default=false]; 264 265 // If set true, then code generators will store unknown fields so that 266 // reserializing a message will retain them. This is the default behaviour 267 // unless LITE_RUNTIME is specified. Therefore, this option only makes sense 268 // when LITE_RUNTIME is in use. 269 optional bool retain_unknown_fields = 12 [default=false]; 270 271 // If set true, then the Java code generator will generate equals() and 272 // hashCode() methods for all messages defined in the .proto file. This is 273 // purely a speed optimization, as the AbstractMessage base class includes 274 // reflection-based implementations of these methods. 275 optional bool java_generate_equals_and_hash = 20 [default=false]; 276 277 // Generated classes can be optimized for speed or code size. 278 enum OptimizeMode { 279 SPEED = 1; // Generate complete code for parsing, serialization, 280 // etc. 281 CODE_SIZE = 2; // Use ReflectionOps to implement these methods. 282 LITE_RUNTIME = 3; // Generate code using MessageLite and the lite runtime. 283 } 284 optional OptimizeMode optimize_for = 9 [default=SPEED]; 285 286 // Sets the Go package where structs generated from this .proto will be 287 // placed. There is no default. 288 optional string go_package = 11; 289 290 291 292 // Should generic services be generated in each language? "Generic" services 293 // are not specific to any particular RPC system. They are generated by the 294 // main code generators in each language (without additional plugins). 295 // Generic services were the only kind of service generation supported by 296 // early versions of proto2. 297 // 298 // Generic services are now considered deprecated in favor of using plugins 299 // that generate code specific to your particular RPC system. Therefore, 300 // these default to false. Old code which depends on generic services should 301 // explicitly set them to true. 302 optional bool cc_generic_services = 16 [default=false]; 303 optional bool java_generic_services = 17 [default=false]; 304 optional bool py_generic_services = 18 [default=false]; 305 306 // The parser stores options it doesn't recognize here. See above. 307 repeated UninterpretedOption uninterpreted_option = 999; 308 309 // Clients can define custom options in extensions of this message. See above. 310 extensions 1000 to max; 311} 312 313message MessageOptions { 314 // Set true to use the old proto1 MessageSet wire format for extensions. 315 // This is provided for backwards-compatibility with the MessageSet wire 316 // format. You should not use this for any other reason: It's less 317 // efficient, has fewer features, and is more complicated. 318 // 319 // The message must be defined exactly as follows: 320 // message Foo { 321 // option message_set_wire_format = true; 322 // extensions 4 to max; 323 // } 324 // Note that the message cannot have any defined fields; MessageSets only 325 // have extensions. 326 // 327 // All extensions of your type must be singular messages; e.g. they cannot 328 // be int32s, enums, or repeated messages. 329 // 330 // Because this is an option, the above two restrictions are not enforced by 331 // the protocol compiler. 332 optional bool message_set_wire_format = 1 [default=false]; 333 334 // Disables the generation of the standard "descriptor()" accessor, which can 335 // conflict with a field of the same name. This is meant to make migration 336 // from proto1 easier; new code should avoid fields named "descriptor". 337 optional bool no_standard_descriptor_accessor = 2 [default=false]; 338 339 // The parser stores options it doesn't recognize here. See above. 340 repeated UninterpretedOption uninterpreted_option = 999; 341 342 // Clients can define custom options in extensions of this message. See above. 343 extensions 1000 to max; 344} 345 346message FieldOptions { 347 // The ctype option instructs the C++ code generator to use a different 348 // representation of the field than it normally would. See the specific 349 // options below. This option is not yet implemented in the open source 350 // release -- sorry, we'll try to include it in a future version! 351 optional CType ctype = 1 [default = STRING]; 352 enum CType { 353 // Default mode. 354 STRING = 0; 355 356 CORD = 1; 357 358 STRING_PIECE = 2; 359 } 360 // The packed option can be enabled for repeated primitive fields to enable 361 // a more efficient representation on the wire. Rather than repeatedly 362 // writing the tag and type for each element, the entire array is encoded as 363 // a single length-delimited blob. 364 optional bool packed = 2; 365 366 367 368 // Should this field be parsed lazily? Lazy applies only to message-type 369 // fields. It means that when the outer message is initially parsed, the 370 // inner message's contents will not be parsed but instead stored in encoded 371 // form. The inner message will actually be parsed when it is first accessed. 372 // 373 // This is only a hint. Implementations are free to choose whether to use 374 // eager or lazy parsing regardless of the value of this option. However, 375 // setting this option true suggests that the protocol author believes that 376 // using lazy parsing on this field is worth the additional bookkeeping 377 // overhead typically needed to implement it. 378 // 379 // This option does not affect the public interface of any generated code; 380 // all method signatures remain the same. Furthermore, thread-safety of the 381 // interface is not affected by this option; const methods remain safe to 382 // call from multiple threads concurrently, while non-const methods continue 383 // to require exclusive access. 384 // 385 // 386 // Note that implementations may choose not to check required fields within 387 // a lazy sub-message. That is, calling IsInitialized() on the outher message 388 // may return true even if the inner message has missing required fields. 389 // This is necessary because otherwise the inner message would have to be 390 // parsed in order to perform the check, defeating the purpose of lazy 391 // parsing. An implementation which chooses not to check required fields 392 // must be consistent about it. That is, for any particular sub-message, the 393 // implementation must either *always* check its required fields, or *never* 394 // check its required fields, regardless of whether or not the message has 395 // been parsed. 396 optional bool lazy = 5 [default=false]; 397 398 // Is this field deprecated? 399 // Depending on the target platform, this can emit Deprecated annotations 400 // for accessors, or it will be completely ignored; in the very least, this 401 // is a formalization for deprecating fields. 402 optional bool deprecated = 3 [default=false]; 403 404 // EXPERIMENTAL. DO NOT USE. 405 // For "map" fields, the name of the field in the enclosed type that 406 // is the key for this map. For example, suppose we have: 407 // message Item { 408 // required string name = 1; 409 // required string value = 2; 410 // } 411 // message Config { 412 // repeated Item items = 1 [experimental_map_key="name"]; 413 // } 414 // In this situation, the map key for Item will be set to "name". 415 // TODO: Fully-implement this, then remove the "experimental_" prefix. 416 optional string experimental_map_key = 9; 417 418 // For Google-internal migration only. Do not use. 419 optional bool weak = 10 [default=false]; 420 421 // The parser stores options it doesn't recognize here. See above. 422 repeated UninterpretedOption uninterpreted_option = 999; 423 424 // Clients can define custom options in extensions of this message. See above. 425 extensions 1000 to max; 426} 427 428message EnumOptions { 429 430 // Set this option to false to disallow mapping different tag names to a same 431 // value. 432 optional bool allow_alias = 2 [default=true]; 433 434 // The parser stores options it doesn't recognize here. See above. 435 repeated UninterpretedOption uninterpreted_option = 999; 436 437 // Clients can define custom options in extensions of this message. See above. 438 extensions 1000 to max; 439} 440 441message EnumValueOptions { 442 // The parser stores options it doesn't recognize here. See above. 443 repeated UninterpretedOption uninterpreted_option = 999; 444 445 // Clients can define custom options in extensions of this message. See above. 446 extensions 1000 to max; 447} 448 449message ServiceOptions { 450 451 // Note: Field numbers 1 through 32 are reserved for Google's internal RPC 452 // framework. We apologize for hoarding these numbers to ourselves, but 453 // we were already using them long before we decided to release Protocol 454 // Buffers. 455 456 // The parser stores options it doesn't recognize here. See above. 457 repeated UninterpretedOption uninterpreted_option = 999; 458 459 // Clients can define custom options in extensions of this message. See above. 460 extensions 1000 to max; 461} 462 463message MethodOptions { 464 465 // Note: Field numbers 1 through 32 are reserved for Google's internal RPC 466 // framework. We apologize for hoarding these numbers to ourselves, but 467 // we were already using them long before we decided to release Protocol 468 // Buffers. 469 470 // The parser stores options it doesn't recognize here. See above. 471 repeated UninterpretedOption uninterpreted_option = 999; 472 473 // Clients can define custom options in extensions of this message. See above. 474 extensions 1000 to max; 475} 476 477 478// A message representing a option the parser does not recognize. This only 479// appears in options protos created by the compiler::Parser class. 480// DescriptorPool resolves these when building Descriptor objects. Therefore, 481// options protos in descriptor objects (e.g. returned by Descriptor::options(), 482// or produced by Descriptor::CopyTo()) will never have UninterpretedOptions 483// in them. 484message UninterpretedOption { 485 // The name of the uninterpreted option. Each string represents a segment in 486 // a dot-separated name. is_extension is true iff a segment represents an 487 // extension (denoted with parentheses in options specs in .proto files). 488 // E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents 489 // "foo.(bar.baz).qux". 490 message NamePart { 491 required string name_part = 1; 492 required bool is_extension = 2; 493 } 494 repeated NamePart name = 2; 495 496 // The value of the uninterpreted option, in whatever type the tokenizer 497 // identified it as during parsing. Exactly one of these should be set. 498 optional string identifier_value = 3; 499 optional uint64 positive_int_value = 4; 500 optional int64 negative_int_value = 5; 501 optional double double_value = 6; 502 optional bytes string_value = 7; 503 optional string aggregate_value = 8; 504} 505 506// =================================================================== 507// Optional source code info 508 509// Encapsulates information about the original source file from which a 510// FileDescriptorProto was generated. 511message SourceCodeInfo { 512 // A Location identifies a piece of source code in a .proto file which 513 // corresponds to a particular definition. This information is intended 514 // to be useful to IDEs, code indexers, documentation generators, and similar 515 // tools. 516 // 517 // For example, say we have a file like: 518 // message Foo { 519 // optional string foo = 1; 520 // } 521 // Let's look at just the field definition: 522 // optional string foo = 1; 523 // ^ ^^ ^^ ^ ^^^ 524 // a bc de f ghi 525 // We have the following locations: 526 // span path represents 527 // [a,i) [ 4, 0, 2, 0 ] The whole field definition. 528 // [a,b) [ 4, 0, 2, 0, 4 ] The label (optional). 529 // [c,d) [ 4, 0, 2, 0, 5 ] The type (string). 530 // [e,f) [ 4, 0, 2, 0, 1 ] The name (foo). 531 // [g,h) [ 4, 0, 2, 0, 3 ] The number (1). 532 // 533 // Notes: 534 // - A location may refer to a repeated field itself (i.e. not to any 535 // particular index within it). This is used whenever a set of elements are 536 // logically enclosed in a single code segment. For example, an entire 537 // extend block (possibly containing multiple extension definitions) will 538 // have an outer location whose path refers to the "extensions" repeated 539 // field without an index. 540 // - Multiple locations may have the same path. This happens when a single 541 // logical declaration is spread out across multiple places. The most 542 // obvious example is the "extend" block again -- there may be multiple 543 // extend blocks in the same scope, each of which will have the same path. 544 // - A location's span is not always a subset of its parent's span. For 545 // example, the "extendee" of an extension declaration appears at the 546 // beginning of the "extend" block and is shared by all extensions within 547 // the block. 548 // - Just because a location's span is a subset of some other location's span 549 // does not mean that it is a descendent. For example, a "group" defines 550 // both a type and a field in a single declaration. Thus, the locations 551 // corresponding to the type and field and their components will overlap. 552 // - Code which tries to interpret locations should probably be designed to 553 // ignore those that it doesn't understand, as more types of locations could 554 // be recorded in the future. 555 repeated Location location = 1; 556 message Location { 557 // Identifies which part of the FileDescriptorProto was defined at this 558 // location. 559 // 560 // Each element is a field number or an index. They form a path from 561 // the root FileDescriptorProto to the place where the definition. For 562 // example, this path: 563 // [ 4, 3, 2, 7, 1 ] 564 // refers to: 565 // file.message_type(3) // 4, 3 566 // .field(7) // 2, 7 567 // .name() // 1 568 // This is because FileDescriptorProto.message_type has field number 4: 569 // repeated DescriptorProto message_type = 4; 570 // and DescriptorProto.field has field number 2: 571 // repeated FieldDescriptorProto field = 2; 572 // and FieldDescriptorProto.name has field number 1: 573 // optional string name = 1; 574 // 575 // Thus, the above path gives the location of a field name. If we removed 576 // the last element: 577 // [ 4, 3, 2, 7 ] 578 // this path refers to the whole field declaration (from the beginning 579 // of the label to the terminating semicolon). 580 repeated int32 path = 1 [packed=true]; 581 582 // Always has exactly three or four elements: start line, start column, 583 // end line (optional, otherwise assumed same as start line), end column. 584 // These are packed into a single field for efficiency. Note that line 585 // and column numbers are zero-based -- typically you will want to add 586 // 1 to each before displaying to a user. 587 repeated int32 span = 2 [packed=true]; 588 589 // If this SourceCodeInfo represents a complete declaration, these are any 590 // comments appearing before and after the declaration which appear to be 591 // attached to the declaration. 592 // 593 // A series of line comments appearing on consecutive lines, with no other 594 // tokens appearing on those lines, will be treated as a single comment. 595 // 596 // Only the comment content is provided; comment markers (e.g. //) are 597 // stripped out. For block comments, leading whitespace and an asterisk 598 // will be stripped from the beginning of each line other than the first. 599 // Newlines are included in the output. 600 // 601 // Examples: 602 // 603 // optional int32 foo = 1; // Comment attached to foo. 604 // // Comment attached to bar. 605 // optional int32 bar = 2; 606 // 607 // optional string baz = 3; 608 // // Comment attached to baz. 609 // // Another line attached to baz. 610 // 611 // // Comment attached to qux. 612 // // 613 // // Another line attached to qux. 614 // optional double qux = 4; 615 // 616 // optional string corge = 5; 617 // /* Block comment attached 618 // * to corge. Leading asterisks 619 // * will be removed. */ 620 // /* Block comment attached to 621 // * grault. */ 622 // optional int32 grault = 6; 623 optional string leading_comments = 3; 624 optional string trailing_comments = 4; 625 } 626} 627