TDWG Standards Documentation Specification

Table of contents

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1 Motivation

Historically TDWG Standards have taken diverse forms. They have included controlled vocabularies (such as lists of approved abbreviations), transfer formats specified as XML Schemas and geographic regions specified in hard copy. TDWG Standards can therefore be made up of multiple documents in many files of different formats. This standard specifies how these documents should be presented.

2 Rationale

Users see a standard as a single 'product'. It is therefore important that, although TDWG standards may contain multiple files, they are presented to the user as a single entity and can be downloaded as a single archive. Filenames need to be tightly constrained to be robust across multiple environments. A Cover Page is required for all standards to supply uniform metadata interface.

3 Documents and Files

A document (a logical entity) may be composed of several files (physical entities) such as an HTML page containing images. This specification recognises 3 types of documents:

The three different types are illustrated in Diagram 1 and Table 1.

Diagram 1: Illustrating the three types of document.

Table 1: Enumeration of document Types.

Type 1 Type 2 Type 3
Normative Yes No No
Part of a standard Yes Yes No
Function Defines Explains and justifies Helps and Supports
Versioned with Standard Yes Yes No
Controlled by TDWG Process Yes Yes No
Document format Tightly Controlled Tightly Controlled Not Controlled
Language English English + translations Any

This document standard specifies how Type 1 and Type 2 documents should be named and structured. It does not govern Type 3 documents.

4 Contents of Standards

At a minimum, each standard must contain:

but should also contain information on:

Standards may contain any number of files provided they are of an appropriate format (see below).

5 Packaging of Standards

Standards take the form of a logical folder or directory but may be distributed as a zip or tar archive file. The name of the archive must be the file name of the standard followed by a period and the appropriate suffix if the standard is compressed.

6 Naming of Standards

All standards have two names.

A standards full name is not controlled and can contain any combination of characters. A standards file name must start with ‘tdwg_’ followed by a shortened version of the full name.

Both the full and file names for a standard must be unique within the scope of TDWG standards.

7 File Naming

The following rules govern file names used in standards and for standards archives:

8 Versioning of Standards

Once a standard has been ratified it can not be changed but must be replaced by a standard with a different name. Relationships between related standards (i.e. old standards and their replacements) should be indicated in the Cover Page document.

9 File Formats

For archival reasons all files in a standard must be in an open format for which parsers are commonly available. For this purpose an open format is defined as being one for which it would be possible to write a parser on the basis of a published specification without having to rely on code libraries for which the source code is not available or to pay a license fee. The definition of ‘commonly available’ is left to the discretion of the TDWG Executive Committee.

Formats that are currently considered to be acceptable include:

10 Human Readable Documents

This section specifies the layout and style that should be followed for any human readable documents that make up part of a TDWG standard. Normative human readable documents should be in XHTML format. Documents should be divided into three main sections:

  1. A header section
  2. Table of contents
  3. A body section

10.1 Header Section

This section must contain the following parts:

Editors must be quoted in the following format: "FirstName Initials LastName (Affiliation) <email>" where:

Examples

10.2 Table of Contents Section

The table of contents section should contain an ordered list of all the headings (along with their numbers) that occur in the body section and nothing else. It is recommended that the items in the list are hypertext links to the headings in the body.

10.3 Body Section

The body text should be divided by a hierarchy of subheadings. The subheadings must be numbered consecutively using simple decimal system. An example:

        1 First Main Section        
        1.1 Subsection within main section      
        1.1.1 Subsubsection within main section. 
        ... 
        1.12.5 The fifth subsub section within the twelth subsection of the first section.        
        2 Another Main Section
      

10.4 Language

All normative (Type 1) documents must be in English. Translations of normative documents may be included in the standard but the translations must treated as informative (Type 2) documents. Note: Type 3 documents may be produced in any language with no requirement for translation but they do not form parts of a standards and are not governed by this document.

10.5 Linguistic Style

It is recommended text is written with the assumption that it will be read from the screen rather than paper. Current best practise should be followed (e.g. http://www.sun.com/980713/webwriting/ )

10.6 Requirement Level Key Words

It is highly RECOMMENED that the policy of the IETF be followed as regards the use of the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL". This policy is specified out in RFC 2119.

11 Cover Page Contents

This section specifies content for the Cover Page documents that must be contained in all TDWG standards. The table below shows the components that must be contained in the cover page of all TDWG standards.

It is envisaged that the contents and format of cover page documents will be controlled by the collaborative environment used to develop and host TDWG standards and that the data will be made available in RDF or similar formats.

Name Notes
Title Required The official TDWG title for the standard (see above)
Description Required A brief (<250 words) description of the standard
Subject Required Key words, key phrases and classification codes that describe the topic covered by the standard.
Creator Required The primary author of the standard following the conventions outlined above. Should only occur once.
Contributor A contributor to the standard following the conventions outlined above. This assertion may be repeated.
Date Modified The date the standard was last modified. Will be prior to Date Accepted if that is present.
Date Accepted Required for accepted standards The date the standard was official ratified by TDWG and fixed. If a modified date is present it must be prior to this date.
Identifier The GUID of the standard. An LSID.
Publisher Required Should always contain the text "Taxonomic Databases Working Group"
Rights Required A URL linking to a document describing the copyright, IPR and disclaimers associated with the standard. Typically this will be contained within another TDWG standard. (see Legal Statements below)
Access Rights Required Should always contain the single word 'public'. All TDWG standards should be freely available to all.
Bibliographic Citation Required How should this standard be cited.
Has Part Required The full URL to a file within the standard. This assertion should be repeated for each file within the standard (other than cover.xml itself).
Replaced By Required if this standard has been replaced by another. If the standard has been replaced then this assertion should be present and contain the full URL to the new standard.
Replaces Required if this standard replaces another. If this standard replaces a previous one then this assertion should be present and contain the full URL to the standard replaced.

12 Legal Statements

This section defines the Copyright, Intellectual Property and Disclaimer texts that should be included in TDWG standards and actions that should be taken if these 'boiler plate' texts are deemed not to be suitable for a particular standard.

Public sector and not-for-profit organisations are increasingly aware of the value of the intellectual property they possess and expect clear terms on its release. Commercial organisations are unlikely to be involved in development and implementation of standards if ownership is ambiguous and less scrupulous organisations may try to gain ownership of standards through copyright and patenting if they are produced in a legal vacuum. By default the copyright of a work remains with the author(s) who may, at a later date, attempt to prevent the circulation of the work.

The majority of workers involved in the production and use of standards do not have the time or inclination to become involved in legal issues. These statements are therefore provided as 'boiler plate' legal texts within standards documents so as to insure long term, free circulation of the standard and also recognition for the authors.

12.1 Copyright

TDWG requires a copyright notice for several reasons.

The following copyright notice and disclaimer shall be included in all TDWG documents

        Copyright © TDWG (date). All Rights Reserved. This document and translations of it may be
        copied and furnished to others, and derivative works that comment on or otherwise explain it
        or assist in its implementation may be prepared, copied, published and distributed, in whole
        or in part, without restriction of any kind, provided that the above copyright notice and this
        paragraph are included on all such copies and derivative works. However, this document itself
        may not be modified in any way, such as by removing the copyright notice or references to the
        TDWG or other organizations, except as needed for the purpose of developing Grid
        Recommendations in which case the procedures for copyrights defined in the TDWG Document
        process must be followed, or as required to translate it into languages other than English.
        The limited permissions granted above are perpetual and will not be revoked by the TDWG or its
        successors or assigns. This document and the information contained herein is provided on an
        "AS IS" basis and THE TDWG DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
        LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR
        ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE 
      

12.2 Intellectual Property

The following text is based on the Global Grid Forum document found here http://www.ggf.org/documents/GFD.1.pdf which is in turn base on “Bradner, S., "The Internet Standards Process – Revision 3,” RFC 2026, October 1996.

TDWG intellectual property right management process is under development and is intended to mirror the intellectual property rights and procedures associated with the Internet Standards Process, as outlined in Bradner, S. (1996), Section 10. In all matters of intellectual property rights and procedures, the intention is to benefit the biodiversity informatic community and the public at large, while respecting the legitimate rights of others.

12.2.1 Contributions

Contributions include verbal statements in TDWG meetings, as well as written and electronic communications made at any time or place, which are addressed to:

Statements made outside of a TDWG meeting, mailing list, or other function that are clearly not intended to be input to an TDWG activity, group, or function are not subject to these provisions.

By submission of a contribution, each person actually submitting the contribution is deemed to agree to the following terms and conditions on his or her own behalf, on behalf of the organization (if any) he or she represents, and on behalf of the owners of any propriety rights in the contribution. Where a submission identifies contributors in addition to the contributor(s) who provide the actual submission, the actual submitter(s) represent that each other named contributor was made aware of and agreed to accept the same terms and conditions on his or her own behalf, on behalf of any organization he or she may represent and any known owner of any proprietary rights in the contribution.

12.2.2 Confidentiality Obligations

No contribution that is subject to any requirement of confidentiality or any restriction on its dissemination may be considered in any part of the TDWG document process, and there must be no assumption of any confidentiality obligation with respect to any such contribution.

12.2.3 Rights and Permissions

In the course of its work developing recommendations, TDWG receives contributions in various forms and from many persons. To best facilitate the dissemination of these contributions, it is necessary to understand any intellectual property rights (IPR) relating to the contributions.

  1. Some works (e.g., works of the U.S. government) are not subject to copyright. However, to the extent that the submission is or may be subject to copyright, the contributor, the organization he or she represents (if any), and the owners of any proprietary rights in the contribution grant an unlimited perpetual, non-exclusive, royalty-free, worldwide right and license to the GGF under any copyrights in the contribution. This license includes the right to copy, publish, and distribute the contribution in any way and to prepare derivative works that are based on or incorporate all or part of the contribution, the license to such derivative works to be of the same scope as the license of the original contribution.
  2. The contributor acknowledges that the TDWG has no duty to publish or otherwise use or disseminate any contribution.
  3. The contributor grants permission to reference the name(s) and address(es) of the contributor(s) and of the organization(s) he or she represents (if any).
  4. The contributor represents that contribution properly acknowledges major contributors.
  5. The contributor, the organization (if any) he or she represents, and the owners of any proprietary rights in the contribution agree that no information in the contribution is confidential and that the GGF and its affiliated organizations may freely disclose any information in the contribution.
  6. The contributor represents that he or she has disclosed the existence of any proprietary or intellectual property rights in the contribution that are reasonably and personally known to the contributor. The contributor does not represent that he or she personally knows of all potentially pertinent proprietary and intellectual property rights owned or claimed by the organization he or she represents (if any) or by third parties.
  7. The contributor represents that there are no limits to the contributor's ability to make the grants acknowledgments and agreements above that are reasonably and personally known to the contributor.

By ratifying this description of the TDWG process, TDWG warrants that it will not inhibit the traditional open and free access to TDWG documents for which license and right have been assigned according to the procedures set forth in this section. This warrant is perpetual and will not be revoked by the TDWG or its successors or assigns.

Where any patents, patent applications, or other proprietary rights are known, or claimed, with respect to any TDWG document and are brought to the attention of the TDWG Executive Committee then TDWG shall not advance the document without including in the document a note indicating the existence of such rights or claimed rights. Where implementations are required before advancement of a specification, only implementations that have, by statement of the implementers, taken adequate steps to comply with any such rights or claimed rights shall be considered for the purpose of showing the adequacy of the specification.

The TDWG Executive Committee disclaims any responsibility for identifying the existence of or for evaluating the applicability of any claimed copyrights, patents, patent applications, or other rights in the fulfilling of the its obligations as outlined in the previous paragraph and will take no position on the validity or scope of any such rights.

Where the TDWG Executive Committee knows of rights, or claimed rights, the TDWG Executive Committee shall attempt to obtain from the claimant of such rights a written assurance that upon approval by the TDWG Executive Committee of the relevant TDWG document(s), any party will be able to obtain the right to implement, use and distribute the technology or works when implementing, using, or distributing technology based upon the specific specification(s) under openly specified, reasonable, nondiscriminatory terms.

The working group or research group proposing the use of the technology with respect to which the proprietary rights are claimed may assist the TDWG Executive Committee in this effort. The results of this procedure shall not affect advancement of document, except that the TDWG Executive Committee may defer approval where a delay may facilitate the obtaining of such assurances. The results will, however, be recorded by the TDWG Executive Committee and made available. The TDWG Executive Committee may also direct that a summary of the results be included in any GFD published containing the specification.

12.2.4 Determination of Reasonable and Nondiscriminatory Terms

TDWG will not make any explicit determination that the assurance of reasonable and nondiscriminatory terms for the use of a technology has been fulfilled in practice. It will instead use the normal requirements for the advancement of TDWG recommendations track documents to verify that the terms for use are reasonable. If the two unrelated implementations of the specification that are required to advance from Proposed Recommendation to Draft Recommendation have been produced by different organizations or individuals or if the "significant implementation and successful operational experience" required to advance from Draft Recommendation to Recommendation has been achieved the assumption is that the terms must be reasonable and, to some degree, nondiscriminatory. This assumption may be challenged during the open comment period.

12.2.5 Notices

The following IPR notice must be included in all TDWG documents:

IPR: The TDWG takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the TDWG Secretariat. The TDWG invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this recommendation. Please address the information to the TDWG Executive.

Explicit statements about IPR should not be included in the document, because including a specific claim implies that the claim is valid and that the listed claims are exhaustive. Once a document has been published as a final TDWG standard, there is no mechanism to effectively update the IPR information. Authors should instead provide the TDWG Executive Committee with any explicit statements or potentially relevant claims.

12.3 Disclaimer

The following text should be included in all TDWG standards documents:

        Disclaimer: This document and the information contained herein is provided on an "AS IS" basis and
        THE TDWG DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
        WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
        IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSEThis
        notice to be replaced

12.4 Convenience Document

The standard texts recommend above are quite long. As a convenience this standard includes a document that just contains these texts which can be linked to from any other document. The link should bear the following text: This document is governed by the standard legal, copyright, intellectual property rights and disclaimers issued by the Taxonomic Databases Working Group.