TAP Examples

What is the syntax of a TAP /examples resource?

Introduction

A /examples endpoint is an RDFa document. Basically, it is an XHTML document whose some nodes have specific attributes. These attributes aim to help client performing automatic processing. Thus, clients like TOPCAT are able to retrieve the list of examples that a TAP service provides (see TOPCAT documentation for a more specific illustration).

This optional resource is not part of TAP 1.0, but has been introduced in TAP Implementation Notes 1.0 and IVOA Data Access Layer Interface 1.0 (often abbreviated DALI). Each has a slightly different syntax and both are supported by the class Examples of the TAP Library. Though the two IVOA documents cited above are clear about this special TAP resource, a different and more pratical description of these two syntaxes will be described in this page.

Which one is the best? Which one is the most supported by clients?

The purpose is different. The DALI definition aims to be as generic as possible so that it can works with any service implementing DALI. Now, the TAP Implementation Notes is really specific to the protocol TAP and could not be used by most of the other VO services. So, in a way, the syntax proposed by the TAP Implementation Notes is more suited for a TAP service. Besides, as you will see below, it is also simpler to use.

Both are supported by TOPCAT. It has not been tested with other VO client.

1. Syntax

TAP Impl. Notes 1.0

UML diagram of the structure described by TAPNotes1.0.

DALI 1.0

UML diagram of the structure expected by DALI.

2. Example

TAP Impl. Notes 1.0

<div vocab="ivo://ivoa.net/std/DALI-examples">
	<div typeof="example" id="Example1" resource="#Example1">
		<h2 property="name">List all tables</h2>
		<span property="table">TAP_SCHEMA.tables</span>
		<pre property="query">SELECT *
FROM TAP_SCHEMA.tables
WHERE schema_name <> 'TAP_SCHEMA'</pre>
	</div>
</div>

DALI 1.0

<div vocab="ivo://ivoa.net/std/DALI-examples">
	<div id="Example1" resource="#Example1" typeof="example">
		<h3 property="name">List all tables</h3>
		<p property="capability">ivo://ivoa.net/std/TAP/v1.0</p>
		<span property="table">TAP_SCHEMA.tables</span>
		<div property="generic-parameter" typeof="keyval">
			<span property="key">QUERY</span>
			<pre property="value">SELECT *
FROM TAP_SCHEMA.tables
WHERE schema_name <> 'TAP_SCHEMA'</pre>
		</div>
		<div property="generic-parameter" typeof="keyval">
			<span property="key">REQUEST</span>
			<span property="value">doQuery</span>
		</div>
		<div property="generic-parameter" typeof="keyval">
			<span property="key">LANG</span>
			<span property="value">ADQL</span>
		</div>
	</div>
</div>
vocab location
Note that you can set the vocab attribute to any XHTML node that can have children, including body.
Characters encoding
You should also note that since the ADQL query is written in an XHTML document, any < and > should be encoded as the XML entities: &lt; and &gt;.