descriptor.proto in grpc-tools-1.60.0.pre1

- old
+ new

@@ -55,10 +55,36 @@
 // files it parses.
 message FileDescriptorSet {
   repeated FileDescriptorProto file = 1;
 }
 
+// The full set of known editions.
+enum Edition {
+  // A placeholder for an unknown edition value.
+  EDITION_UNKNOWN = 0;
+
+  // Legacy syntax "editions".  These pre-date editions, but behave much like
+  // distinct editions.  These can't be used to specify the edition of proto
+  // files, but feature definitions must supply proto2/proto3 defaults for
+  // backwards compatibility.
+  EDITION_PROTO2 = 998;
+  EDITION_PROTO3 = 999;
+
+  // Editions that have been released.  The specific values are arbitrary and
+  // should not be depended on, but they will always be time-ordered for easy
+  // comparison.
+  EDITION_2023 = 1000;
+
+  // Placeholder editions for testing feature resolution.  These should not be
+  // used or relyed on outside of tests.
+  EDITION_1_TEST_ONLY = 1;
+  EDITION_2_TEST_ONLY = 2;
+  EDITION_99997_TEST_ONLY = 99997;
+  EDITION_99998_TEST_ONLY = 99998;
+  EDITION_99999_TEST_ONLY = 99999;
+}
+
 // Describes a complete .proto file.
 message FileDescriptorProto {
   optional string name = 1;     // file name, relative to root of source tree
   optional string package = 2;  // e.g. "foo", "foo.bar", etc.
 
@@ -88,12 +114,12 @@
   // The supported values are "proto2", "proto3", and "editions".
   //
   // If `edition` is present, this value must be "editions".
   optional string syntax = 12;
 
-  // The edition of the proto file, which is an opaque string.
-  optional string edition = 13;
+  // The edition of the proto file.
+  optional Edition edition = 14;
 }
 
 // Describes a message type.
 message DescriptorProto {
   optional string name = 1;
@@ -172,11 +198,11 @@
     DECLARATION = 0;
     UNVERIFIED = 1;
   }
 
   // The verification state of the range.
-  // TODO(b/278783756): flip the default to DECLARATION once all empty ranges
+  // TODO: flip the default to DECLARATION once all empty ranges
   // are marked as UNVERIFIED.
   optional VerificationState verification = 3 [default = UNVERIFIED];
 
   // Clients can define custom options in extensions of this message. See above.
   extensions 1000 to max;
@@ -199,13 +225,14 @@
     TYPE_FIXED64 = 6;
     TYPE_FIXED32 = 7;
     TYPE_BOOL = 8;
     TYPE_STRING = 9;
     // Tag-delimited aggregate.
-    // Group type is deprecated and not supported in proto3. However, Proto3
+    // Group type is deprecated and not supported after google.protobuf. However, Proto3
     // implementations should still be able to parse the group wire format and
-    // treat group fields as unknown fields.
+    // treat group fields as unknown fields.  In Editions, the group wire format
+    // can be enabled via the `message_encoding` feature.
     TYPE_GROUP = 10;
     TYPE_MESSAGE = 11;  // Length-delimited aggregate.
 
     // New in version 2.
     TYPE_BYTES = 12;
@@ -218,12 +245,15 @@
   }
 
   enum Label {
     // 0 is reserved for errors
     LABEL_OPTIONAL = 1;
-    LABEL_REQUIRED = 2;
     LABEL_REPEATED = 3;
+    // The required label is only allowed in google.protobuf.  In proto3 and Editions
+    // it's explicitly prohibited.  In Editions, the `field_presence` feature
+    // can be used to get this behavior.
+    LABEL_REQUIRED = 2;
   }
 
   optional string name = 1;
   optional int32 number = 3;
   optional Label label = 4;
@@ -572,11 +602,11 @@
   // well.
   //
   // This should only be used as a temporary measure against broken builds due
   // to the change in behavior for JSON field name conflicts.
   //
-  // TODO(b/261750190) This is legacy behavior we plan to remove once downstream
+  // TODO This is legacy behavior we plan to remove once downstream
   // teams have had time to migrate.
   optional bool deprecated_legacy_json_field_conflicts = 11 [deprecated = true];
 
   // Any features defined in the specific edition.
   optional FeatureSet features = 12;
@@ -612,11 +642,13 @@
   }
   // The packed option can be enabled for repeated primitive fields to enable
   // a more efficient representation on the wire. Rather than repeatedly
   // writing the tag and type for each element, the entire array is encoded as
   // a single length-delimited blob. In proto3, only explicit setting it to
-  // false will avoid using packed encoding.
+  // false will avoid using packed encoding.  This option is prohibited in
+  // Editions, but the `repeated_field_encoding` feature can be used to control
+  // the behavior.
   optional bool packed = 2;
 
   // The jstype option determines the JavaScript type used for values of the
   // field.  The option is permitted only for 64 bit integral and fixed types
   // (int64, uint64, sint64, fixed64, sfixed64).  A field with jstype JS_STRING
@@ -719,11 +751,11 @@
   }
 
   repeated OptionTargetType targets = 19;
 
   message EditionDefault {
-    optional string edition = 1;
+    optional Edition edition = 3;
     optional string value = 2;  // Textproto value.
   }
   repeated EditionDefault edition_defaults = 20;
 
   // Any features defined in the specific edition.
@@ -766,11 +798,11 @@
 
   // Enable the legacy handling of JSON field name conflicts.  This lowercases
   // and strips underscored from the fields before comparison in proto3 only.
   // The new behavior takes `json_name` into account and applies to proto2 as
   // well.
-  // TODO(b/261750190) Remove this legacy behavior once downstream teams have
+  // TODO Remove this legacy behavior once downstream teams have
   // had time to migrate.
   optional bool deprecated_legacy_json_field_conflicts = 6 [deprecated = true];
 
   // Any features defined in the specific edition.
   optional FeatureSet features = 7;
@@ -890,11 +922,11 @@
 }
 
 // ===================================================================
 // Features
 
-// TODO(b/274655146) Enums in C++ gencode (and potentially other languages) are
+// TODO Enums in C++ gencode (and potentially other languages) are
 // not well scoped.  This means that each of the feature enums below can clash
 // with each other.  The short names we've chosen maximize call-site
 // readability, but leave us very open to this scenario.  A future feature will
 // be designed and implemented to handle this, hopefully before we ever hit a
 // conflict here.
@@ -907,11 +939,13 @@
   }
   optional FieldPresence field_presence = 1 [
     retention = RETENTION_RUNTIME,
     targets = TARGET_TYPE_FIELD,
     targets = TARGET_TYPE_FILE,
-    edition_defaults = { edition: "2023", value: "EXPLICIT" }
+    edition_defaults = { edition: EDITION_PROTO2, value: "EXPLICIT" },
+    edition_defaults = { edition: EDITION_PROTO3, value: "IMPLICIT" },
+    edition_defaults = { edition: EDITION_2023, value: "EXPLICIT" }
   ];
 
   enum EnumType {
     ENUM_TYPE_UNKNOWN = 0;
     OPEN = 1;
@@ -919,11 +953,12 @@
   }
   optional EnumType enum_type = 2 [
     retention = RETENTION_RUNTIME,
     targets = TARGET_TYPE_ENUM,
     targets = TARGET_TYPE_FILE,
-    edition_defaults = { edition: "2023", value: "OPEN" }
+    edition_defaults = { edition: EDITION_PROTO2, value: "CLOSED" },
+    edition_defaults = { edition: EDITION_PROTO3, value: "OPEN" }
   ];
 
   enum RepeatedFieldEncoding {
     REPEATED_FIELD_ENCODING_UNKNOWN = 0;
     PACKED = 1;
@@ -931,24 +966,25 @@
   }
   optional RepeatedFieldEncoding repeated_field_encoding = 3 [
     retention = RETENTION_RUNTIME,
     targets = TARGET_TYPE_FIELD,
     targets = TARGET_TYPE_FILE,
-    edition_defaults = { edition: "2023", value: "PACKED" }
+    edition_defaults = { edition: EDITION_PROTO2, value: "EXPANDED" },
+    edition_defaults = { edition: EDITION_PROTO3, value: "PACKED" }
   ];
 
-  enum StringFieldValidation {
-    STRING_FIELD_VALIDATION_UNKNOWN = 0;
-    MANDATORY = 1;
-    HINT = 2;
-    NONE = 3;
+  enum Utf8Validation {
+    UTF8_VALIDATION_UNKNOWN = 0;
+    NONE = 1;
+    VERIFY = 2;
   }
-  optional StringFieldValidation string_field_validation = 4 [
+  optional Utf8Validation utf8_validation = 4 [
     retention = RETENTION_RUNTIME,
     targets = TARGET_TYPE_FIELD,
     targets = TARGET_TYPE_FILE,
-    edition_defaults = { edition: "2023", value: "MANDATORY" }
+    edition_defaults = { edition: EDITION_PROTO2, value: "NONE" },
+    edition_defaults = { edition: EDITION_PROTO3, value: "VERIFY" }
   ];
 
   enum MessageEncoding {
     MESSAGE_ENCODING_UNKNOWN = 0;
     LENGTH_PREFIXED = 1;
@@ -956,11 +992,11 @@
   }
   optional MessageEncoding message_encoding = 5 [
     retention = RETENTION_RUNTIME,
     targets = TARGET_TYPE_FIELD,
     targets = TARGET_TYPE_FILE,
-    edition_defaults = { edition: "2023", value: "LENGTH_PREFIXED" }
+    edition_defaults = { edition: EDITION_PROTO2, value: "LENGTH_PREFIXED" }
   ];
 
   enum JsonFormat {
     JSON_FORMAT_UNKNOWN = 0;
     ALLOW = 1;
@@ -969,18 +1005,43 @@
   optional JsonFormat json_format = 6 [
     retention = RETENTION_RUNTIME,
     targets = TARGET_TYPE_MESSAGE,
     targets = TARGET_TYPE_ENUM,
     targets = TARGET_TYPE_FILE,
-    edition_defaults = { edition: "2023", value: "ALLOW" }
+    edition_defaults = { edition: EDITION_PROTO2, value: "LEGACY_BEST_EFFORT" },
+    edition_defaults = { edition: EDITION_PROTO3, value: "ALLOW" }
   ];
 
-  optional FeatureSet raw_features = 999 [targets = TARGET_TYPE_UNKNOWN];
+  reserved 999;
 
   extensions 1000;  // for Protobuf C++
   extensions 1001;  // for Protobuf Java
 
   extensions 9995 to 9999;  // For internal testing
+}
+
+// A compiled specification for the defaults of a set of features.  These
+// messages are generated from FeatureSet extensions and can be used to seed
+// feature resolution. The resolution with this object becomes a simple search
+// for the closest matching edition, followed by proto merges.
+message FeatureSetDefaults {
+  // A map from every known edition with a unique set of defaults to its
+  // defaults. Not all editions may be contained here.  For a given edition,
+  // the defaults at the closest matching edition ordered at or before it should
+  // be used.  This field must be in strict ascending order by edition.
+  message FeatureSetEditionDefault {
+    optional Edition edition = 3;
+    optional FeatureSet features = 2;
+  }
+  repeated FeatureSetEditionDefault defaults = 1;
+
+  // The minimum supported edition (inclusive) when this was constructed.
+  // Editions before this will not have defaults.
+  optional Edition minimum_edition = 4;
+
+  // The maximum known edition (inclusive) when this was constructed. Editions
+  // after this will not have reliable defaults.
+  optional Edition maximum_edition = 5;
 }
 
 // ===================================================================
 // Optional source code info
 