Create hierarchy of Contact information (#8)

datatypes/Contact_Information.md

@@ -2,7 +2,7 @@
 
 ## Definition
 The contact information assigned to an [Agent](../entities/Organisation_Unit.md). The contact information might be 
-Postal address, Visiting address, Email address, Telephone number, Website URL
+Physical Address (Postal address, Visiting address) or Electronic Address (Email address, Telephone number, Website URL, etc.)
 
 ## Components
 - postalAddress : [Postal Address](../datatypes/Postal_Address.md)

datatypes/Electronic_Address.md

@@ -0,0 +1,11 @@
+# Electronic Address
+
+## Definition
+An electronic address assigned to an [Agent](../entities/Organisation_Unit.md). 
+
+## Specialization of
+[Contact Information](../datatypes/Contact_Information.md)
+
+## Note
+An electronic address might be [Email address](../datatypes/Email_Address.md), [Telephone number](../datatypes/Telephone_Number.md), [Website URL](../datatypes/Website_Address.md).
+Moreover, additional subtypes of Electronic Address can be created in CERIF modules. 

datatypes/Email_Address.md

@@ -0,0 +1,21 @@
+# Email Address
+
+## Definition
+An email address assigned to an [Agent](../entities/Organisation_Unit.md). 
+
+## Specialization of
+[Electronic Address](../datatypes/Electronic_Address.md)
+
+## Based on
+[URI](../datatypes/URI.md)
+
+## Restrictions
+1. The URI must start with `mailto:`
+2. The rest of the URI must match the regular expression<sup>[1](#fn1)</sup>: `^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$`
+
+---
+## Matches
+1. Close match of [Schema.org Email](https://schema.org/email)
+
+## References
+<a name="fn1">\[1\]</a> Email address validation https://regexr.com/3e48o

datatypes/Phone_Number.md

@@ -0,0 +1,25 @@
+# Phone Number
+
+## Definition
+A phone number assigned to an [Agent](../entities/Organisation_Unit.md). 
+
+## Specialization of
+[Electronic Address](../datatypes/Electronic_Address.md)
+
+## Based on
+[URI](../datatypes/URI.md)
+
+## Restrictions
+1. The URI must match RFC 3966 specification <sup>[1](#fn1)</sup>
+
+## Examples
+- `tel:+1-201-555-0123` - This URI points to a full phone number. 
+- `tel:863-1234;phone-context=+1-914-555` - The URI describes a local
+  phone number that is valid within a particular phone prefix.
+
+---
+## Matches
+1. Close match of [Schema.org Phone](https://schema.org/telephone)
+
+## References
+<a name="fn1">\[1\]</a> The tel URI for Telephone Numbers https://datatracker.ietf.org/doc/html/rfc3966

datatypes/Physical_Address.md

@@ -0,0 +1,12 @@
+# Physical Address
+
+## Definition
+The location assigned to an [Organisation Unit](../entities/Organisation_Unit.md) or some other CERIF entity instance.
+
+## Notes
+Please note there are two specializations of this data type providing more or less structured details about a physical
+address [Simple Physical Address](../datatypes/Simple_Physical_Address.md) and [Structured Physical Address](../datatypes/Structured_Physical_Address.md)
+
+## Components
+- country : [Country](../datatypes/Country.md)
+

datatypes/Postal_Address.md

@@ -1,11 +1,15 @@
 # Postal Address
 
 ## Definition
-The location assigned to an [Organisation Unit](../entities/Organisation_Unit.md) or some other CERIF entity instance.
+A postal address assigned to an [Agent](../entities/Organisation_Unit.md). 
 
-## Notes
-Please note there are two specializations of this data type providing more or less structured details about a postal
-address [Simple Postal Address](../datatypes/Simple_Postal_Address.md) and [Structured Postal Address](../datatypes/Structured_Postal_Address.md)
+## Specialization of
+[Contact Information](../datatypes/Contact_Information.md)
 
 ## Components
-- country : [Country](../datatypes/Country.md)
+- physical address : [Physical Address](../datatypes/Physical_Address.md)
+
+---
+## Matches
+1. Close match of [Schema.org home location](https://schema.org/homeLocation)
+2. Close match of [Schema.org address](https://schema.org/address)

datatypes/Simple_Postal_Address.md → datatypes/Simple_Physical_Address.md

@@ -1,15 +1,15 @@
 # Simple Postal Address
 
 ## Definition
-This data type is used when a string representation of postal address is used.
+This data type is used when a string representation of physical address is used.
 
 ## Notes
 The main intended usage of multiple strings for different languages is to allow the representation of the addresses in different scripts, allowing for transliterations.
 
 ## Specialization of
-[Postal Address](../datatypes/Postal_Address.md)
+[Physical Address](../datatypes/Physical_Address.md)
 
 ## Components
-- those inherited from [Postal Address](../datatypes/Postal_Address.md#components)
+- those inherited from [Physical Address](../datatypes/Physical_Address.md#components)
 - address : [Multilingual String](../datatypes/Multilingual_String.md)
 

datatypes/Structured_Postal_Address.md → datatypes/Structured_Physical_Address.md

@@ -1,19 +1,21 @@
 # Structured Postal Address
 
 ## Definition
-This data type is used when a structured representation of postal address is used.
+This data type is used when a structured representation of physical address is used.
 
 ## Notes
 The main intended usage of multiple strings for different languages is to allow the representation of the addresses in different scripts, allowing for transliterations.
 
 ## Specialization of
-[Postal Address](../datatypes/Postal_Address.md)
+[Physical Address](../datatypes/Physical_Address.md)
 
 ## Components
-- those inherited from [Postal Address](../datatypes/Postal_Address.md#components)
+- those inherited from [Physical Address](../datatypes/Physical_Address.md#components)
 - street : [Multilingual String](../datatypes/Multilingual_String.md)
 - city : [Multilingual String](../datatypes/Multilingual_String.md)
 - ZIP code: [Multilingual String](../datatypes/Multilingual_String.md)
 - stateOrProvince: [Multilingual String](../datatypes/Multilingual_String.md)
 
-
+---
+## Matches
+1. Close match of [Schema.org Postal address](https://schema.org/PostalAddress)

datatypes/Visiting_Address.md

@@ -0,0 +1,14 @@
+# Visiting Address
+
+## Definition
+A visiting address assigned to an [Agent](../entities/Organisation_Unit.md). 
+
+## Specialization of
+[Contact Information](../datatypes/Contact_Information.md)
+
+## Components
+- physical address : [Physical Address](../datatypes/Physical_Address.md)
+
+---
+## Matches
+1. Close match of [Schema.org work location](https://schema.org/workLocation)

datatypes/Website_Address.md

@@ -0,0 +1,20 @@
+# Website Address
+
+## Definition
+A website address assigned to an [Agent](../entities/Organisation_Unit.md). 
+
+## Specialization of
+[Electronic Address](../datatypes/Electronic_Address.md)
+
+## Based on
+[URI](../datatypes/URI.md)
+
+## Restrictions
+1. The URI must match the regular expression<sup>[1](#fn1)</sup>: `[(http(s)?):\/\/(www\.)?a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)`
+
+---
+## Matches
+1. Close match of [Schema.org URL](https://schema.org/url)
+
+## References
+<a name="fn1">\[1\]</a> URL validation https://regexr.com/39nr7

diagrams/core.puml

@@ -330,34 +330,67 @@
     }
 !endsub
 
-!startsub Postal_Address
-    datatype("Postal_Address") {
+!startsub Physical_Address
+    datatype("Physical_Address") {
         country : Country
     }
 
-    datatype("Simple_Postal_Address") {
+    datatype("Simple_Physical_Address") {
         address : Multilingual_String
     }
 
-    datatype("Structured_Postal_Address") {
+    datatype("Structured_Physical_Address") {
         street : Multilingual_String
         city : Multilingual_String
         zipCode : Multilingual_String
     }
 
-     "Postal_Address" <|-d- "Simple_Postal_Address"
-     "Postal_Address" <|-d- "Structured_Postal_Address"
+     "Physical_Address" <|-d- "Simple_Physical_Address"
+     "Physical_Address" <|-d- "Structured_Physical_Address"
 
      datatype("Contact_Information") {
-         postalAddress : Postal_Address
-         visitingAddress : Postal_Address
+         postalAddress : Physical_Address
+         visitingAddress : Physical_Address
          phone : String
          emailAddress : URI
          webSiteURL : URI
      }
 
-     "Contact_Information" --> "Postal_Address" : postalAddress >
-     "Contact_Information" --> "Postal_Address" : visitingAddress >
+     datatype("Postal_Address") {
+          physicalAddress : Physical_Address
+     }
+
+     "Contact_Information" <|-d- "Postal_Address"
+     "Postal_Address" --> "1" "Physical_Address"
+
+
+     datatype("Visiting_Address") {
+          physicalAddress : Physical_Address
+     }
+
+     "Contact_Information" <|-d- "Visiting_Address"
+     "Visiting_Address" --> "1" "Physical_Address"
+
+     datatype("Electronic_Address") {
+     }
+
+     "Contact_Information" <|-d- "Electronic_Address"
+
+     datatype("Email_Address") {
+     }
+
+     "Electronic_Address" <|-d- "Email_Address"
+
+     datatype("Website_Address") {
+     }
+
+     "Electronic_Address" <|-d- "Website_Address"
+
+     datatype("Phone_Number") {
+     }
+
+     "Electronic_Address" <|-d- "Phone_Number"
+
 
 !endsub
 
@@ -368,8 +401,8 @@
     }
 !endsub
 
-!startsub Postal_Address
-    "Postal_Address" o..> "Country" : country >
+!startsub Physical_Address
+    "Physical_Address" o..> "Country" : country >
 !endsub
 
 !startsub Affiliation_Statement

guidelines/DESCRIBING_DATATYPES.md

@@ -26,11 +26,12 @@ Use the [template file](./TEMPLATE_DATATYPE_COMPLEX.md) as a starting point.
 ### For datatypes without components (xsd:simpleType)
 1. **Definition**: The scope of the datatype and its meaning.
 2. **Notes**: An additional description to communicate the purpose of the datatype.
-3. **Based on**: The link to the base datatype (the datatype this type restricts)
-4. **Restrictions**: An enumerated list of restrictions that apply (e.g. maximum length, regular expression, possibly also algorithmic restrictions such as checksums)
-5. **Examples**: A list of examples
+3. **Specialization of**: The link to the super datatype (the datatype this type extends)
+4. **Based on**: The link to the base datatype (the datatype this type restricts)
+5. **Restrictions**: An enumerated list of restrictions that apply (e.g. maximum length, regular expression, possibly also algorithmic restrictions such as checksums)
+6. **Examples**: A list of examples
 ---
-6. **Matches**: Describe any external datatypes this datatype matches.
-7. **References**: References to external resources in case these are referenced.
+7. **Matches**: Describe any external datatypes this datatype matches.
+8. **References**: References to external resources in case these are referenced.
 
 Use the [template file](./TEMPLATE_DATATYPE_SIMPLE.md) as a starting point.

guidelines/TEMPLATE_DATATYPE_SIMPLE.md

@@ -9,6 +9,9 @@ The scope of the datatype and its meaning.<sup>[1](#fn1)</sup>
 ## Notes
 An additional description to communicate the purpose of the datatype.
 
+## Specialization of
+[XXX](../datatypes/XXX.md)
+
 ## Based on
 [XXX](../datatypes/XXX.md)