private/google/type/phone_number.proto
// 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;
}