Overview of available schema documentation

TDWG working group: Structure of Descriptive Data (SDD)

Note: this document has been superseded by a newer version, see Overview of SDD 1.0 beta 2 schema and documentation! (GH, 12. Sept. 2004)

Introduction

As decided at the Lisbon meeting, we have published a stable and documented version 0.9 of the SDD schema1 on 1. Dec. 2003. The purpose of this phase is to invite fresh criticism and focus on remaining problems in the schema.

To facilitate the discussion we have broken two reduced schemata out of the complex complete SDD schema to that the following issues may be studied without distractions: a) core issues of descriptive data (described objects, terminology used for description, descriptions, and keys) and b) generic infrastructure (things that describe a document itself, including the way it was generated, project definition and copyright, links to external data services, etc.).

How you can help depends on your past experience and technical expertise:

If you are new to SDD or did not follow the developments during recent meetings, please first read the "SDD primer draft" by Kevin Thiele, which uses XML examples rather than schema diagrams.
The next recommended step is to browse through the "SDD schema documentation" by Gregor Hagedorn. This is a set of documents describing the root element and each of the sections of SDD documents. Each part contains a short introductory text plus selected schema diagrams. These diagrams are usually several levels deep expanded, but at the end some detail is left hidden to help focusing on relevant issues. The more technical aspects of the XML schema remain hidden. We hope that people who have past experience with descriptive data (DELTA and other standards) or project management in general are able to review and discuss these documents on the email list or the SDD Wiki.
Many details of the SDD schema are not yet included in the "SDD schema documentation" and can only be seen if you look at the schema itself. The most convenient way to study it is to use a schema editor that provides interactive schema diagrams like XML Spy. However, we also provide static views for standard web browsers (generated by XML Spy and Titanium xs3p, see links in the table below). These static documents are not ideal. The display is highly fragmented into small pieces of information and some information presented is of little relevance (e. g. all elements are individually documented). It never makes sense to read such a schema documentations in a sequential fashion, like a book. Instead, either start at the root element ("Document") or directly jump to the type you are interested in. If you have some experience information models (database development, programming, UML, etc.) please do not be scared away from looking directly at the schema. Going to this level of detail and discussing it with use will help the progress in SDD most!

Material available for SDD 0.9:

Format	Descriptive core2	Generic infrastructure3	Complete version4
w3c XML schema	SDD_09_Core.xsd	SDD_09_Infrastructure.xsd	SDD_09.xsd
Example instance documents	technical example	technical example	a) minimalistic example and b) comprehensive technical example
XML Spy documentation (elements and annotations displayed as diagrams)	550 kB html + 205 images = 1.2 MB total	277 kB html + 109 images = 0.7 MB total	1.2 MB html + 430 images = 3.2 MB total
(as above, but including schema source code)			2.3 MB html + 430 images = 4.3 MB total)
Titanium xs3p documentation (no diagrams, but better documentation of type inheritance; provides links present in the schema annotation source attributes which unfortunately are ignored by XML Spy)	430 kB html.	240 kB html	1.1 MB html
Other material (useful for people acquainted with the w3c XML Schema who want to revise or implement the SDD schema)			Tabular view of certain aspects of the schema (100 kB html)

General hints

For local browsing you can download a zip file (4 MB) that contains all documentation mentioned above, including the schema and example instance files. External hyperlinks will not work, however, since all links are relative. You may want to place the "Workbench02.CSS" file into your root directory (e. g. "C:\") for optimal display.

If you use a static html documentation, start browsing at the root element "Document". In the documentation generated by XML Spy you can click on the elements and types both in the text and in the diagrams to jump to the next level of detail.

Some type or element names start with a double underscore, e. g. "__OptionalCreatorsType". These are not considered functional and are present only for the purpose of reminding us that we need further discussion. They may be ignored, unless you want to raise a discussion of the issue, which will be most welcome.

Please also note that the '@'-character has been used in annotations to mark problematic points that need further discussion. For the complete schema a list of annotations marked with '@' character is available to search for such annotations. The list has been automatically generated using xslt, so it may not be as nice as you wish.

How to contribute

Please send your criticism or suggestions to the SDD mailing list or start a topic on the SDD Wiki.

Gregor Hagedorn; Vers. 1.1; 21. Dec. 2003

Footnotes

1 What is a schema? Although it is also written in XML, the SDD Schema is not about the things that SDD describes, but about grammatical constraints on how those descriptions must appear. In general, an XML schema describes how an XML document containing data must be structured. A document conforming to a schema is said to be "valid" under the schema. Opening schema files as plain text makes no more sense than to master Latin grammar before reading any Latin texts. However, if the schema is opened in a schema modeling tool like XML Spy (or viewed in a report formatted for web browsers generated by such a tool), it can be viewed as an information model (similar to ER diagram in database modeling). We have tried to find intuitive names for the various data elements we want to include in the descriptive data and we use annotations to clarify the meaning. Occasionally the annotations even include examples. Therefore, browsing through the schema can provide you with insight how we propose to structure descriptive data in biology.

2 Descriptive Core version: The following features have been removed: All infrastructure data like GenerationMetadata, the ProjectDefinition, definitions of audiences, and the Resource interface; these can be studied in a separate reduced schema (see below). Further, the following descriptive data features present in the full schema have been removed: Recording data from original, repeated observations/raw data, markup of existing natural language descriptions (NaturalLanguageDescriptions), creation of natural language descriptions (Wordings), designer annotations and application-specific extensions, features supporting revision data and documentation of contributions, copyright, etc., dependency rules, class hierarchies, geographical scope, plus various minor simplifications. This version should not be considered a functional alternative, but I hope that it will be helpful to re-focus the discussion on the core features.

3 Infrastructure version: Only the GenerationMetadata, the ProjectDefinition, and the Resource interface remains. For the most part, these are very general definitions that may be useful to all kind of projects. If you are experienced in data exchange management, the federation or modularization of data sources, etc. and are willing to help us, please take a look at these issues!

4 Complete version: The complete version includes all features proposed or under discussion. Note that the union of the two reduced schemata is not identical with the complete version of the SDD schema, since some advanced concepts have been removed from both versions.

Return to the SDD starting page.

First published 2003-12-01, last updated: 2003-12-21.