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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 4216 by kriebe, Wed Aug 23 12:29:07 2017 UTC revision 4217 by kriebe, Tue Aug 29 21:44:29 2017 UTC
# Line 1  Line 1 
1  \subsubsection{ProvDAL}  \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) or activity.  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}.  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.  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    
# Line 10  Line 10 
10  {provdal-base-url}?ID=rave:dr4&ID=rave:act_irafReduction&DEPTH=2  {provdal-base-url}?ID=rave:dr4&ID=rave:act_irafReduction&DEPTH=2
11  \end{verbatim}  \end{verbatim}
12    
13  The format can also be specified via the HTTP Accept header, e.g.  \noindent
14    The format can also be specified via the HTTP accept header, e.g.
15  \begin{verbatim}  \begin{verbatim}
16  wget -d --header="Accept: application/prov-json" \  wget -d --header="Accept: application/json" \
17     {provdal-base-url}?ID=rave:dr4     {provdal-base-url}?ID=rave:dr4
18  \end{verbatim}  \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  \TODO{Which takes precedence, if both, format-keyword and accept header are specified?}  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  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}.  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  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. But the opposite direction, i.e. following the members of an entity collection or the steps of an activityFlow shall only be included if the optional parameter \urlparam{\bf MEMBERS} or \urlparam{\bf STEPS} is set to \urlparam{TRUE}. The default is \urlparam{FALSE}.  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  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}.  \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.}  %\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    
# Line 36  Line 46 
46    
47  \begin{table}[h]  \begin{table}[h]
48  \small  \small
49  \begin{tabulary}{1.0\textwidth}{@{}p{0.17\textwidth}p{0.2\textwidth}p{0.10\textwidth}p{0.43\textwidth}@{}}  \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}}  %{llp{0.2\textwidth}p{0.3\textwidth}}
51  \toprule  \toprule
52  \head{Parameter} & \head{Value/options} & \head{Default} & \head{Description}\\\hline  \head{Parameter} & \head{Value/options} & \head{Description}\\\hline
53  \midrule  \midrule
54  \textbf{\urlparam{ID}} & qualified \urlparam{ID} & -- & a valid qualified identifier for an entity or activity (can occur multiple times)\\  \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{ALL} & \urlparam{ALL} & number of relations to be followed or \texttt{ALL} for everything, independent of the relation type\\  \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  \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{FORTH}, \urlparam{BACK} & \urlparam{BACK} &\urlparam{BACK} = track the provenance history, \newline\urlparam{FORTH} = explore the results of activities and where entities have been used\\  \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{FALSE} & \urlparam{FALSE} & if \urlparam{TRUE}, retrieve and track members of collections\\  \urlparam{MEMBERS} & \urlparam{TRUE} or \urlparam{\underline{FALSE}} & if \urlparam{TRUE}, retrieve and track members of collections\\
59  \urlparam{STEPS} & \urlparam{TRUE} or \urlparam{FALSE} & \urlparam{FALSE} & if \urlparam{TRUE}, retrieve and track steps of activityFlows\\  \urlparam{STEPS} & \urlparam{TRUE} or \urlparam{\underline{FALSE}} & if \urlparam{TRUE}, retrieve and track steps of activityFlows\\
60  \urlparam{AGENT} & \urlparam{TRUE} or \urlparam{FALSE} & \urlparam{FALSE} & if \urlparam{TRUE}, retrieve all relations for agents, i.e. find out what an agent is responsible for\\  \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  \bottomrule
62  \end{tabulary}  \end{tabulary}
63  \caption{ProvDAL request parameters}  \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}  \label{tab:provdal-parameters}
65  \end{table}  \end{table}
66    
Legend:
Removed from v.4216  
changed lines
  Added in v.4217
msdemlei@ari.uni-heidelberg.de
 ViewVC Help
Powered by ViewVC 1.1.26