STILTS-TAPLINT(1)

📦
version 3.5.4 · 5 versions
, in ubuntu stonking

💅 stilts-taplint — the tea on testing TAP services

okay bestie, so this is stilts-taplint, one of the stilts commands, and it Tests TAP services. yes literally that's the whole job description. 💖

✨ SYNOPSIS ✨

stilts taplint [tapurl=<url-value>] [stages=[+/-]XXX ...]
               [maxtable=<int-value>] [tables=<name-list>]
               [format=text|json] [report=[EWISF]+] [maxrepeat=<int-value>]
               [truncate=<int-value>] [debug=true|false]
               [interface=tap1.0|tap1.1|cap] [auth=true|false]
               [syncurl=<url-value>] [asyncurl=<url-value>]
               [tablesurl=<url-value>] [capabilitiesurl=<url-value>]
               [availabilityurl=<url-value>] [examplesurl=<url-value>]

🌸 DESCRIPTION 🌸

so taplint runs a whole series of tests against a Table Access Protocol (TAP) service and then reports back what it found. and no cap, unlike basically every other tool in this package, this one is not really for normal users — it's for the people developing or operating TAP services, so they can vibe check their own service, probably with the goal of making it more compliant. 🫶

🎀 the stages of grief (jk it's just stages)

Testing happens in a bunch of stages, and you can pick which ones actually run using the stages parameter. ✨

the default output (format=text) is line-based text going to standard output, and every report line has this (extremely greppable, honestly iconic) shape:

T-SSS-MMMMxN aaaaa...

and here's what each lil piece means, bestie: 👑

  • T — the Report type, one of E(rror), W(arning), I(nfo), S(ummary), F(ailure). go read the docs for the report parameter if you want the full breakdown of what those actually mean. you can use report to suppress some of them — and FYI, only E means there's a genuine service compliance error, but keeping the others around can make it way easier to see what's going on. 💀
  • SSS — the Stage abbreviation, same ones used by the stages parameter. and yes, stages is how you select which stages actually get run. 🌈
  • MMMM — the Message label. it's always the same for messages coming from the same test, usually different for messages from different tests, and it may be a lil bit mnemonic. lowkey helpful.
  • x — the Continuation indicator, either - or +. most of the time it's - meaning "this is the first line of a message", but multi-line messages (rare, don't worry about them) use - for the first line and + for every continuation line after. 🦋
  • N — the Sequence number. it's 1 the first time message T-SSS-MMMM gets reported, and it goes up by one every time that same message shows up again. but after a certain maximum (and that max is decided by the maxrepeat parameter) any extra reports with the same code stop being output individually — instead a summary of how many got discarded is written at the end of the section, with the character "x" where the sequence number would be. this is the behaviour that stops your output from being completely swamped by the same issue screaming at you a million times. and note: if maxrepeat is pushed above 9, more than one digit gets used here, so like for maxrepeat=999 the format would be NNN not N. ⭐
  • aaaaa... — the Message text. just a free text description of whatever is being reported. 💬

if that format isn't your vibe, there are others you can pick with the format parameter, which right now also supports JSON. and if you want even more flexible interaction with the output, you can invoke taplint programmatically and supply your own instance. main character energy tbh. ✨

🧚 the honest disclaimer (she's complicated)

TAP is a complicated beast, fr fr. it references so many standards, including TAP, UWS, VODataService, ADQL, VOResource, VOSI, TAPRegExt, DALI, ObsCore, ObsLocTAP, EPN-TAP, VOTable, UCD, VOUnits, SSO, SoftID, HTTP, RDFa Lite — and writing a validator that's genuinely comprehensive is hard, especially one that still manages to produce useful output for services sitting at a whole range of compliance levels. 😭

this tool tries to make a wide range of tests, but it does not claim to be comprehensive. if you wanna get an idea of what tests it actually performs, look at the stages listed in the description of the stages parameter. 👀

things it does do pretty well:

  • it checks that declared metadata is consistent, and that it actually matches the data really returned from queries ✅
  • it tests job submission in most of the various ways the TAP standard permits ✅
  • it checks all returned VOTables by effectively running them through votlint ✅

things it does not test much:

  • complex ADQL queries 🙈
  • coordinate/STC-related data types 🙈
  • queries in non-ADQL languages 🙈
  • and service registration 🙈
💅 one more thing: HTTP connections made by this validator are flagged in the User-Agent field with the token "(IVOA-test)". iykyk.

to be continued, bestie... 🌈

💖 OPTIONS 💖

okay bestie, this is the part where we set all the knobs and dials. Every single parameter is right here, no skipping, fr fr. ✨

  • tapurl=<url-value> — this is the base URL of a Table Access Protocol service. It's the bare URL, no trailing "/[a]sync" attached. In the usual case, 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. But sometimes endpoint determination is more complicated, as determined by the interface parameter which may cause endpoints to be read from the capabilities document at tapurl/capabilities, and by other endpoint-specific parameters (syncurl, asyncurl, tablesurl, capabilitiesurl, availabilityurl, examplesurl) for fine tuning.
  • stages=[+/-]XXX ... — determines 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
    • TME: Check content of tables metadata from /tables
    • TMS: Check content of tables metadata from TAP_SCHEMA
    • TMC: Compare table metadata from /tables and TAP_SCHEMA
    • CPV: Validate capabilities against XML schema
    • CAP: Check TAP and TAPRegExt content of capabilities document
    • AVV: Validate availability against XML schema
    • QGE: Make ADQL queries in sync GET mode
    • QPO: Make ADQL queries in sync POST mode
    • QAS: Make ADQL queries in async mode
    • UWS: Test asynchronous UWS/TAP behaviour
    • MDQ: Check table query result columns against declared metadata
    • OBS: Test implementation of ObsCore Data Model
    • LOC: Test implementation of ObsLocTAP Data Model
    • UPL: Make queries with table uploads
    • EXA: Check content of examples document

This parameter can specify what stages to run in the following ways:

  • if left blank, the default list of stages (which is most or all of them) will be run
  • if the value is a space-separated list of three-letter codes, it lists the stages that will be run
  • if the value is a space separated list of three-letter codes preceded by a "+" or "-" character, the named stages will be removed or added to the default list

So "TME CAP" will run only Table Metadata and Capability stages, while "-EXA -UPL" will run all the default stages apart from Examples and Upload. The order in which stages are listed 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 which 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.
  • tables=<name-list> — if supplied, this specifies a list of tables to test. It may be set to a space- or comma-separated list of table names for consideration; any tables not covered by this list are mostly ignored for the purposes of reporting. Matching against table names is case-insensitive, and the asterisk character "*" may be used as a wildcard to match any sequence of characters. Note that matching is against the declared table name which may or may not include a schema name prefix depending on service behaviour. By default this parameter is not set, which means that all tables are considered.
  • 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.
  • interface=tap1.0|tap1.1|cap — defines how the service endpoints and the version of the TAP protocol to use for queries is determined. This may take one of the following (case-insensitive) values:
    • TAP1.0: The standard TAP endpoints are used, without examining the service's capabilities document. The service is queried using version 1.0 of the TAP protocol.
    • TAP1.1: The standard TAP endpoints are used, without examining the service's capabilities document. The service is queried using version 1.1 of the TAP protocol.
    • cap: The service's capabilities document is examined, and the endpoints listed there are used.

The capabilities document, if used, is read from tapurl/capabilities unless the capabilitiesurl parameter is defined, in which case that is used.

The baseline value of all the TAP service endpoints (sync, async, tables, capabilities, examples) are determined by this parameter, but each of those endpoint values may be overridden individually by other endpoint-specific parameters (syncurl, asyncurl, tablesurl, capabilitiesurl, availabilityurl, examplesurl).

For default (unauthenticated) access, the default value is usually suitable.

  • auth=true|false — if true, then an attempt will be made to authenticate with the TAP service even if anonymous operation is permitted. If the service offers authentication, you will be asked for credentials. To use this option in non-interactive contexts, you may want to use the auth.username and auth.password system properties.
  • syncurl=<url-value> — sets the URL to use for the sync endpoint of the TAP service. The default value would be <tapurl>/sync, but it may be influenced by the chosen interface value, and it can be further overridden by setting this value.
  • asyncurl=<url-value> — sets the URL to use for the async endpoint of the TAP service. The default value would be <tapurl>/async, but it may be influenced by the chosen interface value, and it can be further overridden by setting this value.
  • tablesurl=<url-value> — sets the URL to use for the tables endpoint of the TAP service. The default value would be <tapurl>/tables, but it may be influenced by the chosen interface value, and it can be further overridden by setting this value.
  • capabilitiesurl=<url-value> — sets the URL to use for the capabilities endpoint of the TAP service. The default value would be <tapurl>/capabilities, but it may be influenced by the chosen interface value, and it can be further overridden by setting this value.
  • availabilityurl=<url-value> — sets the URL to use for the availability endpoint of the TAP service. The default value would be <tapurl>/availability, but it may be influenced by the chosen interface value, and it can be further overridden by setting this value.
  • examplesurl=<url-value> — sets the URL to use for the examples endpoint of the TAP service. The default value would be <tapurl>/examples, but it may be influenced by the chosen interface value, and it can be further overridden by setting this value.

🦋 SEE ALSO 🦋

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.5.4-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)

okay that's the whole vibe check, bestie. This page is STILTS-TAPLINT(1), dated Mar 2017, and the version we're repping is STILTS version 3.5.4-debian. Now go tap some tables, you icon. 💅✨

📦 where this page comes from