/[volute]/trunk/projects/dm/provenance/description/provdal-afterparis.tex
ViewVC logotype

Contents of /trunk/projects/dm/provenance/description/provdal-afterparis.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4217 - (show annotations)
Tue Aug 29 21:44:29 2017 UTC (3 years, 4 months ago) by kriebe
File MIME type: application/x-tex
File size: 5775 byte(s)
Improve formatting for provdal, include pdf

1 \subsubsection{ProvDAL}
2 ProvDAL is a service the interface of which is organized around one main parameter, the \urlparam{\bf ID} of an entity (obs\_publisher\_did of an ObsDataSet for example), activity or an agent.
3 The response is given in one of the following formats: \urlparam{PROV-N}, \urlparam{PROV-JSON}, \urlparam{PROV-XML}, \urlparam{PROV-VOTABLE}.
4 Additional parameters can complete the \urlparam{ID} to refine the query: \urlparam{\bf FORMAT} allows to choose the output format. \urlparam{\bf DEPTH} gives the number of relations that shall be tracked along the provenance history, independent of the type of relation. Its value is either 0, a positive integer or \urlparam{ALL}. If this parameter is omitted, the default is \urlparam{ALL}, which returns the complete provenance history that the service has stored or the provenance according to a maximum depth number that the server allows.
5
6 The \urlparam{ID} parameter is allowed more than once in order to retrieve provenance details for several activities or datasets at the same time. Here are a few example requests:
7
8 \begin{verbatim}
9 {provdal-base-url}?ID=rave:dr4&FORMAT=PROV-JSON
10 {provdal-base-url}?ID=rave:dr4&ID=rave:act_irafReduction&DEPTH=2
11 \end{verbatim}
12
13 \noindent
14 The format can also be specified via the HTTP accept header, e.g.
15 \begin{verbatim}
16 wget -d --header="Accept: application/json" \
17 {provdal-base-url}?ID=rave:dr4
18 \end{verbatim}
19 would return the provenance information in \urlparam{PROV-JSON} format.
20 \noindent
21 If both \urlparam{FORMAT} and the accept header are used and \urlparam{FORMAT} specifies a format that is incompatible with the HTTP accept header, then the service should return with a HTTP status 406: Not Acceptable.
22
23 For services which allow tracking the provenance information forward, e.g. in order to check for which activities an entity was used, the optional parameter \urlparam{\bf DIRECTION} can be set to \urlparam{FORTH}. Its default value is \urlparam{BACK}. This influences the direction in which the used, wasGeneratedBy, wasDerivedFrom and wasInfluencedBy relations are followed.
24
25 The provenance data model defines also the hierarchical relations \emph{hadMember} for entity collections and \emph{hadStep} for activityFlows. If a node belongs to a collection or activityFlow, these relations shall be returned as well, independent of the specified tracking direction.
26 If one is interested in more details and wants to follow the \emph{members} of an entity collection or the \emph{steps} of an activityFlow, these can be included by setting the optional parameter \urlparam{\bf MEMBERS} or \urlparam{\bf STEPS} to \urlparam{TRUE}, respectively. The default is \urlparam{FALSE}.
27
28 By default, it is recommended to stop any further tracking at an agent node, unless an additional optional parameter \urlparam{\bf AGENT} is set to \urlparam{TRUE}. Note that this means that the request for any agent will always return just the agent node itself and nothing else, unless \urlparam{AGENT=TRUE} is used. Thus, if one wants to know which entities and activities an agent has influenced, the request may look like this:
29
30 \begin{verbatim}
31 {provdal-base-url}?ID=org:rave&AGENT=TRUE&DEPTH=1
32 \end{verbatim}
33
34 \noindent
35 \urlparam{DEPTH=1} was used here in order to avoid following the found entities and activities any further.
36
37 %\comment{Maybe it's better to use DEPTH and DIRECTION instead of FORWARD and BACKWARD. Reason: if a service just implements the backward direction, then it's weird to call something ``backward'' if there is no ``forward'' as well. DEPTH is also a commonly used word when refering to graphs and numbers of relations.}
38
39
40 \TODO{Draw a provenance graph picture here with different relation types and arrows for direction.}
41
42 A ProvDAL service MUST implement the parameters \urlparam{ID}, \urlparam{DEPTH} and \urlparam{FORMAT}; the remaining parameters are optional.
43 If a service does not implement the optional parameters, but they appear in the request, then the service should return with an error.
44
45 Table~\ref{tab:provdal-parameters} summarizes the parameters for such a ProvDAL service interface.
46
47 \begin{table}[h]
48 \small
49 \begin{tabulary}{1.0\textwidth}{@{}p{0.17\textwidth}p{0.22\textwidth}p{0.53\textwidth}@{}}
50 %{llp{0.2\textwidth}p{0.3\textwidth}}
51 \toprule
52 \head{Parameter} & \head{Value/options} & \head{Description}\\\hline
53 \midrule
54 \textbf{\urlparam{ID}} & qualified \urlparam{ID} & a valid qualified identifier for an entity or activity (can occur multiple times)\\
55 \textbf{\urlparam{DEPTH}} & 0,1,2,..., \urlparam{\underline{ALL}} & number of relations to be followed or \texttt{ALL} for everything, independent of the relation type\\
56 \textbf{\urlparam{FORMAT}} & \urlparam{PROV-N}, \newline\urlparam{PROV-JSON}, \newline\urlparam{PROV-XML}, \newline\urlparam{PROV-VOTABLE} & serialisation format of the response\\\hline
57 \urlparam{DIRECTION} & \urlparam{\underline{BACK}}, \urlparam{FORTH} & \urlparam{BACK} = track the provenance history, \newline\urlparam{FORTH} = explore the results of activities and where entities have been used\\
58 \urlparam{MEMBERS} & \urlparam{TRUE} or \urlparam{\underline{FALSE}} & if \urlparam{TRUE}, retrieve and track members of collections\\
59 \urlparam{STEPS} & \urlparam{TRUE} or \urlparam{\underline{FALSE}} & if \urlparam{TRUE}, retrieve and track steps of activityFlows\\
60 \urlparam{AGENT} & \urlparam{TRUE} or \urlparam{\underline{FALSE}} & if \urlparam{TRUE}, retrieve all relations for agents, i.e. find out what an agent is responsible for\\
61 \bottomrule
62 \end{tabulary}
63 \caption{ProvDAL request parameters. Options that are \textbf{required} to be implemented by ProvDAL services are marked with bold face. \underline{Default} values are underlined.}
64 \label{tab:provdal-parameters}
65 \end{table}
66
67

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26