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_formatting_rule is defined specifically for this
86  // NumberFormat.
87  optional bool national_prefix_optional_when_formatting = 6;
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
96message 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
116message 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
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".
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;
141  optional PhoneNumberDesc carrier_specific = 31;
142
143  // The rules here distinguish the numbers that are only able to be dialled
144  // nationally.
145  optional PhoneNumberDesc no_international_dialling = 24;
146
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
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.
157  optional int32 country_code = 10;
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.
164  optional string international_prefix = 11;
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.
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>
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];
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];
278}
279
280message PhoneMetadataCollection {
281  repeated PhoneMetadata metadata = 1;
282}
283