feat: update types in google/type, add Interval, LocalizedText, PhoneNumber

PiperOrigin-RevId: 338275151

google/type/calendar_period.proto

@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// Copyright 2020 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
 
 syntax = "proto3";
 

google/type/color.proto

@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// Copyright 2020 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
 
 syntax = "proto3";
 
@@ -39,6 +38,10 @@ option objc_class_prefix = "GTP";
 // DCI-P3, BT.2020, etc.). By default, applications SHOULD assume the sRGB color
 // space.
 //
+// Note: when color equality needs to be decided, implementations, unless
+// documented otherwise, will treat two colors to be equal if all their red,
+// green, blue and alpha values each differ by at most 1e-5.
+//
 // Example (Java):
 //
 //      import com.google.type.Color;

google/type/date.proto

@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// Copyright 2020 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
 
 syntax = "proto3";
 
@@ -24,27 +23,29 @@ option java_outer_classname = "DateProto";
 option java_package = "com.google.type";
 option objc_class_prefix = "GTP";
 
-// Represents a whole or partial calendar date, e.g. a birthday. The time of day
+// Represents a whole or partial calendar date, such as a birthday. The time of
-// and time zone are either specified elsewhere or are not significant. The date
+// day and time zone are either specified elsewhere or are insignificant. The
-// is relative to the Proleptic Gregorian Calendar. This can represent:
+// date is relative to the Gregorian Calendar. This can represent one of the
+// following:
 //
-// * A full date, with non-zero year, month and day values
+// * A full date, with non-zero year, month, and day values
-// * A month and day value, with a zero year, e.g. an anniversary
+// * A month and day value, with a zero year, such as an anniversary
 // * A year on its own, with zero month and day values
-// * A year and month value, with a zero day, e.g. a credit card expiration date
+// * A year and month value, with a zero day, such as a credit card expiration
+// date
 //
 // Related types are [google.type.TimeOfDay][google.type.TimeOfDay] and `google.protobuf.Timestamp`.
 message Date {
-  // Year of date. Must be from 1 to 9999, or 0 if specifying a date without
+  // Year of the date. Must be from 1 to 9999, or 0 to specify a date without
   // a year.
   int32 year = 1;
 
-  // Month of year. Must be from 1 to 12, or 0 if specifying a year without a
+  // Month of a year. Must be from 1 to 12, or 0 to specify a year without a
   // month and day.
   int32 month = 2;
 
-  // Day of month. Must be from 1 to 31 and valid for the year and month, or 0
+  // Day of a month. Must be from 1 to 31 and valid for the year and month, or 0
-  // if specifying a year by itself or a year and month where the day is not
+  // to specify a year by itself or a year and month where the day isn't
   // significant.
   int32 day = 3;
 }

google/type/datetime.proto

@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// Copyright 2020 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
 
 syntax = "proto3";
 
@@ -26,7 +25,9 @@ option java_outer_classname = "DateTimeProto";
 option java_package = "com.google.type";
 option objc_class_prefix = "GTP";
 
-// Represents civil time in one of a few possible ways:
+// Represents civil time (or occasionally physical time).
+//
+// This type can represent a civil time in one of a few possible ways:
 //
 //  * When utc_offset is set and time_zone is unset: a civil time on a calendar
 //    day with a particular offset from UTC.
@@ -40,6 +41,12 @@ option objc_class_prefix = "GTP";
 // If year is 0, the DateTime is considered not to have a specific year. month
 // and day must have valid, non-zero values.
 //
+// This type may also be used to represent a physical time if all the date and
+// time fields are set and either case of the `time_offset` oneof is set.
+// Consider using `Timestamp` message for physical time instead. If your use
+// case also would like to store the user's timezone, that can be done in
+// another field.
+//
 // This type is more flexible than some applications may want. Make sure to
 // document and validate your application's limitations.
 message DateTime {

google/type/dayofweek.proto

@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// Copyright 2020 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
 
 syntax = "proto3";
 
@@ -23,29 +22,29 @@ option java_outer_classname = "DayOfWeekProto";
 option java_package = "com.google.type";
 option objc_class_prefix = "GTP";
 
-// Represents a day of week.
+// Represents a day of the week.
 enum DayOfWeek {
-  // The unspecified day-of-week.
+  // The day of the week is unspecified.
   DAY_OF_WEEK_UNSPECIFIED = 0;
 
-  // The day-of-week of Monday.
+  // Monday
   MONDAY = 1;
 
-  // The day-of-week of Tuesday.
+  // Tuesday
   TUESDAY = 2;
 
-  // The day-of-week of Wednesday.
+  // Wednesday
   WEDNESDAY = 3;
 
-  // The day-of-week of Thursday.
+  // Thursday
   THURSDAY = 4;
 
-  // The day-of-week of Friday.
+  // Friday
   FRIDAY = 5;
 
-  // The day-of-week of Saturday.
+  // Saturday
   SATURDAY = 6;
 
-  // The day-of-week of Sunday.
+  // Sunday
   SUNDAY = 7;
 }

google/type/expr.proto

@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// Copyright 2020 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
 
 syntax = "proto3";
 
@@ -23,29 +22,52 @@ option java_outer_classname = "ExprProto";
 option java_package = "com.google.type";
 option objc_class_prefix = "GTP";
 
-// Represents an expression text. Example:
+// Represents a textual expression in the Common Expression Language (CEL)
+// syntax. CEL is a C-like expression language. The syntax and semantics of CEL
+// are documented at https://github.com/google/cel-spec.
 //
-//     title: "User account presence"
+// Example (Comparison):
-//     description: "Determines whether the request has a user account"
+//
-//     expression: "size(request.user) > 0"
+//     title: "Summary size limit"
+//     description: "Determines if a summary is less than 100 chars"
+//     expression: "document.summary.size() < 100"
+//
+// Example (Equality):
+//
+//     title: "Requestor is owner"
+//     description: "Determines if requestor is the document owner"
+//     expression: "document.owner == request.auth.claims.email"
+//
+// Example (Logic):
+//
+//     title: "Public documents"
+//     description: "Determine whether the document should be publicly visible"
+//     expression: "document.type != 'private' && document.type != 'internal'"
+//
+// Example (Data Manipulation):
+//
+//     title: "Notification string"
+//     description: "Create a notification string with a timestamp."
+//     expression: "'New message received at ' + string(document.create_time)"
+//
+// The exact variables and functions that may be referenced within an expression
+// are determined by the service that evaluates it. See the service
+// documentation for additional information.
 message Expr {
-  // Textual representation of an expression in
+  // Textual representation of an expression in Common Expression Language
-  // Common Expression Language syntax.
+  // syntax.
-  //
-  // The application context of the containing message determines which
-  // well-known feature set of CEL is supported.
   string expression = 1;
 
-  // An optional title for the expression, i.e. a short string describing
+  // Optional. Title for the expression, i.e. a short string describing
   // its purpose. This can be used e.g. in UIs which allow to enter the
   // expression.
   string title = 2;
 
-  // An optional description of the expression. This is a longer text which
+  // Optional. Description of the expression. This is a longer text which
   // describes the expression, e.g. when hovered over it in a UI.
   string description = 3;
 
-  // An optional string indicating the location of the expression for error
+  // Optional. String indicating the location of the expression for error
   // reporting, e.g. a file name and a position in the file.
   string location = 4;
 }

google/type/fraction.proto

@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// Copyright 2020 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
 
 syntax = "proto3";
 
@@ -25,7 +24,7 @@ option objc_class_prefix = "GTP";
 
 // Represents a fraction in terms of a numerator divided by a denominator.
 message Fraction {
-  // The portion of the denominator in the faction, e.g. 2 in 2/3.
+  // The numerator in the fraction, e.g. 2 in 2/3.
   int64 numerator = 1;
 
   // The value by which the numerator is divided, e.g. 3 in 2/3. Must be

google/type/interval.proto

@@ -0,0 +1,46 @@
+// Copyright 2020 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.type;
+
+import "google/protobuf/timestamp.proto";
+
+option cc_enable_arenas = true;
+option go_package = "google.golang.org/genproto/googleapis/type/interval;interval";
+option java_multiple_files = true;
+option java_outer_classname = "IntervalProto";
+option java_package = "com.google.type";
+option objc_class_prefix = "GTP";
+
+// Represents a time interval, encoded as a Timestamp start (inclusive) and a
+// Timestamp end (exclusive).
+//
+// The start must be less than or equal to the end.
+// When the start equals the end, the interval is empty (matches no time).
+// When both start and end are unspecified, the interval matches any time.
+message Interval {
+  // Optional. Inclusive start of the interval.
+  //
+  // If specified, a Timestamp matching this interval will have to be the same
+  // or after the start.
+  google.protobuf.Timestamp start_time = 1;
+
+  // Optional. Exclusive end of the interval.
+  //
+  // If specified, a Timestamp matching this interval will have to be before the
+  // end.
+  google.protobuf.Timestamp end_time = 2;
+}

google/type/latlng.proto

@@ -23,8 +23,8 @@ option java_outer_classname = "LatLngProto";
 option java_package = "com.google.type";
 option objc_class_prefix = "GTP";
 
-// An object representing a latitude/longitude pair. This is expressed as a pair
+// An object that represents a latitude/longitude pair. This is expressed as a
-// of doubles representing degrees latitude and degrees longitude. Unless
+// pair of doubles to represent degrees latitude and degrees longitude. Unless
 // specified otherwise, this must conform to the
 // <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84
 // standard</a>. Values must be within normalized ranges.

google/type/localized_text.proto

@@ -0,0 +1,36 @@
+// Copyright 2020 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.type;
+
+option cc_enable_arenas = true;
+option go_package = "google.golang.org/genproto/googleapis/type/localized_text;localized_text";
+option java_multiple_files = true;
+option java_outer_classname = "LocalizedTextProto";
+option java_package = "com.google.type";
+option objc_class_prefix = "GTP";
+
+// Localized variant of a text in a particular language.
+message LocalizedText {
+  // Localized string in the language corresponding to `language_code' below.
+  string text = 1;
+
+  // The text's BCP-47 language code, such as "en-US" or "sr-Latn".
+  //
+  // For more information, see
+  // http://www.unicode.org/reports/tr35/#Unicode_locale_identifier.
+  string language_code = 2;
+}

google/type/money.proto

@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// Copyright 2020 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
 
 syntax = "proto3";
 
@@ -26,7 +25,7 @@ option objc_class_prefix = "GTP";
 
 // Represents an amount of money with its currency type.
 message Money {
-  // The 3-letter currency code defined in ISO 4217.
+  // The three-letter currency code defined in ISO 4217.
   string currency_code = 1;
 
   // The whole units of the amount.

google/type/month.proto

@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// Copyright 2020 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
 
 syntax = "proto3";
 

google/type/phone_number.proto

@@ -0,0 +1,113 @@
+// Copyright 2020 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.type;
+
+option cc_enable_arenas = true;
+option go_package = "google.golang.org/genproto/googleapis/type/phone_number;phone_number";
+option java_multiple_files = true;
+option java_outer_classname = "PhoneNumberProto";
+option java_package = "com.google.type";
+option objc_class_prefix = "GTP";
+
+// An object representing a phone number, suitable as an API wire format.
+//
+// This representation:
+//
+//  - should not be used for locale-specific formatting of a phone number, such
+//    as "+1 (650) 253-0000 ext. 123"
+//
+//  - is not designed for efficient storage
+//  - may not be suitable for dialing - specialized libraries (see references)
+//    should be used to parse the number for that purpose
+//
+// To do something meaningful with this number, such as format it for various
+// use-cases, convert it to an `i18n.phonenumbers.PhoneNumber` object first.
+//
+// For instance, in Java this would be:
+//
+//    com.google.type.PhoneNumber wireProto =
+//        com.google.type.PhoneNumber.newBuilder().build();
+//    com.google.i18n.phonenumbers.Phonenumber.PhoneNumber phoneNumber =
+//        PhoneNumberUtil.getInstance().parse(wireProto.getE164Number(), "ZZ");
+//    if (!wireProto.getExtension().isEmpty()) {
+//      phoneNumber.setExtension(wireProto.getExtension());
+//    }
+//
+//  Reference(s):
+//   - https://github.com/google/libphonenumber
+message PhoneNumber {
+  // An object representing a short code, which is a phone number that is
+  // typically much shorter than regular phone numbers and can be used to
+  // address messages in MMS and SMS systems, as well as for abbreviated dialing
+  // (e.g. "Text 611 to see how many minutes you have remaining on your plan.").
+  //
+  // Short codes are restricted to a region and are not internationally
+  // dialable, which means the same short code can exist in different regions,
+  // with different usage and pricing, even if those regions share the same
+  // country calling code (e.g. US and CA).
+  message ShortCode {
+    // Required. The BCP-47 region code of the location where calls to this
+    // short code can be made, such as "US" and "BB".
+    //
+    // Reference(s):
+    //  - http://www.unicode.org/reports/tr35/#unicode_region_subtag
+    string region_code = 1;
+
+    // Required. The short code digits, without a leading plus ('+') or country
+    // calling code, e.g. "611".
+    string number = 2;
+  }
+
+  // Required.  Either a regular number, or a short code.  New fields may be
+  // added to the oneof below in the future, so clients should ignore phone
+  // numbers for which none of the fields they coded against are set.
+  oneof kind {
+    // The phone number, represented as a leading plus sign ('+'), followed by a
+    // phone number that uses a relaxed ITU E.164 format consisting of the
+    // country calling code (1 to 3 digits) and the subscriber number, with no
+    // additional spaces or formatting, e.g.:
+    //  - correct: "+15552220123"
+    //  - incorrect: "+1 (555) 222-01234 x123".
+    //
+    // The ITU E.164 format limits the latter to 12 digits, but in practice not
+    // all countries respect that, so we relax that restriction here.
+    // National-only numbers are not allowed.
+    //
+    // References:
+    //  - https://www.itu.int/rec/T-REC-E.164-201011-I
+    //  - https://en.wikipedia.org/wiki/E.164.
+    //  - https://en.wikipedia.org/wiki/List_of_country_calling_codes
+    string e164_number = 1;
+
+    // A short code.
+    //
+    // Reference(s):
+    //  - https://en.wikipedia.org/wiki/Short_code
+    ShortCode short_code = 2;
+  }
+
+  // The phone number's extension. The extension is not standardized in ITU
+  // recommendations, except for being defined as a series of numbers with a
+  // maximum length of 40 digits. Other than digits, some other dialing
+  // characters such as ',' (indicating a wait) or '#' may be stored here.
+  //
+  // Note that no regions currently use extensions with short codes, so this
+  // field is normally only set in conjunction with an E.164 number. It is held
+  // separately from the E.164 number to allow for short code extensions in the
+  // future.
+  string extension = 3;
+}

google/type/postal_address.proto

@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// Copyright 2020 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
 
 syntax = "proto3";
 

google/type/quaternion.proto

@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// Copyright 2020 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
 
 syntax = "proto3";
 

google/type/timeofday.proto

@@ -1,4 +1,4 @@
-// Copyright 2019 Google LLC.
+// Copyright 2020 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,7 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
 
 syntax = "proto3";