Provided by: stilts_3.4.3-1_all bug

NAME

       stilts-datalinklint - Validates DataLink documents

SYNOPSIS

       stilts datalinklint [votable=<filename>|<URL>|-] [format=text|json] [report=[EWISF]+]
                           [maxrepeat=<int-value>] [truncate=<int-value>] [debug=true|false]

DESCRIPTION

       datalinklint runs a series of tests on a VOTable  that  is  supposed  to  conform  to  the
       {links}-response  format  defined  in  the  IVOA  DataLink  specification, and reports the
       results. This is not likely to be of use to  normal  users,  it  is  intended  for  people
       developing  or operating DataLink-compliant services to assess correctness, perhaps with a
       view to improving compliance.

       To run it, you point it at the URL or filename of a  VOTable  of  interest,  and  it  runs
       various  tests on it and reports them to standard output. Only the input table itself, and
       if the input location uses HTTP the HTTP headers, are  tested,  this  validator  does  not
       inspect  any  other resources. As well as validation checks, some reporting of the table's
       content (such as a summary of the link defined by each row and a listing  of  the  defined
       service  descriptors)  is  provided  as  INFO-level  output  for  convenience. This can be
       suppressed if preferred by use of the report parameter.

       This operates in much the same way as the taplint command, and the output  has  a  similar
       format,  though  unlike  taplint  this command does not divide the testing up into stages.
       Each report line is of the form: T-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.

         * 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-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.

       As with any validator, this command does not guarantee to pick up  everything  wrong  with
       the  indicated  VOTable, but it tries as hard as it can to check against the rules set out
       in the DataLink specification and other related documents as appropriate. A non-exhaustive
       list of the items checked is:

         * VOTable validation à la votlint

         * Correct RESOURCE structure of VOTable document

         * All required columns are present with mandated metadata

         * Each row contains one of access_url, service_def, error_message

         * Service descriptors correctly specified and referenced

         * Syntax of error_message column values

         * Syntax of content_type column values

         * Syntax of semantics column values

         * Reported HTTP content-type, if applicable

         * Correct serialization (TABLEDATA) is used

         * DALI error-response checking, if applicable
        At  present  no  checking  is  performed  on  the link targets; tests are confined to the
       presented document itself.

       HTTP connections made by this validator are flagged in the User-Agent field with the token
       "(IVOA-test)".

OPTIONS

       votable=<filename>|<URL>|-
              Location  of  the  DataLink  VOTable  document  to  check.  This may be a URL, or a
              filename, or the special value "-" to indicate standard input.

       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 E, W, I, S, F 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.

SEE ALSO

       stilts(1)

       If  the  package  stilts-doc  is installed, the full documentation SUN/256 is available in
       HTML format:
       file:///usr/share/doc/stilts/sun256/index.html

VERSION

       STILTS version 3.4.3-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-DATALINKLINT(1)