Ubuntu Manpage: stilts-datalinklint - Validates DataLink documents

NAME

       stilts-datalinklint - Validates DataLink documents

SYNOPSIS

       stilts datalinklint [votable=<filename>|<URL>|-] [version=1.0|1.1] [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

* Optional but documented columns have mandated metadata if present

* 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

* Values of content_qualifier column values if present

* Syntax of link_auth column values if present

* Results for the same ID are contiguous (DataLink 1.1)

* StandardID INFO is present and correct (Datalink 1.1)

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

version=1.0|1.1
Selects the version of the DataLink standard which the input document is supposed
to conform to. If left blank, the default, then the version will be determined from
the document itself if possible, otherwise a default value for the application will
be used.

Options are currently:

* 1.0: REC-DataLink-1.0

* 1.1: PR-DataLink-1.1-20230413

If a non-null version is specified and it conflicts with declarations in the
document itself, this conflict will be reported as an error.

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.

VERSION

       STILTS version 3.4.9-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