Ubuntu Manpage: stilts-taplint - Tests TAP services

NAME

       stilts-taplint - Tests TAP services

SYNOPSIS

       stilts taplint [tapurl=<url-value>]
                      [stages=TMV|TME|TMS|TMC|CPV|CAP|AVV|QGE|QPO|QAS|UWS|MDQ|OBS|UPL|EXA[ ...]]
                      [maxtable=<int-value>] [format=text|json] [report=[EWISF]+]
                      [maxrepeat=<int-value>] [truncate=<int-value>] [debug=true|false]
                      [syncurl=<url-value>] [asyncurl=<url-value>] [tablesurl=<url-value>]
                      [capabilitiesurl=<url-value>] [availabilityurl=<url-value>]
                      [examplesurl=<url-value>]

DESCRIPTION

taplint runs a series of tests on a Table Access Protocol (TAP) service and reports the
results. Unlike most of the other tools in this package it is not likely to be of use to
normal users; its intended use is for people developing or operating TAP services to
assess their services, perhaps with a view to improving compliance.

Testing takes place in a number of stages; it is possible to choose which stages are run
in by using the stages parameter. The default output (format=text) is line-based text to
standard output, and each report line is of the (fairly greppable) form: T-SSS-MMMMxN
aaaaa... where the parts have the following meanings:

* T: Report type, one of E(rror), W(arning), I(nfo), S(ummary), F(ailure). See the
documentation of the report parameter for further description of what these mean. The
report parameter can be used to suppress some of these; only E indicates actual
service compliance errors, but including the others may make it easier to see what's
going on.

* SSS: Stage abbreviation, as used in the stages parameter. The stages parameter can be
used to select which stages are run.

* MMMM: Message label, which is always the same for messages generated by the same test,
is usually different for messages generated by different tests, and may be somewhat
mnemonic.

* x: Continuation indicator, either "-" or "+". In most cases it is "-", indicating the
first line of a message, but multi-line messages (rare) use "-" for the first line and
"+" for any continuation lines.

* N: Sequence number, which is 1 for the first time message T-SSS-MMMM is reported, and
increases by one for each subsequent appearance. After a certain maximum (determined
by the maxrepeat parameter) additional reports with the same code are no longer output
individually, but a summary of the number of reports so discarded is written at the
end of the section with the character "x" instead of the sequence number. This
behaviour prevents the output being swamped by multiple reports of the same issue. If
the maxrepeat parameter is increased above 9, more than one digit will be used here
(so e.g. for maxrepeat=999, the format would be NNN not N).

* aaaaa...: Message text, a free text description of what is being reported.

If you don't like that format, others may be selected using the format parameter, which
currently also supports JSON. For more flexible interaction with the output you can invoke
taplint programmatically and supply your own instance.

TAP is a complicated beast, referencing many standards (including TAP, UWS, VODataService,
ADQL, VOResource, VOSI, TAPRegExt, DALI, ObsCore, VOTable, HTTP, RDFa Lite), and it is
hard to write a validator which is comprehensive, especially one which can provide useful
output for services with a range of compliance levels. This tool tries to make a wide
range of tests, but does not claim to be comprehensive. An idea of what tests it does
perform can be gained from the stages listed in the description of the stages parameter.
It does make a fairly good job of checking that declared metadata is consistent and
matches the data actually returned from queries, and it tests job submission in most of
the various ways permitted by the TAP standard. Things it does not test much include
complex ADQL queries, coordinate/STC-related data types, queries in non-ADQL languages,
and service registration.

OPTIONS

       tapurl=<url-value>
              The  base  URL  of  a Table Access Protocol service. This is the bare URL without a
              trailing "/[a]sync".

              The default values of the various  endpoints  (sync  and  async  query  submission,
              tables metadata, service-provided examples etc) use this URL as a parent and append
              standard sub-paths. However, other parameters (syncurl, asyncurl, ...) are provided
              so that the different endpoints can be set individually if required.

       stages=TMV|TME|TMS|TMC|CPV|CAP|AVV|QGE|QPO|QAS|UWS|MDQ|OBS|UPL|EXA[ ...]
              Lists  the  validation  stages  which  the  validator  will  perform. Each stage is
              represented by a short code, as follows:

                * TMV: Validate table metadata against XML schema (on)

                * TME: Check content of tables metadata from /tables (on)

                * TMS: Check content of tables metadata from TAP_SCHEMA (on)

                * TMC: Compare table metadata from /tables and TAP_SCHEMA (on)

                * CPV: Validate capabilities against XML schema (on)

                * CAP: Check content of TAPRegExt capabilities record (on)

                * AVV: Validate availability against XML schema (on)

                * QGE: Make ADQL queries in sync GET mode (on)

                * QPO: Make ADQL queries in sync POST mode (on)

                * QAS: Make ADQL queries in async mode (on)

                * UWS: Test asynchronous UWS/TAP behaviour (on)

                * MDQ: Check table query result columns against declared metadata (on)

                * OBS: Test implementation of ObsCore Data Model (on)

                * UPL: Make queries with table uploads (on)

                * EXA: Check content of examples document (on)
               You can specify a  list  of  stage  codes,  separated  by  spaces.  Order  is  not
              significant.

              Note  that  removing  some  stages may affect the operation of others; for instance
              table metadata is acquired from the metadata stages, and avoiding those  will  mean
              that  later  stages that use the table metadata to pose queries will not be able to
              do so with knowledge of the database schema.

       maxtable=<int-value>
              Limits the number of tables from the service that will be tested.  Currently,  this
              only  affects  stage  MDQ.  If  the  value is left blank (the default), or if it is
              larger than the number of tables actually present in the service, it will  have  no
              effect.

       format=text|json
              Determines the format of the output. Possible values are text, json.

              Note not all of the other parameters may be applicable to all output formats.

       report=[EWISF]+
              Letters  indicating  which  message  types  should be listed. Each character of the
              string is one of the letters , , , , with the following meanings:

                * E: Error in operation or standard compliance of the service.

                * W: Warning that service behaviour is questionable, or  contravenes  a  standard
                  recommendation, but is not in actual violation of the standard.

                * I: Information about progress, for instance details of queries made.

                * S: Summary of previous successful/unsuccessful reports.

                * F:  Failure  of the validator to perform some testing. The cause is either some
                  error internal to the validator, or some error or missing functionality in  the
                  service which has already been reported.

       maxrepeat=<int-value>
              Puts  a  limit  on  the  number of times that a single message will be repeated. By
              setting this to some reasonably small number, you can ensure that the  output  does
              not get cluttered up by millions of repetitions of essentially the same error.

       truncate=<int-value>
              Limits the line length written to the output.

       debug=true|false
              If  true,  debugging  output  including  stack traces will be output along with the
              normal validation messages.

       syncurl=<url-value>
              Sets the URL to use for the sync endpoint of the  TAP  service.  By  default,  this
              would  be  <tapurl>/sync  but  you can set this parameter to some other location if
              required. If left blank, the default value is used.

       asyncurl=<url-value>
              Sets the URL to use for the async endpoint of the TAP  service.  By  default,  this
              would  be  <tapurl>/async  but you can set this parameter to some other location if
              required. If left blank, the default value is used.

       tablesurl=<url-value>
              Sets the URL to use for the tables endpoint of the TAP service.  By  default,  this
              would  be  <tapurl>/tables but you can set this parameter to some other location if
              required. If left blank, the default value is used.

       capabilitiesurl=<url-value>
              Sets the URL to use for the capabilities endpoint of the TAP service.  By  default,
              this  would  be  <tapurl>/capabilities but you can set this parameter to some other
              location if required. If left blank, the default value is used.

       availabilityurl=<url-value>
              Sets the URL to use for the availability endpoint of the TAP service.  By  default,
              this  would  be  <tapurl>/availability but you can set this parameter to some other
              location if required. If left blank, the default value is used.

       examplesurl=<url-value>
              Sets the URL to use for the examples endpoint of the TAP service. By default,  this
              would be <tapurl>/examples but you can set this parameter to some other location if
              required. If left blank, the default value is used.

VERSION

       STILTS version 3.1-2-debian

       This  is  the  Debian  version  of Stilts, which lack the support of some file formats and
       network protocols. For differences see
       file:///usr/share/doc/stilts/README.Debian

AUTHOR