source: trunk/docs/services/zcfg-reference.rst @ 792

Last change on this file since 792 was 792, checked in by djay, 4 years ago

Add nested inputs / outputs definition to the documentation.

  • Property svn:keywords set to Date Author
  • Property svn:mime-type set to text/plain
File size: 10.5 KB
Line 
1.. _services-zcfg:
2   
3ZOO-Service configuration file
4========================================= 
5
6The ZOO-Service configuration file (.zcfg) describes a
7WPS service. It provides metadata information on a particular WPS
8Service and it is parsed by ZOO-Kernel when *DescribeProcess* and
9*Execute* request are sent.
10
11The ZOO-Service configuration file is divided into three distinct sections :
12
13 * Main Metadata information
14 * List of Inputs metadata information (optional since `rev. 469 <http://zoo-project.org/trac/changeset/469>`__)
15 * List of Outputs metadata information
16
17.. warning:: The ZOO-Service configuration file is case sensitive.
18
19.. note:: There are many example ZCFG files in the ``cgi-env``
20          directory of the `ZOO-Project svn
21          <http://zoo-project.org/trac/browser/trunk/zoo-project/zoo-services>`__.
22
23.. note:: A ZCFG file can be converted to the YAML syntaxe by using
24          the zcfg2yaml command line tool.
25
26Main section
27-------------------------
28
29The fist part of the ZOO-Service configuration file is the ``main`` section,
30which contains general metadata information on the related WPS
31Service.
32
33Note that the "name of your service" between brackets on the first line has to be the exact same name
34as the function you defined in your services provider code. In most cases, this name is also the name
35of the ZCFG file without the "``.zcfg``" extension.
36
37An example of the ``main`` section  is given bellow as reference.
38
39.. code-block:: none
40   :linenos:
41
42   [Name of WPS Service]
43   Title = Title of the WPS Service
44   Abstract = Description of the WPS Service
45   processVersion = Version number of the WPS Service
46   storeSupported = true/false
47   statusSupported = true/false
48   serviceType = Pprogramming language used to implement the service (C|Fortran|Python|Java|PHP|Ruby|Javascript)
49   serviceProvider = Name of the Services provider (shared library|Python Module|Java Class|PHP Script|JavaScript Script)
50   <MetaData>
51     title = Metadata title of the WPS Service
52   </MetaData>
53
54.. warning::  'Name of WPS Service' must be the exact same name as the function defined in the WPS Service source code.
55
56.. note:: An ``extend`` parameter may be used for the `Process profile registry <process-profiles.html>`__.
57
58List of Inputs
59--------------
60
61The second part of the ZOO-Service configuration file is the ``<DataInputs>``
62section which lists the supported inputs. Each input is defined as :
63
64 * Name (between brackets as for the name of the service before)
65 * Various medata properties (``Title``, ``Abstract``, ``minOccurs``, ``maxOccurs`` and, in case of ComplexData, the optional ``maximumMegabytes``)
66 * :ref:`Type Of Data Node  <typeDataNodes>`
67
68A typical list of inputs (``<DataInputs>``) looks like the following:
69
70.. code-block:: none
71   :linenos:
72   
73   <DataInputs>
74     [Name of the first input]
75       Title = Title of the first input
76       Abstract = Abstract describing the first input
77       minOccurs = Minimum occurence of the first input
78       maxOccurs = Maximum occurence of the first input
79       <Type Of Data Node />
80     [Name of the second input]
81       Title = Title of the second input
82       Abstract = Abstract describing the second input
83       minOccurs = Minimum occurence of the second input
84       maxOccurs = Maximum occurence of the second input
85       <Type Of Data Node />
86   </DataInputs>
87   
88.. note:: A ``<MetaData>`` node can also be added, as in the main metadata information.
89
90List of Outputs
91---------------
92
93The third part of the ZOO Service configuration file is the ``<DataOutputs>``
94section, which lists the supported outputs and is is very similar to a
95list of inputs.
96
97A typical list of outputs (``<DataOutputs>``) looks like the
98following:
99
100.. code-block:: none
101   :linenos:
102   
103   <DataOutputs>
104     [Name of the output]
105       Title = Title of the output
106       Abstract = Description of the output
107       <Type Of Data Node />
108   </DataOutputs>
109
110.. _typeDataNodes:
111
112Type Of Data Nodes
113------------------
114
115The *Type Of Data Nodes* describes data types for inputs and
116outputs. There are three different types which are described in this
117section.
118 * :ref:`LiteralData <LiteralData>`
119 * :ref:`BoundingBoxData <BoundingBoxData>`
120 * :ref:`ComplexData <ComplexData>`
121
122 .. warning:: Every *BoundingBoxData* and *ComplexData* must have at
123              least one ``<Default>`` node (even empty like ``<Default
124              />``)
125
126 .. warning:: In WPS 2.0.0 version, it is possible to define nested
127              inputs and outputs. So, from revision `790
128              <http://www.zoo-project.org/trac/changeset/790>`__, you
129              are allowed to use a new input/output definition here.
130
131.. _LiteralData:
132
133LiteralData node
134****************
135
136A ``<LiteralData>`` node contains:
137
138- one (optional) ``AllowedValues`` key containing all value allowed for this input
139- one (optional) ``range`` properties containing the range (``[``, ``]``)
140- one (optional) ``rangeMin`` (``rangeMax``) properties containing the minimum (maximum) value of this range
141- one (optional) ``rangeSpacing`` properties containing the regular distance or spacing between value in this range
142- one (optional) ``rangeClosure`` properties containing the closure type (``c``, ``o``, ``oc``, ``co``)
143- one ``<Default>`` node,
144- zero or more ``<Supported>`` nodes depending on the existence or the number of supported Units Of Measure (UOM), and
145- a ``dataType`` property. The ``dataType`` property defines the type of literal data, such as a string, an interger and so on
146  (consult `the complete list <http://www.w3.org/TR/xmlschema-2/#built-in-datatypes>`__ of supported data types).
147
148``<Default>`` and ``<Supported>`` nodes can contain the ``uom`` property to define which UOM has to be used for
149this input value.
150
151For input ``<LiteralData>`` nodes, you can add the ``value`` property to the ``<Default>`` node to define a default
152value for this input. This means that, when your Service will be run, even if the input wasn't defined, this default
153value will be set as the current value for this input.
154
155A typical ``<LiteralData>`` node, defining a ``float`` data type using meters or degrees for its UOM, looks like the
156following:
157
158.. code-block:: guess
159   :linenos:
160   
161   <LiteralData>
162     dataType = float
163     <Default>
164       uom = meters
165     </Default>
166     <Supported>
167       uom = feet
168     </Supported>
169   </LiteralData>
170
171
172A typical ``<LiteralData>`` node, defining a ``float`` data type which
173should take values contained in ``[0.0,100.0]``, looks like the following:
174
175.. code-block:: guess
176   :linenos:
177   
178   <LiteralData>
179     dataType = float
180     rangeMin = 0.0
181     rangeMax = 100.0
182     rangeClosure = c
183     <Default />
184   </LiteralData>
185
186Or more simply:
187
188.. code-block:: guess
189   :linenos:
190   
191   <LiteralData>
192     dataType = float
193     range = [0.0,100.0]
194     <Default />
195   </LiteralData>
196
197A typical ``<LiteralData>`` node, defining a ``string`` data type which
198support values ``hillshade``, ``slope``, ``aspect``, ``TRI``, ``TPI``
199and ``roughness``, looks like the following:
200
201.. code-block:: guess
202   :linenos:
203   
204   <LiteralData>
205     dataType = string
206     AllowedValues = hillshade,slope,aspect,TRI,TPI,roughness
207     <Default />
208   </LiteralData>
209
210Properties ``AllowedValues`` and ``range*`` can be conbined with both ``<Default>`` and
211``<Supported>`` nodes in the same was as ``<LiteralData>`` node. For
212instance, the following is supported:
213
214.. code-block:: guess
215   :linenos:
216   
217   <LiteralData>
218     dataType = int
219     <Default>
220       value = 11
221       AllowedValues = -10,-8,-7,-5,-1
222       rangeMin = 0
223       rangeMin = 100
224       rangeClosure = co
225     </Default>
226     <Supported>
227       rangeMin = 200
228       rangeMin = 600
229       rangeClosure = co
230     </Supported>
231     <Supported>
232       rangeMin = 750
233       rangeMin = 990
234       rangeClosure = co
235       rangeSpacing = 10
236     </Supported>
237   </LiteralData>
238
239.. _BoundingBoxData:
240
241BoundingBoxData node
242********************
243
244A ``<BoundingBoxData>`` node contains:
245
246- one ``<Default>`` node with a CRS property defining the default Coordinate Reference Systems (CRS), and
247- one or more ``<Supported>`` nodes depending on the number of CRS your service supports (note that you can
248  alternatively use a single ``<Supported>`` node with a comma-separated list of supported CRS).
249
250A typical ``<BoundingBoxData>`` node, for two supported CRS (`EPSG:4326 <http://www.epsg-registry.org/indicio/query?request=GetRepositoryItem&id=urn:ogc:def:crs:EPSG::4326>`__
251and `EPSG:3785 <http://www.epsg-registry.org/indicio/query?request=GetRepositoryItem&id=urn:ogc:def:crs:EPSG::3785>`__),
252looks like the following:
253
254.. code-block:: guess
255   :linenos:
256   
257   <BoundingBoxData>
258     <Default>
259       CRS = urn:ogc:def:crs:EPSG:6.6:4326
260     </Default>
261     <Supported>
262       CRS = urn:ogc:def:crs:EPSG:6.6:4326
263     </Supported>
264     <Supported>
265       CRS = urn:ogc:def:crs:EPSG:6.6:3785
266     </Supported>
267   </BoundingBoxData>
268
269.. _ComplexData:
270
271ComplexData node
272****************
273
274A ComplexData node contains:
275
276- a ``<Default>`` node and
277- one or more ``<Supported>`` nodes depending on the number of supported formats. A format is made up of this
278  set of properties : ``mimeType``, ``encoding`` and optionaly ``schema``.
279
280For output ComplexData nodes, you can add the ``extension`` property to define what extension to use to name
281the file when storing the result is required. Obviously, you'll have to add the ``extension`` property to each
282supported format (for the ``<Default>`` and ``<Supported>`` nodes).
283
284You can also add the ``asReference`` property to the ``<Default>`` node to define if the output should be
285stored on server side per default.
286
287.. Note:: the client can always modify this behavior by setting ``asReference`` attribute to ``true`` or ``false``
288          for this output in the request ``ResponseDocument`` parameter.
289
290You can see below a sample ComplexData node for default ``application/json`` and ``text/xml`` (encoded in UTF-8
291or base64) mimeTypes support:
292
293.. code-block:: guess
294   :linenos:
295   
296   <ComplexData>
297     <Default>
298       mimeType = application/json
299       encoding = UTF-8
300     </Default>
301     <Supported>
302       mimeType = text/xml
303       encoding = base64
304       schema = http://fooa/gml/3.1.0/polygon.xsd
305     </Supported>
306     <Supported>
307       mimeType = text/xml
308       encoding = UTF-8
309       schema = http://fooa/gml/3.1.0/polygon.xsd
310     </Supported>
311   </ComplexData>
Note: See TracBrowser for help on using the repository browser.

Search

ZOO Sponsors

http://www.zoo-project.org/trac/chrome/site/img/geolabs-logo.pnghttp://www.zoo-project.org/trac/chrome/site/img/neogeo-logo.png http://www.zoo-project.org/trac/chrome/site/img/apptech-logo.png http://www.zoo-project.org/trac/chrome/site/img/3liz-logo.png http://www.zoo-project.org/trac/chrome/site/img/gateway-logo.png

Become a sponsor !

Knowledge partners

http://www.zoo-project.org/trac/chrome/site/img/ocu-logo.png http://www.zoo-project.org/trac/chrome/site/img/gucas-logo.png http://www.zoo-project.org/trac/chrome/site/img/polimi-logo.png http://www.zoo-project.org/trac/chrome/site/img/fem-logo.png http://www.zoo-project.org/trac/chrome/site/img/supsi-logo.png http://www.zoo-project.org/trac/chrome/site/img/cumtb-logo.png

Become a knowledge partner

Related links

http://zoo-project.org/img/ogclogo.png http://zoo-project.org/img/osgeologo.png