Add Markdown schema and protobuf implementatiion for phone number.

proto/aep-type/aep/type/phone_number.proto

@@ -0,0 +1,121 @@
+// This message is derived from an existing Apache 2.0-licensed work that
+// comes with the following copyright notice:
+//
+// Copyright 2021 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 aep.type;
+
+option cc_enable_arenas = true;
+option go_package = "aep.dev/type";
+option java_multiple_files = true;
+option java_outer_classname = "PhoneNumberProto";
+option java_package = "dev.aep.type";
+option objc_class_prefix = "AEP";
+
+import "buf/validate/validate.proto";
+
+// An object representing a phone number in a way 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, you will need a library like
+// https://github.com/google/libphonenumber.
+//
+// For instance, in Java this would be:
+//
+//    ```java
+//    dev.aep.type.PhoneNumber wireProto =
+//        dev.aep.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());
+//    }
+//    ````
+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
+        [(buf.validate.field).string = { pattern: "^([A-Z]{2}|[0-9]{3})$" }];
+
+    // Required. The short code digits, without a leading plus ('+') or country
+    // calling code, e.g. "611".
+    string number = 2 [(buf.validate.field).string = { pattern: "^[0-9]+$" }];
+  }
+
+  // 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
+        [(buf.validate.field).string = { pattern: "^\\+[0-9]{1,3}[0-9]+$" }];
+
+    // 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 [(buf.validate.field).string = { max_len: 40 }];
+}

proto/aep-type/buf.lock

@@ -0,0 +1,8 @@
+# Generated by buf. DO NOT EDIT.
+version: v1
+deps:
+  - remote: buf.build
+    owner: bufbuild
+    repository: protovalidate
+    commit: 12f9cba37c9d49eeb6827dde227d6031
+    digest: shake256:a9470135a1736bdb74396e35342b4431b0bf3a5e7a2198fb77f49be46af744aae134f8e0593683216e836f1f0a551ccf86a9f8857c6829b8d33f4b604602a5ff

proto/aep-type/buf.yaml

@@ -8,3 +8,5 @@ lint:
     - DEFAULT
   except:
    - PACKAGE_VERSION_SUFFIX
+deps:
+  - buf.build/bufbuild/protovalidate

schemas/type/phone_number.md

@@ -0,0 +1,89 @@
+# PhoneNumber
+
+The `PhoneNumber` type represents a phone number.
+
+A `PhoneNumber` represents a phone number in a way 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, you will need a library like
+https://github.com/google/libphonenumber.
+
+For instance, in Java this would be:
+
+```java
+dev.aep.type.PhoneNumber wireProto =
+    dev.aep.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());
+}
+```
+
+## Schema
+
+### `PhoneNumber`
+
+A `PhoneNumber` has two main fields, exactly one of which must be populated:
+
+- A `ShortCode` field named `short_code` (see below for details on `ShortCode`).
+- A string field named `e164_number`, representing an [E164][] number.
+
+  This field is formatted 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.
+
+A `PhoneNumber` also has a string `extension` field, which is optional. An
+`extension` can be no longer than 40 characters. Typically, this is a series of
+numberical digits, but it may also include dialing characters such as `#`, `,`,
+`p`, and `w`.
+
+An `extension` **must not** include a leading "x" that services simply to
+indicate that the value is a phone number extension; this is implicit in the
+field itself.
+
+### `ShortCode`
+
+A `ShortCode` represents 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).
+
+A `ShortCode` has two fields, both of which are required:
+
+- A string field named `region_code`, representing a BCP-47 region code. This
+  must be exactly one of:
+  - Two alphabetical characters (such as "US"); OR
+  - Three numeric digits (such as "419").
+- A string field named `number`, comprising only numeric digits and representing
+  the actual number (such as "611").
+
+## Examples
+
+- `{short_code: {region_code: "US", number: "911"}}`
+- `{e164_number: "+15552220123"}`
+- `{e164_number: "+15552220123", extension: "123,,456"}`
+
+[E164]: https://en.wikipedia.org/wiki/E.164