From 29b789912908e71d60551022a0521206794b501c Mon Sep 17 00:00:00 2001 From: Google APIs Date: Wed, 21 Oct 2020 09:10:54 -0700 Subject: [PATCH] feat: update types in google/type, add Interval, LocalizedText, PhoneNumber PiperOrigin-RevId: 338275151 --- google/type/calendar_period.proto | 3 +- google/type/color.proto | 7 +- google/type/date.proto | 25 +++---- google/type/datetime.proto | 13 +++- google/type/dayofweek.proto | 21 +++--- google/type/expr.proto | 50 +++++++++---- google/type/fraction.proto | 5 +- google/type/interval.proto | 46 ++++++++++++ google/type/latlng.proto | 4 +- google/type/localized_text.proto | 36 ++++++++++ google/type/money.proto | 5 +- google/type/month.proto | 3 +- google/type/phone_number.proto | 113 ++++++++++++++++++++++++++++++ google/type/postal_address.proto | 3 +- google/type/quaternion.proto | 3 +- google/type/timeofday.proto | 3 +- 16 files changed, 280 insertions(+), 60 deletions(-) create mode 100644 google/type/interval.proto create mode 100644 google/type/localized_text.proto create mode 100644 google/type/phone_number.proto diff --git a/google/type/calendar_period.proto b/google/type/calendar_period.proto index a91d0c35..497fffc3 100644 --- a/google/type/calendar_period.proto +++ b/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"; diff --git a/google/type/color.proto b/google/type/color.proto index 417f1c4b..ed4cb1d3 100644 --- a/google/type/color.proto +++ b/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; diff --git a/google/type/date.proto b/google/type/date.proto index b958feeb..a73fe36b 100644 --- a/google/type/date.proto +++ b/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 -// and time zone are either specified elsewhere or are not significant. The date -// is relative to the Proleptic Gregorian Calendar. This can represent: +// Represents a whole or partial calendar date, such as a birthday. The time of +// day and time zone are either specified elsewhere or are insignificant. The +// 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 month and day value, with a zero year, e.g. an anniversary +// * A full date, with non-zero year, month, and day values +// * 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 - // if specifying a year by itself or a year and month where the day is not + // Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 + // to specify a year by itself or a year and month where the day isn't // significant. int32 day = 3; } diff --git a/google/type/datetime.proto b/google/type/datetime.proto index 5aebc4b9..0d5949fd 100644 --- a/google/type/datetime.proto +++ b/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 { diff --git a/google/type/dayofweek.proto b/google/type/dayofweek.proto index 7544e151..e07017e2 100644 --- a/google/type/dayofweek.proto +++ b/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; } diff --git a/google/type/expr.proto b/google/type/expr.proto index 5d4f2f71..fbadd350 100644 --- a/google/type/expr.proto +++ b/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" -// description: "Determines whether the request has a user account" -// expression: "size(request.user) > 0" +// Example (Comparison): +// +// 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 - // Common Expression Language syntax. - // - // The application context of the containing message determines which - // well-known feature set of CEL is supported. + // Textual representation of an expression in Common Expression Language + // syntax. 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; } diff --git a/google/type/fraction.proto b/google/type/fraction.proto index 8ad008dd..04c3bcff 100644 --- a/google/type/fraction.proto +++ b/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 diff --git a/google/type/interval.proto b/google/type/interval.proto new file mode 100644 index 00000000..029957b0 --- /dev/null +++ b/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; +} diff --git a/google/type/latlng.proto b/google/type/latlng.proto index e5d45f1e..a90b7c23 100644 --- a/google/type/latlng.proto +++ b/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 -// of doubles representing degrees latitude and degrees longitude. Unless +// An object that represents a latitude/longitude pair. This is expressed as a +// pair of doubles to represent degrees latitude and degrees longitude. Unless // specified otherwise, this must conform to the // WGS84 // standard. Values must be within normalized ranges. diff --git a/google/type/localized_text.proto b/google/type/localized_text.proto new file mode 100644 index 00000000..cbf27bc4 --- /dev/null +++ b/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; +} diff --git a/google/type/money.proto b/google/type/money.proto index ef41f108..2a3ea6fb 100644 --- a/google/type/money.proto +++ b/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. diff --git a/google/type/month.proto b/google/type/month.proto index 54b7865f..86033093 100644 --- a/google/type/month.proto +++ b/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"; diff --git a/google/type/phone_number.proto b/google/type/phone_number.proto new file mode 100644 index 00000000..24035131 --- /dev/null +++ b/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; +} diff --git a/google/type/postal_address.proto b/google/type/postal_address.proto index 688af8a1..9cf1c785 100644 --- a/google/type/postal_address.proto +++ b/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"; diff --git a/google/type/quaternion.proto b/google/type/quaternion.proto index 7ab5dc72..677edd73 100644 --- a/google/type/quaternion.proto +++ b/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"; diff --git a/google/type/timeofday.proto b/google/type/timeofday.proto index b609a487..495d3595 100644 --- a/google/type/timeofday.proto +++ b/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";