Electronic address

Meaning & purpose

An electronic address will generally contain a URI pointing to the object being described, although it can also contain an email or other electronic address (fax, telephone and mobile numbers are recorded in the Physical Address element). However, in the case of a service it is possible to describe the service in terms of its base URL using the Value element and using the Arg element to describe the service arguments. 

The Electronic element is contained within the Address wrapper element (itself contained within Location) and records the electronic address of the registry object. Electronic addresses are preferred over physical addresses or spatial locations.

Electronic has a number of child elements:

• a Value containing a URI representing the electronic address (required)
• a Title for the electronic address target (optional)
• Notes providing any information relevant to the electronic element (optional)
• the MediaType(s) of the electronic target formatted in accordance with the IANA standard media-types (optional)
• the ByteSize of the electronic target (optional)
• Arg to describe the arguments for a machine-to-machine service (optional, services only). If Arg is used, the attributes @required and @type are required, and @use is optional.

Electronic address attributes

Electronic Address Type

An Electronic Address Type is optional. If used, preferably specify a type from the Electronic Address Type vocabulary:

Electronic Target attribute (collections only)

A Target attribute is optional. Preferably use one of the following values to indicate the function served by the URL within the Value child element:

Arg attributes (services only)

Arguments can apply to the URI contained in the Value element within Electronic. If the Arg element is used, attributes @required and @type must be recorded, and @use is optional.

Use in Research Data Australia

Electronic addresses are displayed in Research Data Australia for use in accessing collections or services, contacting parties, or obtaining more information about research domain activities or entities. 

URIs and email addresses recorded in Electronic are displayed as active hyperlinks in Research Data Australia. On collection view pages, these are accessed via the "Access the data" button.

Arguments are not displayed in Research Data Australia as they are intended for use in machine-to-machine services.

Best practice

Collections

The access point for openly available online collections will usually be a URI recorded in Value, e.g. a URI to a landing page in a repository, or a URL that triggers a direct download of data files. 

The Target attribute enables a user to know whether the URL will trigger a direct download of data files, or send them to a metadata landing page (usually in the source repository) from which the data may be downloaded. Landing pages may include useful information such as links to data definitions, analytical methodologies and extended conditions of use. When a link in the Value element directly downloads the data, this additional metadata may not be exposed to the searcher. However, if a direct download from Research Data Australia is preferred, it is possible to provide additional information about the file(s) to be downloaded in Title, MediaType, ByteSize and Notes (see second XML example below).  

For collections with mediated access or collections of physical objects, an appropriate electronic address is an email address of a person or organisation that can respond to enquiries about access. 

Services

Web services, software and workflows

Electronic should contain a URI in the Value element that provides access to the service. For web services in particular, it is a URI that can be processed by a client according to the service protocol (service endpoint).

For online services (in which the service call URL contains service arguments), use the Arg child element in addition to the Value element, to differentiate between a base URL and the service arguments. The Arg element indicates whether each of the URL arguments is required or optional, whether they are plain text or embedded objects, and whether they are inline (embedded in the base URL) or key-value pairs in a HTTP query. The Arg element does not describe the semantics of the arguments, and should not be treated as a substitute for linking to protocol documentation for the service in RelatedInfo. Where a collection is made available via a service, the record describing the collection should include the URL to the service endpoint from which the collection can be directly accessed. The Value element can also be used to specify the location of a service's description. This can be done by providing the service's base URL as well as the additional service arguments that are required to access such a description - for example, where appending 'WSDL' to a service URL returns a description of that service in WSDL format.

An email address can also be provided as a contact for arranging access to the service.

Offline services

A URL is not acceptable as a location, because an instrument home page does not provide direct access to the service the way an RSS feed address or a search query does. Web pages about the service should be recorded in the RelatedInfo element, just as they are for online services.  

An email address (and/or physical address) should be provided instead to allow users to gain access to the offline service.

Activities 

• Electronic addresses are preferred over physical addresses, e.g. a project web page URL, and/or the email address of a person or organisation that can respond to enquiries.

Parties

• Electronic addresses are preferred over physical addresses, e.g. the URL of a personal profile, and/or an email address. 

XML encoding examples

<location>
 <address>
  <electronic type="url" target="landingPage">
   	<value>http://www.datadryad.org/resource/doi:10.5061/dryad.32r3q</value>
  </electronic>
 </address>
</location>

<location>
 <address>
  <electronic type="url" target="directDownload">
   	<value>http://www.ga.gov.au/corporate_data/64739/64739_sh50-04_kml.zip</value>
  	<title>Youanmi Map Series</title>
  	<mediaType>application/zip/kml</mediaType>
  	<byteSize>5 MB</byteSize>
  </electronic>
 </address>
</location>

<location>
 <address>
	<electronic type="url">
		<value>http://services.ands.org.au/pids/mint</value>
		<arg required="true" type="string" use="keyValue">type</arg>
		<arg required="true" type="string" use="keyValue">value</arg>
		<arg required="false" type="string" use="keyValue">index</arg>
	</electronic>
 </address>
</location>

<location>
  <address>
      <electronic type="url">
            <value>https://sarigdata.pir.sa.gov.au/nvcl/geoserver/wfs</value>
       </electronic>
       <electronic type="other">
            <value>WFS</value>
            <arg type="string" required="true" use="keyValue">service</arg>
       </electronic>
       <electronic type="other">
            <value>1.1.0</value>
            <arg type="string" required="true" use="keyValue">version</arg>
       </electronic>
          <electronic type="other">
            <value>GetCapabilities</value>
            <arg type="string" required="true" use="keyValue">request</arg>
       </electronic>
       <electronic type="other">
            <value>DescribeFeatureType</value>
            <arg type="string" required="true" use="keyValue">request</arg>
       </electronic>
       <electronic type="other">
            <value>GetFeature</value>
            <arg type="string" required="true" use="keyValue">request</arg>
       </electronic>
   </address>
</location>

Change history