jia.shao.peng | 25d4969 | 2011-03-31 13:52:22 +0000 | [diff] [blame] | 1 | /* |
philip.liard@gmail.com | ef3cfa8 | 2011-08-18 11:41:24 +0000 | [diff] [blame] | 2 | * Copyright (C) 2009 The Libphonenumber Authors |
jia.shao.peng | 25d4969 | 2011-03-31 13:52:22 +0000 | [diff] [blame] | 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | // Definition of protocol buffer for holding metadata for international |
lararennie@google.com | 0822218 | 2011-11-10 13:02:10 +0000 | [diff] [blame] | 18 | // telephone numbers. The fields here correspond exactly to those in |
davinci@google.com | a693e57 | 2013-07-12 08:33:42 +0000 | [diff] [blame] | 19 | // resources/PhoneNumberMetadata.xml. |
jia.shao.peng | 25d4969 | 2011-03-31 13:52:22 +0000 | [diff] [blame] | 20 | // @author Shaopeng Jia |
| 21 | |
| 22 | syntax = "proto2"; |
| 23 | |
jia.shao.peng | 08c7140 | 2011-04-26 08:09:23 +0000 | [diff] [blame] | 24 | option optimize_for = LITE_RUNTIME; |
| 25 | |
lararennie@google.com | 4ec9839 | 2013-09-02 17:02:03 +0000 | [diff] [blame] | 26 | option java_package = "com.google.i18n.phonenumbers"; |
jia.shao.peng | 25d4969 | 2011-03-31 13:52:22 +0000 | [diff] [blame] | 27 | package i18n.phonenumbers; |
| 28 | |
| 29 | message NumberFormat { |
| 30 | // pattern is a regex that is used to match the national (significant) |
| 31 | // number. For example, the pattern "(20)(\d{4})(\d{4})" will match number |
| 32 | // "2070313000", which is the national (significant) number for Google London. |
| 33 | // Note the presence of the parentheses, which are capturing groups what |
| 34 | // specifies the grouping of numbers. |
| 35 | required string pattern = 1; |
| 36 | |
| 37 | // format specifies how the national (significant) number matched by |
| 38 | // pattern should be formatted. |
| 39 | // Using the same example as above, format could contain "$1 $2 $3", |
| 40 | // meaning that the number should be formatted as "20 7031 3000". |
| 41 | // Each $x are replaced by the numbers captured by group x in the |
| 42 | // regex specified by pattern. |
| 43 | required string format = 2; |
| 44 | |
| 45 | // This field is a regex that is used to match a certain number of digits |
| 46 | // at the beginning of the national (significant) number. When the match is |
| 47 | // successful, the accompanying pattern and format should be used to format |
| 48 | // this number. For example, if leading_digits="[1-3]|44", then all the |
| 49 | // national numbers starting with 1, 2, 3 or 44 should be formatted using the |
| 50 | // accompanying pattern and format. |
| 51 | // |
| 52 | // The first leadingDigitsPattern matches up to the first three digits of the |
| 53 | // national (significant) number; the next one matches the first four digits, |
| 54 | // then the first five and so on, until the leadingDigitsPattern can uniquely |
| 55 | // identify one pattern and format to be used to format the number. |
| 56 | // |
| 57 | // In the case when only one formatting pattern exists, no |
| 58 | // leading_digits_pattern is needed. |
| 59 | repeated string leading_digits_pattern = 3; |
| 60 | |
| 61 | // This field specifies how the national prefix ($NP) together with the first |
| 62 | // group ($FG) in the national significant number should be formatted in |
| 63 | // the NATIONAL format when a national prefix exists for a certain country. |
| 64 | // For example, when this field contains "($NP$FG)", a number from Beijing, |
| 65 | // China (whose $NP = 0), which would by default be formatted without |
| 66 | // national prefix as 10 1234 5678 in NATIONAL format, will instead be |
| 67 | // formatted as (010) 1234 5678; to format it as (0)10 1234 5678, the field |
| 68 | // would contain "($NP)$FG". Note $FG should always be present in this field, |
| 69 | // but $NP can be omitted. For example, having "$FG" could indicate the |
| 70 | // number should be formatted in NATIONAL format without the national prefix. |
lararennie@google.com | 0822218 | 2011-11-10 13:02:10 +0000 | [diff] [blame] | 71 | // This is commonly used to override the rule specified for the territory in |
| 72 | // the XML file. |
jia.shao.peng | 25d4969 | 2011-03-31 13:52:22 +0000 | [diff] [blame] | 73 | // |
| 74 | // When this field is missing, a number will be formatted without national |
| 75 | // prefix in NATIONAL format. This field does not affect how a number |
| 76 | // is formatted in other formats, such as INTERNATIONAL. |
| 77 | optional string national_prefix_formatting_rule = 4; |
| 78 | |
lararennie@google.com | 0822218 | 2011-11-10 13:02:10 +0000 | [diff] [blame] | 79 | // This field specifies whether the $NP can be omitted when formatting a |
| 80 | // number in national format, even though it usually wouldn't be. For example, |
| 81 | // a UK number would be formatted by our library as 020 XXXX XXXX. If we have |
| 82 | // commonly seen this number written by people without the leading 0, for |
| 83 | // example as (20) XXXX XXXX, this field would be set to true. This will be |
| 84 | // inherited from the value set for the territory in the XML file, unless a |
| 85 | // national_prefix_formatting_rule is defined specifically for this |
| 86 | // NumberFormat. |
| 87 | optional bool national_prefix_optional_when_formatting = 6; |
| 88 | |
jia.shao.peng | 25d4969 | 2011-03-31 13:52:22 +0000 | [diff] [blame] | 89 | // This field specifies how any carrier code ($CC) together with the first |
| 90 | // group ($FG) in the national significant number should be formatted |
| 91 | // when formatWithCarrierCode is called, if carrier codes are used for a |
| 92 | // certain country. |
| 93 | optional string domestic_carrier_code_formatting_rule = 5; |
| 94 | } |
| 95 | |
| 96 | message PhoneNumberDesc { |
| 97 | // The national_number_pattern is the pattern that a valid national |
| 98 | // significant number would match. This specifies information such as its |
| 99 | // total length and leading digits. |
| 100 | optional string national_number_pattern = 2; |
| 101 | |
| 102 | // The possible_number_pattern represents what a potentially valid phone |
| 103 | // number for this region may be written as. This is a superset of the |
| 104 | // national_number_pattern above and includes numbers that have the area code |
| 105 | // omitted. Typically the only restrictions here are in the number of digits. |
| 106 | // This could be used to highlight tokens in a text that may be a phone |
| 107 | // number, or to quickly prune numbers that could not possibly be a phone |
| 108 | // number for this locale. |
| 109 | optional string possible_number_pattern = 3; |
| 110 | |
| 111 | // An example national significant number for the specific type. It should |
| 112 | // not contain any formatting information. |
| 113 | optional string example_number = 6; |
| 114 | } |
| 115 | |
| 116 | message PhoneMetadata { |
| 117 | // The general_desc contains information which is a superset of descriptions |
| 118 | // for all types of phone numbers. If any element is missing in the |
| 119 | // description of a specific type in the XML file, the element will inherit |
| 120 | // from its counterpart in the general_desc. Every locale is assumed to have |
lararennie@google.com | 4ec9839 | 2013-09-02 17:02:03 +0000 | [diff] [blame] | 121 | // fixed line and mobile numbers - if these types are missing in the |
| 122 | // PhoneNumberMetadata XML file, they will inherit all fields from the |
| 123 | // general_desc. For all other types that are generally relevant to normal |
| 124 | // phone numbers, if the whole type is missing in the PhoneNumberMetadata XML |
| 125 | // file, it will be given a national_number_pattern of "NA" and a |
| 126 | // possible_number_pattern of "NA". |
lararennie@google.com | c40c292 | 2013-08-08 11:14:29 +0000 | [diff] [blame] | 127 | optional PhoneNumberDesc general_desc = 1; |
| 128 | optional PhoneNumberDesc fixed_line = 2; |
| 129 | optional PhoneNumberDesc mobile = 3; |
| 130 | optional PhoneNumberDesc toll_free = 4; |
| 131 | optional PhoneNumberDesc premium_rate = 5; |
| 132 | optional PhoneNumberDesc shared_cost = 6; |
| 133 | optional PhoneNumberDesc personal_number = 7; |
| 134 | optional PhoneNumberDesc voip = 8; |
| 135 | optional PhoneNumberDesc pager = 21; |
| 136 | optional PhoneNumberDesc uan = 25; |
| 137 | optional PhoneNumberDesc emergency = 27; |
| 138 | optional PhoneNumberDesc voicemail = 28; |
| 139 | optional PhoneNumberDesc short_code = 29; |
| 140 | optional PhoneNumberDesc standard_rate = 30; |
lararennie@google.com | 4ec9839 | 2013-09-02 17:02:03 +0000 | [diff] [blame] | 141 | optional PhoneNumberDesc carrier_specific = 31; |
| 142 | |
jia.shao.peng | 25d4969 | 2011-03-31 13:52:22 +0000 | [diff] [blame] | 143 | // The rules here distinguish the numbers that are only able to be dialled |
| 144 | // nationally. |
lararennie@google.com | c40c292 | 2013-08-08 11:14:29 +0000 | [diff] [blame] | 145 | optional PhoneNumberDesc no_international_dialling = 24; |
jia.shao.peng | 25d4969 | 2011-03-31 13:52:22 +0000 | [diff] [blame] | 146 | |
lararennie@google.com | 92548ce | 2012-06-21 16:37:38 +0000 | [diff] [blame] | 147 | // The ISO 3166-1 alpha-2 representation of a country/region, with the |
| 148 | // exception of "country calling codes" used for non-geographical entities, |
| 149 | // such as Universal International Toll Free Number (+800). These are all |
| 150 | // given the ID "001", since this is the numeric region code for the world |
| 151 | // according to UN M.49: http://en.wikipedia.org/wiki/UN_M.49 |
jia.shao.peng | 25d4969 | 2011-03-31 13:52:22 +0000 | [diff] [blame] | 152 | required string id = 9; |
| 153 | |
| 154 | // The country calling code that one would dial from overseas when trying to |
| 155 | // dial a phone number in this country. For example, this would be "64" for |
| 156 | // New Zealand. |
lararennie@google.com | 4ec9839 | 2013-09-02 17:02:03 +0000 | [diff] [blame] | 157 | optional int32 country_code = 10; |
jia.shao.peng | 25d4969 | 2011-03-31 13:52:22 +0000 | [diff] [blame] | 158 | |
| 159 | // The international_prefix of country A is the number that needs to be |
| 160 | // dialled from country A to another country (country B). This is followed |
| 161 | // by the country code for country B. Note that some countries may have more |
| 162 | // than one international prefix, and for those cases, a regular expression |
| 163 | // matching the international prefixes will be stored in this field. |
lararennie@google.com | 4ec9839 | 2013-09-02 17:02:03 +0000 | [diff] [blame] | 164 | optional string international_prefix = 11; |
jia.shao.peng | 25d4969 | 2011-03-31 13:52:22 +0000 | [diff] [blame] | 165 | |
| 166 | // If more than one international prefix is present, a preferred prefix can |
| 167 | // be specified here for out-of-country formatting purposes. If this field is |
| 168 | // not present, and multiple international prefixes are present, then "+" |
| 169 | // will be used instead. |
| 170 | optional string preferred_international_prefix = 17; |
| 171 | |
| 172 | // The national prefix of country A is the number that needs to be dialled |
| 173 | // before the national significant number when dialling internally. This |
| 174 | // would not be dialled when dialling internationally. For example, in New |
| 175 | // Zealand, the number that would be locally dialled as 09 345 3456 would be |
| 176 | // dialled from overseas as +64 9 345 3456. In this case, 0 is the national |
| 177 | // prefix. |
| 178 | optional string national_prefix = 12; |
| 179 | |
| 180 | // The preferred prefix when specifying an extension in this country. This is |
| 181 | // used for formatting only, and if this is not specified, a suitable default |
| 182 | // should be used instead. For example, if you wanted extensions to be |
| 183 | // formatted in the following way: |
| 184 | // 1 (365) 345 445 ext. 2345 |
| 185 | // " ext. " should be the preferred extension prefix. |
| 186 | optional string preferred_extn_prefix = 13; |
| 187 | |
| 188 | // This field is used for cases where the national prefix of a country |
| 189 | // contains a carrier selection code, and is written in the form of a |
| 190 | // regular expression. For example, to dial the number 2222-2222 in |
| 191 | // Fortaleza, Brazil (area code 85) using the long distance carrier Oi |
| 192 | // (selection code 31), one would dial 0 31 85 2222 2222. Assuming the |
| 193 | // only other possible carrier selection code is 32, the field will |
| 194 | // contain "03[12]". |
| 195 | // |
| 196 | // When it is missing from the XML file, this field inherits the value of |
| 197 | // national_prefix, if that is present. |
| 198 | optional string national_prefix_for_parsing = 15; |
| 199 | |
| 200 | // This field is only populated and used under very rare situations. |
| 201 | // For example, mobile numbers in Argentina are written in two completely |
| 202 | // different ways when dialed in-country and out-of-country |
| 203 | // (e.g. 0343 15 555 1212 is exactly the same number as +54 9 343 555 1212). |
| 204 | // This field is used together with national_prefix_for_parsing to transform |
| 205 | // the number into a particular representation for storing in the phonenumber |
| 206 | // proto buffer in those rare cases. |
| 207 | optional string national_prefix_transform_rule = 16; |
| 208 | |
| 209 | // Specifies whether the mobile and fixed-line patterns are the same or not. |
| 210 | // This is used to speed up determining phone number type in countries where |
| 211 | // these two types of phone numbers can never be distinguished. |
| 212 | optional bool same_mobile_and_fixed_line_pattern = 18 [default=false]; |
| 213 | |
| 214 | // Note that the number format here is used for formatting only, not parsing. |
| 215 | // Hence all the varied ways a user *may* write a number need not be recorded |
| 216 | // - just the ideal way we would like to format it for them. When this element |
| 217 | // is absent, the national significant number will be formatted as a whole |
| 218 | // without any formatting applied. |
| 219 | repeated NumberFormat number_format = 19; |
| 220 | |
| 221 | // This field is populated only when the national significant number is |
| 222 | // formatted differently when it forms part of the INTERNATIONAL format |
| 223 | // and NATIONAL format. A case in point is mobile numbers in Argentina: |
| 224 | // The number, which would be written in INTERNATIONAL format as |
| 225 | // +54 9 343 555 1212, will be written as 0343 15 555 1212 for NATIONAL |
| 226 | // format. In this case, the prefix 9 is inserted when dialling from |
| 227 | // overseas, but otherwise the prefix 0 and the carrier selection code |
| 228 | // 15 (inserted after the area code of 343) is used. |
lararennie@google.com | 0822218 | 2011-11-10 13:02:10 +0000 | [diff] [blame] | 229 | // Note: this field is populated by setting a value for <intlFormat> inside |
| 230 | // the <numberFormat> tag in the XML file. If <intlFormat> is not set then it |
| 231 | // defaults to the same value as the <format> tag. |
| 232 | // |
| 233 | // Examples: |
| 234 | // To set the <intlFormat> to a different value than the <format>: |
| 235 | // <numberFormat pattern=....> |
| 236 | // <format>$1 $2 $3</format> |
| 237 | // <intlFormat>$1-$2-$3</intlFormat> |
| 238 | // </numberFormat> |
| 239 | // |
| 240 | // To have a format only used for national formatting, set <intlFormat> to |
| 241 | // "NA": |
| 242 | // <numberFormat pattern=....> |
| 243 | // <format>$1 $2 $3</format> |
| 244 | // <intlFormat>NA</intlFormat> |
| 245 | // </numberFormat> |
jia.shao.peng | 25d4969 | 2011-03-31 13:52:22 +0000 | [diff] [blame] | 246 | repeated NumberFormat intl_number_format = 20; |
| 247 | |
| 248 | // This field is set when this country is considered to be the main country |
| 249 | // for a calling code. It may not be set by more than one country with the |
| 250 | // same calling code, and it should not be set by countries with a unique |
| 251 | // calling code. This can be used to indicate that "GB" is the main country |
| 252 | // for the calling code "44" for example, rather than Jersey or the Isle of |
| 253 | // Man. |
| 254 | optional bool main_country_for_code = 22 [default=false]; |
| 255 | |
| 256 | // This field is populated only for countries or regions that share a country |
| 257 | // calling code. If a number matches this pattern, it could belong to this |
| 258 | // region. This is not intended as a replacement for IsValidForRegion, and |
| 259 | // does not mean the number must come from this region (for example, 800 |
| 260 | // numbers are valid for all NANPA countries.) This field should be a regular |
| 261 | // expression of the expected prefix match. |
| 262 | optional string leading_digits = 23; |
| 263 | |
| 264 | // The leading zero in a phone number is meaningful in some countries (e.g. |
| 265 | // Italy). This means they cannot be dropped from the national number when |
| 266 | // converting into international format. If leading zeros are possible for |
| 267 | // valid international numbers for this region/country then set this to true. |
| 268 | // This only needs to be set for the region that is the main_country_for_code |
| 269 | // and all regions associated with that calling code will use the same |
| 270 | // setting. |
| 271 | optional bool leading_zero_possible = 26 [default=false]; |
lararennie@google.com | d2c6d23 | 2013-09-20 15:28:08 +0000 | [diff] [blame] | 272 | |
| 273 | // This field is set when this country has implemented mobile number |
| 274 | // portability. This means that transferring mobile numbers between carriers |
| 275 | // is allowed. A consequence of this is that phone prefix to carrier mapping |
| 276 | // is less reliable. |
| 277 | optional bool mobile_number_portable_region = 32 [default=false]; |
jia.shao.peng | 25d4969 | 2011-03-31 13:52:22 +0000 | [diff] [blame] | 278 | } |
| 279 | |
| 280 | message PhoneMetadataCollection { |
| 281 | repeated PhoneMetadata metadata = 1; |
| 282 | } |