Slides of my talk at the SETP-10-conference in Orlando, FL, USA on 13th July 2010

1. Using Thematic Grids to
Document Web Service
Operations
Conference SETP-10, July 13, 2010 (Orlando, FL, USA)
Jan Christian Krause
AKRA GmbH
Domstraße 17, 20095 Hamburg, Germany
jan-christian.krause@akra.de

2. Using Thematic Grids to Document Web Service Operations
1. Motivation
2. State-of-the-Art Approaches to Document Web Services
3. Constructing Web Service Documentation with Thematic Grids
4. Conclusion and Outlook
Agenda:
July 13, 2010 2Jan Christian Krause

3. Using Thematic Grids to Document Web Service Operations
„[…] Rather, the architect should expose only what users of an element
[a Web Service] need to know in order
to interact [or communicate] with it. […]“
Which aspects of a web service should be documented? (I)
[Clements et al., 2002], p. 226
My experience from software projects:
„[…] Rather, the architect should expose only what users of an element
[a Web Service] need to know in order
to understand it and interact [or communicate] with it. […]“
July 13, 2010 3Jan Christian Krause

4. Using Thematic Grids to Document Web Service Operations
Which aspects of a web service should be documented? (II)
Assumption (has to be verified):
The understanding of a web service operation (WSO) is determined by:
 Its identifier
 Consumed resources (e.g. data stores)
 Exchangeable behaviour specifications („strategies“, e.g. formulas)
Practical problem:
Not all resources and strategies are part of the signature of a web service
operation.
How to construct web service documentation including the set of
consumed resources and applied strategies?
July 13, 2010 4Jan Christian Krause

5. Using Thematic Grids to Document Web Service Operations
State-of-the-Art Approaches to Document Web Services: Summary
 The current documentation grid of a web service operation only
describes the elements required for interacting and communicating
with the operation.
 The task of documenting resources and strategies is not explicitly
supported.
 Implicitly it is delegated to further documentation models (e.g.
taxonomies, ontologies or process models)
 None of the state-of-the-art approaches (WSDL-<documentation>,
WSDL-S, OWL-S, etc.) support explicitly the derivation of required
resources and strategies.
July 13, 2010 5Jan Christian Krause

6. Using Thematic Grids to Document Web Service Operations
Constructing Web Service Documentation with Thematic Grids (I)
July 13, 2010 6Jan Christian Krause
 Observation: Many web service operation identifiers contain a verb.
 A verb comes with a meaning, which is instantiated by mandantory
and optional „parameters“ (in linguistics: complements), e.g.
to find requires an object and a location
 In linguistics the possible complements (thematic roles) of a verb are
formally described by a thematic grid.
 The WSDL-index of the web service search engine seekda.com has been used
as corpus.
 The corpus contains 163,368 operation identifiers with 830 different English
verbs.
 ~ 88% of all identifiers contain an English verb.
Empirical verification of verb-usage in WSO-identifiers:

7. Using Thematic Grids to Document Web Service Operations
Constructing Web Service Documentation with Thematic Grids (II)
Find
[OBJECT] [COMPARISON] [SOURCE]
Find
[OBJECT Customer] [COMPARISON id] [SOURCE ???]
Example:
July 13, 2010 7Jan Christian Krause

8. Using Thematic Grids to Document Web Service Operations
 The verb of an identifier is part of an operation‘s signature and could be
used as additional information source.
 By identifying the verb the thematic grid of the operation could be derived.
 The thematic grid is filled by associating signature-elements with roles and
/ or manually describing them.
 By filling thematic grids, hidden resources and strategies could be
derived (without deep information about the implementation).
 The association of a parameter with a role covers a lot of
documentation purposes (less documentation effort).
 An appropriate set of thematic roles for web service-
documentation has to be identified.
 No cardinalities can be derived for the hidden resources and
strategies.
July 13, 2010 8Jan Christian Krause
Constructing Web Service Documentation with Thematic Grids (III)

9. Using Thematic Grids to Document Web Service Operations
 Practical requirement: The association of verbs and thematic roles must be
easy and extendable (to integrate domain specific verbs of an organisation).
 Our approach (to be verified): Organize verbs in semantic classes and
define thematic grids per class.
 The Extended Levin Classes classify more verbs than the MIT Process
Handbook and are therefore preferred.
Constructing Web Service Documentation with Thematic Grids (IV)
July 13, 2010 9Jan Christian Krause
# Classified Identifiers # Not classified Identifiers
MIT Process HB 147,454 2,734
Ext. Levin Classes 147,890 2,298
Classified verbs Not classified verbs
MIT Process HB 644 186
Ext. Levin Classes 744 86

10. Using Thematic Grids to Document Web Service Operations
 Verb-focussed approach to construct documentation of web service operations
has been introduced.
 Thematic roles have been introduced to identify hidden resources and
strategies.
 Usage of English verbs and an appropriate classification scheme have been
verified / identified empirically.
 Next steps:
 Derive set of thematic roles being appropriate for web service
documentation
 Extend the WSDL-grammar to support documentation with thematic grids
 Implementation of a software-assistant supporting web service
documentation with thematic grids.
Conclusion and outlook
July 13, 2010 10Jan Christian Krause

11. Using Thematic Grids to Document Web Service Operations
Thank you for your attention.
Any questions, comments or
contributions???
July 13, 2010 11Jan Christian Krause