1/* 2 * Copyright (C) 2009 The Libphonenumber Authors 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 18// telephone numbers. The fields here correspond exactly to those in 19// resources/PhoneNumberMetadata.xml. 20// @author Shaopeng Jia 21 22syntax = "proto2"; 23 24option optimize_for = LITE_RUNTIME; 25 26option java_package = "com.google.i18n.phonenumbers"; 27package i18n.phonenumbers; 28 29message 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. 71 // This is commonly used to override the rule specified for the territory in 72 // the XML file. 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 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_optional_when_formatting is defined specifically for this 86 // NumberFormat. 87 optional bool national_prefix_optional_when_formatting = 6 [default=false]; 88 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// If you add, remove, or rename fields, or change their semantics, check if you 97// should change the excludable field sets or the behavior in MetadataFilter. 98message PhoneNumberDesc { 99 // The national_number_pattern is the pattern that a valid national 100 // significant number would match. This specifies information such as its 101 // total length and leading digits. 102 optional string national_number_pattern = 2; 103 104 // These represent the lengths a phone number from this region can be. They 105 // will be sorted from smallest to biggest. Note that these lengths are for 106 // the full number, without country calling code or national prefix. For 107 // example, for the Swiss number +41789270000, in local format 0789270000, 108 // this would be 9. 109 // This could be used to highlight tokens in a text that may be a phone 110 // number, or to quickly prune numbers that could not possibly be a phone 111 // number for this locale. 112 repeated int32 possible_length = 9; 113 114 // These represent the lengths that only local phone numbers (without an area 115 // code) from this region can be. They will be sorted from smallest to 116 // biggest. For example, since the American number 456-1234 may be locally 117 // diallable, although not diallable from outside the area, 7 could be a 118 // possible value. 119 // This could be used to highlight tokens in a text that may be a phone 120 // number. 121 // To our knowledge, area codes are usually only relevant for some fixed-line 122 // and mobile numbers, so this field should only be set for those types of 123 // numbers (and the general description) - however there are exceptions for 124 // NANPA countries. 125 // This data is used to calculate whether a number could be a possible number 126 // for a particular type. 127 repeated int32 possible_length_local_only = 10; 128 129 // An example national significant number for the specific type. It should 130 // not contain any formatting information. 131 optional string example_number = 6; 132} 133 134// If you add, remove, or rename fields, or change their semantics, check if you 135// should change the excludable field sets or the behavior in MetadataFilter. 136message PhoneMetadata { 137 // The general_desc contains information which is a superset of descriptions 138 // for all types of phone numbers. If any element is missing in the 139 // description of a specific type in the XML file, the element will inherit 140 // from its counterpart in the general_desc. For all types that are generally 141 // relevant to normal phone numbers, if the whole type is missing in the 142 // PhoneNumberMetadata XML file, it will not have national number data, and 143 // the possible lengths will be [-1]. 144 optional PhoneNumberDesc general_desc = 1; 145 optional PhoneNumberDesc fixed_line = 2; 146 optional PhoneNumberDesc mobile = 3; 147 optional PhoneNumberDesc toll_free = 4; 148 optional PhoneNumberDesc premium_rate = 5; 149 optional PhoneNumberDesc shared_cost = 6; 150 optional PhoneNumberDesc personal_number = 7; 151 optional PhoneNumberDesc voip = 8; 152 optional PhoneNumberDesc pager = 21; 153 optional PhoneNumberDesc uan = 25; 154 optional PhoneNumberDesc emergency = 27; 155 optional PhoneNumberDesc voicemail = 28; 156 optional PhoneNumberDesc short_code = 29; 157 optional PhoneNumberDesc standard_rate = 30; 158 optional PhoneNumberDesc carrier_specific = 31; 159 optional PhoneNumberDesc sms_services = 33; 160 161 // The rules here distinguish the numbers that are only able to be dialled 162 // nationally. 163 optional PhoneNumberDesc no_international_dialling = 24; 164 165 // The CLDR 2-letter representation of a country/region, with the exception of 166 // "country calling codes" used for non-geographical entities, such as 167 // Universal International Toll Free Number (+800). These are all given the ID 168 // "001", since this is the numeric region code for the world according to UN 169 // M.49: http://en.wikipedia.org/wiki/UN_M.49 170 required string id = 9; 171 172 // The country calling code that one would dial from overseas when trying to 173 // dial a phone number in this country. For example, this would be "64" for 174 // New Zealand. 175 optional int32 country_code = 10; 176 177 // The international_prefix of country A is the number that needs to be 178 // dialled from country A to another country (country B). This is followed 179 // by the country code for country B. Note that some countries may have more 180 // than one international prefix, and for those cases, a regular expression 181 // matching the international prefixes will be stored in this field. 182 optional string international_prefix = 11; 183 184 // If the international prefix that we want to use when formatting the number 185 // for out-of-country dialling contains non-digit symbols, or there is more 186 // than one international prefix is present, a preferred prefix can be 187 // specified here for out-of-country formatting purposes. If this field is 188 // not present, and multiple international prefixes are present, then "+" 189 // will be used instead. 190 optional string preferred_international_prefix = 17; 191 192 // The national prefix of country A is the number that needs to be dialled 193 // before the national significant number when dialling internally. This 194 // would not be dialled when dialling internationally. For example, in New 195 // Zealand, the number that would be locally dialled as 09 345 3456 would be 196 // dialled from overseas as +64 9 345 3456. In this case, 0 is the national 197 // prefix. 198 optional string national_prefix = 12; 199 200 // The preferred prefix when specifying an extension in this country. This is 201 // used for formatting only, and if this is not specified, a suitable default 202 // should be used instead. For example, if you wanted extensions to be 203 // formatted in the following way: 204 // 1 (365) 345 445 ext. 2345 205 // " ext. " should be the preferred extension prefix. 206 optional string preferred_extn_prefix = 13; 207 208 // This field is used for cases where the national prefix of a country 209 // contains a carrier selection code, and is written in the form of a 210 // regular expression. For example, to dial the number 2222-2222 in 211 // Fortaleza, Brazil (area code 85) using the long distance carrier Oi 212 // (selection code 31), one would dial 0 31 85 2222 2222. Assuming the 213 // only other possible carrier selection code is 32, the field will 214 // contain "03[12]". 215 // 216 // When it is missing from the XML file, this field inherits the value of 217 // national_prefix, if that is present. 218 optional string national_prefix_for_parsing = 15; 219 220 // This field is only populated and used under very rare situations. 221 // For example, mobile numbers in Argentina are written in two completely 222 // different ways when dialed in-country and out-of-country 223 // (e.g. 0343 15 555 1212 is exactly the same number as +54 9 343 555 1212). 224 // This field is used together with national_prefix_for_parsing to transform 225 // the number into a particular representation for storing in the phonenumber 226 // proto buffer in those rare cases. 227 optional string national_prefix_transform_rule = 16; 228 229 // Specifies whether the mobile and fixed-line patterns are the same or not. 230 // This is used to speed up determining phone number type in countries where 231 // these two types of phone numbers can never be distinguished. 232 optional bool same_mobile_and_fixed_line_pattern = 18 [default=false]; 233 234 // Note that the number format here is used for formatting only, not parsing. 235 // Hence all the varied ways a user *may* write a number need not be recorded 236 // - just the ideal way we would like to format it for them. When this element 237 // is absent, the national significant number will be formatted as a whole 238 // without any formatting applied. 239 repeated NumberFormat number_format = 19; 240 241 // This field is populated only when the national significant number is 242 // formatted differently when it forms part of the INTERNATIONAL format 243 // and NATIONAL format. A case in point is mobile numbers in Argentina: 244 // The number, which would be written in INTERNATIONAL format as 245 // +54 9 343 555 1212, will be written as 0343 15 555 1212 for NATIONAL 246 // format. In this case, the prefix 9 is inserted when dialling from 247 // overseas, but otherwise the prefix 0 and the carrier selection code 248 // 15 (inserted after the area code of 343) is used. 249 // Note: this field is populated by setting a value for <intlFormat> inside 250 // the <numberFormat> tag in the XML file. If <intlFormat> is not set then it 251 // defaults to the same value as the <format> tag. 252 // 253 // Examples: 254 // To set the <intlFormat> to a different value than the <format>: 255 // <numberFormat pattern=....> 256 // <format>$1 $2 $3</format> 257 // <intlFormat>$1-$2-$3</intlFormat> 258 // </numberFormat> 259 // 260 // To have a format only used for national formatting, set <intlFormat> to 261 // "NA": 262 // <numberFormat pattern=....> 263 // <format>$1 $2 $3</format> 264 // <intlFormat>NA</intlFormat> 265 // </numberFormat> 266 repeated NumberFormat intl_number_format = 20; 267 268 // This field is set when this country is considered to be the main country 269 // for a calling code. It may not be set by more than one country with the 270 // same calling code, and it should not be set by countries with a unique 271 // calling code. This can be used to indicate that "GB" is the main country 272 // for the calling code "44" for example, rather than Jersey or the Isle of 273 // Man. 274 optional bool main_country_for_code = 22 [default=false]; 275 276 // This field is populated only for countries or regions that share a country 277 // calling code. If a number matches this pattern, it could belong to this 278 // region. This is not intended as a replacement for IsValidForRegion since a 279 // matching prefix is insufficient for a number to be valid. Furthermore, it 280 // does not contain all the prefixes valid for a region - for example, 800 281 // numbers are valid for all NANPA countries and are hence not listed here. 282 // This field should be a regular expression of the expected prefix match. 283 // It is used merely as a short-cut for working out which region a number 284 // comes from in the case that there is only one, so leading_digit prefixes 285 // should not overlap. 286 optional string leading_digits = 23; 287 288 // This field is set when this country has implemented mobile number 289 // portability. This means that transferring mobile numbers between carriers 290 // is allowed. A consequence of this is that phone prefix to carrier mapping 291 // is less reliable. 292 optional bool mobile_number_portable_region = 32 [default=false]; 293 294 reserved 26; 295 reserved "leading_zero_possible"; 296} 297 298message PhoneMetadataCollection { 299 repeated PhoneMetadata metadata = 1; 300} 301