Tarin Gamberini

A software engineer and a passionate java programmer

How to validate DocBook 5.0 in Netbeans 7.0.1

This is the DocBook file I’d like to validate:

sample_article.xml 
1
2
3
4
5
6
7
8
9
10

<?xml version='1.0' encoding='UTF-8'?>
<article version="5.0" xml:lang="en"
  xmlns="http://docbook.org/ns/docbook"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xsi:schemaLocation="
    http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd">
    <title>Sample article</title>
    <para>This is a very short article.</para>
</article>

I’ve tried validating sample_article.xml In NetBeans:

unfortunately NetBeans logs:

1
2
3
4
5
6
7
8
9
10
11

XML validation started.
Checking file:/C:/sample_article.xml...
Referenced entity at "http://docbook.org/xml/5.0/xsd/docbook.xsd".
Referenced entity at "http://docbook.org/xml/5.0/xsd/xlink.xsd".
Referenced entity at "nbres:/org/netbeans/modules/j2ee/ddloaders/catalog/resources/XMLSchema.dtd".
Referenced entity at "nbres:/org/netbeans/modules/j2ee/ddloaders/catalog/resources/datatypes.dtd".
src-resolve: Cannot resolve the name 'xml:id' to a(n) 'attribute declaration' component. [6] http://docbook.org/xml/5.0/xsd/docbook.xsd
s4s-elt-must-match.1: The content of 'db.common.attributes' must match (annotation?, ((attribute | attributeGroup)*, anyAttribute?)). A problem was found starting at: attribute. [6] http://docbook.org/xml/5.0/xsd/docbook.xsd
cvc-complex-type.3.2.2: Attribute 'version' is not allowed to appear in element 'article'. [6]
cvc-complex-type.3.2.2: Attribute 'xml:lang' is not allowed to appear in element 'article'. [6]
XML validation finished.

complaining it Cannot resolve the name 'xml:id' as defined in the http://docbook.org/xml/5.0/xsd/docbook.xsd.

But wait a moment! Where does NetBeans get such http://docbook.org/xml/5.0/xsd/docbook.xsd?If I disconnect my PC from Internet, and I re-validate the sample_article.xml again, NetBeans logs something different:

1
2
3
4
5
6
7
8
9
10

XML validation started.
Checking file:/C:/sample_article.xml...
Referenced entity at "http://docbook.org/xml/5.0/xsd/docbook.xsd".
schema_reference.4: Failed to read schema document 'http://docbook.org/xml/5.0/xsd/docbook.xsd', because 1) could not find the document; 2) the document could not be read; 3) the root element of the document is not <xsd:schema>. [6]
cvc-elt.1: Cannot find the declaration of element 'article'. [6]
Referenced entity at "http://docbook.org/xml/5.0/xsd/docbook.xsd".
schema_reference.4: Failed to read schema document 'http://docbook.org/xml/5.0/xsd/docbook.xsd', because 1) could not find the document; 2) the document could not be read; 3) the root element of the document is not <xsd:schema>. [7]
Referenced entity at "http://docbook.org/xml/5.0/xsd/docbook.xsd".
schema_reference.4: Failed to read schema document 'http://docbook.org/xml/5.0/xsd/docbook.xsd', because 1) could not find the document; 2) the document could not be read; 3) the root element of the document is not <xsd:schema>. [8]
XML validation finished.

so it is now clear that NetBeans validates sample_article.xml against the http://docbook.org/xml/5.0/xsd/docbook.xsd file taken form the Internet.

Table of Contents

Investigating

During the validation process something goes wrong. In order to avoid any eventual interference from the Internet, I’ve decided to investigate the problem in isolation by using a DocBook 5.0 local copy.

Setting up a DocBook 5.0 local copy

I’ve downloaded the docbook-5.0.zip from the DocBook 5.0 distribution page, and I’ve expanded it in a NetBeans project. Than I’ve disconnected my PC from the Internet and I’ve said to NetBeans where I’ve expanded the docbook.xsd file by the Tools > DTDs and XML Schemas menu:

then I’ve added a local schema under the User Catalog:

binding the http://docbook.org/xml/5.0/xsd/docbook.xsd URI location to the actual docbook.xsd file location by the System ID radio button:

Trying re-validating the sample_article.xml NetBeans logs the previously seen error:

1
2
3
4
5
6
7
8
9
10
11

XML validation started.
Checking file:/C:/sample_article.xml...
Referenced entity at "http://docbook.org/xml/5.0/xsd/docbook.xsd".
Referenced entity at "http://docbook.org/xml/5.0/xsd/xlink.xsd".
Referenced entity at "nbres:/org/netbeans/modules/j2ee/ddloaders/catalog/resources/XMLSchema.dtd".
Referenced entity at "nbres:/org/netbeans/modules/j2ee/ddloaders/catalog/resources/datatypes.dtd".
src-resolve: Cannot resolve the name 'xml:id' to a(n) 'attribute declaration' component. [6] http://docbook.org/xml/5.0/xsd/docbook.xsd
s4s-elt-must-match.1: The content of 'db.common.attributes' must match (annotation?, ((attribute | attributeGroup)*, anyAttribute?)). A problem was found starting at: attribute. [6] http://docbook.org/xml/5.0/xsd/docbook.xsd
cvc-complex-type.3.2.2: Attribute 'version' is not allowed to appear in element 'article'. [6]
cvc-complex-type.3.2.2: Attribute 'xml:lang' is not allowed to appear in element 'article'. [6]
XML validation finished.

Now the on-line error has been recreated I’m ready to investigate it without any eventual interference from the Internet.

I’ve noticed that in the docbook-5.0\xsd\ directory there’s the docbook.xsd in which, at line 6, there’s: <xs:attribute ref="xml:id"/>:

docbook.xsd 
1
2
3
4
5
6
7

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:docbook="http://docbook.org/ns/docbook">
  <xs:import namespace="http://www.w3.org/1999/xlink" schemaLocation="xlink.xsd"/>
  <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="xml.xsd"/>
  <xs:attributeGroup name="db.common.attributes">
    <xs:attribute ref="xml:id"/>
  ...

When Netbeans complains Cannot resolve the name 'xml:id' seems it isn’t able to locate the xml.xsd in the docbook-5.0\xsd\ directory even if correctly imported as declared at line 4.

As previously done for docbook.xsd I’ve bound the xml.xsd URI location to the actual xml.xsd file location:

so I’ve ended up with two cataloged xsd the docbook.xsd and the xml.xsd:

User Catalog

Trying re-validating the sample_article.xml NetBeans logs the previously seen error again:

1
2
3
4
5
6
7
8
9
10
11

XML validation started.
Checking file:/C:/sample_article.xml...
Referenced entity at "http://docbook.org/xml/5.0/xsd/docbook.xsd".
Referenced entity at "http://docbook.org/xml/5.0/xsd/xlink.xsd".
Referenced entity at "nbres:/org/netbeans/modules/j2ee/ddloaders/catalog/resources/XMLSchema.dtd".
Referenced entity at "nbres:/org/netbeans/modules/j2ee/ddloaders/catalog/resources/datatypes.dtd".
src-resolve: Cannot resolve the name 'xml:id' to a(n) 'attribute declaration' component. [6] http://docbook.org/xml/5.0/xsd/docbook.xsd
s4s-elt-must-match.1: The content of 'db.common.attributes' must match (annotation?, ((attribute | attributeGroup)*, anyAttribute?)). A problem was found starting at: attribute. [6] http://docbook.org/xml/5.0/xsd/docbook.xsd
cvc-complex-type.3.2.2: Attribute 'version' is not allowed to appear in element 'article'. [6]
cvc-complex-type.3.2.2: Attribute 'xml:lang' is not allowed to appear in element 'article'. [6]
XML validation finished.

I’ve tried several URI combined with various User Catalog and Catalog Resolver but, in my opinion, there’s something wrong in how NetBeans binds URI location to actual file location. I suppose NetBeans tries getting the file only if its URI has the form of an URL, downloading the file from Internet, while if the file hasn’t the URL form NetBeans doesn’t try interpreting the URL as a relative pathname to an actual file.

I’ve found a solved bug but I’m not sure that is truly solved, as someone else has pointed out.

Workaround

This is the workaround I’ve came up to get DocBook 5.0 validation working in Netbeans 7.0.1. The idea is based above investigation: NetBeans succesfully resolves URI only if they are in a URL form.

Before going on, if you’ve done what I did in the preceding sections, remove docbook.xsd and xml.xsd from User Catalog, then proceed as with the following paragraphs.

Firstly download the docbook-5.0.zip from the DocBook 5.0 distribution page, and expand it in a NetBeans project (probably you may like a project that builds a docbook-xml-5.0-wrapper.jar).

Then in the docbook-5.0\xsd\docbook.xsd file change URI schema locations from the relative pathname form:

1
2

<xs:import namespace="http://www.w3.org/1999/xlink" schemaLocation="xlink.xsd"/>
<xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="xml.xsd"/>

to the URL form:

1
2

<xs:import namespace="http://www.w3.org/1999/xlink" schemaLocation="http://docbook.org/xml/5.0/xsd/xlink.xsd"/>
<xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://docbook.org/xml/5.0/xsd/xml.xsd"/>

Now put this systemCatalog.xml, I’ve specifically created in order to maps DocBook 5.0 URI location to actual local file, in the same directory in which there’s the docbook-5.0 folder of the DocBook 5.0 distribution:

Finally add a catalog resolver for the just added systemCatalog.xml:

Trying re-validating the sample_article.xml NetBeans finally logs a successful message:

1
2
3

XML validation started.
Checking file:/C:/sample_article.xml...
XML validation finished.

Post a comment

A comment is submitted by an ordinary e-mail. Your e-mail address will not be published or broadcast.

This blog is moderated, therefore some comments might not be published. Comments are usually approved by the moderator in one/three days.