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:
Other electronic address
Uniform Resource Locator
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:
Electronic URL value points to the metadata for the collection
Electronic URL value triggers a direct download
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.
indicates that the argument is required
indicates that the argument is optional
indicates the value of an argument is a plain text string
indicates the value of an argument is an object, most likely in serialised form
indicates the argument forms part of the base URL
indicates the argument is passed using key=value pairings in the query component of a URL
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.
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.
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.
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.
- 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.
- Electronic addresses are preferred over physical addresses, e.g. the URL of a personal profile, and/or an email address.
XML encoding examples
Example showing electronic access via a landing page
<location> <address> <electronic type="url" target="landingPage"> <value>http://www.datadryad.org/resource/doi:10.5061/dryad.32r3q</value> </electronic> </address> </location>
Example showing electronic access via a direct download
<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>
Example showing electronic address argument elements for a service
<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>
Example showing multiple arguments in separate electronic elements
<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>
|April 2010||Consultation draft|
|26 October 2010||RIF-CS 1.2 changes added|
|5 April 2011||Fax and voice types vocabulary and example removed - from RIF-CS version 1.2 these must be entered in the physical address part type element|
|21 Nov 2014||Added information about the @target attribute for data download. Removed reference to wdsl. These changes implemented with RIF-CS v1.6.0|
|16 Mar 2017||Incorporated information about the @arg attribute for services.|
|27 Jul 2018||Changed the reference to the "Go to Data Provider(s)" button in RDA to the "Access the data" button.|