stilts-datalinklint - Validates DataLink documents
stilts datalinklint
[votable=<filename>|<URL>|-] [format=text|json]
[report=[EWISF]+] [maxrepeat=<int-value>]
[truncate=<int-value>] [debug=true|false]
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.
- 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.
stilts(1)
If the package stilts-doc is installed, the full documentation
SUN/256 is available in HTML format:
file:///usr/share/doc/stilts-doc/sun256/index.html
STILTS version 3.1-5-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
Mark Taylor (Bristol University)