Merge pull request #137 from ga4gh/issue-128

Issue #128: Create separate email and url fields

search-api.md

@@ -41,11 +41,12 @@ After receiving a request, the remote server can respond in one of two ways:
     "contact" : {
       "name" : "Full Name",
       "institution" : "Contact Institution",
+      "href" : <URL>,
+      "email" : "full.name@institution.edu",
       "roles" : [
         "clinician"|"researcher"|"patient",
         …
-      ],
-      "href" : <URL>
+      ]
     },
 
     "species" : <NCBI taxon identifier>,
@@ -117,15 +118,16 @@ After receiving a request, the remote server can respond in one of two ways:
 #### Contact
 * ***Mandatory***
 * The contact information describes how the eventual recipient of the match response can contact the owner of the matched patient record to follow-up on the match.
-  1. `name` : The human-readable name of the person or organization that the user is contacting with the provided URL. A transparent string, limited to 255 characters in utf-8. (***Mandatory***)
-  1. `institution` : The human-readable institution of the contact person, if available. A transparent string, limited to 255 characters in utf-8. (*Optional*)
-  1. `roles` : A list of roles of the contact person. These may be self-declared by the submitting user, and might not have been verified by the sending server. (*Optional*) (*since v1.1)
+  * `name` : The human-readable name of the person or organization that the user is contacting with the provided URL. A transparent string, limited to 255 characters in utf-8. (***Mandatory***)
+  * `institution` : The human-readable institution of the contact person, if available. A transparent string, limited to 255 characters in utf-8. (*Optional*)
+  * `roles` : A list of roles of the contact person. These may be self-declared by the submitting user, and might not have been verified by the sending server. (*Optional*) (*since v1.1)
     * `clinician`: The contact person is a clinician responsible for the patient's care
     * `researcher`: The contact person is a researcher with the necessary consent to submit the patient record
     * `patient`: The contact person is the patient or a caregiver for the patient
-  1. `href` : A public (no login required) URL for contacting the owner of the patient record to follow up with a match. This must be a valid URL (of the form `<scheme>:<address>`), and could take a number of forms: (***Mandatory***)
-    * an `HTTP` URL: in this case, the URL could be a contact form which would allow the user to contact the owner of the matched patient.
-    * a `mailto` URL: in this case, the URL could be a (potentially-anonymized) email address to contact regarding the patient match.
+  * `href` : A public (no login required) URL for contacting the owner of the patient record to follow up with a match. This must be a valid URL (of the form `<scheme>:<address>`), and could take a number of forms: (***Mandatory***)
+    * An `HTTP` URL: in this case, the URL could be a contact form which would allow the user to contact the owner of the matched patient.
+    * A `mailto` URL: in this case, the URL could be a (potentially-anonymized) email address to contact regarding the patient match. It is preferred to use the `email` field for this purpose.
+  * `email` : A (potentially-anonymized) email address for contacting the owner of the patient record to follow up with a match. (*Optional*) (*since v1.1*)
 
 #### Species
 * *Optional*