/[volute]/trunk/projects/registry/VOResource/VOResource.tex
ViewVC logotype

Contents of /trunk/projects/registry/VOResource/VOResource.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3299 - (show annotations)
Thu Apr 14 13:45:13 2016 UTC (5 years, 3 months ago) by msdemlei
File MIME type: application/x-tex
File size: 103029 byte(s)
VOResource: another attempt at clarifying the namespace prefix policy.


1 \documentclass[11pt,a4paper]{ivoa}
2 \input tthdefs
3
4 \usepackage{todonotes}
5 \usepackage{listings}
6 \lstloadlanguages{XML}
7 \lstset{flexiblecolumns=true,tagstyle=\ttfamily, showstringspaces=False}
8
9 \title{VOResource: an XML Encoding Schema for Resource Metadata}
10
11 \ivoagroup{Registry}
12
13 \author[http://www.ivoa.net/twiki/bin/view/IVOA/RayPlante]{Raymond Plante}
14 \author[http://www.ivoa.net/twiki/bin/view/IVOA/KevinBenson]{Kevin Benson}
15 \author[http://www.ivoa.net/twiki/bin/view/IVOA/MarkusDemleitner]{Markus Demleitner}
16 \author[http://www.ivoa.net/twiki/bin/view/IVOA/MatthewGraham]{Matthew Graham}
17 \author[http://www.ivoa.net/twiki/bin/view/IVOA/GretchenGreene]{Gretchen Greene}
18 \author[http://www.ivoa.net/twiki/bin/view/IVOA/PaulHarrison]{Paul Harrison}
19 \author[http://www.ivoa.net/twiki/bin/view/IVOA/GerardLemson]{Gerard Lemson}
20 \author[http://www.ivoa.net/twiki/bin/view/IVOA/TonyLinde]{Tony Linde}
21 \author[http://www.ivoa.net/twiki/bin/view/IVOA/GuyRixon]{Guy Rixon}
22
23 \editor{Ray Plante, Markus Demleitner}
24
25 \previousversion[http://www.ivoa.net/Documents/REC/ReR/VOResource-20080222.html]{REC -1.03}
26 \previousversion[http://www.ivoa.net/Documents/WD/ReR/VOResource-20061107.html]
27 {WD 2006-11-07}
28 \previousversion[http://www.ivoa.net/Documents/WD/ReR/VOResource-20060620.html]
29 {WD 2006-06-20}
30 \previousversion[http://www.ivoa.net/Documents/WD/ReR/VOResource-20060530.html]
31 {WD-2006-05-30}
32
33
34 \begin{document}
35 \begin{abstract}
36 This document describes an XML encoding standard for IVOA Resource
37 Metadata, referred to as VOResource. This schema is primarily
38 intended to support interoperable registries used for discovering
39 resources; however, any application that needs to describe resources
40 may use this schema. In this document, we define the types and
41 elements that make up the schema as representations of metadata terms
42 defined in Resource Metadata for the Virtual Observatory
43 \citep{2007ivoa.spec.0302H}. We also describe the general model for the
44 schema and explain how it may be extended to add new metadata terms and
45 describe more specific types of resources.
46 \end{abstract}
47
48
49 \section*{Acknowledgments}
50
51 This document has been developed with support from the
52 National Science Foundation's
53 Information Technology Research Program under Cooperative Agreement
54 AST0122449 with The Johns Hopkins University, from the
55 UK Particle Physics and Astronomy
56 Research Council (PPARC), and from the
57 Eurpean Commission's Sixth
58 Framework Program via the
59 Optical Infrared Coordination Network (OPTICON). Funding for the 2016
60 update was provided by BMBF grant GAVO-2014, grant number 05A14VHA.
61
62 \section*{Conformance-related definitions}
63
64 The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
65 ``OPTIONAL'' (in upper or lower case) used in this document are to be
66 interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.
67
68 The \emph{Virtual Observatory (VO)} is a
69 general term for a collection of federated resources that can be used
70 to conduct astronomical research, education, and outreach.
71 The \href{http://www.ivoa.net}{International
72 Virtual Observatory Alliance (IVOA)} is a global
73 collaboration of separately funded projects to develop standards and
74 infrastructure that enable VO applications.
75
76 \section*{Syntax Notation Using XML Schema}
77
78 The eXtensible Markup Language, or XML, is document syntax for marking
79 textual information with named tags and is defined by \citet{std:XML}.
80 The set of XML tag names and the syntax
81 rules for their use is referred to as the document schema. One way to
82 formally define a schema for XML documents is using the W3C standard
83 known as XML Schema \citep{std:XSD}.
84
85 This document defines the VOResource schema using XML Schema, the
86 authoritative version of which is available at the IVOA document
87 repository\footnote{\url{http://www.ivoa.net/xml}} at any time.
88 Parts of the schema appear within the main sections of this document;
89 however, documentation nodes have been left out for the sake of brevity,
90 and where their content diverges from the one in the document
91 repository, the one in the document repository is authoritative.
92
93 Reference to specific elements and types defined in the VOResource
94 schema include the namespaces prefix \xmlel{vr} as in
95 \xmlel{vr:Resource} (a type defined in the VOResource schema).
96
97 \section{Introduction}
98
99 The IVOA Standard Resource Metadata for the Virtual Observatory
100 \citep{2007ivoa.spec.0302H}, hereafter referred to as RM, defines
101 metadata terms for describing resources. The RM defines a resource as:
102
103 \begin{quotation}
104 \dots VO element that can be described in terms of who curates or
105 maintains it and which can be given a name and a unique identifier.
106 Just about anything can be a resource: it can be an abstract idea,
107 such as sky coverage or an instrumental setup, or it can be fairly
108 concrete, like an organization or a data collection. This definition
109 is consistent with its use in the general Web community as
110 ``anything that has an identity'' \citep{std:RFC2396}. We
111 expand on this definition by saying that it is also describable.
112 \end{quotation}
113
114 The resource metadata are, then, the terms and concepts that describe
115 a resource in general. The RM defines the terms as well as describes
116 reasonable or allowed values; it does not, however, describe how the
117 terms and values should be encoded. This is because resource metadata
118 may be encoded in several different formats, depending on the
119 context. This document specifically describes an encoding called
120 VOResource.
121
122 The primary intended use of VOResource is to provide an XML interchange
123 format for use with resource registries. A registry is a repository of
124 resource descriptions and is employed by users and applications to
125 discover resources. VOResource can be used to pass descriptions from
126 publishers to registries and then from registries to applications.
127 Another inended use is as a language for services to describe themselves
128 directly. VOResource may be used in other ways, in whole or in part,
129 using the standard XML mechanisms (e.g., import, include).
130
131 The VOResource schema provides XML encoding for so-called core
132 metadata from the RM that (with a few exceptions)
133 can apply to all resources; however, it is recognized that a full and
134 useful description of a \emph{specific} resource will require
135 additional metadata that is relevant only to a resource of its type.
136 Thus, the VOResource schema has been especially designed to be
137 extended. The model for doing this is described in
138 sect.~\ref{sect:extending}.
139
140 \begin{admonition}{Note}
141 The name ``VOResource'' has in practice had two meanings within
142 IVOA discussions. The first refers specifically to the core
143 XML schema defined by this document. The second refers more
144 broadly to the core schema plus the set of legal extensions.
145 In this document, use of the name ``VOResource'' corresponds to
146 the first meaning. Reference to the broader set of schemas
147 will be indicated explicitly with the annotating phrase, ``and
148 its legal extensions.''
149 \end{admonition}
150
151 \subsection{Role within the VO Architecture}
152
153 \begin{figure}
154 \centering
155
156 \includegraphics[width=0.9\textwidth]{archdiag.png}
157 \caption{Architecture diagram for this document}
158 \label{fig:archdiag}
159 \end{figure}
160
161 Fig.~\ref{fig:archdiag} shows the VOResource plays within the
162 IVOA architecture \citep{note:VOARCH}.
163
164
165
166 \section{The VOResource Data Model}
167 \label{sect:model}
168
169 The primary use for VOResource, of course, is to describe a resource
170 using the metadata concepts defined in the RM. Here is an example of a
171 VOResource document describing an organisation, the Radio Astronomy
172 Imaging Group at the National Center for Supercomputing Applications.
173
174 \begin{lstlisting}[language=XML,numbers=right,basicstyle=\footnotesize]
175 <?xml version="1.0" encoding="UTF-8"?>
176 <resource xsi:type="Organisation"
177 xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
178 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
179 xsi:schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0
180 http://www.ivoa.net/xml/VOResource/v1.0">
181
182 <title>NCSA Radio Astronomy Imaging</title>
183 <shortName>NCSA-RAI</shortName>
184 <identifier>ivo://rai.ncsa/RAI</identifier>
185
186 <curation>
187 <publisher ivo-id="ivo://ncsa.uiuc/NCSA">
188 National Center for Supercomputing Applications
189 </publisher>
190 <creator>
191 <name> Dr. Richard Crutcher </name>
192 <logo>
193 http://rai.ncsa.uiuc.edu/rai.jpg
194 </logo>
195 </creator>
196 <date>1993-01-01</date>
197 <contact>
198 <name>Dr. Raymond Plante</name>
199 <email>rplante@ncsa.uiuc.edu</email>
200 </contact>
201 </curation>
202
203 <content>
204 <subject>radio astronomy</subject>
205 <subject>data repositories</subject>
206 <subject>digital libraries</subject>
207 <subject>grid-based processing</subject>
208 <description>
209 The Radio Astronomy Imaging Group at the National Center for
210 Supercomputing Applications is focused on applying
211 high-performance computing to astronomical research. Our
212 projects include the NCSA Astronomy Digital Image Library,
213 the BIMA Data Archive, the BIMA Image Pipeline, and the
214 National Virtual Observatory.
215 </description>
216 <referenceURL>http://rai.ncsa.uiuc.edu/</referenceURL>
217 <type>Organisation</type>
218 <contentLevel>Research</contentLevel>
219 </content>
220
221 <facility>Berkeley-Illinois-Maryland Array (BIMA)</facility>
222 <facility>
223 Combined Array for Research in Millimeter Astronomy (CARMA)
224 </facility>
225
226 </resource>
227 \end{lstlisting}
228
229 This example illustrates some important components of a VOResource
230 record:
231
232 \begin{enumerate}
233 \item the VOResource namespace (line 3),
234 \item the specific type of resource indicated by
235 the value of the \xmlel{xsi:type} attribute (line 2),
236 \item the location of the schema documents used by
237 this description (lines 5f),
238 \item values for the three main types core metadata:
239 identity, curation, and content,
240 \item a reference to another resource is made by
241 providing that resource's IVOA identifier (line 13),
242 \item string values can be padded with spaces
243 for easier readability (e.g., line 17),
244 \item extension metadata specific to the type of
245 resource (lines 47ff).
246 \end{enumerate}
247
248
249 \subsection{The Schema Namespace and Location}
250
251 \label{sect:namespace}
252
253
254 The VOResource schema namespace is
255 $$\hbox{\texttt{http://www.ivoa.net/xml/VOResource/v1.0}}.$$
256 The namespace URI has been chosen to allow it to be resolved as a URL
257 to the XML Schema document that defines the VOResource schema.
258 Applications may assume that the namespace URI is so resolvable.
259
260 Document authors are strongly encouraged to bind this namespace to the
261 \xmlel{vr:} prefix. While in generic XML processing, the concrete
262 prefix used is irrelevant as long as the namespace URI mapped is the one
263 given by this specification, in the Virtual Observatory context uniform,
264 per-major-version prefixes are viewed as helping interoperability. This
265 is particularly true when prefixes appear in attribute values (e.g.,
266 \xmlel{xsi:type}), as non-schema aware XML processors cannot
267 URI-normalize such occurrences. Also, non-XML-aware software (e.g., SQL
268 databases) will use these prefixes rather than the full namespace URIs.
269
270 Authors of instance documents that use the VOResource schema may choose
271 to provide a location for VOResource XML Schema document using the
272 \xmlel{xsi:schemaLocation} attribute; the choice of the location value
273 is the choice of the author. In general, the use of
274 \xmlel{xsi:schemaLocation} is recommended by this specification with
275 a the namespace URI given as the location as illustrated in the example
276 above, unless the application prefers otherwise.
277
278
279 \begin{verbatim}
280 xsi:schemaLocation="http://www.ivoa.net/xml/VOResource/v1.0
281 http://www.ivoa.net/xml/VOResource/v1.0"
282 \end{verbatim}
283
284 Because the VOResource XML schema sets \xmlel{elementFormDefault} to
285 unqualified, documents that use the VOResource schema must not bind the
286 empty namespace (using \verb|xmlns="..."|), anywhere in the document
287 where the VOResource schema is in effect. (This is a restriction set by
288 the rules of XML Schema.) Furthermore, in accordance with the Schema
289 rules for unqualified elements, the VOResource namespace prefix must not
290 used to qualify VOResource elements. In general, namespace prefixes are
291 only used to qualify type names given as values to the \xmlel{xsi:type}
292 attribute (see next section). Legal extensions of the VOResource schema
293 SHOULD also set \verb|elementFormDefault="unqualified"| for consistancy.
294
295
296
297 \subsection{The Core Structural and Semantic Model}
298 \label{sect:core}
299
300 The VOResource schema only defines global types; it does not define
301 any global elements (often referred to as root elements). It is the
302 responsibility of the application to define the root element of the
303 VOResource-employing documents it operates on. Typically, the root
304 element is defined in a separate application-specific schema. The
305 type of an application document's root element is not assumed to be
306 any particular type defined in the VOResource schema (nor any of its
307 legal extensions). In fact, it need not be of a type from the
308 VOResource at all; rather, VOResource types may appear anywhere in the
309 document.
310
311
312
313 \begin{admonition}{Note}
314 The IVOA Registry Interface standard, for example, includes a
315 small schema that defines a single global element,
316 \xmlel{VOResources}, that can contain a series of
317 \xmlel{resource} child elements. The child
318 element is defined to be of the type \xmlel{Resource} from
319 the VOResource schema.
320 \end{admonition}
321
322 \begin{admonition}{Note}
323 In the example instance
324 document at the beginning of section~\ref{sect:model}, the root element,
325 \xmlel{resource} is not defined in any schema.
326 Nevertheless, this document is still legal and verifiable XML.
327 This is because the element's type is explicitly specified with
328 the \xmlel{xsi:type} attribute.
329 \end{admonition}
330
331
332 % TODO: subsection name convention?
333
334 VOResource uses the following conventions for
335 names of elements and types:
336
337 \begin{itemize}
338 \item all global types it defines have names that are capitalized.
339 (This practice would extend to global elements, if they existed
340 in the VOResource.)
341 \item Locally defined elements begin with a lower-case character.
342 \item For all types and element names that are made up of multiple
343 words, such as \xmlel{shortName}, upper-case letters are
344 used demarcate the start of appended word (the ``camel''
345 format).
346 \item Names that include abbreviations, such as
347 \xmlel{IdentifierURI}, all letters in the abbreviation are
348 capitalized.
349 \end{itemize}
350
351 It is recommended that this convention be followed in other schemas
352 that either use the VOResource schema (via an \xmlel{xsd:import} or
353 \xmlel{xsd:include}) or extend it.
354
355 Applications describe a single resource using an element of the type
356 \xmlel{vr:Resource} or a legal derivation of it. The content of the
357 \xmlel{vr:Resource} type is referred to as the \textbf{core VOResource
358 metadata}, and they fall into four categories (corresponding to the
359 sections 3.1, 3.2, 3.3, and 4 of the RM):
360
361 \begin{itemize}
362 \item identity metadata: the \xmlel{title},
363 \xmlel{shortName}, and
364 \xmlel{identifier} elements;
365 \item curation metadata: the contents of the
366 \xmlel{curation} element;
367 \item general content metadata: the contents of the
368 \xmlel{content} element;
369 \item metadata quality flags: the
370 \xmlel{validationLevel} element.
371 \end{itemize}
372
373
374 These elements are defined in more detail in sect.~\ref{sect:metadata}.
375
376
377
378 Many of the elements in VOResource that are meant to have string or
379 URI values are defined as being of the type \xmlel{xs:token}.
380 This allows authors of VOResource instance documents to pad string and
381 URI values with spaces and include carriage returns to improve
382 readability. The definition of these types will cause an XML
383 Schema-compliant parser to replace tab, line feed, and carraige return
384 characters with simple spaces, then replace multiple sequential
385 occurrences of spaces with a single space, and then remove all leading
386 and trailing spaces.
387
388
389 % TODO: Actually specify time format
390 All VOResource elements and attributes that contain dates must be
391 interpreted as UTC dates and must be encoded in compliance with ISO8601
392 standard Date and Time Format. The \xmlel{vr:UTCTimestamp} type
393 provides a special restriction of the format that requires includsion of
394 date and time, but disallows the timezone format. This enforces a
395 restricted form of this format which allows encoding of the date and
396 time, but disallows the timezone format:
397
398 % GENERATED: !schemadoc VOResource-v1.0.xsd UTCTimestamp
399 \begingroup
400 \renewcommand*\descriptionlabel[1]{%
401 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:UTCTimestamp} Type Schema Documentation}
402
403 \noindent{\small
404 A timestamp that is compliant with ISO8601 but disallows
405 the use of a timezone indicator.
406 \par}
407
408 \vspace{1ex}\noindent\textbf{\xmlel{vr:UTCTimestamp} Type Schema Definition}
409
410 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
411 <xs:simpleType name="UTCTimestamp" >
412 <xs:restriction base="xs:dateTime" >
413 <xs:pattern
414 value="\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(\.\d+)?" />
415 </xs:restriction>
416 </xs:simpleType>
417 \end{lstlisting}\endgroup
418 % /GENERATED
419
420
421 The \xmlel{vr:UTCDateTime} type allows the date to appear either
422 as a simple date--i.e. conforming to \xmlel{xs:date}--or as a
423 date and time as restricted by \xmlel{vr:UTCTimestamp}.
424 When either of these VOResource types is used, authors must provide an
425 applicable UTC date and time, and applications must interpret the time
426 and date as UTC.
427
428 All VOResource types and elements have an associated semantic meaning
429 which is given in the first \xmlel{xsd:documentation}
430 node within the type or element's definition in the schema. The
431 meaning associated with a type is generic, indicating the kind of
432 information the type provides. The semantics that are delivered by a
433 VOResource instance document, however, are those associated with
434 VOResource elements. The meaning of a VOResource element can be
435 thought of as having two parts: the generic meaning of the set of
436 information it contains as defined by its type, and a specific meaning
437 describing the context in which that information applies. Because all
438 VOResource elements are locally defined (in the XML Schema
439 sense), they do not have an absolute meaning, but rather have a
440 meaning tied to the thing being described by that element as
441 represented by the enclosing type.
442
443 Here are three examples that illustrate the semantics communicated by
444 VOResource entities:
445
446 \begin{enumerate}
447 \item The \xmlel{vr:Curation} type describes the curation of a
448 resource. The \xmlel{curation} element
449 describes curation of the specific resource described by the
450 enclosing \xmlel{vr:Resource} type and identified by its
451 \xmlel{identifier} element.
452
453 \item The \xmlel{vr:ResourceName} type is a generic reference to
454 another resource. The \xmlel{publisher} element
455 gives a reference to the publisher of the specific resource being
456 described which may itself be a registered resource described
457 elsewhere.
458
459 \item The \xmlel{title} element gives the title of
460 the resource being described the enclosing
461 \xmlel{vr:Resource} type and identified by its
462 \xmlel{identifier} element. The
463 \xmlel{title} element's type,
464 \xmlel{xs:token} (a restriction on
465 \xmlel{xsd:string}), has no inherent meaning associated
466 with it.
467 \end{enumerate}
468
469
470 % TODO: reference example?
471 Additional semantics are transmitted through the use of derived types
472 using the \xmlel{xsi:type} attribute. In the sample instance document
473 above, the use of \verb|xsi:type="Organisation"| means that the
474 resource being described is specifically an organisation as defined by
475 the \xmlel{vr:Organisation} type. This type provides additional
476 metadata that are not part of the core resource metadata. The semantics
477 associated with the use of \xmlel{xsi:type} is described further in the
478 next subsection.
479
480
481
482 \subsubsection{Refined Semantics with Derived Types}
483 \label{sect:derivedtypes}
484
485 When a resource is described with an element explicitly of the type
486 \xmlel{vr:Resource}, it is being described in the most generic
487 sense. The metadata presented in this type, including both free text
488 values and controlled vocabulary, can give some sense of what
489 type of resource is being described and what it might be used for.
490 However, the most useful descriptions of resources will not explicitly
491 use the \xmlel{vr:Resource} type; rather, they will use types
492 that are derived from \xmlel{vr:Resource}.
493
494
495
496 Defining derived \xmlel{vr:Resource} types accomplishes two
497 things:
498 \begin{enumerate}
499 \item it sharpens the semantic meaning of the resource description by
500 indicating what specific type of resource it is, and
501 \item it \emph{may} allow additional metadata not part of the core
502 but specific to the that type of resource.
503 \end{enumerate}
504
505
506
507 The VOResource schema defines two types derived from
508 \xmlel{vr:Resource}: \xmlel{vr:Organisation} and
509 \xmlel{vr:Service}. The \xmlel{vr:Organisation} adds
510 metadata describing the astronomical facilities such as telescopes
511 that are associated with the organisation it describes. The
512 \xmlel{vr:Service} type adds an element called
513 \xmlel{capability} which describes the service's interface as
514 well as information regarding its behavior.
515
516
517
518 Extensions of the \xmlel{vr:Resource} type is a key way
519 derivation is used in VOResource to provide refined resource
520 descriptions. Two other important parent types in the schema are
521 \xmlel{vr:Capability} and \xmlel{vr:Interface}; these are
522 extended to provide more refined descriptions of services (see
523 sect.~\ref{sect:servicemodel}). The motivation for extending
524 these types are the same as for \xmlel{vr:Resource}: to provide
525 more specific semantic meaning through the derived type's name, and to
526 provide additional, specialized metadata that is not part of the
527 parent type. Note, however, that in general, a derived type need not
528 alter the content model of its base type. This allows derived types
529 to add more specific meaning with out adding any additional metadata.
530
531
532
533 As described in sect.~\ref{sect:core}, it is intended that derived
534 \xmlel{vr:Resource}, \xmlel{vr:Capability} and \xmlel{vr:Interface}
535 types be invoked in instance documents using the \xmlel{xsi:type}
536 attribute (as illustrated in the sample document above). This method
537 illustrates a polymorphism for resource metadata in that any place where
538 an element of parent type is expected, the derived type may be inserted.
539 The use of \xmlel{xsi:type} illustrates both what specific type is being
540 inserted in as well as what it is being inserted in for. That is, as in
541 our example, the \emph{resource} being described is an
542 \emph{organisation}.
543
544
545
546 The other mechanism for polymorphism provided by XML Schema is
547 substitution groups. Invoking derived \xmlel{vr:Resource} types via
548 elements in a substitution group is discouraged because it is less
549 obvious from looking at the instance document that a substitution is
550 being made.
551
552
553 \subsubsection{The Service Data Model}
554 \label{sect:servicemodel}
555
556
557 The \xmlel{vr:Service} type extends the core \xmlel{vr:Resource}
558 metadata data by adding the \xmlel{capability} element (see
559 sect.~\ref{sect:serviceelements}). This element is used to describe a major
560 functionality of the service, usually accessible through a single
561 service endpoint URL. In particular, it is used to describe support for
562 an IVOA service standard (e.g. Simple Image Access Protocol). A service
563 resource record may have multiple child \xmlel{capability} elements,
564 each describing a different major functionality; however, these
565 capabilities should be related in an obvious, logical way by virtue of
566 sharing same core VOResource metadata.
567
568
569 \begin{admonition}{Note}
570 Whether multiple related capabilities are grouped together in a
571 single Service record or are described in separate Service
572 records is expected to be the choice of the VOResource record
573 author. However, it is also expected that resource registry
574 providers will provide some guidance to authors on best
575 practices. This guidance could in part come in the form of a
576 GUI that naturally encourage or contrains to aggregation of
577 capabilities in a single record.
578 \end{admonition}
579
580 The \xmlel{capability} element, through its type \xmlel{vr:Capability},
581 describes the behavior of service capability and how to access it. The
582 latter is described by a child \xmlel{interface} element. As for the
583 behavior, the base \xmlel{vr:Capability} type only provides a
584 \xmlel{description} element that can contain human-readable text on what
585 this capability provides. More structured behavioral information must
586 be provided through specialized \xmlel{vr:Capability} extensions. In
587 particular, it is expected that a service standard (e.g. Simple Image
588 Access Protocol) would define an extension of \xmlel{vr:Capability} that
589 adds additional metadata that can describe the service's behavior in
590 relation to the standard; for example, the added metadata can describe
591 limitations of the service implementation or indicate support for
592 optional features. The specific \xmlel{vr:Capability} type is invoked
593 using the \xmlel{xsi:type} mechanism described in
594 sect.~\ref{sect:namespace}.
595
596
597 Here is an example for assigning a specialized Capability type for
598 a standard service capability. In this example, it is assumed that
599 \xmlel{SimpleImageAccess} extension type is defined in a separate
600 schema document.
601 \begin{lstlisting}[language=XML]
602 <capability xsi:type="sia:SimpleImageAccess"
603 standardID="ivo://ivoa.net/std/SIA">
604 ...
605 </capability>
606 \end{lstlisting}
607
608
609 As the example above suggests, a common way for locating or otherwise
610 identifying support for a standard service capability is by looking for
611 the appropriate value in a \xmlel{capability}'s \xmlel{xsi:type}
612 attribute.
613
614
615 If the service capability being described does not conform to any
616 standard or if the standard does not require any specialized
617 capability metadata for describing an implementation's behavior, then
618 no \xmlel{vr:Capability} extension is required. In this case,
619 the base \xmlel{capability} element is simply used without any
620 \xmlel{xsi:type} attribute provided. It is expected that the
621 metadata provided outside of the \xmlel{capability} element as
622 well as (optionally) it's \xmlel{description} element is
623 sufficient for describing what the service does.
624
625
626
627 Because each \xmlel{vr:Capability} extension features a different
628 set of behavioral metadata, introducing a new
629 \xmlel{vr:Capability} extension can impose a non-trivial cost on
630 applications that process VOResource records. Thus, an alternative
631 way to indicate support for a service standard is provided by the
632 \xmlel{standardID} attribute which is useful when the standard
633 does not require any specialized behavioral metadata to be provided.
634 The value is set to a URI which represents the service standard. Some
635 service standards that do extend \xmlel{vr:Capability}
636 \emph{may} force the value of this attribute to be set to the
637 appropriate value (see sect.~\ref{sect:derivedtypes});
638 this allows one to use, when appropriate, the \xmlel{standardID}
639 as a way to locate support for a standard regardless of whether an
640 extension type has been defined or not.
641
642
643
644 Each \xmlel{capability} element can contain one or more child
645 \xmlel{interface} elements, each describing how the capability
646 can be accessed. The \xmlel{interface} element's type,
647 \xmlel{vr:Interface}, is abstract; thus, the
648 \xmlel{interface} element must be accompanied by an
649 \xmlel{xsi:type} attribute that indicates an
650 \xmlel{vr:Interface} extension type. The VOResource schema
651 defines two \xmlel{vr:Interface} extension types:
652 \xmlel{vr:WebBrowser}, for describing an interface access via web
653 browser, and \xmlel{vr:WebService}, for accessing a service
654 described by a Web Service Description Language (WSDL) document.
655
656
657 When a \xmlel{capability} contains more than one
658 \xmlel{interface}, each \xmlel{interface} should be
659 interpreted as an alternative interface for accessing essentially the
660 same underlying capability. The interfaces can differ in their
661 overall type (e.g. \xmlel{vr:WebBrowser},
662 \xmlel{vr:WebService}) or in the supported input parameters or
663 output products.
664
665
666 When a standard capability is being described (i.e. either the
667 \xmlel{vr:Capability} sub-type is defined by a standard or the
668 \xmlel{standardID} is provided), then at least one of the
669 \xmlel{interface} elements should describe an interface required
670 by the standard. The \xmlel{role} attribute is used to mark the
671 standard interfaces (typically with the value ``std'').
672 All other interfaces are considered non-standard
673 alternatives.
674
675
676 % TODO: We probably don't want this any more
677 Another important way \xmlel{interface}s inside the same
678 \xmlel{capability} element can be different is in the version of
679 the service standard the interface supports. Whenever, an interface
680 supports a version other than \texttt{"1.0"}, the \xmlel{interface}
681 element must include a \xmlel{version} attribute set to the
682 version being supported. Valid values for \xmlel{version} are
683 defined by the standard.
684
685 Here is an example for describing multiple interfaces for the same
686 capability. It is assumed that SkyNode extension type is defined in a
687 separate schema document.
688
689 \begin{lstlisting}[language=XML]
690 <capability xsi:type="sn:SkyNode"
691 standardID="ivo://ivoa.net/std/SkyNode">
692
693 <!-- version 1.0 of the standard SkyNode interface -->
694 <interface xsi:type="vr:WebService" role="std" version="1.0">
695 <accessURL> http://archive.org/service/skynode </accessURL>
696 </interface>
697
698 <!-- version 1.1 of the standard SkyNode interface -->
699 <interface xsi:type="vr:WebService" role="std" version="1.1">
700 <accessURL> http://archive.org/service/skynode1.1 </accessURL>
701 </interface>
702
703 <!-- a interactive alternative interface, assesible via a browser -->
704 <interface xsi:type="vr:WebBrowser">
705 <accessURL> http://archive.org/skynode.html </accessURL>
706 </interface>
707 ...
708 </capability>
709 \end{lstlisting}
710
711 % TODO: discourage this pattern
712
713 \subsection{Extending the VOResource Schema}
714
715 \label{sect:extending}
716
717 A schema made up only of global type definitions provides great
718 flexibility for extension. Any global type defined in the VOResource
719 schema may be used as the base of a derived type defined in another
720 schema. The schema containing the derived types must declare its own
721 namespace URI or default to the null namespace; it must not adopt the
722 VOResource namespace URI. The application must then define what
723 schemas, identified by their namespace URIs, are supported and/or
724 required.
725
726
727
728 A \textbf{VOResource extension} is an XML Schema document whose primary
729 purpose is to define new types derived from those defined in the
730 VOResource schema for use in resource descriptions. It is recommended
731 that VOResource extensions follow the definition styles used by the core
732 VOResource. In particular:
733
734 \begin{itemize}
735 \item \emph{Provide semantic definitions of all types and elements within
736 the first \xmlel{xsd:documentation} element inside
737 the type or element definition.} Subsequent
738 \xmlel{xsd:documentation} elements may provide
739 additional comments or discussion.
740
741 \item \emph{Avoid the use of \xmlel{xsd:choice} elements.}
742 VOResource does not use the choice structure because it does
743 not map readily into any object-oriented software language
744 structure. Choices are handled instead as multiple derived
745 types that can be inserted in place of a parent type.
746
747 \item \emph{Avoid the use of substitution groups}. VOResource
748 prefers instead the use of \xmlel{xsi:type} which are
749 (with a few exceptions) functionally equivalent to substitution
750 groups in terms of structure; however, \xmlel{xsi:type}
751 serves as an obvious flag in the instance document that a
752 substitution has been made.
753
754 \item \emph{Choose semantically meaningful names for derived
755 types.} When the derived type appears in the pattern
756 \verb|<elname xsi:type="derivedType"|,
757 choose a \textit{derivedType} name such that the sentence, ``a
758 \textit{derivedType} is a kind of \textit{elname}'' makes natural
759 and obvious sense. For example, ``an \textit{Organisation} is a
760 kind of \textit{resource}.''
761
762 \item \emph{Follow the VOResource naming conventions}.
763 \end{itemize}
764
765
766
767 There are two types of derivation that are particularly important to
768 the VOResource data model: derivation of the \xmlel{vr:Resource}
769 type, used to define specific types of resources, and the derivation
770 of service metadata elements.
771
772
773 \subsubsection{Defining New Resource Types}
774 \label{sect:definingresourcetypes}
775
776
777 Derivation of \xmlel{vr:Resource} to define new kinds of
778 resources should be done by extension (i.e. using
779 \xmlel{xsd:extension}) rather than restriction. It is
780 not required that the derived type change the content model from that
781 of the \xmlel{vr:Resource} base type; in this case, the purpose
782 of the derivation is only to sharpen the semantic meaning of the
783 resource description.
784
785
786 \subsubsection{Defining New Service Capabilities and Interfaces}
787 \label{sect:serviceelements}
788
789
790 As described in sect.~\ref{sect:servicemodel}, a service
791 standard will often define a new \xmlel{vr:Capability} extension
792 type to allow implementations to describe how they support the
793 standard. This definition of the \xmlel{vr:Capability} extension
794 should be done in a schema document with a namespace identifier that
795 is dedicated to that standard (hereafter referred to as \emph{the
796 standard's extension schema}). The extension type should include
797 elements representing the applicable Capability metadata described in
798 section 5.2 of the RM
799 (e.g. \emph{Service.MaxReturnRecords}, \emph{Service.MaxReturnSize})
800 but can also include other concepts that are specific to that standard.
801
802
803
804 The standard's extension schema \emph{may} create a derived
805 \xmlel{vr:Capability} type that forces the value of the
806 \xmlel{standardID} attribute to be set to a given URI. This
807 should be done by first deriving from \xmlel{vr:Capability} by
808 \emph{restriction} (i.e. using
809 \xmlel{xsd:restriction}), keeping all of the parent's
810 content model except adding to the \xmlel{standardID}'s attribute
811 definition \verb|use="required"| along with the
812 \xmlel{fixed} modifier set to the desired URI. Since this
813 restricted type is not intended for direct use in an instance
814 document, it should be marked as abstract. The restricted type should
815 then be extended to add the specialized capability metadata required
816 by the standard. (See the example below.)
817
818
819
820 It is not recommended that standard's extension schema attempt to
821 force the inclusion of a required interface type.
822
823
824
825 An extension schema can define new interface types, though not
826 necessarily in the context of any specific standard service
827 capability. The basic \xmlel{vr:Interface} type provides only
828 \xmlel{accessURL} and \xmlel{securityMethod} as child
829 elements. A derived \xmlel{vr:Interface} type must indicate in
830 the documentation how the \xmlel{accessURL} should be
831 interpreted and used. The derived type may also include other added
832 metadata describing how to use the service (e.g., a description of the
833 input arguments). If the interface extension type is expected to be
834 referenced by a standard service capability, then it is recommended
835 that the additional metadata be optional unless the metadata is
836 absolutely required by clients in order to invoke the service.
837
838
839
840 \begin{admonition}{Note}
841 It is intended that a set of common generic interface types
842 would be defined in a separate VOResource extension schema.
843 At the time of this writing, this schema is called
844 VODataService. It currently defines an interface type for
845 describing traditional GET and POST services. More specific
846 interfaces, particularly those associated with standard IVOA
847 services (like a Registry Service) would derive its specific
848 interface descriptions from one of the common types as
849 appropriate.
850 \end{admonition}
851
852
853 \begin{admonition}{Note}
854 The Simple Image Access Protocol \citep{2009ivoa.spec.1111H} is an
855 example of a standard service that defines capability
856 metadata. These include ``maxRecords'' that list the maximum
857 number of records the SIA implementation can return at a time,
858 and ``MaxImageSize'' gives the maximum image size that the
859 service can return.
860 \end{admonition}
861
862 % TODO: cite some examples for capability derivations
863
864
865 \section{The VOResource Metadata}
866 \label{sect:metadata}
867
868
869 This section enumerates the types and elements defined in the
870 VOResource schema and describes their meaning in terms of the
871 RM.
872
873
874 \subsection{The Base Resource Type}
875
876 \label{sect:restype}
877
878 A resource, as defined by the RM, is any entity or component of a VO
879 application that is describable and identifiable by a IVOA Identifier.
880 A resource is described using VOResource by an element of the type
881 \xmlel{vr:Resource} or one of its legal extensions. The schema
882 definition (below) includes elements that encode the identity, curation,
883 and general content metadata for a resource (see sections 3.1 through
884 3.3 of the RM). The RM states that certain metadata are required in a
885 minimally compliant resource description; this requirement is enforced
886 by the VOResource schema definition.
887
888 % GENERATED: !schemadoc VOResource-v1.0.xsd Resource
889 \begingroup
890 \renewcommand*\descriptionlabel[1]{%
891 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Resource} Type Schema Documentation}
892
893 \noindent{\small
894 Any entity or component of a VO application that is
895 describable and identifiable by a IVOA Identifier.
896 \par}
897
898 \vspace{1ex}\noindent\textbf{\xmlel{vr:Resource} Type Schema Definition}
899
900 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
901 <xs:complexType name="Resource" >
902 <xs:sequence >
903 <xs:element name="validationLevel" type="vr:Validation" minOccurs="0"
904 maxOccurs="unbounded" />
905 <xs:element name="title" type="xs:token" />
906 <xs:element name="shortName" type="vr:ShortName" minOccurs="0" />
907 <xs:element name="identifier" type="vr:IdentifierURI" />
908 <xs:element name="curation" type="vr:Curation" />
909 <xs:element name="content" type="vr:Content" />
910 </xs:sequence>
911 <xs:attribute name="created" type="xs:dateTime" use="required" />
912 <xs:attribute name="updated" type="xs:dateTime" use="required" />
913 <xs:attribute name="status" use="required" >
914 <xs:simpleType >
915 <xs:restriction base="xs:string" >
916 <xs:enumeration value="active" />
917 <xs:enumeration value="inactive" />
918 <xs:enumeration value="deleted" />
919 </xs:restriction>
920 </xs:simpleType>
921 </xs:attribute>
922 </xs:complexType>
923 \end{lstlisting}
924
925 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Resource} Attributes}
926
927 \begingroup\small\begin{bigdescription}
928 \item[created]
929 \begin{description}
930 \item[Type] \xmlel{xs:dateTime}
931 \item[Meaning]
932 The UTC date and time this resource metadata description
933 was created.
934
935 \item[Occurrence] required
936 \item[Comment]
937 This timestamp must not be in the future. This time is
938 not required to be accurate; it should be at least
939 accurate to the day. Any insignificant time fields
940 should be set to zero.
941
942 \end{description}
943 \item[updated]
944 \begin{description}
945 \item[Type] \xmlel{xs:dateTime}
946 \item[Meaning]
947 The UTC date this resource metadata description was last updated.
948
949 \item[Occurrence] required
950 \item[Comment]
951 This timestamp must not be in the future. This time is
952 not required to be accurate; it should be at least
953 accurate to the day. Any insignificant time fields
954 should be set to zero.
955
956 \end{description}
957 \item[status]
958 \begin{description}
959 \item[Type] string with controlled vocabulary
960 \item[Meaning]
961 a tag indicating whether this resource is believed to be still
962 actively maintained.
963
964 \item[Occurrence] required
965
966 \item[Allowed Values]\hfil
967 \begin{longtermsdescription}\item[active]
968 resource is believed to be currently maintained, and its
969 description is up to date (default).
970
971 \item[inactive]
972 resource is apparently not being maintained at the present.
973
974 \item[deleted]
975 resource publisher has explicitly deleted the resource.
976
977 \end{longtermsdescription}
978 \end{description}
979
980
981 \end{bigdescription}\endgroup
982
983
984
985 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Resource} Metadata Elements}
986
987 \begingroup\small\begin{bigdescription}\item[Element \xmlel{validationLevel}]
988 \begin{description}
989 \item[Type] \xmlel{vr:ValidationLevel} with optional attributes
990 \item[Meaning]
991 A numeric grade describing the quality of the
992 resource description, when applicable,
993 to be used to indicate the confidence an end-user
994 can put in the resource as part of a VO application
995 or research study.
996
997 \item[Occurrence] optional; multiple occurrences allowed.
998 \item[Comment]
999 See vr:ValidationLevel for an explanation of the
1000 allowed levels.
1001
1002 \item[Comment]
1003 Note that when this resource is a Service, this
1004 grade applies to the core set of metadata.
1005 Capability and interface metadata, as well as the
1006 compliance of the service with the interface
1007 standard, is rated by validationLevel tag in the
1008 capability element (see the vr:Service complex
1009 type).
1010
1011
1012 \end{description}
1013 \item[Element \xmlel{title}]
1014 \begin{description}
1015 \item[Type] string: \xmlel{xs:token}
1016 \item[Meaning]
1017 the full name given to the resource
1018
1019 \item[Occurrence] required
1020
1021 \end{description}
1022 \item[Element \xmlel{shortName}]
1023 \begin{description}
1024 \item[Type] string
1025 \item[Meaning]
1026 a short name or abbreviation given to the resource.
1027
1028 \item[Occurrence] optional
1029
1030 \item[Comment]
1031 This name will be used where brief annotations for
1032 the resource name are required. Applications may
1033 use to refer to this resource in a compact display.
1034
1035 \item[Comment]
1036 One word or a few letters is recommended. No more
1037 than sixteen characters are allowed.
1038
1039
1040 \end{description}
1041 \item[Element \xmlel{identifier}]
1042 \begin{description}
1043 \item[Type] an IVOA Identifier URI: vr:IdentifierURI
1044 \item[Meaning]
1045 Unambiguous reference to the resource conforming to the IVOA
1046 standard for identifiers
1047
1048 \item[Occurrence] required
1049
1050
1051 \end{description}
1052 \item[Element \xmlel{curation}]
1053 \begin{description}
1054 \item[Type] composite: \xmlel{vr:Curation}
1055 \item[Meaning]
1056 Information regarding the general curation of the resource
1057
1058 \item[Occurrence] required
1059
1060 \end{description}
1061 \item[Element \xmlel{content}]
1062 \begin{description}
1063 \item[Type] composite: \xmlel{vr:Content}
1064 \item[Meaning]
1065 Information regarding the general content of the resource
1066
1067 \item[Occurrence] required
1068
1069 \end{description}
1070
1071
1072 \end{bigdescription}\endgroup
1073
1074 \endgroup
1075 % /GENERATED
1076
1077 Note that the \xmlel{vr:Resource} attributes (\xmlel{created},
1078 \xmlel{updated}, \xmlel{status}) represent a special class of
1079 metadata: they describe the resource metadata description contained
1080 within the \xmlel{vr:Resource} itself as opposed to the resource being
1081 described.
1082
1083 The following sections discuss the items mentioned in the above
1084 definitions.
1085 All rules and advice given in the ``Comments'' portions in
1086 the RM definition for the individual items
1087 apply. In some details, in particular as regards enumerations of values,
1088 this document deviates from RM in content.
1089
1090 \subsubsection{Identity Metadata}
1091
1092 The identity metadata described in the RM (section
1093 3.1) are represented as top-level children of the
1094 \xmlel{vr:Resource} type.
1095
1096 \todo{I think we should deprecate IdentifierURI (what's that URI in
1097 there now? And then there'd be IVOID (which may have query parts and
1098 fragments) and perhaps RegistryReference (as in ``Reference into the
1099 registry'' with the current IdentifierURI's pattern.}
1100 Two special types, \xmlel{vr:ShortName} and
1101 \xmlel{vr:IdentifierURI} are defined to support identity
1102 metadata. The \xmlel{vr:ShortName} definition enforces the
1103 16-character limit on shortNames.
1104
1105 % GENERATED: !schemadoc VOResource-v1.0.xsd ShortName
1106 \begingroup
1107 \renewcommand*\descriptionlabel[1]{%
1108 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:ShortName} Type Schema Documentation}
1109
1110 \noindent{\small
1111 a short name or abbreviation given to something.
1112 \par}
1113
1114 \noindent{\small
1115 This name will be used where brief annotations for
1116 the resource name are required. Applications may
1117 use to refer to this resource in a compact display.
1118 \par}
1119
1120 \noindent{\small
1121 One word or a few letters is recommended. No more
1122 than sixteen characters are allowed.
1123 \par}
1124
1125 \vspace{1ex}\noindent\textbf{\xmlel{vr:ShortName} Type Schema Definition}
1126
1127 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1128 <xs:simpleType name="ShortName" >
1129 <xs:restriction base="xs:token" >
1130 <xs:maxLength value="16" />
1131 </xs:restriction>
1132 </xs:simpleType>
1133 \end{lstlisting}\endgroup
1134 % /GENERATED
1135
1136 % GENERATED: !schemadoc VOResource-v1.0.xsd ResourceKey
1137 \begingroup
1138 \renewcommand*\descriptionlabel[1]{%
1139 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{1ex}\noindent\textbf{\xmlel{vr:ResourceKey} Type Schema Definition}
1140
1141 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1142 <xs:simpleType name="ResourceKey" >
1143 <xs:restriction base="xs:token" >
1144 <xs:pattern
1145 value="[\w\d\-_\.!~\*'\(\)\+=]+(/[\w\d\-_\.!~\*'\(\)\+=]+)*" />
1146 </xs:restriction>
1147 </xs:simpleType>
1148 \end{lstlisting}\endgroup
1149 % /GENERATED
1150
1151
1152
1153 \subsubsection{Curation Metadata}
1154
1155
1156 The curation metadata described in the RM (section
1157 3.2) are bundled together into the \xmlel{vr:Resource} child element
1158 \xmlel{curation}. Its content is defined by the
1159 \xmlel{vr:Curation} complex type.
1160
1161
1162
1163 % GENERATED: !schemadoc VOResource-v1.0.xsd Curation
1164 \begingroup
1165 \renewcommand*\descriptionlabel[1]{%
1166 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Curation} Type Schema Documentation}
1167
1168 \noindent{\small
1169 Information regarding the general curation of a resource
1170 \par}
1171
1172 \vspace{1ex}\noindent\textbf{\xmlel{vr:Curation} Type Schema Definition}
1173
1174 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1175 <xs:complexType name="Curation" >
1176 <xs:sequence >
1177 <xs:element name="publisher" type="vr:ResourceName" />
1178 <xs:element name="creator" type="vr:Creator" minOccurs="0"
1179 maxOccurs="unbounded" />
1180 <xs:element name="contributor" type="vr:ResourceName" minOccurs="0"
1181 maxOccurs="unbounded" />
1182 <xs:element name="date" type="vr:Date" minOccurs="0"
1183 maxOccurs="unbounded" />
1184 <xs:element name="version" type="xs:token" minOccurs="0" />
1185 <xs:element name="contact" type="vr:Contact" maxOccurs="unbounded" />
1186 </xs:sequence>
1187 </xs:complexType>
1188 \end{lstlisting}
1189
1190 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Curation} Metadata Elements}
1191
1192 \begingroup\small\begin{bigdescription}\item[Element \xmlel{publisher}]
1193 \begin{description}
1194 \item[Type] string with ID attribute: vr:ResourceName
1195 \item[Meaning]
1196 Entity (e.g. person or organisation) responsible for making the
1197 resource available
1198
1199 \item[Occurrence] required
1200
1201 \end{description}
1202 \item[Element \xmlel{creator}]
1203 \begin{description}
1204 \item[Type] composite: \xmlel{vr:Creator}
1205 \item[Meaning]
1206 The entity (e.g. person or organisation) primarily responsible
1207 for creating the content or constitution of the resource.
1208
1209 \item[Occurrence] optional; multiple occurrences allowed.
1210 \item[Comment]
1211 A logo need only be provided for the first occurance.
1212 When multiple logos are supplied via multiple creator
1213 elements, the application is free to choose which to
1214 use.
1215
1216
1217 \end{description}
1218 \item[Element \xmlel{contributor}]
1219 \begin{description}
1220 \item[Type] string with ID attribute: vr:ResourceName
1221 \item[Meaning]
1222 Entity responsible for contributions to the content of
1223 the resource
1224
1225 \item[Occurrence] optional; multiple occurrences allowed.
1226
1227 \end{description}
1228 \item[Element \xmlel{date}]
1229 \begin{description}
1230 \item[Type] \xmlel{vr:UTCDateTime} with optional attributes
1231 \item[Meaning]
1232 Date associated with an event in the life cycle of the
1233 resource.
1234
1235 \item[Occurrence] optional; multiple occurrences allowed.
1236 \item[Comment]
1237 This will typically be associated with the creation or
1238 availability (i.e., most recent release or version) of
1239 the resource. Use the role attribute to clarify.
1240
1241
1242 \end{description}
1243 \item[Element \xmlel{version}]
1244 \begin{description}
1245 \item[Type] string: \xmlel{xs:token}
1246 \item[Meaning]
1247 Label associated with creation or availablilty of a version of
1248 a resource.
1249
1250 \item[Occurrence] optional
1251
1252 \end{description}
1253 \item[Element \xmlel{contact}]
1254 \begin{description}
1255 \item[Type] composite: \xmlel{vr:Contact}
1256 \item[Meaning]
1257 Information that can be used for contacting someone with
1258 regard to this resource.
1259
1260 \item[Occurrence] required; multiple occurrences allowed.
1261
1262 \end{description}
1263
1264
1265 \end{bigdescription}\endgroup
1266
1267 \endgroup
1268 % /GENERATED
1269
1270 Several of the curation elements (most importantly,
1271 \xmlel{publisher}\/) make use of the
1272 \xmlel{vr:ResourceName} type. This type is provides a means of
1273 refering to another resource both by name and by its IVOA
1274 identifier. Not all resources referred to using this type will
1275 necessarily be registered and, therefore, will have an identifier;
1276 thus, the identifier (which is encoded as an attribute) is optional.
1277
1278
1279 % GENERATED: !schemadoc VOResource-v1.0.xsd ResourceName
1280 \begingroup
1281 \renewcommand*\descriptionlabel[1]{%
1282 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:ResourceName} Type Schema Documentation}
1283
1284 \noindent{\small
1285 The name of a potentially registered resource. That is, the entity
1286 referred to may have an associated identifier.
1287 \par}
1288
1289 \vspace{1ex}\noindent\textbf{\xmlel{vr:ResourceName} Type Schema Definition}
1290
1291 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1292 <xs:complexType name="ResourceName" >
1293 <xs:simpleContent >
1294 <xs:extension base="xs:token" >
1295 <xs:attribute name="ivo-id" type="vr:IdentifierURI" />
1296 </xs:extension>
1297 </xs:simpleContent>
1298 </xs:complexType>
1299 \end{lstlisting}
1300
1301 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:ResourceName} Attributes}
1302
1303 \begingroup\small\begin{bigdescription}
1304 \item[ivo-id]
1305 \begin{description}
1306 \item[Type] an IVOA Identifier URI: vr:IdentifierURI
1307 \item[Meaning]
1308 The IVOA identifier for the resource referred to.
1309
1310 \item[Occurrence] optional
1311
1312 \end{description}
1313
1314
1315 \end{bigdescription}\endgroup
1316
1317 \endgroup
1318 % /GENERATED
1319
1320
1321 The \xmlel{creator} element is defined by the \xmlel{vr:Creator} complex
1322 type which bundles together the RM metadata \emph{Creator} and
1323 \emph{Creator.Logo}.
1324
1325
1326
1327 % GENERATED: !schemadoc VOResource-v1.0.xsd Creator
1328 \begingroup
1329 \renewcommand*\descriptionlabel[1]{%
1330 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Creator} Type Schema Documentation}
1331
1332 \noindent{\small
1333 The entity (e.g. person or organisation) primarily responsible
1334 for creating something
1335 \par}
1336
1337 \vspace{1ex}\noindent\textbf{\xmlel{vr:Creator} Type Schema Definition}
1338
1339 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1340 <xs:complexType name="Creator" >
1341 <xs:sequence >
1342 <xs:element name="name" type="vr:ResourceName" />
1343 <xs:element name="logo" type="xs:anyURI" minOccurs="0" />
1344 </xs:sequence>
1345 </xs:complexType>
1346 \end{lstlisting}
1347
1348 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Creator} Metadata Elements}
1349
1350 \begingroup\small\begin{bigdescription}\item[Element \xmlel{name}]
1351 \begin{description}
1352 \item[Type] string with ID attribute: vr:ResourceName
1353 \item[Meaning]
1354 the name or title of the creating person or organization
1355
1356 \item[Occurrence] required
1357 \item[Comment]
1358 Users of the creation should use this name in
1359 subsequent credits and acknowledgements.
1360
1361
1362 \end{description}
1363 \item[Element \xmlel{logo}]
1364 \begin{description}
1365 \item[Type] a URI: \xmlel{xs:anyURI}
1366 \item[Meaning]
1367 URL pointing to a graphical logo, which may be used to help
1368 identify the information source
1369
1370 \item[Occurrence] optional
1371
1372 \end{description}
1373
1374
1375 \end{bigdescription}\endgroup
1376
1377 \endgroup
1378 % /GENERATED
1379
1380
1381 The \xmlel{Date} element's type, \xmlel{vr:Date}, is an extension of the
1382 \xmlel{UTCDateTime} type that adds an
1383 optional attribute called \xmlel{role}.
1384
1385 The purpose of the role attribute is to indicate what aspect of the
1386 resource the date describes. This allows several \xmlel{date} elements to be
1387 provided, each with a different role. The possible values for this
1388 attribute are not controlled; however, several values are recommended
1389 below and may be recognized by applications. Other roles may be given.
1390 If a role is not given, applications should interpret the date as
1391 representative as defined below.
1392
1393 % GENERATED: !schemadoc VOResource-v1.0.xsd Date
1394 \begingroup
1395 \renewcommand*\descriptionlabel[1]{%
1396 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{1ex}\noindent\textbf{\xmlel{vr:Date} Type Schema Definition}
1397
1398 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1399 <xs:complexType name="Date" >
1400 <xs:simpleContent >
1401 <xs:extension base="vr:UTCDateTime" >
1402 <xs:attribute name="role" type="xs:string" default="representative" />
1403 </xs:extension>
1404 </xs:simpleContent>
1405 </xs:complexType>
1406 \end{lstlisting}
1407
1408 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Date} Attributes}
1409
1410 \begingroup\small\begin{bigdescription}
1411 \item[role]
1412 \begin{description}
1413 \item[Type] string: \xmlel{xs:string}
1414 \item[Meaning]
1415 A string indicating what the date refers to.
1416
1417 \item[Occurrence] optional
1418 representative
1419 \item[Comment]
1420 While this vocabulary is uncontrolled, recognized strings
1421 include {"}creation{"}, indicating the date that the resource
1422 itself was created, and {"}update{"}, indicating when the
1423 resource was updated last. The default value,
1424 {"}representative{"}, means that the date is a rough
1425 representation of the time coverage of the resource.
1426
1427 \item[Comment]
1428 Note that this date refers to the resource; dates describing
1429 the metadata description of the resource are handled by
1430 the {"}created{"} and {"}updated{"} attributes of the Resource
1431 element.
1432
1433 \end{description}
1434
1435
1436 \end{bigdescription}\endgroup
1437
1438 \endgroup
1439 % /GENERATED
1440
1441
1442
1443 The \xmlel{contact} element is defined by the
1444 \xmlel{vr:Contact} type which bundles together several component
1445 pieces of information, including the RM metadata \emph{Contact.Name}
1446 and \emph{Contact.Email}.
1447
1448
1449
1450 % GENERATED: !schemadoc VOResource-v1.0.xsd Contact
1451 \begingroup
1452 \renewcommand*\descriptionlabel[1]{%
1453 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Contact} Type Schema Documentation}
1454
1455 \noindent{\small
1456 Information that can be used for contacting someone
1457 \par}
1458
1459 \vspace{1ex}\noindent\textbf{\xmlel{vr:Contact} Type Schema Definition}
1460
1461 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1462 <xs:complexType name="Contact" >
1463 <xs:sequence >
1464 <xs:element name="name" type="vr:ResourceName" />
1465 <xs:element name="address" type="xs:token" minOccurs="0" />
1466 <xs:element name="email" type="xs:token" minOccurs="0" />
1467 <xs:element name="telephone" type="xs:token" minOccurs="0" />
1468 </xs:sequence>
1469 </xs:complexType>
1470 \end{lstlisting}
1471
1472 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Contact} Metadata Elements}
1473
1474 \begingroup\small\begin{bigdescription}\item[Element \xmlel{name}]
1475 \begin{description}
1476 \item[Type] string with ID attribute: vr:ResourceName
1477 \item[Meaning]
1478 the name or title of the contact person.
1479
1480 \item[Occurrence] required
1481 \item[Comment]
1482 This can be a person's name, e.g. {"}John P. Jones{"} or
1483 a group, {"}Archive Support Team{"}.
1484
1485
1486 \end{description}
1487 \item[Element \xmlel{address}]
1488 \begin{description}
1489 \item[Type] string: \xmlel{xs:token}
1490 \item[Meaning] the contact mailing address
1491 \item[Occurrence] optional
1492 \item[Comment]
1493 All components of the mailing address are given in one
1494 string, e.g. {"}3700 San Martin Drive, Baltimore, MD 21218 USA{"}.
1495
1496
1497 \end{description}
1498 \item[Element \xmlel{email}]
1499 \begin{description}
1500 \item[Type] string: \xmlel{xs:token}
1501 \item[Meaning] the contact email address
1502 \item[Occurrence] optional
1503
1504 \end{description}
1505 \item[Element \xmlel{telephone}]
1506 \begin{description}
1507 \item[Type] string: \xmlel{xs:token}
1508 \item[Meaning] the contact telephone number
1509 \item[Occurrence] optional
1510 \item[Comment]
1511 Complete international dialing codes should be given, e.g.
1512 {"}+1-410-338-1234{"}.
1513
1514
1515 \end{description}
1516
1517
1518 \end{bigdescription}\endgroup
1519
1520 \endgroup
1521 % /GENERATED
1522
1523
1524
1525 \subsubsection{General Content Metadata}
1526
1527
1528 The general content metadata described in the RM
1529 (section 3.3) are bundled together into the \xmlel{vr:Resource}
1530 child element \xmlel{content}. Its content is
1531 defined by the \xmlel{vr:Content} complex type.
1532
1533
1534 % GENERATED: !schemadoc VOResource-v1.0.xsd Content
1535 \begingroup
1536 \renewcommand*\descriptionlabel[1]{%
1537 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Content} Type Schema Documentation}
1538
1539 \noindent{\small
1540 Information regarding the general content of a resource
1541 \par}
1542
1543 \vspace{1ex}\noindent\textbf{\xmlel{vr:Content} Type Schema Definition}
1544
1545 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1546 <xs:complexType name="Content" >
1547 <xs:sequence >
1548 <xs:element name="subject" type="xs:token" maxOccurs="unbounded" />
1549 <xs:element name="description" type="xs:token" />
1550 <xs:element name="source" type="vr:Source" minOccurs="0" />
1551 <xs:element name="referenceURL" type="xs:anyURI" />
1552 <xs:element name="type" type="vr:Type" minOccurs="0"
1553 maxOccurs="unbounded" />
1554 <xs:element name="contentLevel" type="vr:ContentLevel" minOccurs="0"
1555 maxOccurs="unbounded" />
1556 <xs:element name="relationship" type="vr:Relationship" minOccurs="0"
1557 maxOccurs="unbounded" />
1558 </xs:sequence>
1559 </xs:complexType>
1560 \end{lstlisting}
1561
1562 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Content} Metadata Elements}
1563
1564 \begingroup\small\begin{bigdescription}\item[Element \xmlel{subject}]
1565 \begin{description}
1566 \item[Type] string: \xmlel{xs:token}
1567 \item[Meaning]
1568 a topic, object type, or other descriptive keywords
1569 about the resource.
1570
1571 \item[Occurrence] required; multiple occurrences allowed.
1572 \item[Comment]
1573 Terms for Subject should be drawn from the IAU Astronomy
1574 Thesaurus (http://msowww.anu.edu.au/library/thesaurus/).
1575
1576
1577 \end{description}
1578 \item[Element \xmlel{description}]
1579 \begin{description}
1580 \item[Type] string: \xmlel{xs:token}
1581 \item[Meaning]
1582 An account of the nature of the resource
1583
1584 \item[Occurrence] required
1585 \item[Comment]
1586 The description may include but is not limited to an abstract,
1587 table of contents, reference to a graphical representation of
1588 content or a free-text account of the content.
1589
1590
1591 \end{description}
1592 \item[Element \xmlel{source}]
1593 \begin{description}
1594 \item[Type] a string with optional attributes
1595 \item[Meaning]
1596 a bibliographic reference from which the present resource is
1597 derived or extracted.
1598
1599 \item[Occurrence] optional
1600 \item[Comment]
1601 This is intended to point to an article in the published
1602 literature. An ADS Bibcode is recommended as a value when
1603 available.
1604
1605
1606 \end{description}
1607 \item[Element \xmlel{referenceURL}]
1608 \begin{description}
1609 \item[Type] a URI: \xmlel{xs:anyURI}
1610 \item[Meaning]
1611 URL pointing to a human-readable document describing this
1612 resource.
1613
1614 \item[Occurrence] required
1615
1616 \end{description}
1617 \item[Element \xmlel{type}]
1618 \begin{description}
1619 \item[Type] string with controlled vocabulary
1620 \item[Meaning]
1621 Nature or genre of the content of the resource
1622
1623 \item[Occurrence] optional; multiple occurrences allowed.
1624
1625 \item[Allowed Values]\hfil
1626 \begin{longtermsdescription}
1627 \item[Other]
1628 resource that does not fall into any of the category names
1629 currently defined.
1630
1631 \item[Archive]
1632 Collection of pointed observations
1633
1634 \item[Bibliography]
1635 Collection of bibliographic reference, abstracts, and
1636 publications
1637
1638 \item[Catalog]
1639 Collection of derived data, primarily in tabular form
1640
1641 \item[Journal]
1642 Collection of scholarly publications under common editorial
1643 policy
1644
1645 \item[Library]
1646 Collection of published materials (journals, books, etc.)
1647
1648 \item[Simulation]
1649 Theoretical simulation or model
1650
1651 \item[Survey]
1652 Collection of observations covering substantial and
1653 contiguous areas of the sky
1654
1655 \item[Transformation]
1656 A service that transforms data
1657
1658 \item[Education]
1659 Collection of materials appropriate for educational use, such
1660 as teaching resources, curricula, etc.
1661
1662 \item[Outreach]
1663 Collection of materials appropriate for public outreach, such
1664 as press releases and photo galleries
1665
1666 \item[EPOResource]
1667 Collection of materials that may be suitable for EPO
1668 products but which are not in final product form, as in Type
1669 Outreach or Type Education. EPOResource would apply,
1670 e.g., to archives with easily accessed preview images or to
1671 surveys with easy-to-use images.
1672
1673 \item[Animation]
1674 Animation clips of astronomical phenomena
1675
1676 \item[Artwork]
1677 Artists' renderings of astronomical phenomena or objects
1678
1679 \item[Background]
1680 Background information on astronomical phenomena or objects
1681
1682 \item[BasicData]
1683 Compilations of basic astronomical facts about objects,
1684 such as approximate distance or membership in constellation.
1685
1686 \item[Historical]
1687 Historical information about astronomical objects
1688
1689 \item[Photographic]
1690 Publication-quality photographs of astronomical objects
1691
1692 \item[Press]
1693 Press releases about astronomical objects
1694
1695 \item[Organisation]
1696 An organization that is a publisher or curator of other
1697 resources.
1698
1699 \item[Project]
1700 A project that is a publisher or curator of other resources
1701
1702 \item[Registry]
1703 a query service for which response is a structured
1704 description of resources.
1705
1706 \end{longtermsdescription}
1707
1708 \end{description}
1709 \item[Element \xmlel{contentLevel}]
1710 \begin{description}
1711 \item[Type] string with controlled vocabulary
1712 \item[Meaning]
1713 Description of the content level or intended audience
1714
1715 \item[Occurrence] optional; multiple occurrences allowed.
1716
1717 \item[Allowed Values]\hfil
1718 \begin{longtermsdescription}
1719 \item[General]
1720 Resource provides information appropriate for all users
1721
1722 \item[Elementary Education]
1723 Resource provides information appropriate for use in elementary
1724 education (e.g. approximate ages 6-11)
1725
1726 \item[Middle School Education]
1727 Resource provides information appropriate for use in middle
1728 school education (e.g. approximate ages 11-14)
1729
1730 \item[Secondary Education]
1731 Resource provides information appropriate for use in elementary
1732 education (e.g. approximate ages 14-18)
1733
1734 \item[Community College]
1735 Resource provides information appropriate for use in
1736 community/junior college or early university education.
1737
1738 \item[University]
1739 Resource provides information appropriate for use in
1740 university education
1741
1742 \item[Research]
1743 Resource provides information appropriate for
1744 supporting scientific research.
1745
1746 \item[Amateur]
1747 Resource provides information of interest to
1748 amateur astronomers.
1749
1750 \item[Informal Education]
1751 Resource provides information appropriate for education
1752 at museums, planetariums, and other centers of informal learning.
1753
1754 \end{longtermsdescription}
1755
1756 \end{description}
1757 \item[Element \xmlel{relationship}]
1758 \begin{description}
1759 \item[Type] composite: \xmlel{vr:Relationship}
1760 \item[Meaning]
1761 a description of a relationship to another resource.
1762
1763 \item[Occurrence] optional; multiple occurrences allowed.
1764 \item[Comment]
1765 Because this element's type is abstract, an xsi:type must be
1766 to indicate the set of relationship types that are valid.
1767
1768
1769 \end{description}
1770
1771
1772 \end{bigdescription}\endgroup
1773
1774 \endgroup
1775 % /GENERATED
1776
1777
1778
1779 The \xmlel{source} element's type,
1780 \xmlel{vr:Source}, is an extension of the
1781 \xmlel{xs:token} type that adds an optional attribute called
1782 \xmlel{format}.
1783
1784
1785 % GENERATED: !schemadoc VOResource-v1.0.xsd Source
1786 \begingroup
1787 \renewcommand*\descriptionlabel[1]{%
1788 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{1ex}\noindent\textbf{\xmlel{vr:Source} Type Schema Definition}
1789
1790 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1791 <xs:complexType name="Source" >
1792 <xs:simpleContent >
1793 <xs:extension base="xs:token" >
1794 <xs:attribute name="format" type="xs:string" />
1795 </xs:extension>
1796 </xs:simpleContent>
1797 </xs:complexType>
1798 \end{lstlisting}
1799
1800 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Source} Attributes}
1801
1802 \begingroup\small\begin{bigdescription}
1803 \item[format]
1804 \begin{description}
1805 \item[Type] string: \xmlel{xs:string}
1806 \item[Meaning]
1807 The reference format. Recognized values include {"}bibcode{"},
1808 referring to a standard astronomical bibcode
1809 (http://cdsweb.u-strasbg.fr/simbad/refcode.html).
1810
1811 \item[Occurrence] optional
1812 \end{description}
1813
1814
1815 \end{bigdescription}\endgroup
1816
1817 \endgroup
1818 % /GENERATED
1819
1820
1821 The \xmlel{relationship} is defined by the
1822 \xmlel{vr:Relationship} complex type which bundles together the
1823 RM metadata \emph{Relationship} and
1824 \emph{RelationshipID}.
1825
1826
1827 % GENERATED: !schemadoc VOResource-v1.0.xsd Relationship
1828 \begingroup
1829 \renewcommand*\descriptionlabel[1]{%
1830 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Relationship} Type Schema Documentation}
1831
1832 \noindent{\small
1833 A description of the relationship between one resource and one or
1834 more other resources.
1835 \par}
1836
1837 \vspace{1ex}\noindent\textbf{\xmlel{vr:Relationship} Type Schema Definition}
1838
1839 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1840 <xs:complexType name="Relationship" >
1841 <xs:sequence >
1842 <xs:element name="relationshipType" type="xs:token" />
1843 <xs:element name="relatedResource" type="vr:ResourceName" minOccurs="1"
1844 maxOccurs="unbounded" />
1845 </xs:sequence>
1846 </xs:complexType>
1847 \end{lstlisting}
1848
1849 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Relationship} Metadata Elements}
1850
1851 \begingroup\small\begin{bigdescription}\item[Element \xmlel{relationshipType}]
1852 \begin{description}
1853 \item[Type] string: \xmlel{xs:token}
1854 \item[Meaning]
1855 the named type of relationship
1856
1857 \item[Occurrence] required
1858 \item[Comment]
1859 The VOResource Core specification defines a standard
1860 set of names that are not enforced by this schema,
1861 but are otherwise required by the spec.
1862
1863
1864 \end{description}
1865 \item[Element \xmlel{relatedResource}]
1866 \begin{description}
1867 \item[Type] string with ID attribute: vr:ResourceName
1868 \item[Meaning]
1869 the name of resource that this resource is related to.
1870
1871 \item[Occurrence] required; multiple occurrences allowed.
1872
1873 \end{description}
1874
1875
1876 \end{bigdescription}\endgroup
1877
1878 \endgroup
1879 % /GENERATED
1880
1881
1882 It is important to note that the \xmlel{relationshipType}
1883 controlled vocabulary is not enforced by the schema itself. This
1884 allows a future version of this specification to define additional
1885 terms without requiring a change in the XML Schema document.
1886
1887
1888 \subsubsection{Resource Record Quality with validationLevel}
1889
1890
1891
1892 The RM's \emph{ResourceValidationLevel} is encoded in the VOResource
1893 schema with the \xmlel{validationLevel} element, which can appear in
1894 multiple places within a \xmlel{vr:Resource} type or sub-type. It may
1895 appear zero or more times as direct children of a \xmlel{vr:Resource}
1896 type and/or, if the resource is a \xmlel{vr:Service} type or sub-type,
1897 one or more times as the first children of any \xmlel{capability}
1898 element.
1899
1900 The \xmlel{validationLevel} element requires an attribute called
1901 \xmlel{validatedBy} which takes an IVOID as a value. This IVOID
1902 must refer to a registered organisation or registry that assigned the
1903 numerical value. This element can appear multiple times, each with
1904 a different \xmlel{validatedBy} value, to reflect the code
1905 assigned by different organisations.
1906
1907
1908 % GENERATED: !schemadoc VOResource-v1.0.xsd ValidationLevel
1909 \begingroup
1910 \renewcommand*\descriptionlabel[1]{%
1911 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:ValidationLevel} Type Schema Documentation}
1912
1913 \noindent{\small
1914 the allowed values for describing the resource descriptions
1915 and interfaces.
1916 \par}
1917
1918 \noindent{\small
1919 See the RM (v1.1, section 4) for more guidance on the use of
1920 these values.
1921 \par}
1922
1923 \vspace{2ex}\noindent\textbf{\xmlel{vr:ValidationLevel} Type Allowed Values}
1924
1925 \begin{longtermsdescription}\item[0]
1926 The resource has a description that is stored in a
1927 registry. This level does not imply a compliant
1928 description.
1929
1930 \item[1]
1931 In addition to meeting the level 0 definition, the
1932 resource description conforms syntactically to this
1933 standard and to the encoding scheme used.
1934
1935 \item[2]
1936 In addition to meeting the level 1 definition, the
1937 resource description refers to an existing resource that
1938 has demonstrated to be functionally compliant.
1939
1940 \item[3]
1941 In addition to meeting the level 2 definition, the
1942 resource description has been inspected by a human and
1943 judged to comply semantically to this standard as well
1944 as meeting any additional minimum quality criteria (e.g.,
1945 providing values for important but non-required
1946 metadata) set by the human inspector.
1947
1948 \item[4]
1949 In addition to meeting the level 3 definition, the
1950 resource description meets additional quality criteria
1951 set by the human inspector and is therefore considered
1952 an excellent description of the resource. Consequently,
1953 the resource is expected to be operate well as part of a
1954 VO application or research study.
1955
1956 \end{longtermsdescription}
1957 \vspace{1ex}\noindent\textbf{\xmlel{vr:ValidationLevel} Type Schema Definition}
1958
1959 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1960 <xs:simpleType name="ValidationLevel" >
1961 <xs:restriction base="xs:integer" >
1962 <xs:whiteSpace value="collapse" />
1963 <xs:enumeration value="0" />
1964 <xs:enumeration value="1" />
1965 <xs:enumeration value="2" />
1966 <xs:enumeration value="3" />
1967 <xs:enumeration value="4" />
1968 </xs:restriction>
1969 </xs:simpleType>
1970 \end{lstlisting}\endgroup
1971 % /GENERATED
1972
1973 % GENERATED: !schemadoc VOResource-v1.0.xsd Validation
1974 \begingroup
1975 \renewcommand*\descriptionlabel[1]{%
1976 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Validation} Type Schema Documentation}
1977
1978 \noindent{\small
1979 a validation stamp combining a validation level and the ID of
1980 the validator.
1981 \par}
1982
1983 \vspace{1ex}\noindent\textbf{\xmlel{vr:Validation} Type Schema Definition}
1984
1985 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
1986 <xs:complexType name="Validation" >
1987 <xs:simpleContent >
1988 <xs:extension base="vr:ValidationLevel" >
1989 <xs:attribute name="validatedBy" type="vr:IdentifierURI" use="required" />
1990 </xs:extension>
1991 </xs:simpleContent>
1992 </xs:complexType>
1993 \end{lstlisting}
1994
1995 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Validation} Attributes}
1996
1997 \begingroup\small\begin{bigdescription}
1998 \item[validatedBy]
1999 \begin{description}
2000 \item[Type] an IVOA Identifier URI: vr:IdentifierURI
2001 \item[Meaning]
2002 The IVOA ID of the registry or organisation that
2003 assigned the validation level.
2004
2005 \item[Occurrence] required
2006
2007 \end{description}
2008
2009
2010 \end{bigdescription}\endgroup
2011
2012 \endgroup
2013 % /GENERATED
2014
2015 \subsection{Resource Type Extensions: Organisation and Service}
2016
2017 The VOResource schema defines two extensions of the base
2018 \xmlel{vr:Resource} type for describing two specific types of
2019 resources: \xmlel{vr:Organisation} and \xmlel{vr:Service}. In
2020 addition to providing more refined semantic meaning over
2021 \xmlel{vr:Resource}, they add additional metadata for the
2022 describing the resource which don't necessarily apply in the generic
2023 case.
2024
2025
2026
2027 \subsubsection{The Organisation Resource Type}
2028
2029
2030 The Organisation resource type is used to describe an organisation in
2031 the sense defined by the RM:
2032
2033
2034 \begin{quotation}
2035 An organisation is a specific type of resource that brings people
2036 together to pursue participation in VO applications. Organisations
2037 can be hierarchical and range greatly in size and scope. At a high
2038 level, an organisation could be a university, observatory, or
2039 government agency. At a finer level, it could be a specific
2040 scientific project space mission, or individual researcher.
2041 \end{quotation}
2042
2043
2044 The Organisation type extends the Resource type by adding two additional
2045 elements to the core set of metadata, \xmlel{facility} and
2046 \xmlel{instrument}:
2047
2048
2049 % GENERATED: !schemadoc VOResource-v1.0.xsd Organisation
2050 \begingroup
2051 \renewcommand*\descriptionlabel[1]{%
2052 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Organisation} Type Schema Documentation}
2053
2054 \noindent{\small
2055 A named group of one or more persons brought together to pursue
2056 participation in VO applications.
2057 \par}
2058
2059 \noindent{\small
2060 According to the Resource Metadata Recommendation, organisations
2061 "can be hierarchical and range in size and scope. At a high level,
2062 an organisation could be a university, observatory, or government
2063 agency. At a finer level, it could be a specific scientific
2064 project, mission, or individual researcher."
2065 \par}
2066
2067 \noindent{\small
2068 The main purpose of an organisation as a registered resource is
2069 to serve as a publisher of other resources.
2070 \par}
2071
2072 \vspace{1ex}\noindent\textbf{\xmlel{vr:Organisation} Type Schema Definition}
2073
2074 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2075 <xs:complexType name="Organisation" >
2076 <xs:complexContent >
2077 <xs:extension base="vr:Resource" >
2078 <xs:sequence >
2079 <xs:element name="facility" type="vr:ResourceName" minOccurs="0"
2080 maxOccurs="unbounded" />
2081 <xs:element name="instrument" type="vr:ResourceName" minOccurs="0"
2082 maxOccurs="unbounded" />
2083 </xs:sequence>
2084 </xs:extension>
2085 </xs:complexContent>
2086 </xs:complexType>
2087 \end{lstlisting}
2088
2089 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Organisation} Extension Metadata Elements}
2090
2091 \begingroup\small\begin{bigdescription}\item[Element \xmlel{facility}]
2092 \begin{description}
2093 \item[Type] string with ID attribute: vr:ResourceName
2094 \item[Meaning]
2095 the observatory or facility used to collect the data
2096 contained or managed by this resource.
2097
2098 \item[Occurrence] optional; multiple occurrences allowed.
2099
2100 \end{description}
2101 \item[Element \xmlel{instrument}]
2102 \begin{description}
2103 \item[Type] string with ID attribute: vr:ResourceName
2104 \item[Meaning]
2105 the Instrument used to collect the data contain or
2106 managed by a resource.
2107
2108 \item[Occurrence] optional; multiple occurrences allowed.
2109
2110 \end{description}
2111
2112
2113 \end{bigdescription}\endgroup
2114
2115 \endgroup
2116 % /GENERATED
2117
2118 The main role of an organisation in the VO (that is, the main reason
2119 for describing organisations in a registry) is as a provider or
2120 publishier of other resources. In particular, an organisation
2121 description in a registry declares the association of an IVOA
2122 identifier with the organisation. The
2123 organisation can then be referred to in other resource descriptions.
2124 For example, an organisation identifier will appear as the publisher
2125 identifier of service resource (as illustrated in the opening
2126 example in sect.~\ref{sect:model}.
2127
2128
2129 \subsubsection{The Service Resource Type}
2130
2131
2132 The Service resource type is used to describe a service--a resource
2133 that actually does something--in the sense defined by the
2134 RM:
2135
2136 \begin{quotation}
2137 A service is any VO resource that can be invoked by the user to
2138 perform some action on their behalf.
2139 \end{quotation}
2140
2141
2142 The general data model is described in sect.~\ref{sect:servicemodel}.
2143 The Service type extends the Resource type by adding two elements:
2144 \xmlel{rights} which indicates who may access it, and
2145 \xmlel{capability} which describes how the service behaves and how it is
2146 invoked.
2147
2148
2149 % GENERATED: !schemadoc VOResource-v1.0.xsd Service
2150 \begingroup
2151 \renewcommand*\descriptionlabel[1]{%
2152 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Service} Type Schema Documentation}
2153
2154 \noindent{\small
2155 a resource that can be invoked by a client to perform some action
2156 on its behalf.
2157 \par}
2158
2159 \vspace{1ex}\noindent\textbf{\xmlel{vr:Service} Type Schema Definition}
2160
2161 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2162 <xs:complexType name="Service" >
2163 <xs:complexContent >
2164 <xs:extension base="vr:Resource" >
2165 <xs:sequence >
2166 <xs:element name="rights" type="vr:Rights" minOccurs="0"
2167 maxOccurs="unbounded" />
2168 <xs:element name="capability" type="vr:Capability" minOccurs="0"
2169 maxOccurs="unbounded" />
2170 </xs:sequence>
2171 </xs:extension>
2172 </xs:complexContent>
2173 </xs:complexType>
2174 \end{lstlisting}
2175
2176 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Service} Extension Metadata Elements}
2177
2178 \begingroup\small\begin{bigdescription}\item[Element \xmlel{rights}]
2179 \begin{description}
2180 \item[Type] string with controlled vocabulary
2181 \item[Meaning]
2182 Information about rights held in and over the resource.
2183
2184 \item[Occurrence] optional; multiple occurrences allowed.
2185
2186 \item[Allowed Values]\hfil
2187 \begin{longtermsdescription}
2188 \item[public]
2189 unrestricted, public access is allowed without
2190 authentication.
2191
2192 \item[secure]
2193 authenticated, public access is allowed.
2194
2195 \item[proprietary]
2196 only proprietary access is allowed with authentication.
2197
2198 \end{longtermsdescription}
2199 \item[Comment]
2200 This should be repeated for all Rights values that apply.
2201
2202
2203 \end{description}
2204 \item[Element \xmlel{capability}]
2205 \begin{description}
2206 \item[Type] composite: \xmlel{vr:Capability}
2207 \item[Meaning]
2208 a description of a general capability of the
2209 service and how to use it.
2210
2211 \item[Occurrence] optional; multiple occurrences allowed.
2212 \item[Comment]
2213 This describes a general function of the
2214 service, usually in terms of a standard
2215 service protocol (e.g. SIA), but not
2216 necessarily.
2217
2218 \item[Comment]
2219 A service can have many capabilities
2220 associated with it, each reflecting different
2221 aspects of the functionality it provides.
2222
2223
2224 \end{description}
2225
2226
2227 \end{bigdescription}\endgroup
2228
2229 \endgroup
2230 % /GENERATED
2231
2232 As described in sect.~\ref{sect:servicemodel}, multiple
2233 \xmlel{capability} elements may appear, each describing a
2234 different capability of the service.
2235
2236
2237 % GENERATED: !schemadoc VOResource-v1.0.xsd Capability
2238 \begingroup
2239 \renewcommand*\descriptionlabel[1]{%
2240 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Capability} Type Schema Documentation}
2241
2242 \noindent{\small
2243 a description of what the service does (in terms of
2244 context-specific behavior), and how to use it (in terms of
2245 an interface)
2246 \par}
2247
2248 \vspace{1ex}\noindent\textbf{\xmlel{vr:Capability} Type Schema Definition}
2249
2250 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2251 <xs:complexType name="Capability" >
2252 <xs:sequence >
2253 <xs:element name="validationLevel" type="vr:Validation" minOccurs="0"
2254 maxOccurs="unbounded" />
2255 <xs:element name="description" type="xs:token" minOccurs="0" />
2256 <xs:element name="interface" type="vr:Interface" minOccurs="0"
2257 maxOccurs="unbounded" />
2258 </xs:sequence>
2259 <xs:attribute name="standardID" type="xs:anyURI" />
2260 </xs:complexType>
2261 \end{lstlisting}
2262
2263 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Capability} Attributes}
2264
2265 \begingroup\small\begin{bigdescription}
2266 \item[standardID]
2267 \begin{description}
2268 \item[Type] a URI: \xmlel{xs:anyURI}
2269 \item[Meaning]
2270 A URI identifier for a standard service.
2271
2272 \item[Occurrence] optional
2273 \item[Comment]
2274 This provides a unique way to refer to a service
2275 specification standard, such as a Simple Image Access service.
2276 The use of an IVOA identifier here implies that a
2277 VOResource description of the standard is registered and
2278 accessible.
2279
2280 \end{description}
2281
2282
2283 \end{bigdescription}\endgroup
2284
2285
2286
2287 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Capability} Metadata Elements}
2288
2289 \begingroup\small\begin{bigdescription}\item[Element \xmlel{validationLevel}]
2290 \begin{description}
2291 \item[Type] \xmlel{vr:ValidationLevel} with optional attributes
2292 \item[Meaning]
2293 A numeric grade describing the quality of the
2294 capability description and interface, when applicable,
2295 to be used to indicate the confidence an end-user
2296 can put in the resource as part of a VO application
2297 or research study.
2298
2299 \item[Occurrence] optional; multiple occurrences allowed.
2300 \item[Comment]
2301 See vr:ValidationLevel for an explanation of the
2302 allowed levels.
2303
2304
2305 \end{description}
2306 \item[Element \xmlel{description}]
2307 \begin{description}
2308 \item[Type] string: \xmlel{xs:token}
2309 \item[Meaning]
2310 A human-readable description of what this capability
2311 provides as part of the over-all service
2312
2313 \item[Occurrence] optional
2314 \item[Comment]
2315 Use of this optional element is especially encouraged when
2316 this capability is non-standard and is one of several
2317 capabilities listed.
2318
2319
2320 \end{description}
2321 \item[Element \xmlel{interface}]
2322 \begin{description}
2323 \item[Type] composite: \xmlel{vr:Interface}
2324 \item[Meaning]
2325 a description of how to call the service to access
2326 this capability
2327
2328 \item[Occurrence] optional; multiple occurrences allowed.
2329 \item[Comment]
2330 Since the Interface type is abstract, one must describe
2331 the interface using a subclass of Interface, denoting
2332 it via xsi:type.
2333
2334 \item[Comment]
2335 Multiple occurances can describe different interfaces to
2336 the logically same capability--i.e. data or functionality.
2337 That is, the inputs accepted and the output provides should
2338 be logically the same. For example, a WebBrowser interface
2339 given in addition to a WebService interface would simply
2340 provide an interactive, human-targeted interface to the
2341 underlying WebService interface.
2342
2343
2344 \end{description}
2345
2346
2347 \end{bigdescription}\endgroup
2348
2349 \endgroup
2350 % /GENERATED
2351
2352
2353 The \xmlel{capability} element is sufficient for describing a
2354 \emph{custom service capability}--i.e., a service that is
2355 particular to one provider and does not conform to a specific standard
2356 (be it recognized by the IVOA or some other sub-community). However,
2357 service standards will often create a \xmlel{vr:Capability}
2358 extension that adds additional metadata that are specific that that
2359 are specific to the behavior of that particular type of service.
2360
2361
2362
2363 \begin{admonition}{Note}
2364 The RM defines three metadata that may be
2365 important for several standard query services:
2366 \emph{Service.MaxSearchRadius},
2367 \emph{Service.MaxReturnRecords}, and
2368 \emph{Service.MaxReturnSize}. These are examples of
2369 service-specific metadata that should be encoded as child
2370 elements in a type derived from \xmlel{vr:Capability}.
2371 \end{admonition}
2372
2373
2374 The \xmlel{interface} element is of the complex type
2375 \xmlel{vr:Interface}.
2376
2377 The \xmlel{vr:Interface} type is defined as abstract, so as described in
2378 sect.~\ref{sect:servicemodel}, the \xmlel{interface} element must not be
2379 used as part of a \xmlel{vr:Service} description unless it includes an
2380 \xmlel{xsi:type} attribute that refers to a type derived from
2381 \xmlel{vr:Interface}. The VOResource schema defines two derived
2382 \xmlel{vr:Interface} types: \xmlel{vr:WebBrowser} and
2383 \xmlel{vr:WebService}.
2384
2385 As described in sect.~\ref{sect:servicemodel}, the \xmlel{vr:Interface}
2386 attributes help distinguish between multiple interfaces within the same
2387 \xmlel{capability} element:
2388
2389
2390 % GENERATED: !schemadoc VOResource-v1.0.xsd Interface
2391 \begingroup
2392 \renewcommand*\descriptionlabel[1]{%
2393 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:Interface} Type Schema Documentation}
2394
2395 \noindent{\small
2396 A description of a service interface.
2397 \par}
2398
2399 \noindent{\small
2400 Since this type is abstract, one must use an Interface subclass
2401 to describe an actual interface.
2402 \par}
2403
2404 \noindent{\small
2405 Additional interface subtypes (beyond WebService and WebBrowser) are
2406 defined in the VODataService schema.
2407 \par}
2408
2409 \vspace{1ex}\noindent\textbf{\xmlel{vr:Interface} Type Schema Definition}
2410
2411 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2412 <xs:complexType name="Interface" abstract="true" >
2413 <xs:sequence >
2414 <xs:element name="accessURL" type="vr:AccessURL" minOccurs="1"
2415 maxOccurs="unbounded" />
2416 <xs:element name="securityMethod" type="vr:SecurityMethod" minOccurs="0"
2417 maxOccurs="unbounded" />
2418 </xs:sequence>
2419 <xs:attribute name="version" type="xs:string" default="1.0" />
2420 <xs:attribute name="role" type="xs:NMTOKEN" />
2421 </xs:complexType>
2422 \end{lstlisting}
2423
2424 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Interface} Attributes}
2425
2426 \begingroup\small\begin{bigdescription}
2427 \item[version]
2428 \begin{description}
2429 \item[Type] string: \xmlel{xs:string}
2430 \item[Meaning]
2431 The version of a standard interface specification that this
2432 interface complies with. When the interface is
2433 provided in the context of a Capability element, then
2434 the standard being referred to is the one identified by
2435 the Capability's standardID element. If the standardID
2436 is not provided, the meaning of this attribute is
2437 undefined.
2438
2439 \item[Occurrence] optional
2440 1.0
2441 \end{description}
2442 \item[role]
2443 \begin{description}
2444 \item[Type] \xmlel{xs:NMTOKEN}
2445 \item[Meaning]
2446 A tag name the identifies the role the interface plays
2447 in the particular capability. If the value is equal to
2448 {"}std{"} or begins with {"}std:{"}, then the interface refers
2449 to a standard interface defined by the standard
2450 referred to by the capability's standardID attribute.
2451
2452 \item[Occurrence] optional
2453 \item[Comment]
2454 For an interface complying with some registered
2455 standard (i.e. has a legal standardID), the role can be
2456 match against interface roles enumerated in standard
2457 resource record. The interface descriptions in
2458 the standard record can provide default descriptions
2459 so that such details need not be repeated here.
2460
2461 \end{description}
2462
2463
2464 \end{bigdescription}\endgroup
2465
2466
2467
2468 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:Interface} Metadata Elements}
2469
2470 \begingroup\small\begin{bigdescription}\item[Element \xmlel{accessURL}]
2471 \begin{description}
2472 \item[Type] a URI with optional attributes
2473 \item[Meaning]
2474 The URL (or base URL) that a client uses to access the
2475 service. How this URL is to be interpreted and used
2476 depends on the specific Interface subclass
2477
2478 \item[Occurrence] required; multiple occurrences allowed.
2479 \item[Comment]
2480 When more than one URL is given, each represents an
2481 alternative (i.e. mirror) endpoint whose behavior is
2482 identical to all the other accessURLs listed.
2483
2484 \item[Comment]
2485 Editor's note: this element assumes that
2486 all registered services are inherently web based.
2487
2488
2489 \end{description}
2490 \item[Element \xmlel{securityMethod}]
2491 \begin{description}
2492 \item[Type] composite: \xmlel{vr:SecurityMethod}
2493 \item[Meaning]
2494 the mechanism the client must employ to gain secure
2495 access to the service.
2496
2497 \item[Occurrence] optional; multiple occurrences allowed.
2498 \item[Comment]
2499 when more than one method is listed, each one must
2500 be employed to gain access.
2501
2502
2503 \end{description}
2504
2505
2506 \end{bigdescription}\endgroup
2507
2508 \endgroup
2509 % /GENERATED
2510
2511
2512 As mentioned in the table above, exactly how a client uses the value
2513 of the \xmlel{accessURL} element depends on the specific
2514 type derived from \xmlel{vr:Interface}. Extension schemas that
2515 define non-abstract types derived from \xmlel{vr:Interface } MUST
2516 provide documentation that explains the exact use of the
2517 \xmlel{accessURL}; this documentation should follow the
2518 documention conventions described in sect.~\ref{sect:core}. If multiple
2519 \xmlel{accessURL} may be provide; however, each URL should
2520 point to a functionally identical or ``mirror'' installation of the same
2521 service and administered by the same publisher listed above. An
2522 \xmlel{accessURL} must not point to an installation
2523 that is outside the administrative control of the service's listed
2524 publisher; such a mirror should be describe in a separate resource
2525 record.
2526
2527
2528
2529 As an additional aid to software agents that will attempt to interpret
2530 its URL, the \xmlel{vr:AccessURL} includes an optional element,
2531 \xmlel{use} (pronounced and interpreted as in the noun form of
2532 the word use) which takes a controlled vocabulary:
2533
2534
2535 % GENERATED: !schemadoc VOResource-v1.0.xsd AccessURL
2536 \begingroup
2537 \renewcommand*\descriptionlabel[1]{%
2538 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{1ex}\noindent\textbf{\xmlel{vr:AccessURL} Type Schema Definition}
2539
2540 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2541 <xs:complexType name="AccessURL" >
2542 <xs:simpleContent >
2543 <xs:extension base="xs:anyURI" >
2544 <xs:attribute name="use" >
2545 <xs:simpleType >
2546 <xs:restriction base="xs:NMTOKEN" >
2547 <xs:enumeration value="full" />
2548 <xs:enumeration value="base" />
2549 <xs:enumeration value="dir" />
2550 </xs:restriction>
2551 </xs:simpleType>
2552 </xs:attribute>
2553 </xs:extension>
2554 </xs:simpleContent>
2555 </xs:complexType>
2556 \end{lstlisting}
2557
2558 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:AccessURL} Attributes}
2559
2560 \begingroup\small\begin{bigdescription}
2561 \item[use]
2562 \begin{description}
2563 \item[Type] string
2564 \item[Meaning]
2565 A flag indicating whether this should be interpreted as a base
2566 URL, a full URL, or a URL to a directory that will produce a
2567 listing of files.
2568
2569 \item[Occurrence] optional
2570
2571 \item[Allowed Values]\hfil
2572 \begin{longtermsdescription}\item[full]
2573 Assume a full URL--that is, one that can be invoked
2574 directly without alteration. This usually returns a
2575 single document or file.
2576
2577 \item[base]
2578 Assume a base URL--that is, one requiring an extra portion
2579 to be appended before being invoked.
2580
2581 \item[dir]
2582 Assume URL points to a directory that will return a listing
2583 of files.
2584
2585 \end{longtermsdescription}
2586 \item[Comment]
2587 The default value assumed when one is not given depends on the
2588 context.
2589
2590 \end{description}
2591
2592
2593 \end{bigdescription}\endgroup
2594
2595 \endgroup
2596 % /GENERATED
2597
2598
2599 The \xmlel{vr:SecurityMethod} type is
2600 defined as a complex type but with empty content:
2601
2602
2603 % GENERATED: !schemadoc VOResource-v1.0.xsd SecurityMethod
2604 \begingroup
2605 \renewcommand*\descriptionlabel[1]{%
2606 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:SecurityMethod} Type Schema Documentation}
2607
2608 \noindent{\small
2609 a description of a security mechanism.
2610 \par}
2611
2612 \noindent{\small
2613 this type only allows one to refer to the mechanism via a
2614 URI. Derived types would allow for more metadata.
2615 \par}
2616
2617 \vspace{1ex}\noindent\textbf{\xmlel{vr:SecurityMethod} Type Schema Definition}
2618
2619 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2620 <xs:complexType name="SecurityMethod" >
2621 <xs:sequence />
2622 <xs:attribute name="standardID" type="xs:anyURI" />
2623 </xs:complexType>
2624 \end{lstlisting}
2625
2626 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:SecurityMethod} Attributes}
2627
2628 \begingroup\small\begin{bigdescription}
2629 \item[standardID]
2630 \begin{description}
2631 \item[Type] a URI: \xmlel{xs:anyURI}
2632 \item[Meaning]
2633 A URI identifier for a standard security mechanism.
2634
2635 \item[Occurrence] optional
2636 \item[Comment]
2637 This provides a unique way to refer to a security
2638 specification standard. The use of an IVOA identifier here
2639 implies that a VOResource description of the standard is
2640 registered and accessible.
2641
2642 \end{description}
2643
2644
2645 \end{bigdescription}\endgroup
2646
2647 \endgroup
2648 % /GENERATED
2649
2650 While this simple element (when the \xmlel{standardID} attribute
2651 is provided) may on its own be sufficient to describe the security
2652 mechanism used, it is expected that some future
2653 VOResource extension schema will define
2654 additional types derived from \xmlel{vr:SecurityMethod}. If such
2655 a sub-type is available, it may be employed at
2656 \xmlel{securityMethod} location within a
2657 \xmlel{vr:Interface}-typed element, in which case, it should be
2658 invoked via a \xmlel{xsi:type} attribute to the
2659 \xmlel{securityMethod} element.
2660
2661
2662 \xmlel{vr:WebBrowser} is one of the two \xmlel{vr:Interface}
2663 sub-types defined by the VOResource schema. This type indicates that
2664 the service is intended to be accessed interactively by a user through
2665 a web browser. The \xmlel{accessURL}, then, represents
2666 the URL of a web page containing one or more forms used to invoke the
2667 service.
2668
2669
2670 % GENERATED: !schemadoc VOResource-v1.0.xsd WebBrowser
2671 \begingroup
2672 \renewcommand*\descriptionlabel[1]{%
2673 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:WebBrowser} Type Schema Documentation}
2674
2675 \noindent{\small
2676 A (form-based) interface intended to be accesed interactively
2677 by a user via a web browser.
2678 \par}
2679
2680 \noindent{\small
2681 The accessURL represents the URL of the web form itself.
2682 \par}
2683
2684 \vspace{1ex}\noindent\textbf{\xmlel{vr:WebBrowser} Type Schema Definition}
2685
2686 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2687 <xs:complexType name="WebBrowser" >
2688 <xs:complexContent >
2689 <xs:extension base="vr:Interface" >
2690 <xs:sequence />
2691 </xs:extension>
2692 </xs:complexContent>
2693 </xs:complexType>
2694 \end{lstlisting}\endgroup
2695 % /GENERATED
2696
2697
2698 As can be seen in the schema definition above, the
2699 \xmlel{vr:WebBrowser} type does not define any additional
2700 interface metadata (though other \xmlel{vr:Interface} derivations
2701 may). Thus, this type is provide purely for its semantic meaning.
2702
2703
2704
2705 \xmlel{vr:WebService} is the second \xmlel{vr:Interface}
2706 sub-type available from the VOResource schema:
2707
2708 % GENERATED: !schemadoc VOResource-v1.0.xsd WebService
2709 \begingroup
2710 \renewcommand*\descriptionlabel[1]{%
2711 \hbox to 5.5em{\emph{#1}\hfil}}\vspace{2ex}\noindent\textbf{\xmlel{vr:WebService} Type Schema Documentation}
2712
2713 \noindent{\small
2714 A Web Service that is describable by a WSDL document.
2715 \par}
2716
2717 \noindent{\small
2718 The accessURL element gives the Web Service's endpoint URL.
2719 \par}
2720
2721 \vspace{1ex}\noindent\textbf{\xmlel{vr:WebService} Type Schema Definition}
2722
2723 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
2724 <xs:complexType name="WebService" >
2725 <xs:complexContent >
2726 <xs:extension base="vr:Interface" >
2727 <xs:sequence >
2728 <xs:element name="wsdlURL" type="xs:anyURI" minOccurs="0"
2729 maxOccurs="unbounded" />
2730 </xs:sequence>
2731 </xs:extension>
2732 </xs:complexContent>
2733 </xs:complexType>
2734 \end{lstlisting}
2735
2736 \vspace{0.5ex}\noindent\textbf{\xmlel{vr:WebService} Extension Metadata Elements}
2737
2738 \begingroup\small\begin{bigdescription}\item[Element \xmlel{wsdlURL}]
2739 \begin{description}
2740 \item[Type] a URI: \xmlel{xs:anyURI}
2741 \item[Meaning]
2742 The location of the WSDL that describes this
2743 Web Service. If not provided, the location is
2744 assumed to be the accessURL with {"}?wsdl{"} appended.
2745
2746 \item[Occurrence] optional; multiple occurrences allowed.
2747 \item[Comment]
2748 Multiple occurances should represent mirror copies of
2749 the same WSDL file.
2750
2751
2752 \end{description}
2753
2754
2755 \end{bigdescription}\endgroup
2756
2757 \endgroup
2758 % /GENERATED
2759
2760 The \xmlel{vr:WebService} interface is one that is described by a Web
2761 Service Description Language \citep{booth07} document. This is typically
2762 realized as one that employs the Simple Object Access Protocol
2763 \citep{std:SOAP}; however, like WSDL, this interface type is not
2764 restricted to it. With this interface, the \xmlel{vr:accessURL} must
2765 refer to the service endpoint URL.
2766
2767 \appendix
2768
2769 \section{Change History}
2770
2771 \subsection{Changes from REC-1.03}
2772
2773 \begin{itemize}
2774 \item Removed SOAP/WSDL example and a bit of the accompanying language.
2775 \item Section 3 needed some refactoring since the schema documentation
2776 is now generated from the schema document. To accomodate this, some
2777 text manually embedded within the schema documentation had to be moved
2778 out of the generated material or removed.
2779 \item While we still reference RM, it is now no longer informally
2780 authoritative for VOResource (we'd have to change RM before we change
2781 VOResource otherwise)
2782 \item References to the RM terms in the metadata definition dropped
2783 (could add support in ivoates/schemadoc if we want them back).
2784 \item Strongly advising the use of the vr: prefix, removing some
2785 duplicated advice regarding prefixes
2786 \item Removed example for deriving a SIA capability (this is now
2787 in the document repository)
2788 \item Ported document source to \ivoatex.
2789 \end{itemize}
2790
2791 \subsection{Changes from v1.02}
2792 \begin{itemize}
2793 \item converted to Recommendation
2794 \end{itemize}
2795
2796 \subsection{Changes from v1.01:}
2797 \begin{itemize}
2798 \item \xmlel{status} attribute is now required.
2799 \item added this Change History appendix.
2800 \end{itemize}
2801
2802 \subsection{Changes from v1.0}
2803 \begin{itemize}
2804 \item dropped \xmlel{PaddedString}, \xmlel{PaddedURI} and replaced
2805 with \xmlel{xs:token}.
2806 \item made \xmlel{Validation}'s \xmlel{validatedBy} attribute
2807 required.
2808 \item reference citation correction for SOAP, WSDL
2809 \end{itemize}
2810
2811
2812
2813 \bibliography{ivoatex/ivoabib,ivoatex/docrepo}
2814
2815
2816 \end{document}

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26