FlexDoc/XML - XSDDoc - FAQ

Troubleshooting

There is some oddity in the documentation I've generated. What may be wrong?

Your problem is that: You have generated a documentation by your XML schema(s) and it appears that something is wrong in it. For instance, some hyperlinks lead to wrong locations, others may be absent at all when they should be there and so on.

Most likely, the cause of all such odd things may be that some of your input XML schemas are actually invalid (that is, they do not strictly comply with W3C XML Schema specification).

The default namespace is not set to schema's target one

A common mistake is specifying the schema's target namespace and forgetting to set that namespace to be default within the <xs:schema> element. For example, in the following schema definition:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.company.com/project">
...
<!-- Complex Type Definitions -->
<xs:complexType name="Account">
<xs:sequence>
<xs:element name="NAME" type="acctholdername"/>
...
</xs:sequence>
</xs:complexType>
...
<!-- Simple Type Definitions -->
<xs:simpleType name="acctholdername">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="80"/>
</xs:restriction>
</xs:simpleType>
...
</xs:schema>

the element 'NAME' specified within the complex type is supposed to have a simple type 'acctholdername', which is defined just below and belongs to the schema's target namespace "http://www.company.com/project". However, the type attribute of the <xs:element> element requires a value of xs:QName type, that is a qualified name. Since the default namespace was not assigned in that schema, what that particular type attribute actually refers to is the 'acctholdername' type within the global namespace (or {no namespace}). Such a type has nothing to do with the simple type 'acctholdername' defined in that schema and will be simply unknown here. Hence, the whole schema is incorrect and the documentation generated by it will be incorrect too.

However, the situation can be easily fixed. All is needed is to set the default namespace in the start tag of the <xs:schema> element (highlighted with yellow):

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.company.com/project"
xmlns="http://www.company.com/project">
...
<!-- Complex Type Definitions -->
<xs:complexType name="Account">
<xs:sequence>
<xs:element name="NAME" type="acctholdername"/>
...
</xs:sequence>
</xs:complexType>
...
<!-- Simple Type Definitions -->
<xs:simpleType name="acctholdername">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="80"/>
</xs:restriction>
</xs:simpleType>
...
</xs:schema>

Alternatively, a custom namespace prefix may be used, for instance "prj", which is first declared in the <xs:schema> start tag (highlighted with yellow), and when a name from that namespace is used (e.g. 'acctholdername' in the declaration of 'NAME' element) that prefix must be applied (highlighted with yellow):

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.company.com/project"
xmlns:prj="http://www.company.com/project">
...
<!-- Complex Type Definitions -->
<xs:complexType name="Account">
<xs:sequence>
<xs:element name="NAME" type="prj:acctholdername"/>
...
</xs:sequence>
</xs:complexType>
...
<!-- Simple Type Definitions -->
<xs:simpleType name="acctholdername">
<xs:restriction base="xs:string">
<xs:minLength value="1"/>
<xs:maxLength value="80"/>
</xs:restriction>
</xs:simpleType>
...
</xs:schema>

Validate your XML schemas!

In fact, XSDDoc templates do not verify the validity of the input XML schemas. The templates were designed in assumption that the input XML schemas are correct. When the schema is incorrect a certain documentation will be generated still. However, what that documentation will be no one knows... Actually, it may be even more incorrect than the source schema because what exactly processing a particular invalid XML schema will spawn is difficult to predict.

So, before running the documentation generator, we suggest to verify your schemas(s) with a proper tool.

If all your schemas pass the validation and the errors in the generated documentation still persist, then, indeed, there may be something wrong in the templates (or elsewhere)... In that case, please, let us know by sending an e-mail to: support@flexdoc.xyz

Cannot insert an image into my XSDDoc output

You are trying to insert an image into your XML schema annotation using some HTML tags (formed as XML), which looks something like this:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:annotation>
<xs:documentation>
My Image:
<p/>
<img src="http://www.flexdoc.xyz/images/flowers.png"/>
</xs:documentation>
</xs:annotation>
</xs:schema>

Then, you generate a documentation by it (using XSDDoc with all necessary parameters and options selected) and in the corresponding «Annotation» section, instead of the image, you see this:

My Image: <p/> <img src="http://www.flexdoc.xyz/images/flowers.png"/>

What may be wrong? The wrong is that those XHTML-looking elements are not XHTML at all, because besides element names, there is also some namespace any XML element belongs to. Since no namespace prefixes are specified, that namespace is automatically assumed the default one. What is the default namespace within the <xs:documentation> element? If you take the sample schema above, the default namespace will be the global one. So, those XHTML-looking elements belong to the global namespace. By default, XSDDoc doesn't process such things and prints them as is to the output. That's what you see!

In order to fix it, you need to set the default namespace within <xs:documentation> to XHTML namespace (associated with the URI "http://www.w3.org/1999/xhtml"). Here is how it can be done. Switching of the default namespace is highlighted with yellow:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:annotation>
<xs:documentation xmlns="http://www.w3.org/1999/xhtml">
My Image:
<p/>
<img src="http://www.flexdoc.xyz/images/flowers.png"/>
</xs:documentation>
</xs:annotation>
</xs:schema>

Now, if you apply XSDDoc to such a schema, you will get in the generated documentation this:

My Image:

See Also: