Ubuntu Manpage: stilts-taplint - Tests TAP services

name
synopsis
description
options
see also
version
author

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

       Mark Taylor (Bristol University)

                                                    Mar 2017                                   STILTS-TAPLINT(1)