Skip to content
Permalink
Browse files

Initial revision

  • Loading branch information...
wrygiel committed Oct 26, 2016
0 parents commit cf9b101270185d5986692c1a1295b6e57ef8eff9
Showing with 173 additions and 0 deletions.
  1. +81 −0 README.md
  2. +92 −0 schema.xsd
@@ -0,0 +1,81 @@
EWP Phone Number Types
======================

* [What is the status of this document?][statuses]
* [See the index of all other EWP Specifications][develhub]


Summary
-------

This repository contains XML Schemas used in EWP APIs for encoding phone and
fax numbers. It follows the same [versioning rules][compat-rules] as all EWP
APIs do. Other projects are welcome to reuse this schema, along with its
namespace. We are also open to suggestions of extending it.


About this data type
--------------------

### About E.164 standard

As opposed to [addresses][specs-address], phone number formats were much
easier to decide upon, because there already exists an international standard
for handling those.

You can read more on this standard:

* [on our issue pages][discussion],
* [on Twilio's support pages][twilio-article],
* [on Wikipedia](https://en.wikipedia.org/wiki/E.164).


### Compatibility and conversions

There are free libraries, such as Google's [libphonenumber]
(https://github.com/googlei18n/libphonenumber), which allow you to convert
between national phone numbers and E.164. This means that clients will be able
to "pretty print" such number, and server should also be able to easily provide
them in E.164 format.

However, if - for some reason - the server is not able to convert its data to
E.164 format, we allow it to be provided in unformatted way too (with the
`<other-format>` element).


The Schema
----------

See attached [`schema.xsd`](schema.xsd) file.


Examples
--------

```xml
<phone>
<e164>+4723456789</e164>
</phone>
```

```xml
<phone>
<e164>+4722222222</e164>
<ext>3407</ext>
</phone>
```

```xml
<fax>
<!-- To be avoided. -->
<other-format>(23) 456789</other-format>
</fax>
```


[develhub]: http://developers.erasmuswithoutpaper.eu/
[statuses]: https://github.com/erasmus-without-paper/ewp-specs-management#statuses
[compat-rules]: https://github.com/erasmus-without-paper/ewp-specs-architecture/#backward-compatibility-rules
[discussion]: https://github.com/erasmus-without-paper/ewp-specs-architecture/issues/15
[specs-address]: https://github.com/erasmus-without-paper/ewp-specs-types-address
[twilio-article]: https://support.twilio.com/hc/en-us/articles/223183008-Formatting-International-Phone-Numbers
@@ -0,0 +1,92 @@
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xml="http://www.w3.org/XML/1998/namespace"
xmlns:ewp="https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/stable-v1/common-types.xsd"
elementFormDefault="qualified"

targetNamespace="https://github.com/erasmus-without-paper/ewp-specs-types-phonenumber/tree/master"
xmlns="https://github.com/erasmus-without-paper/ewp-specs-types-phonenumber/tree/master"
>
<!-- WRTODO: Replace all occurrences of 'master' (in all projects) with 'stable-v1' upon release. -->

<xs:import
schemaLocation="../ewp-specs-architecture/common-types.xsd"
namespace="https://github.com/erasmus-without-paper/ewp-specs-architecture/blob/stable-v1/common-types.xsd"
/> <!-- WRTODO: absolute paths! -->

<xs:annotation>
<xs:documentation>
This schema is a part of the Erasmus Without Paper project. Before you start
using it, make sure you have read the general rules described here:

http://developers.erasmuswithoutpaper.eu/
</xs:documentation>
</xs:annotation>

<xs:complexType name="PhoneNumber">
<xs:annotation>
<xs:documentation>
A phone number. Whenever possible, this SHOULD be provided in E.164 format
(with the leading "+" sign).

More information and reasoning here:
https://github.com/erasmus-without-paper/ewp-specs-architecture/issues/15
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name='e164' minOccurs="0" maxOccurs="1">
<xs:annotation>
<xs:documentation>
Phone number in the E.164 format, with the leading "+" sign.

This MUST be a "plain" E.164 string, without any extensions. Extensions are
transferred in the `ext` element instead.
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:pattern value="\+[0-9]{1,15}"></xs:pattern>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name='ext' minOccurs="0" maxOccurs="1">
<xs:annotation>
<xs:documentation>
Extension number.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name='other-format' minOccurs="0" maxOccurs="1" type="xs:string">
<xs:annotation>
<xs:documentation>
If, for some reason, you are unable to provide a valid phone number with the
`e164` and `ext` elements, then you can provide it in any other format here.
Server developers MAY also provide both - E.164 along with the original
other-format - which might be useful for debugging on-the-fly conversion.

Client developers MAY ignore `other-format` numbers. Server developers SHOULD
use `other-format` only as a last resort.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>

<xs:element name="phone-number" type="PhoneNumber">
<xs:annotation>
<xs:documentation>
A phone number.
</xs:documentation>
</xs:annotation>
</xs:element>

<xs:element name="fax-number" type="PhoneNumber">
<xs:annotation>
<xs:documentation>
A fax number.
</xs:documentation>
</xs:annotation>
</xs:element>

</xs:schema>

0 comments on commit cf9b101

Please sign in to comment.
You can’t perform that action at this time.