IVOA

CEA Application Model: A model of an Application in the Common Application Architecture
Version 1.0

IVOA Working Draft 4 May, 2007

This version:
http://www.ivoa.net/Documents/WD/GWS/CEAApplicationDM-XXXX.html
Latest version:
http://www.ivoa.net/Documents/latest/CEAApplicationDM.html
Previous versions
Authors:
Paul Harrison, Editor
and the IVOA Grid and Web Services Working Group.

Abstract

This document describes the data model for an Application that is used in the Common Execution Architecture (CEA). In addition an XML encoding of this model is presented. The model is expressed by two schema, CEABase-v1.0.xsd which encodes the majority of the metadata and is included in the WSDL interface definition [CEAINT] and as a schema VOCEA-v1.0.xsd which defineds a standard for IVOA CEAApplication Metadata which can be used to describe the application in an IVOA interoperable registry.

Status of this document

This is an IVOA Working Draft for review by IVOA members and other interested parties. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use IVOA Working Drafts as reference materials or to cite them as other than "work in progress."

Parts that the editor considers should be removed from the document are marked in red with a strike through line, and parts to be expanded are in green

Comments on this document are due 15 December 2006 for consideration in the next version of this document. They should be sent to registry@ivoa.net, a mailing list with a public archive or on the VOApplication twiki discussion page. General discussion of related technology is also welcome on the Rwp03 wiki site.

A list of current IVOA Recommendations and other technical documents can be found at http://www.ivoa.net/Documents/.

Acknowledgements

This document has been developed with support from the UK Particle Physics and Astronomy Research Council (PPARC), and from the Eurpean Commission's Sixth Framework Program via the VOTech project.

Conformance-related definitions

The words "MUST", "SHALL", "SHOULD", "MAY", "RECOMMENDED", and "OPTIONAL" (in upper or lower case) used in this document are to be interpreted as described in IETF standard, RFC 2119 [RFC 2119].

The Virtual Observatory (VO) is general term for a collection of federated resources that can be used to conduct astronomical research, education, and outreach. The International Virtual Observatory Alliance (IVOA) is a global collaboration of separately funded projects to develop standards and infrastructure that enable VO applications.

Syntax Notation Using XML Schema

The eXtensible Markup Language, or XML, is document syntax for marking textual information with named tags and is defined by the World Wide Web Consortium (W3C) Recommendation, XML 1.0 [XML]. The set of XML tag names and the syntax rules for their use is referred to as the document schema. One way to formally define a schema for XML documents is using the W3C standard known as XML Schema [Schema].

This document defines the VOCEA and CEABase schema using XML Schema. The full Schema documents are listed in Appendix A and Appendix B. Parts of the schema appear within the main sections of this document; however, documentation nodes have been left out for the sake of brevity.

Reference to specific elements and types defined in the VOCEA schema include the namespaces prefix, cea, as in cea:CeaApplication (a type defined in the VOCEA schema). Use of the specific cea prefix in compliant instance documents is not required (the actual namespace "http://www.ivoa.net/xml/CEA/v1.0" could be assigned to any prefix); its use in this document is simply to indicate that it is an entity defined in the VOCEA schema. The prefixes for other namespaces are given within the folllowing table

Namespace prefixes used in this document
prefix namespace
cea http://www.ivoa.net/xml/CEA/v1.0
ceab http://www.ivoa.net/xml/CEA/base/v1.0
vr http://www.ivoa.net/xml/VOResource/v1.0
vs http://www.ivoa.net/xml/VODataService/v1.0
va http://www.ivoa.net/xml/VOApplication/v1.0

Note that as this document represents a draft the cea: and ceab: namespaces in attached schema and instance documents have the string "rc<n>" appended where "rc" stands for release candidate and <n> is an integer representing the iteration number of the release candidate draft of the associated namespace.

Contents

Introduction

The concept of an abstraction of implementation specific details from the creation of an astronomy specific computing grid was introduced in the IVOA Note "A Proposal for a Common Execution Architecture" [CEA] which described the motivation for and benefits of such an abstraction as well as the concrete schema and web interface definitions that were used by the Astrogrid [AG] implementation of the system at the time. The description of CEA is now split into two parts

  1. The data model for an application, as defined in this document. This model is a general description of what parameters a particular application can accept, and as such it may be regarded as a "language" that is implementation independent to describe at the user-level how the application should be called.
  2. A specific web interface (defined in the [CEAIMP] document) for remote invocation of applications that conform to the CEA. The web interface can take a tool XML instance document describing the desired application invocation and actually run the application and return the results in an asynchronous, secure fashion that is consistent with the Universal Worker Pattern ([UWS])

This split between the application model and interface emphasises the fact that the application model could be re-used in other circumstances.

The schema that are presented in this document represent an evolution of those presented in [CEA] that incorporates both

The CEA Application Data Model

As presented in [CEA] the basic model for an application is simply a process that can expose a number of "interfaces" which each may have a number of input and output parameters. This means that the UML domain model for the application description is relatively simple as displayed below;

CEA Application domain model

It is important to realise that the parameter definitions can be reused in multiple interfaces (indicated by the fact that the interfaces are aggregations of parameters) and that the final xml schema representation reflects this by defining all of the parameters for an application first, and then defining the interfaces which contain references to the original parameter definitions.

Design Aims

The main design aims are;

In addition the model also needs to be able to specify

More detail

This diagram does not show the full model that is expressed in the schema, however, a more detailed UML diagram to represent the all of types used in the Application Data model is in Appendix D. The additional complexity that is present in this diagram results from

Detailed Description of the CEABase Schema

The two major types within the schema are

  1. ApplicationDefinition - This is the description of an application
  2. Tool - This represents an invocation of an application.

ApplicationDefinition

The main type that is used to describe an application is the cea:CeaApplication which is derived from va:Application, which in turn is derived from vr:Resource. This means that the start of a such a description would be as below, where the elements possible in the region marked "..." are described in [VR] and [VA] - the CEA specific part starts with the <applicationDefinition> element.

Start of the CeaApplication definition
   <Resource xsi:type="cea:CeaApplication"
created="2005-09-09T12:28:16" updated="2005-09-09T12:28:16" status="active">
<title>SExtractor</title>
<shortName>SExtractor</shortName>
<identifier>ivo://org.astrogrid/SExtractor</identifier> ...

<applicationDefinition>

ApplicationType

Parameters

The first elemtent of the <applicationDefinition> is the <parameters> element. Parameters are defined once per application, and each parameter is defined with a <parameterDefinition> element which is of type ceab:BaseParameterDefinition, which in turn is derived from vs:BaseParam. This means that the possible attributes and sub-elements of the <parameterDefinition> are listed below.

id attribute

This is the identifier for the parameter - the references to parameters in the interfaces use this value as the parameter identifier.

type attribute

The type of a parameter is CEA is a rather broad concept, with the type ranging from standard atomic types, to aggregate 'types'. The choices were made based on an empirical survey of the most common kinds of parameter that occured in the original target application for CEA namely typical astronomical legacy command-line application. In this sense the types are not intended to be "complete", but to represent a useful subset of all possible types.

It should be noted that the formal type of the parameter value that is passed in the Common Exectution Connector [CEAINT] interface is always an xsd:string - any interpretation of this type information is done at the client or the server, but not by the transport protocol.

The choice of what type to declare a parameter is largely a matter of the how much processing or validation of the parameter that the application designer wants the CEA infrastructure to perform - it would be possible to delare just about any parameter as text of binary for instance, which would imply no validation or processing of the value by the CEA client or server.

The server side representation of the parameter is determined from the form of the defaultValue element. A concrete example of this is that a boolean value may be represented in many ways on the client as in the table below, but it might be that on the server side that only true/false can be understood, so the defaultValue would be declared 'true'. The server side treatment of parameters is largely implementation dependent, however, the treatment described in this paragraph is that performed by the 'Commandline Common Excecution Controller' [CEAIMP] and as such possibly should be addressed by a separate implementation defined attribute.

type Description String representation
integer an integer value  

real

a real value (any precision)  
complex a complex number pair  
text any data that could be interpreted as human readable text in a well known encoding.  
boolean a boolean value 0/1 true/false yes/no on /off
anyURI a string that could be interpreted as a URI.  
VOTable a VOTable conforming to the IVOA specification  
RA Right ascension sexagesimal allowed
Dec    
MJD Modified julian data  
DateTime A date and time in ISO 8601 format  
ADQL Astronomical  
binary arbitrary  
FITS a file conforming to the [FITS] standard  
xml arbitrary xml the schema for the xml is optionally indicated in the UType of the parameter

Future versions of the allowed enumerations for values of this attribute will be influenced by the work of other IVOA standards working groups, particularly in the areas of Semantics, Theory and Applications.

array attribute

If present this attribute specifies that the parameter is an array, and it also defines the shape and size of the array. This definition is essentially the same as for the arraySize attribute in VOTable [VOTABLE], where the first specified dimension changes fastest, and the final dimension can be specified as an asterisk which means unbounded, or an integer followed by an asterisk which means guarenteed to be less than or equal to the attribute.

example of the array attribute
  
array="64*10*x"

Note that strings (the text type above) do not follow the same conventions as VOTable in that they are not considered as arrays of characters.

name element

This is used to present a name of the parameter in a user interface - This is included because the id attribute of the parameter will often be tied to the name that the underlying application uses, and that name might not be very "human-readable".

description element

This can be used to present a human-readable description of the purpose and meaning of the parameter.

unit element

The physical unit of the parameter. The actual strings used to denote units follow the same conventions as for the unit attribute of [VOTABLE].

ucd element

A UCD for the parameter if appropriate.

UType element

The UType of the parameter if appropriate.

mimeType element

The mimeType of the parameter if appropriate.

defaultValue element

A default value for the parameter - note that this is simply for presentation to the user interface - in a tool element the value for the parameter should be explicitly given - it is not part of CEA that the parameter description will be reparsed to obtain a default value for a missing parameter.

optionList element

This can be used to specify that a parameter can have only an enumerated list of values. The client is expected to enforce this requirement.

example of the optionList
  
<optionList>
<optionVal>NONE</optionVal>
<optionVal>BLANK</optionVal>
<optionVal>CORRECT</optionVal>
</optionList>

 

range element

This element can be used to specify the range of values that a parameter may have

Interfaces

An application needs at least one interface to be callable. Interfaces are identified by their "id" attribute. The 4 possible sub-elements of the <interface> element are

The exact order and grouping of parameters within the input and output sections is made using the pref, pgroup and cgroupHead elements which are described in more detail below

pref

This element is the principal method of making a reference to a parameter definition, and the use is illustrated below.

A pref element referring to the corresponding parameterDefinition
      ...
            <parameterDefinition id="PHOT_APERTURES"
type="integer">
<name>Photometry apertures</name>
<description>
MAG_APER aperture diameter(s) in pixels
</description>
<ucd />
<defaultValue>5</defaultValue>
</parameterDefinition>
</parameters>
<interfaces>
<interfaceDefinition id="qa">
<input>
<pref maxOccurs="1" minOccurs="1"
ref="PHOT_APERTURES" /> ...

 

The ref attribute of the pref element must have a value that corresponds to the id attribute of a <parameterDefinition> to make a valid reference to a parameter in an interface, as illustrated by the blue text in the example above. In addition the <pref> element can have the following attribute

minOccurs
The minimum number of times that the parameter should occur in the interface. The default value is 1.
maxOccurs
The maximum number of times that the parameter should occur in the interace. A value of 0 is interpreted as the parameter being allowed to be repeated an unbounded number of times. The default value is 1.
hidden
If true this is a hint to a client side GUI builder that this parameter should be hidden

pgroup

A <pgroup> element can be used to group parameters in the interface. This grouping can be done for two primary reasons.

  1. To specify that a set of parameters should be repeated as a group
  2. To give hints to the client side GUI builder that the parameters should be presented to the used in a grouped fashion.

The example below shows that the 'targets' and 'matches' parameters should be repeated as a pairs (if at all, as minOccurs takes the default value of 1).

The use of pgroup to group parameter references, so that they need to be repeated in pairs.
               <input>
<pgroup maxOccurs="2">
<pref ref="targets" />
<pref ref="matches" />
</pgroup>
<pgroup>
<pref ref="matchRadius" />
<pref ref="radMax" />
</pgroup>

 

cgroupHead & cgroup

These constructs allow a set of alternative groups of parameters to be required dependent on the value of another parameter. In the example below different parameters need to be specified depending on the value of the 'output' parameter - if it takes on the value of "html" then a parameter called "htmlversion" will be required, and if it has the value "VOTABLE" a parameter 'votableserialization' will be required.

The use of a conditional group.
                  <cgroupHead ref="output" >
<cgroup name="html options">
<value>html</value>
<pref ref="htmlversion" />
</cgroup>
<cgroup name="votable options">
<value>VOTABLE</value>
<pref ref="votableserialization" />
</cgroup>
</cgroupHead>

 

As well as giving instruction to a client side GUI building tool, the cgroupHead and cgroup constructs should also be used by the server side CEA component to do basic validity checking on the parameters that it actually receives.

Tool

The ceab:Tool type represents an invocation of the application, i.e. it specifies which interface to use and supplies values for all of the necessary parameters. This is principally of interest of course when calling an application via the CEA interfaces and is discussed more fully in [CEAINT]. An important feature of CEA is that the parameter values that are passed to the server side CEA component are fully specified by this <tool> element, and the description of the application specified by ApplicationDefinition is used by the server side CEA component merely for validation purposes - no parameter value would be changed by the server side CEA component. The application that is to be run is identified by the id attribute and the particular interface by the interface attribute of the tool element.

pval

The <pval> element is the principal element that carries parameter values, which are always passed within a <value> element, whether directly or within an <array>. The schema type of the value element is always xs:string.

A complete tool invocation
<tool xsi:type="ceab:Tool" xmlns:ceab="http://www.ivoa.net/xml/CEA/base/v1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ivoa.net/xml/CEA/base/v1.0 ../v11/CEABase.xsd"
id="ivo://dummy" interface="test">
<input>
<pval id="p1">
<array>
<value>1</value>
<value>2</value>
</array>
</pval>
<pval id="p2">
<value>hello</value>
</pval>
</input>
<output>
<pval id="out" indirect="true">
<value>vos://org.test!vospace/mydata</value>
</pval>
</output>
</tool>

 

Note on ordering of parameter values.

Generating User Interfaces

Names and descriptions

Default Values

Default values where specified for parameter values are intended for client side GUI builders only, and are not substituted by the server side components for missing parameters.

Validity Checking

The client should attempt to perform validity checking on parameters wherever possible, however this is not manadatory as the server must perform validity checking of parameters and will reject requests to run applications with invalid parameter value specifications.

Repeatable parameters

Where a parameter is repeatable (or deletable) the GUI should attempt to inform the user of such a possibility to the user either by using some direct visual form such as an icon next to the parameter input widget, or by enabling or disabling a "repeat parameter" functionality in another GUI element such as a toolbar or pop-up menu when the parameter is selected.

Parameter Groups

One of the intentions of parameter groups is to provide formatting hints to a client producing an automatic user interface. The client should attempt to show this grouping by means of devices such as "tab panes".

needs diagram illustrating typical GUI widgets

Registering CEA Applications and CEA Services

To register CEA Applications and services, types from the VOCEA.xsd schema need to be used. The relationships between the types defined by that schema are illustrated below. The main type that is used to register the description of an application is a CeaApplication, which contains standard Resource metadata, as well as an <applicationDefinition > element which contains the actual CEA application description as detailed in the desciption of the CEABase schema above. A service that can run one or more of CEA Applications is registered with a Service type that has a <capability> element of type CeaCapability. The CeaCapability lists references to the ivoa identifiers of the CeaApplications that particular service can offer, as well as detailing which particular CEA interface can be used.

The preceding paragraph describes all of the structures necessary to register CEA applications and services, however there is one convenience type CeaApplicationExtension that can be useful in describing a family of similar applications. The CeaApplicationExtension defines a limited form of application description subclassing, in that it is assumed to inherit all of the parameter and interface definitions of the parent CeaApplication (the one referred to by the extends attribute). It is then allowed to define additional parameters and interfaces, but it should be considered an error if the CeaApplicationExtension tries to redefine an existing parameter.

Class diagram of CEA Registry Types

There is a fully annotated example of the registration entries for a CEA application and server in appendix C

Recommendations for Application Description Authors

Validation

Optional Parameters or different interfaces? TBC

Comparision with other "Parameter Models" TBC

There have been a number of other parameter systems implemented in astronomical software systems and it is worthwhile to see the ways in which CEA is different and also the features that CEA has copied to obtain a deeper understanding of the best ways to use the CEA Model.

AIPS

IRAF ICL

Starlink ADAM

 

Summary of updates since [CEA]

The following represent updates to the CEA Application model since the publication of the original IVOA Note [CEA].

Appendix A: The complete CEABase Schema

Note that this schema can be found on-line at http://www.ivoa.net/xml/CEABase/v1.0 (i.e. the target namespace can also be used as a URL for the schema.) This location should represent the definitive source, the schema is only copied below for completeness of this document.

Appendix B: The complete VOCEA Schema

Note that this schema can be found on-line at http://www.ivoa.net/xml/VOCEA/v1.0 (i.e. the target namespace can also be used as a URL for the schema.) This location should represent the definitive source, the schema is only copied below for completeness of this document.

The Complete VOCEA Schema

Appendix C: An example VOCEA Instance

Appendix D: Full UML diagram for VOCEA and CEABase schema

CEA Application Model FullThis diagram presents more detail than the average author of a CEA application definition will need to understand as instance documents typically have a simpler looking structure because of the choice of common element names. It is included as a aid to authors of CEA based service implementations where the detailed relationships could be more important.

Appendix : Change History

This is the first version that has been made public - it is derived from IVOA WG wiki content, and the original [CEA] document.

References

[RFC 2119]
Bradner, S. 1997. Key words for use in RFCs to Indicate Requirement Levels, IETF RFC 2119, http://www.ietf.org/rfc/rfc2119.txt
[RM]
Hanisch, Robert (ed.) 2004. Resource Metadata for the Virtual Observatory, Version 1.01, IVOA Recommendation, http://www.ivoa.net/Documents/REC/ResMetadata/RM-20040426.htm
[VR]
Plante, Ray (ed.) 2006. VOResource: an XML Encoding Schema for Resource Metadata, IVOA Working Draft, http://www.ivoa.net/Documents/latest/VOResource.html
[VA]
Harrison, Paul. (ed.) 2007. VOApplication: an XML Encoding Schema for Application Resource Metadata, IVOA Working Draft, http://www.ivoa.net/Documents/latest/VOApplicationDM.html
[VSTD]
Harrison, Paul. (ed.) 2007. VOStandard: an XML Encoding Schema for IVOA Standards, IVOA Working Draft, http://www.ivoa.net/Documents/latest/VOResource.html
[VOTABLE]
Ochsenbein & Williams. (eds.) 2004. VOTable Format Definition, version 1.1, http://www.ivoa.net/Documents/latest/VOT.html
[UCD]
Derriere et. al. 2004. An IVOA Standard for Unified Content Descriptors, version 1.10, http://www.ivoa.net/Documents/latest/UCD.html
 
[CEA]
Harrison, Paul. 2005. A Proposal for a Common Execution Architecture , IVOA Working Draft, http://www.ivoa.net/Documents/latest/CEA.html
[CEAINT]
Harrison, Paul. 2007. CEA Interfaces: How to Invoke Applications in the Common Execution Architecture, IVOA Working Draft, http://www.ivoa.net/Documents/latest/CEAInterface.html
 
[xml]
Bray, Tim, Paoli, Jean, Sperberg-McQueen, C. M., Maler, Eve, Yergeau, Francois (editors) 2004, Extensible Markup Language (XML) 1.0 (Third Edition), W3C /TR/REC-xml
[schema]
Fallside, David C., Walmsley, Priscilla (editors) 2004, XML Schema Part 0: Primer Second Edition, W3C Recommendation 28 October 2004, http://www.w3.org/TR/xmlschema-0/
[ISO8601]
Wolf, Misha and Wicksteed, Charles 1997, Date and Time Format, http://www.w3.org/TR/NOTE-datetime.
[OAI]
Lagoze, Carl, Van de Sompel, Herbert, Nelson, Michael, and Warner, Simeon 2004, The Open Archives Initiative Protocol for Metadata Harvesting, http://www.openarchives.org/OAI/openarchivesprotocol.html.
[ID]
Plante, R., Linde, T., Williams, R., Noddle, K. 2005, IVOA Identifiers v1.1, http://www.ivoa.net/Documents/REC/Identifiers/Identifiers-200505XX.html.
[FITS]
FITS: Flexible Image Transport Specification, specifically the Binary Tables Extension, http://fits.gsfc.nasa.gov/.
[WSDL]
Christensen, E., Curbera, F., Meredith, G., Weerawarana, S. Web Services Description Language (WSDL) 1.1, W3C Note 15 March 2001, http://www.w3.org/TR/wsdl.
[SOAP]
Box, D., Ehnebuske, D., Kakivaya, G., Layman, A., Mendolsohn, N., Neilsen, H.F., Thatte, S., Winer, D. Simple Object Access Protocol (SOAP) 1.1, W3C Note 08 May 2000, http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.

Last modified: 04-May-2007 3:33