1// Protocol Buffers - Google's data interchange format 2// Copyright 2008 Google Inc. All rights reserved. 3// https://developers.google.com/protocol-buffers/ 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 40syntax = "proto2"; 41 42package google.protobuf; 43option go_package = "descriptor"; 44option java_package = "com.google.protobuf"; 45option java_outer_classname = "DescriptorProtos"; 46option csharp_namespace = "Google.Protobuf.Reflection"; 47option objc_class_prefix = "GPB"; 48option cc_enable_arenas = true; 49 50// descriptor.proto must be optimized for speed because reflection-based 51// algorithms don't work during bootstrapping. 52option optimize_for = SPEED; 53 54// The protocol compiler can output a FileDescriptorSet containing the .proto 55// files it parses. 56message FileDescriptorSet { 57 repeated FileDescriptorProto file = 1; 58} 59 60// Describes a complete .proto file. 61message FileDescriptorProto { 62 optional string name = 1; // file name, relative to root of source tree 63 optional string package = 2; // e.g. "foo", "foo.bar", etc. 64 65 // Names of files imported by this file. 66 repeated string dependency = 3; 67 // Indexes of the public imported files in the dependency list above. 68 repeated int32 public_dependency = 10; 69 // Indexes of the weak imported files in the dependency list. 70 // For Google-internal migration only. Do not use. 71 repeated int32 weak_dependency = 11; 72 73 // All top-level definitions in this file. 74 repeated DescriptorProto message_type = 4; 75 repeated EnumDescriptorProto enum_type = 5; 76 repeated ServiceDescriptorProto service = 6; 77 repeated FieldDescriptorProto extension = 7; 78 79 optional FileOptions options = 8; 80 81 // This field contains optional information about the original source code. 82 // You may safely remove this entire field without harming runtime 83 // functionality of the descriptors -- the information is needed only by 84 // development tools. 85 optional SourceCodeInfo source_code_info = 9; 86 87 // The syntax of the proto file. 88 // The supported values are "proto2" and "proto3". 89 optional string syntax = 12; 90} 91 92// Describes a message type. 93message DescriptorProto { 94 optional string name = 1; 95 96 repeated FieldDescriptorProto field = 2; 97 repeated FieldDescriptorProto extension = 6; 98 99 repeated DescriptorProto nested_type = 3; 100 repeated EnumDescriptorProto enum_type = 4; 101 102 message ExtensionRange { 103 optional int32 start = 1; 104 optional int32 end = 2; 105 106 optional ExtensionRangeOptions options = 3; 107 } 108 repeated ExtensionRange extension_range = 5; 109 110 repeated OneofDescriptorProto oneof_decl = 8; 111 112 optional MessageOptions options = 7; 113 114 // Range of reserved tag numbers. Reserved tag numbers may not be used by 115 // fields or extension ranges in the same message. Reserved ranges may 116 // not overlap. 117 message ReservedRange { 118 optional int32 start = 1; // Inclusive. 119 optional int32 end = 2; // Exclusive. 120 } 121 repeated ReservedRange reserved_range = 9; 122 // Reserved field names, which may not be used by fields in the same message. 123 // A given name may only be reserved once. 124 repeated string reserved_name = 10; 125} 126 127message ExtensionRangeOptions { 128 // The parser stores options it doesn't recognize here. See above. 129 repeated UninterpretedOption uninterpreted_option = 999; 130 131 // Clients can define custom options in extensions of this message. See above. 132 extensions 1000 to max; 133} 134 135// Describes a field within a message. 136message FieldDescriptorProto { 137 enum Type { 138 // 0 is reserved for errors. 139 // Order is weird for historical reasons. 140 TYPE_DOUBLE = 1; 141 TYPE_FLOAT = 2; 142 // Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT64 if 143 // negative values are likely. 144 TYPE_INT64 = 3; 145 TYPE_UINT64 = 4; 146 // Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT32 if 147 // negative values are likely. 148 TYPE_INT32 = 5; 149 TYPE_FIXED64 = 6; 150 TYPE_FIXED32 = 7; 151 TYPE_BOOL = 8; 152 TYPE_STRING = 9; 153 // Tag-delimited aggregate. 154 // Group type is deprecated and not supported in proto3. However, Proto3 155 // implementations should still be able to parse the group wire format and 156 // treat group fields as unknown fields. 157 TYPE_GROUP = 10; 158 TYPE_MESSAGE = 11; // Length-delimited aggregate. 159 160 // New in version 2. 161 TYPE_BYTES = 12; 162 TYPE_UINT32 = 13; 163 TYPE_ENUM = 14; 164 TYPE_SFIXED32 = 15; 165 TYPE_SFIXED64 = 16; 166 TYPE_SINT32 = 17; // Uses ZigZag encoding. 167 TYPE_SINT64 = 18; // Uses ZigZag encoding. 168 }; 169 170 enum Label { 171 // 0 is reserved for errors 172 LABEL_OPTIONAL = 1; 173 LABEL_REQUIRED = 2; 174 LABEL_REPEATED = 3; 175 }; 176 177 optional string name = 1; 178 optional int32 number = 3; 179 optional Label label = 4; 180 181 // If type_name is set, this need not be set. If both this and type_name 182 // are set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP. 183 optional Type type = 5; 184 185 // For message and enum types, this is the name of the type. If the name 186 // starts with a '.', it is fully-qualified. Otherwise, C++-like scoping 187 // rules are used to find the type (i.e. first the nested types within this 188 // message are searched, then within the parent, on up to the root 189 // namespace). 190 optional string type_name = 6; 191 192 // For extensions, this is the name of the type being extended. It is 193 // resolved in the same manner as type_name. 194 optional string extendee = 2; 195 196 // For numeric types, contains the original text representation of the value. 197 // For booleans, "true" or "false". 198 // For strings, contains the default text contents (not escaped in any way). 199 // For bytes, contains the C escaped value. All bytes >= 128 are escaped. 200 // TODO(kenton): Base-64 encode? 201 optional string default_value = 7; 202 203 // If set, gives the index of a oneof in the containing type's oneof_decl 204 // list. This field is a member of that oneof. 205 optional int32 oneof_index = 9; 206 207 // JSON name of this field. The value is set by protocol compiler. If the 208 // user has set a "json_name" option on this field, that option's value 209 // will be used. Otherwise, it's deduced from the field's name by converting 210 // it to camelCase. 211 optional string json_name = 10; 212 213 optional FieldOptions options = 8; 214} 215 216// Describes a oneof. 217message OneofDescriptorProto { 218 optional string name = 1; 219 optional OneofOptions options = 2; 220} 221 222// Describes an enum type. 223message EnumDescriptorProto { 224 optional string name = 1; 225 226 repeated EnumValueDescriptorProto value = 2; 227 228 optional EnumOptions options = 3; 229 230 // Range of reserved numeric values. Reserved values may not be used by 231 // entries in the same enum. Reserved ranges may not overlap. 232 // 233 // Note that this is distinct from DescriptorProto.ReservedRange in that it 234 // is inclusive such that it can appropriately represent the entire int32 235 // domain. 236 message EnumReservedRange { 237 optional int32 start = 1; // Inclusive. 238 optional int32 end = 2; // Inclusive. 239 } 240 241 // Range of reserved numeric values. Reserved numeric values may not be used 242 // by enum values in the same enum declaration. Reserved ranges may not 243 // overlap. 244 repeated EnumReservedRange reserved_range = 4; 245 246 // Reserved enum value names, which may not be reused. A given name may only 247 // be reserved once. 248 repeated string reserved_name = 5; 249} 250 251// Describes a value within an enum. 252message EnumValueDescriptorProto { 253 optional string name = 1; 254 optional int32 number = 2; 255 256 optional EnumValueOptions options = 3; 257} 258 259// Describes a service. 260message ServiceDescriptorProto { 261 optional string name = 1; 262 repeated MethodDescriptorProto method = 2; 263 264 optional ServiceOptions options = 3; 265} 266 267// Describes a method of a service. 268message MethodDescriptorProto { 269 optional string name = 1; 270 271 // Input and output type names. These are resolved in the same way as 272 // FieldDescriptorProto.type_name, but must refer to a message type. 273 optional string input_type = 2; 274 optional string output_type = 3; 275 276 optional MethodOptions options = 4; 277 278 // Identifies if client streams multiple client messages 279 optional bool client_streaming = 5 [default=false]; 280 // Identifies if server streams multiple server messages 281 optional bool server_streaming = 6 [default=false]; 282} 283 284 285// =================================================================== 286// Options 287 288// Each of the definitions above may have "options" attached. These are 289// just annotations which may cause code to be generated slightly differently 290// or may contain hints for code that manipulates protocol messages. 291// 292// Clients may define custom options as extensions of the *Options messages. 293// These extensions may not yet be known at parsing time, so the parser cannot 294// store the values in them. Instead it stores them in a field in the *Options 295// message called uninterpreted_option. This field must have the same name 296// across all *Options messages. We then use this field to populate the 297// extensions when we build a descriptor, at which point all protos have been 298// parsed and so all extensions are known. 299// 300// Extension numbers for custom options may be chosen as follows: 301// * For options which will only be used within a single application or 302// organization, or for experimental options, use field numbers 50000 303// through 99999. It is up to you to ensure that you do not use the 304// same number for multiple options. 305// * For options which will be published and used publicly by multiple 306// independent entities, e-mail protobuf-global-extension-registry@google.com 307// to reserve extension numbers. Simply provide your project name (e.g. 308// Objective-C plugin) and your project website (if available) -- there's no 309// need to explain how you intend to use them. Usually you only need one 310// extension number. You can declare multiple options with only one extension 311// number by putting them in a sub-message. See the Custom Options section of 312// the docs for examples: 313// https://developers.google.com/protocol-buffers/docs/proto#options 314// If this turns out to be popular, a web service will be set up 315// to automatically assign option numbers. 316 317 318message FileOptions { 319 320 // Sets the Java package where classes generated from this .proto will be 321 // placed. By default, the proto package is used, but this is often 322 // inappropriate because proto packages do not normally start with backwards 323 // domain names. 324 optional string java_package = 1; 325 326 327 // If set, all the classes from the .proto file are wrapped in a single 328 // outer class with the given name. This applies to both Proto1 329 // (equivalent to the old "--one_java_file" option) and Proto2 (where 330 // a .proto always translates to a single class, but you may want to 331 // explicitly choose the class name). 332 optional string java_outer_classname = 8; 333 334 // If set true, then the Java code generator will generate a separate .java 335 // file for each top-level message, enum, and service defined in the .proto 336 // file. Thus, these types will *not* be nested inside the outer class 337 // named by java_outer_classname. However, the outer class will still be 338 // generated to contain the file's getDescriptor() method as well as any 339 // top-level extensions defined in the file. 340 optional bool java_multiple_files = 10 [default=false]; 341 342 // This option does nothing. 343 optional bool java_generate_equals_and_hash = 20 [deprecated=true]; 344 345 // If set true, then the Java2 code generator will generate code that 346 // throws an exception whenever an attempt is made to assign a non-UTF-8 347 // byte sequence to a string field. 348 // Message reflection will do the same. 349 // However, an extension field still accepts non-UTF-8 byte sequences. 350 // This option has no effect on when used with the lite runtime. 351 optional bool java_string_check_utf8 = 27 [default=false]; 352 353 354 // Generated classes can be optimized for speed or code size. 355 enum OptimizeMode { 356 SPEED = 1; // Generate complete code for parsing, serialization, 357 // etc. 358 CODE_SIZE = 2; // Use ReflectionOps to implement these methods. 359 LITE_RUNTIME = 3; // Generate code using MessageLite and the lite runtime. 360 } 361 optional OptimizeMode optimize_for = 9 [default=SPEED]; 362 363 // Sets the Go package where structs generated from this .proto will be 364 // placed. If omitted, the Go package will be derived from the following: 365 // - The basename of the package import path, if provided. 366 // - Otherwise, the package statement in the .proto file, if present. 367 // - Otherwise, the basename of the .proto file, without extension. 368 optional string go_package = 11; 369 370 371 372 // Should generic services be generated in each language? "Generic" services 373 // are not specific to any particular RPC system. They are generated by the 374 // main code generators in each language (without additional plugins). 375 // Generic services were the only kind of service generation supported by 376 // early versions of google.protobuf. 377 // 378 // Generic services are now considered deprecated in favor of using plugins 379 // that generate code specific to your particular RPC system. Therefore, 380 // these default to false. Old code which depends on generic services should 381 // explicitly set them to true. 382 optional bool cc_generic_services = 16 [default=false]; 383 optional bool java_generic_services = 17 [default=false]; 384 optional bool py_generic_services = 18 [default=false]; 385 optional bool php_generic_services = 42 [default=false]; 386 387 // Is this file deprecated? 388 // Depending on the target platform, this can emit Deprecated annotations 389 // for everything in the file, or it will be completely ignored; in the very 390 // least, this is a formalization for deprecating files. 391 optional bool deprecated = 23 [default=false]; 392 393 // Enables the use of arenas for the proto messages in this file. This applies 394 // only to generated classes for C++. 395 optional bool cc_enable_arenas = 31 [default=false]; 396 397 398 // Sets the objective c class prefix which is prepended to all objective c 399 // generated classes from this .proto. There is no default. 400 optional string objc_class_prefix = 36; 401 402 // Namespace for generated classes; defaults to the package. 403 optional string csharp_namespace = 37; 404 405 // By default Swift generators will take the proto package and CamelCase it 406 // replacing '.' with underscore and use that to prefix the types/symbols 407 // defined. When this options is provided, they will use this value instead 408 // to prefix the types/symbols defined. 409 optional string swift_prefix = 39; 410 411 // Sets the php class prefix which is prepended to all php generated classes 412 // from this .proto. Default is empty. 413 optional string php_class_prefix = 40; 414 415 // Use this option to change the namespace of php generated classes. Default 416 // is empty. When this option is empty, the package name will be used for 417 // determining the namespace. 418 optional string php_namespace = 41; 419 420 421 // Use this option to change the namespace of php generated metadata classes. 422 // Default is empty. When this option is empty, the proto file name will be used 423 // for determining the namespace. 424 optional string php_metadata_namespace = 44; 425 426 // Use this option to change the package of ruby generated classes. Default 427 // is empty. When this option is not set, the package name will be used for 428 // determining the ruby package. 429 optional string ruby_package = 45; 430 431 // The parser stores options it doesn't recognize here. 432 // See the documentation for the "Options" section above. 433 repeated UninterpretedOption uninterpreted_option = 999; 434 435 // Clients can define custom options in extensions of this message. 436 // See the documentation for the "Options" section above. 437 extensions 1000 to max; 438 439 //reserved 38; 440} 441 442message MessageOptions { 443 // Set true to use the old proto1 MessageSet wire format for extensions. 444 // This is provided for backwards-compatibility with the MessageSet wire 445 // format. You should not use this for any other reason: It's less 446 // efficient, has fewer features, and is more complicated. 447 // 448 // The message must be defined exactly as follows: 449 // message Foo { 450 // option message_set_wire_format = true; 451 // extensions 4 to max; 452 // } 453 // Note that the message cannot have any defined fields; MessageSets only 454 // have extensions. 455 // 456 // All extensions of your type must be singular messages; e.g. they cannot 457 // be int32s, enums, or repeated messages. 458 // 459 // Because this is an option, the above two restrictions are not enforced by 460 // the protocol compiler. 461 optional bool message_set_wire_format = 1 [default=false]; 462 463 // Disables the generation of the standard "descriptor()" accessor, which can 464 // conflict with a field of the same name. This is meant to make migration 465 // from proto1 easier; new code should avoid fields named "descriptor". 466 optional bool no_standard_descriptor_accessor = 2 [default=false]; 467 468 // Is this message deprecated? 469 // Depending on the target platform, this can emit Deprecated annotations 470 // for the message, or it will be completely ignored; in the very least, 471 // this is a formalization for deprecating messages. 472 optional bool deprecated = 3 [default=false]; 473 474 // Whether the message is an automatically generated map entry type for the 475 // maps field. 476 // 477 // For maps fields: 478 // map<KeyType, ValueType> map_field = 1; 479 // The parsed descriptor looks like: 480 // message MapFieldEntry { 481 // option map_entry = true; 482 // optional KeyType key = 1; 483 // optional ValueType value = 2; 484 // } 485 // repeated MapFieldEntry map_field = 1; 486 // 487 // Implementations may choose not to generate the map_entry=true message, but 488 // use a native map in the target language to hold the keys and values. 489 // The reflection APIs in such implementions still need to work as 490 // if the field is a repeated message field. 491 // 492 // NOTE: Do not set the option in .proto files. Always use the maps syntax 493 // instead. The option should only be implicitly set by the proto compiler 494 // parser. 495 optional bool map_entry = 7; 496 497 //reserved 8; // javalite_serializable 498 //reserved 9; // javanano_as_lite 499 500 // The parser stores options it doesn't recognize here. See above. 501 repeated UninterpretedOption uninterpreted_option = 999; 502 503 // Clients can define custom options in extensions of this message. See above. 504 extensions 1000 to max; 505} 506 507message FieldOptions { 508 // The ctype option instructs the C++ code generator to use a different 509 // representation of the field than it normally would. See the specific 510 // options below. This option is not yet implemented in the open source 511 // release -- sorry, we'll try to include it in a future version! 512 optional CType ctype = 1 [default = STRING]; 513 enum CType { 514 // Default mode. 515 STRING = 0; 516 517 CORD = 1; 518 519 STRING_PIECE = 2; 520 } 521 // The packed option can be enabled for repeated primitive fields to enable 522 // a more efficient representation on the wire. Rather than repeatedly 523 // writing the tag and type for each element, the entire array is encoded as 524 // a single length-delimited blob. In proto3, only explicit setting it to 525 // false will avoid using packed encoding. 526 optional bool packed = 2; 527 528 // The jstype option determines the JavaScript type used for values of the 529 // field. The option is permitted only for 64 bit integral and fixed types 530 // (int64, uint64, sint64, fixed64, sfixed64). A field with jstype JS_STRING 531 // is represented as JavaScript string, which avoids loss of precision that 532 // can happen when a large value is converted to a floating point JavaScript. 533 // Specifying JS_NUMBER for the jstype causes the generated JavaScript code to 534 // use the JavaScript "number" type. The behavior of the default option 535 // JS_NORMAL is implementation dependent. 536 // 537 // This option is an enum to permit additional types to be added, e.g. 538 // goog.math.Integer. 539 optional JSType jstype = 6 [default = JS_NORMAL]; 540 enum JSType { 541 // Use the default type. 542 JS_NORMAL = 0; 543 544 // Use JavaScript strings. 545 JS_STRING = 1; 546 547 // Use JavaScript numbers. 548 JS_NUMBER = 2; 549 } 550 551 // Should this field be parsed lazily? Lazy applies only to message-type 552 // fields. It means that when the outer message is initially parsed, the 553 // inner message's contents will not be parsed but instead stored in encoded 554 // form. The inner message will actually be parsed when it is first accessed. 555 // 556 // This is only a hint. Implementations are free to choose whether to use 557 // eager or lazy parsing regardless of the value of this option. However, 558 // setting this option true suggests that the protocol author believes that 559 // using lazy parsing on this field is worth the additional bookkeeping 560 // overhead typically needed to implement it. 561 // 562 // This option does not affect the public interface of any generated code; 563 // all method signatures remain the same. Furthermore, thread-safety of the 564 // interface is not affected by this option; const methods remain safe to 565 // call from multiple threads concurrently, while non-const methods continue 566 // to require exclusive access. 567 // 568 // 569 // Note that implementations may choose not to check required fields within 570 // a lazy sub-message. That is, calling IsInitialized() on the outer message 571 // may return true even if the inner message has missing required fields. 572 // This is necessary because otherwise the inner message would have to be 573 // parsed in order to perform the check, defeating the purpose of lazy 574 // parsing. An implementation which chooses not to check required fields 575 // must be consistent about it. That is, for any particular sub-message, the 576 // implementation must either *always* check its required fields, or *never* 577 // check its required fields, regardless of whether or not the message has 578 // been parsed. 579 optional bool lazy = 5 [default=false]; 580 581 // Is this field deprecated? 582 // Depending on the target platform, this can emit Deprecated annotations 583 // for accessors, or it will be completely ignored; in the very least, this 584 // is a formalization for deprecating fields. 585 optional bool deprecated = 3 [default=false]; 586 587 // For Google-internal migration only. Do not use. 588 optional bool weak = 10 [default=false]; 589 590 591 // The parser stores options it doesn't recognize here. See above. 592 repeated UninterpretedOption uninterpreted_option = 999; 593 594 // Clients can define custom options in extensions of this message. See above. 595 extensions 1000 to max; 596 597 //reserved 4; // removed jtype 598} 599 600message OneofOptions { 601 // The parser stores options it doesn't recognize here. See above. 602 repeated UninterpretedOption uninterpreted_option = 999; 603 604 // Clients can define custom options in extensions of this message. See above. 605 extensions 1000 to max; 606} 607 608message EnumOptions { 609 610 // Set this option to true to allow mapping different tag names to the same 611 // value. 612 optional bool allow_alias = 2; 613 614 // Is this enum deprecated? 615 // Depending on the target platform, this can emit Deprecated annotations 616 // for the enum, or it will be completely ignored; in the very least, this 617 // is a formalization for deprecating enums. 618 optional bool deprecated = 3 [default=false]; 619 620 //reserved 5; // javanano_as_lite 621 622 // The parser stores options it doesn't recognize here. See above. 623 repeated UninterpretedOption uninterpreted_option = 999; 624 625 // Clients can define custom options in extensions of this message. See above. 626 extensions 1000 to max; 627} 628 629message EnumValueOptions { 630 // Is this enum value deprecated? 631 // Depending on the target platform, this can emit Deprecated annotations 632 // for the enum value, or it will be completely ignored; in the very least, 633 // this is a formalization for deprecating enum values. 634 optional bool deprecated = 1 [default=false]; 635 636 // The parser stores options it doesn't recognize here. See above. 637 repeated UninterpretedOption uninterpreted_option = 999; 638 639 // Clients can define custom options in extensions of this message. See above. 640 extensions 1000 to max; 641} 642 643message ServiceOptions { 644 645 // Note: Field numbers 1 through 32 are reserved for Google's internal RPC 646 // framework. We apologize for hoarding these numbers to ourselves, but 647 // we were already using them long before we decided to release Protocol 648 // Buffers. 649 650 // Is this service deprecated? 651 // Depending on the target platform, this can emit Deprecated annotations 652 // for the service, or it will be completely ignored; in the very least, 653 // this is a formalization for deprecating services. 654 optional bool deprecated = 33 [default=false]; 655 656 // The parser stores options it doesn't recognize here. See above. 657 repeated UninterpretedOption uninterpreted_option = 999; 658 659 // Clients can define custom options in extensions of this message. See above. 660 extensions 1000 to max; 661} 662 663message MethodOptions { 664 665 // Note: Field numbers 1 through 32 are reserved for Google's internal RPC 666 // framework. We apologize for hoarding these numbers to ourselves, but 667 // we were already using them long before we decided to release Protocol 668 // Buffers. 669 670 // Is this method deprecated? 671 // Depending on the target platform, this can emit Deprecated annotations 672 // for the method, or it will be completely ignored; in the very least, 673 // this is a formalization for deprecating methods. 674 optional bool deprecated = 33 [default=false]; 675 676 // Is this method side-effect-free (or safe in HTTP parlance), or idempotent, 677 // or neither? HTTP based RPC implementation may choose GET verb for safe 678 // methods, and PUT verb for idempotent methods instead of the default POST. 679 enum IdempotencyLevel { 680 IDEMPOTENCY_UNKNOWN = 0; 681 NO_SIDE_EFFECTS = 1; // implies idempotent 682 IDEMPOTENT = 2; // idempotent, but may have side effects 683 } 684 optional IdempotencyLevel idempotency_level = 685 34 [default=IDEMPOTENCY_UNKNOWN]; 686 687 // The parser stores options it doesn't recognize here. See above. 688 repeated UninterpretedOption uninterpreted_option = 999; 689 690 // Clients can define custom options in extensions of this message. See above. 691 extensions 1000 to max; 692} 693 694 695// A message representing a option the parser does not recognize. This only 696// appears in options protos created by the compiler::Parser class. 697// DescriptorPool resolves these when building Descriptor objects. Therefore, 698// options protos in descriptor objects (e.g. returned by Descriptor::options(), 699// or produced by Descriptor::CopyTo()) will never have UninterpretedOptions 700// in them. 701message UninterpretedOption { 702 // The name of the uninterpreted option. Each string represents a segment in 703 // a dot-separated name. is_extension is true iff a segment represents an 704 // extension (denoted with parentheses in options specs in .proto files). 705 // E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents 706 // "foo.(bar.baz).qux". 707 message NamePart { 708 required string name_part = 1; 709 required bool is_extension = 2; 710 } 711 repeated NamePart name = 2; 712 713 // The value of the uninterpreted option, in whatever type the tokenizer 714 // identified it as during parsing. Exactly one of these should be set. 715 optional string identifier_value = 3; 716 optional uint64 positive_int_value = 4; 717 optional int64 negative_int_value = 5; 718 optional double double_value = 6; 719 optional bytes string_value = 7; 720 optional string aggregate_value = 8; 721} 722 723// =================================================================== 724// Optional source code info 725 726// Encapsulates information about the original source file from which a 727// FileDescriptorProto was generated. 728message SourceCodeInfo { 729 // A Location identifies a piece of source code in a .proto file which 730 // corresponds to a particular definition. This information is intended 731 // to be useful to IDEs, code indexers, documentation generators, and similar 732 // tools. 733 // 734 // For example, say we have a file like: 735 // message Foo { 736 // optional string foo = 1; 737 // } 738 // Let's look at just the field definition: 739 // optional string foo = 1; 740 // ^ ^^ ^^ ^ ^^^ 741 // a bc de f ghi 742 // We have the following locations: 743 // span path represents 744 // [a,i) [ 4, 0, 2, 0 ] The whole field definition. 745 // [a,b) [ 4, 0, 2, 0, 4 ] The label (optional). 746 // [c,d) [ 4, 0, 2, 0, 5 ] The type (string). 747 // [e,f) [ 4, 0, 2, 0, 1 ] The name (foo). 748 // [g,h) [ 4, 0, 2, 0, 3 ] The number (1). 749 // 750 // Notes: 751 // - A location may refer to a repeated field itself (i.e. not to any 752 // particular index within it). This is used whenever a set of elements are 753 // logically enclosed in a single code segment. For example, an entire 754 // extend block (possibly containing multiple extension definitions) will 755 // have an outer location whose path refers to the "extensions" repeated 756 // field without an index. 757 // - Multiple locations may have the same path. This happens when a single 758 // logical declaration is spread out across multiple places. The most 759 // obvious example is the "extend" block again -- there may be multiple 760 // extend blocks in the same scope, each of which will have the same path. 761 // - A location's span is not always a subset of its parent's span. For 762 // example, the "extendee" of an extension declaration appears at the 763 // beginning of the "extend" block and is shared by all extensions within 764 // the block. 765 // - Just because a location's span is a subset of some other location's span 766 // does not mean that it is a descendent. For example, a "group" defines 767 // both a type and a field in a single declaration. Thus, the locations 768 // corresponding to the type and field and their components will overlap. 769 // - Code which tries to interpret locations should probably be designed to 770 // ignore those that it doesn't understand, as more types of locations could 771 // be recorded in the future. 772 repeated Location location = 1; 773 message Location { 774 // Identifies which part of the FileDescriptorProto was defined at this 775 // location. 776 // 777 // Each element is a field number or an index. They form a path from 778 // the root FileDescriptorProto to the place where the definition. For 779 // example, this path: 780 // [ 4, 3, 2, 7, 1 ] 781 // refers to: 782 // file.message_type(3) // 4, 3 783 // .field(7) // 2, 7 784 // .name() // 1 785 // This is because FileDescriptorProto.message_type has field number 4: 786 // repeated DescriptorProto message_type = 4; 787 // and DescriptorProto.field has field number 2: 788 // repeated FieldDescriptorProto field = 2; 789 // and FieldDescriptorProto.name has field number 1: 790 // optional string name = 1; 791 // 792 // Thus, the above path gives the location of a field name. If we removed 793 // the last element: 794 // [ 4, 3, 2, 7 ] 795 // this path refers to the whole field declaration (from the beginning 796 // of the label to the terminating semicolon). 797 repeated int32 path = 1 [packed=true]; 798 799 // Always has exactly three or four elements: start line, start column, 800 // end line (optional, otherwise assumed same as start line), end column. 801 // These are packed into a single field for efficiency. Note that line 802 // and column numbers are zero-based -- typically you will want to add 803 // 1 to each before displaying to a user. 804 repeated int32 span = 2 [packed=true]; 805 806 // If this SourceCodeInfo represents a complete declaration, these are any 807 // comments appearing before and after the declaration which appear to be 808 // attached to the declaration. 809 // 810 // A series of line comments appearing on consecutive lines, with no other 811 // tokens appearing on those lines, will be treated as a single comment. 812 // 813 // leading_detached_comments will keep paragraphs of comments that appear 814 // before (but not connected to) the current element. Each paragraph, 815 // separated by empty lines, will be one comment element in the repeated 816 // field. 817 // 818 // Only the comment content is provided; comment markers (e.g. //) are 819 // stripped out. For block comments, leading whitespace and an asterisk 820 // will be stripped from the beginning of each line other than the first. 821 // Newlines are included in the output. 822 // 823 // Examples: 824 // 825 // optional int32 foo = 1; // Comment attached to foo. 826 // // Comment attached to bar. 827 // optional int32 bar = 2; 828 // 829 // optional string baz = 3; 830 // // Comment attached to baz. 831 // // Another line attached to baz. 832 // 833 // // Comment attached to qux. 834 // // 835 // // Another line attached to qux. 836 // optional double qux = 4; 837 // 838 // // Detached comment for corge. This is not leading or trailing comments 839 // // to qux or corge because there are blank lines separating it from 840 // // both. 841 // 842 // // Detached comment for corge paragraph 2. 843 // 844 // optional string corge = 5; 845 // /* Block comment attached 846 // * to corge. Leading asterisks 847 // * will be removed. */ 848 // /* Block comment attached to 849 // * grault. */ 850 // optional int32 grault = 6; 851 // 852 // // ignored detached comments. 853 optional string leading_comments = 3; 854 optional string trailing_comments = 4; 855 repeated string leading_detached_comments = 6; 856 } 857} 858 859// Describes the relationship between generated code and its original source 860// file. A GeneratedCodeInfo message is associated with only one generated 861// source file, but may contain references to different source .proto files. 862message GeneratedCodeInfo { 863 // An Annotation connects some span of text in generated code to an element 864 // of its generating .proto file. 865 repeated Annotation annotation = 1; 866 message Annotation { 867 // Identifies the element in the original source .proto file. This field 868 // is formatted the same as SourceCodeInfo.Location.path. 869 repeated int32 path = 1 [packed=true]; 870 871 // Identifies the filesystem path to the original source .proto. 872 optional string source_file = 2; 873 874 // Identifies the starting offset in bytes in the generated code 875 // that relates to the identified object. 876 optional int32 begin = 3; 877 878 // Identifies the ending offset in bytes in the generated code that 879 // relates to the identified offset. The end offset should be one past 880 // the last relevant byte (so the length of the text = end - begin). 881 optional int32 end = 4; 882 } 883} 884