OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Updating the backwards compatibility rules

Here's a new version of the spec that includes my proposal for
amending the backwards incompatibility rules:

Title: The DocBook Schema

OASIS logo

The DocBook Schema Version 5.0

Editor's Draft

18 May 2010

Technical Committee:
OASIS DocBook Technical Committee
Norman Walsh, MarkLogic Corporation
Norman Walsh, MarkLogic Corporation
Related Work:
This specification is related to:
Declared XML Namespace


DocBook is a general purpose [XML] schema particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications).

The Technical Committee provides the DocBook 5.0 schema in other schema languages, including W3C XML Schema and an XML DTD, but the RELAX NG Schema is now the normative schema.


This is a Editor's Draft. It does not necessarily represent the consensus of the committee.

Please send comments on this specification to the list. To subscribe, please use the OASIS Subscription Manager.


Copyright © OASIS® 2010. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

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 section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, 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 OASIS or its successors or assigns.


OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS 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. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. 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 OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.

1. Introduction

DocBook is general purpose XML schema particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications).

The DocBook Technical Committee maintains the DocBook schema. Starting with V5.0, DocBook is normatively available as a [RELAX NG] Schema (with some additional [Schematron] assertions). W3C XML Schema and Document Type Definition (DTD) versions are also available.

The Version 5.0 release is a complete rewrite. In programming-language terms, think of it as a code refactoring.

This rewrite introduces a large number of backwards-incompatible changes. Essentially all DocBook V4.x documents will have to be modified to validate against DocBook V5.0. An XSLT 1.0 stylesheet is provided to ease this transition.

The DocBook Technical Committee welcomes bug reports and requests for enhancement (RFEs) from the user community. The current list of outstanding requests is available through the SourceForge tracker interface. This is also the preferred mechanism for submitting new requests. Old RFEs, from a previous legacy tracking system, are archived for reference.

1.1. Terminology

The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this Editor's Draft are to be interpreted as described in [RFC 2119]. Note that for reasons of style, these words are not capitalized in this document.

1.2. Normative References

[XML] Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, et. al., editors. Extensible Markup Language (XML) 1.0 (Fifth Edition). World Wide Web Consortium. 26 November 2008.

[XLink11] Steven DeRose, Eve Maler, David Orchard, Norman Walsh, editors. XML Linking Language (XLink) Version 1.1. World Wide Web Consortium, 2005.

[W3C XML Datatypes] Paul V. Biron and Ashok Malhotra, editors. XML Schema Part 2: Datatypes. World Wide Web Consortium, 2000.

[RELAX NG] ISO/IEC JTC 1, SC 34. ISO 19757-2:2008(E) Information technology — Document Schema Definition Language (DSDL) — Part 2: Regular-grammare-based validation — RELAX NG. 2008.

[Schematron] ISO/IEC JTC 1, SC 34. ISO 19757-3:2006(E) Information technology — Document Schema Definition Languages (DSDL) — Part 3: Rule-based validation — Schematron. 2006.

[RFC 2119] IETF (Internet Engineering Task Force). RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. 1997.

[RFC 3023] IETF (Internet Engineering Task Force). RFC 3023: XML Media Types. M. Murata, S. St. Laurent, D. Kohn. 2001.

[DocBook: TDG5] Norman Walsh and Leonard Meullner. DocBook 5.0: The Definitive Guide.

1.3. Non-Normative References

[SGML] ISO/IEC JTC 1, SC 34. ISO 8879:1986 Information processing -- Text and office systems -- Standard Generalized Markup Language (SGML). 1986.

[W3C XML Schema] Henry S. Thompson, David Beech, Murray Maloney, et. al., editors. XML Schema Part 1: Structures. World Wide Web Consortium, 2000.

2. The DocBook RELAX NG Schema

The DocBook RELAX NG Schema is distributed from the DocBook site at OASIS. DocBook is also available from the mirror on http://docbook.org/.

In V5.0, DocBook has been rewritten as a native RELAX NG grammar. The goals of this redesign were to produce a schema that:

  1. “feels like” DocBook. Most existing documents should still be valid or it should be possible to transform them in simple, mechanical ways into valid documents.

  2. enforces as many constraints as possible in the schema. Some additional constraints are expressed with Schematron rules.

  3. cleans up the content models.

  4. gives users the flexibility to extend or subset the schema in an easy and straightforward way.

  5. can be used to generate XML DTD and W3C XML Schema versions of DocBook.

Under the ordinary operating rules of DocBook evolution, the only backwards incompatible changes that could be made in DocBook V5.0 were those announced in DocBook V4.0. In light of the fact that this is a complete rewrite, the Technical Committee gave itself the freedom to make “unannounced” backwards-incompatible changes for this one release.

2.1. Removing Legacy Elements

A number of elements have been removed from DocBook. Many of these have been replaced by simpler, more versatile alternatives. Others have simply been removed because they are not believed to be widely used:

DocBook Element Changes
articleinfo, bookinfoinfo, …, *info

Replaced by info, see Section 2.3, “Uniform Info Elements”.


Replaced by personblurb. This more general name better reflects the fact that it is available in elements other than author (e.g., editor).

collabname, corpauthor, corpcredit corpname

Replaced by orgname and the updated content models of author, editor, and othercredit.

graphic, graphicco, inlinegraphic mediaobjectco

Removed in favor of mediaobject and inlinemediaobject.

isbn, issn, pubsnumber

Replaced by biblioid.

lot, lotentry, tocback, tocchap, tocfront, toclevel1, toclevel2, toclevel3, toclevel4, toclevel5, tocpart

Replaced by simpler tocdiv element.


Replaced by ubiquitous linking, see Section 2.9, “Universal Linking”.


Replaced by tag.

action, beginpage, highlights, interface, invpartnumber, medialabel, modespec, structfield, structname


2.2. Smaller Content Models

The content models of many inlines have been reduced, sometimes drastically. The parameter entity customization of DocBook V4.x and previous versions resulted in very broad content models for some inlines.

Consider, for example, command in DocBook V4.4:

command ::=

In DocBook V5.0, command has a much smaller, more rational content model:

command ::=

  * Zero or more of:
      o text
      o alt
      o anchor
      o annotation
      o biblioref
      o indexterm
      o inlinemediaobject
      o link
      o phrase
      o remark
      o replaceable
      o subscript
      o superscript
      o xref

DocBook V5.0 may be overzealous in its simplification of content models. The Technical Committee expects to adjust these simplifications during user testing. Users are encouraged to report places where formally valid documents can no longer be made valid because content models have been reduced.

2.3. Uniform Info Elements

DocBook V4.x has setinfo, bookinfo, chapterinfo, appendixinfo, sectioninfo, etc. DocBook would be smaller and simpler if it had a single info element in all these places.

There’s an historical reason for the large number of unique names: customizers might very well want to adjust the content models of info elements at different levels. For example, a copyright statement might be required at the book level, or an author forbidden at the sub-section level. In DTDs, there’s only one content model allowed per element name, so in order to support independent customization, each info element must have a different name.

In RELAX NG, no such limitation exists. We can use patterns to achieve both a single info element while still allowing customizers to change its content model in different contexts. In light of this functionality, we've replaced all the various flavors of info with a single element name.

2.4. Required Titles

DocBook V5.0 enforces the constraint that titles are required on articles and other large structures where they are effectively optional in DocBook V4.x. (They are optional only in the sense that DTDs are unable to enforce the constraint that they be present, the documentation has always made it clear that titles were required.)

2.5. Required Version

In DocBook V4.x and earlier, the presence of a document type declaration served as a mechanism for identifying the DocBook version of a document. Although the declaration was not actually required, it was present in the vast majority of DocBook documents.

In RELAX NG, no similar declaration exists. Although a document type declaration might still be present, it seems likely that this will not usually be the case.

Nevertheless, downstream processors may benefit from some indication of the version of DocBook being used. As a result DocBook V5.0 adds a new version attribute which must be present on the document element of a DocBook document.

Mixing versions is explicitly allowed and the version attribute may be used on other elements as well. This might be the case, for example, in a compound document constructed from multiple documents each with its own version.

2.6. Co-Constraints

DocBook V5.0 enforces attribute co-constraints such as the class/otherclass attributes on biblioid.

2.7. Improved HTML and CALS Table Support

In DocBook V5.0, HTML tables and CALS tables are independently specified. Where the DTD of DocBook V4.x allows for incoherent mixing of the two models, DocBook V5.0 forbids such mixtures.

2.8. Data Types

DocBook V5.0 adds a few simple data types. For example, the cols attribute on tgroup must be a positive integer.

Some of these constraints, such as the requirement that elements like pubdate include a proper date-time type, may prove controversial. Users are encouraged to report places where formally valid documents can no longer be made valid because data types have been introduced.

2.10. Improved Accessibility

Accessibility is improved by allowing both inline and block annotations in most context. The alt element is now allowed in most places for inline annotations, the new element annotation supports block annotations.

2.11. Simplified Table of Contents Markup

The DocBook V4.x markup for Tables of Contents, or more generally for Lists of Titles, was complex and had not evolved quite in step with the rest of DocBook. In DocBook V5.0, it has all been replaced by a quite simple, recursive toc/tocdiv/tocentry structure.

While most Tables of Contents and Lists of Titles are generated automatically and authors never have to produce markup for them by hand, this simplified content model should make it easier for authors to generate them when necessary. One possible application of hand-authored toc markup is to generate custom hierarchies which can be assembled on-the-fly from a library of topics marked up in DocBook.

2.12. Extra-Grammatical Constraints

Grammar based validation technologies (like RELAX NG) and rule based validation technologies (like Schematron) are naturally complementary. Mixing them allows us to play to the strengths of each without stretching either to enforce constraints that they aren’t readily designed to enforce.

For example, DocBook NG requires that the root element of a document have an explicit version attribute. Because there are a great many elements that can be root elements in DocBook, and because they can almost all appear as descendants of a root element as well, it would be tedious to express this constraint in RELAX NG. But it is easy in a rule-based schema language.

DocBook V5.0 uses Schematron where appropriate.

2.13. Customization

From the very beginning, one of the goals of DocBook has been that users should be able to produce customizations that are either subsets of extensions of DocBook.

Customization is possible in DocBook V4.x, but because of the intricacies of XML DTD syntax and the complex and highly stylized patterns of parameter entitiy usage in DocBook, it's not as easy as we would like it to be.

In DocBook V5.0, we hope to take advantage of RELAX NGs more robust design (and it's lack of pernicious determinism rules) to make customization easier.

Three schema design patterns get us most of the way there.

2.13.1. Logical Groupings

DocBook elements, particularly the inlines, can be divided into broad classes: general purpose, technical, error-related, operating-system related, bibliographic, publishing, etc. In DocBook V5.0, these are collected together in named patterns.

To add a new inline, endpoint for example, to the list of technical inlines, one need only extend the appropriate pattern. If an element should appear in several classes, they can all be extended in the same way:

db.technical.inlines |= endpoint
db.programming.inlines |= endpoint
db.os.inlines |= endpoint

Much the same concept was used in DocBook V4.x, where instead of patterns we had parameter entities. However, the constraints of DTD validation severely limit the circumstances under which an element can appear twice in a content model. That meant that adding an element to one parameter entity might make it an error to add it to another. Such constraints do not exist in RELAX NG which greatly simplifies the customization.

2.13.2. Element Definitions

Each element in DocBook V5.0 is defined by its own pattern. To change the content model of an element, only that pattern need be redefined. To remove an element from DocBook, that pattern can be redefined as “notAllowed”.

2.13.3. Attribute Definitions

Each attribute list in DocBook V5.0 is defined by its own pattern. To change the list of attributes available on an element, only that pattern need be redefined. To remove all the attributes, that pattern can be redefined as “empty”.

2.14. Conversion

There’s an XSLT 1.0 stylesheet for performing conversion from DocBook V4.x to DocBook V5.0. Presented with a valid DocBook V4.x document, it attempts to produce a valid DocBook V5.0 document.

It succeeds entirely automatically for the most part, though human intervention is suggested for constructs that might have multiple interpretations (and therefore multiple possible transformations).

Users are encouraged to report documents that are not successfully transformed by the stylesheet, especially those which do have valid DocBook V5.0 representations.

3. Identifying DocBook Documents and Schemas

Historically, when DocBook was defined by a DTD, DocBook documents could be identified by the presence of standard public and/or system identifiers in the document type declaration. RELAX NG, the normative schema language for DocBook V5.0, does not provide any equivalent mechanism.

For systems that can make use of public identifiers, e.g., systems where the informative DTD is being used, the following public identifier can be used for DocBook V5.0: “-//OASIS//DTD DocBook V5.0//EN//XML”.

4. Conformance

This specification normatively defines DocBook V5.0 with a RELAX NG grammar and a set of Schematron assertions. A conformant DocBook V5.0 document must be valid according to both the grammar and the assertions.

The reference documentation describes additional constraints and processing expectations. A conformant DocBook V5.0 document should respect those constraints and anticipate those processing expectations.

5. Backwards compatibility

The DocBook Technical Committee understands that the community benefits from the long-term stability of the DocBook family of schemas. We also understand that DocBook must continue to adapt and change in order to remain relevant in a changing world.

All changes, and especially changes that are backwards incompatible (changes that make a currently valid document no longer valid under a new version of the schema), have a cost associated with them. Our duty is to balance those costs against the need to remain responsive to the community's desire to see DocBook grow to cover the new use cases that inevitably arise in documentation.

With that in mind, the DocBook Technical Committee has adopted the following policy on backwards incompatible changes. This policy spells out when backwards incompatible changes can occur and how much notice the TC must provide before adopting a schema that is backwards incompatible with the current release.

This policy allows DocBook to continue to change and adapt while simultaneously guaranteeing that existing users will have sufficient advance notice to develop reasonable migration plans.

With respect to schema changes, the following points must always apply:

  1. A point release (X.1 to X.2, X.2 to X.3, X.1 to X.1.2, etc.) must not contain any backwards incompatible changes unless those changes correct obvious bugs accidentally introduced in the preceding version.

  2. A major release (X.1 to Y.0, X.2 to Y.0, X.1.2 to Y.0, etc.) may contain backwards incompatible changes if both of the following conditions are true:

    • The change was announced in the release notes for the previous version (major or minor).

    • The change was announced in a release that occurred at least six months previously.

By these rules, the TC can announce, in V5.1 for example, its plans to make a backwards incompatible change in V6.0. Then, in V6.0, if it's been at least six months since V5.1 was released, it can make that change.

The exclusion in point 1 is designed to allow the committee to correct errors accidentally introduced in a point release, that are technically backwards incompatible, without having to leave them in the schema until the next full version.

6. Release Notes

See http://www.relaxng.org/ for a list of tools that can validate an XML document using RELAX NG. Note that not all products are capable of evaluating the Schematron assertions in the schema.

A. The DocBook Media Type

This appendix registers a new MIME media type, “application/docbook+xml”.

A.1. Registration of MIME media type application/docbook+xml

MIME media type name:


MIME subtype name:


Required parameters:


Optional parameters:

This parameter has identical semantics to the charset parameter of the application/xml media type as specified in [RFC 3023] or its successors.

Encoding considerations:

By virtue of DocBook XML content being XML, it has the same considerations when sent as “application/docbook+xml” as does XML. See [RFC 3023], Section 3.2.

Security considerations:

Several DocBook elements may refer to arbitrary URIs. In this case, the security issues of RFC 2396, section 7, should be considered.

Interoperability considerations:


Published specification:

This media type registration is for DocBook documents as described by [DocBook: TDG5].

Applications which use this media type:

There is no experimental, vendor specific, or personal tree predecessor to “application/docbook+xml”, reflecting the fact that no applications currently recognize it. This new type is being registered in order to allow for the deployment of DocBook on the World Wide Web, as a first class XML application.

Additional information:
Magic number(s):

There is no single initial octet sequence that is always present in DocBook documents.

File extension(s):

DocBook documents are most often identified with the extension “.xml”.

Macintosh File Type Code(s):


Person & email address to contact for further information:

Norman Walsh, .

Intended usage:


Author/Change controller:

The DocBook specification is a work product of the DocBook Technical Committee at OASIS.

A.2. Fragment Identifiers

For documents labeled as “application/docbook+xml”, the fragment identifier notation is exactly that for “application/xml”, as specified in [RFC 3023] or its successors.

B. Acknowledgements

The following individuals have participated in the creation of this specification and are gratefully acknowledged:

  • Steve Cogorno, Sun Microsystems
  • Gary Cornelius, Individual
  • Adam Di Carlo, Debian
  • Paul Grosso, Arbortext
  • Dick Hamilton, Individual
  • Nancy Harrison, IBM
  • Scott Hudson, Individual
  • Mark Johnson, Debian
  • Gershon Joseph, Tech-Tav Documentation Ltd.
  • Jirka Kosek, Individual
  • Larry Rowland, Hewlett-Packard
  • Michael Smith, Individual
  • Robert Stayton, Individual (Secretary)
  • Norman Walsh, Mark Logic Corporation (Chair, Editor)

C. Revision History

This specification does not yet reflect any schema changes.

                                        Be seeing you,

Norman Walsh <ndw@nwalsh.com>      | A man is not necessarily
http://www.oasis-open.org/docbook/ | intelligent because he has plenty
Chair, DocBook Technical Committee | of ideas, any more than he is a
                                   | good general because he has plenty
                                   | of soldiers.-- Chamfort

PGP signature

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]