Attributes namespace in DocBook output

[fred]

Hello! There is an xsd schema for which I am trying to create documentation in DocBook format (Ctrl+Alt+S, DocBook output). The problem is that in the generated document, attributes of complex types for some reason do not have a namespace (although the namespace is set for the entire schema). In the output document, these attributes are placed in a separate section, while all other schema data (elements, types) are placed in a different (correct) section with the schema namespace. Is this a bug or should it be? Thank you in advance
Xsd schema

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
    targetNamespace="http://testNamespace" xmlns="http://testNamespace">

    <xs:element name="newElement" type="TestType"/>
    <xs:complexType name="TestType">
        <xs:attribute name="testAttribute1" type="xs:string"/>
        <xs:attribute name="testAttribute2" type="xs:string"/>
    </xs:complexType>
    <xs:simpleType name="newSimpleType">
        <xs:restriction base="xs:string"/>
    </xs:simpleType>
</xs:schema>

Output DocBook file

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="xml"?>
<!--XML Schema documentation generated by <oXygen/> XML Editor Trial Edition.-->
<article xmlns="http://docbook.org/ns/docbook" version="5.0">
    <title>Schema documentation for Untitled2.xsd</title>
    <info>
        <pubdate>april 12, 2020</pubdate>
    </info>
    <section>
        <title> Namespace: "http://testNamespace/com/ru" </title>
        <section>
            <title>Schema(s)</title>
            <section xml:id="Untitled2.xsd">
                <title>Main schema <literal>Untitled2.xsd</literal></title>              
            </section>
        </section>
    </section>
    <section>
        <title> Namespace: "" </title>
        <section>
            <title>Attribute(s)</title>
            <section xml:id="TestType_testAttribute1">
                <title>Attribute <literal>TestType / @testAttribute1</literal></title>
                <informaltable frame="all" colsep="1">
                    <tgroup cols="2">
                        <colspec colwidth="3*" align="left"/>
                        <colspec colwidth="25*" align="left"/>
                        <tbody>
                            <row>
                                <entry> Namespace </entry>
                                <entry>No namespace</entry>
                            </row>
                            <row>
                                <entry> Type </entry>
                                <entry>xs:string</entry>
                            </row>
                            <row>
                                <entry> Properties </entry>
                                <entry><informaltable frame="none" colsep="0">
                                        <tgroup cols="2">
                                            <colspec colwidth="2*" align="left"/>
                                            <colspec colwidth="8*" align="left"/>
                                            <tbody>
                                                <row>
                                                  <entry>content: </entry>
                                                  <entry><literal>simple</literal></entry>
                                                </row>
                                            </tbody>
                                        </tgroup>
                                    </informaltable></entry>
                            </row>
                            <row>
                                <entry> Used by </entry>
                                <entry><informaltable frame="none" colsep="0">
                                        <tgroup cols="2">
                                            <colspec colwidth="2*" align="left"/>
                                            <colspec colwidth="8*" align="left"/>
                                            <tbody>
                                                <row>
                                                  <entry>Complex Type </entry>
                                                  <entry><link linkend="TestType"
                                                  >TestType</link></entry>
                                                </row>
                                            </tbody>
                                        </tgroup>
                                    </informaltable></entry>
                            </row>
                            <row>
                                <entry>Source</entry>
                                <entry><programlisting><tag class="element">&lt;xs:attribute</tag><tag class="attribute"> name=</tag><tag class="attvalue">"testAttribute1"</tag><tag class="attribute"> type=</tag><tag class="attvalue">"xs:string"</tag><tag class="element">/&gt;</tag></programlisting></entry>
                            </row>
                        </tbody>
                    </tgroup>
                </informaltable>
            </section>         
    </section>
    </section>
</article>

[adrian]

Hello,

The problem is that in the generated document, attributes of complex types for some reason do not have a namespace (although the namespace is set for the entire schema).

This (in bold) is false in relation to attributes. It is only true for elements.
You have set a target namespace and have set elementFormDefault="qualified". But, as its name implies, elementFormDefault only applies to elements. So the attributes are still in "no namespace". If you also want the attributes to be in the schema target namespace, set attributeFormDefault="qualified" on the schema root.

Regards,
Adrian

[fred]

Thanks! Then I have another question, why if I explicitly specify elementFormDefault= "qualified" and attributeFormDefault= "unqualified", then the result is still the same. I.e., elements have a namespace, but attributes don't. Can I achieve the same processing for attributes as for elements. I want the attributes to fall into the namespace section when forming the document, even if they have attributeFormDefault="unqualified" or are missing. Thank you in advance!
xsd file

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="unqualified" attributeFormDefault="unqualified"
    targetNamespace="http://testNamespace" xmlns="http://testNamespace">
    
    <xs:element name="newElement" type="TestType"/>
    <xs:complexType name="TestType">
        <xs:attribute name="testAttribute1" type="xs:string"/>
        <xs:attribute name="testAttribute2" type="xs:string"/>
    </xs:complexType>
    <xs:simpleType name="newSimpleType">
        <xs:restriction base="xs:string"/>
    </xs:simpleType>
</xs:schema>

output DocBook file

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="xml"?>
<!--XML Schema documentation generated by <oXygen/> XML Editor Trial Edition.-->
<article xmlns="http://docbook.org/ns/docbook" version="5.0">
    <title>Schema documentation for Untitled2.xsd</title>
    <info>
        <pubdate>april 14, 2020</pubdate>
    </info>
    <section>
        <title> Namespace: "http://testNamespace" </title>
        <section>
            <title>Element(s)</title>
            <section xml:id="newElement">
                <title>Element <literal>newElement</literal></title>
                <informaltable frame="all" colsep="1">
                    <tgroup cols="2">
                        <colspec colwidth="3*" align="left"/>
                        <colspec colwidth="25*" align="left"/>
                        <tbody>
                            <row>
                                <entry> Namespace </entry>
                                <entry>http://testNamespace</entry>
                            </row>
                            <row>
                                <entry> Diagram </entry>
                                <entry><para>
                                        <mediaobject>
                                            <imageobjectco>

                                                <areaspec xml:id="Untitled2_xsd_Element_newElement">

                                                  <area linkends="TestType_testAttribute1"
                                                  units="other" otherunits="imagemap"
                                                  coords="164,79,279,123"
                                                  xml:id="Untitled2_xsd_Element_newElement-1"/>

                                                  <area linkends="TestType_testAttribute2"
                                                  units="other" otherunits="imagemap"
                                                  coords="164,133,279,177"
                                                  xml:id="Untitled2_xsd_Element_newElement-2"/>

                                                  <area linkends="TestType" units="other"
                                                  otherunits="imagemap" coords="139,3,235,25"
                                                  xml:id="Untitled2_xsd_Element_newElement-3"/>


                                                </areaspec>
                                                <imageobject>
                                                  <imagedata
                                                  fileref="img/Untitled2_xsd_Element_newElement.jpeg"
                                                  width="148.5pt"/>
                                                  <!--If you want to use this Docbook document to generate
                                            HTML output you will have to delete the "width" attributes in order for the imagemaps to function.
                                        -->
                                                </imageobject>
                                            </imageobjectco>
                                        </mediaobject>
                                    </para></entry>
                            </row>
                            <row>
                                <entry> Type </entry>
                                <entry><link linkend="TestType">TestType</link></entry>
                            </row>
                            <row>
                                <entry> Properties </entry>
                                <entry><informaltable frame="none" colsep="0">
                                        <tgroup cols="2">
                                            <colspec colwidth="2*" align="left"/>
                                            <colspec colwidth="8*" align="left"/>
                                            <tbody>
                                                <row>
                                                  <entry>content: </entry>
                                                  <entry><literal>complex</literal></entry>
                                                </row>
                                            </tbody>
                                        </tgroup>
                                    </informaltable></entry>
                            </row>
                            <row>
                                <entry> Attributes </entry>
                                <entry><informaltable frame="none" colsep="1">
                                        <tgroup cols="6">
                                            <colspec colnum="1" colname="col1" align="left"
                                                colwidth="3*"/>
                                            <colspec colnum="2" colname="col2" align="left"
                                                colwidth="3*"/>
                                            <colspec colnum="3" colname="col3" align="left"
                                                colwidth="2*"/>
                                            <colspec colnum="4" colname="col4" align="left"
                                                colwidth="2*"/>
                                            <colspec colnum="5" colname="col5" align="left"
                                                colwidth="1*"/>
                                            <colspec colnum="6" colname="col6" align="left"
                                                colwidth="1*"/>
                                            <thead>
                                                <row>
                                                  <entry>QName</entry>
                                                  <entry>Type</entry>
                                                  <entry>Use</entry>
                                                </row>
                                            </thead>
                                            <tbody>
                                                <row>
                                                  <entry><emphasis role="bold"><link
                                                  linkend="TestType_testAttribute1"
                                                  >testAttribute1</link></emphasis></entry>
                                                  <entry>xs:string</entry>
                                                  <entry>optional</entry>
                                                </row>
                                                <row>
                                                  <entry><emphasis role="bold"><link
                                                  linkend="TestType_testAttribute2"
                                                  >testAttribute2</link></emphasis></entry>
                                                  <entry>xs:string</entry>
                                                  <entry>optional</entry>
                                                </row>
                                            </tbody>
                                        </tgroup>
                                    </informaltable></entry>
                            </row>
                            <row>
                                <entry>Source</entry>
                                <entry><programlisting><tag class="element">&lt;xs:element</tag><tag class="attribute"> name=</tag><tag class="attvalue">"newElement"</tag><tag class="attribute"> type=</tag><tag class="attvalue">"TestType"</tag><tag class="element">/&gt;</tag></programlisting></entry>
                            </row>
                        </tbody>
                    </tgroup>
                </informaltable>
            </section>
        </section>
    </section>
    <section>
        <title> Namespace: "" </title>
        <section>
            <title>Attribute(s)</title>
            <section xml:id="TestType_testAttribute1">
                <title>Attribute <literal>TestType / @testAttribute1</literal></title>
                <informaltable frame="all" colsep="1">
                    <tgroup cols="2">
                        <colspec colwidth="3*" align="left"/>
                        <colspec colwidth="25*" align="left"/>
                        <tbody>
                            <row>
                                <entry> Namespace </entry>
                                <entry>No namespace</entry>
                            </row>
                            <row>
                                <entry> Type </entry>
                                <entry>xs:string</entry>
                            </row>
                            <row>
                                <entry> Properties </entry>
                                <entry><informaltable frame="none" colsep="0">
                                        <tgroup cols="2">
                                            <colspec colwidth="2*" align="left"/>
                                            <colspec colwidth="8*" align="left"/>
                                            <tbody>
                                                <row>
                                                  <entry>content: </entry>
                                                  <entry><literal>simple</literal></entry>
                                                </row>
                                            </tbody>
                                        </tgroup>
                                    </informaltable></entry>
                            </row>
                            <row>
                                <entry> Used by </entry>
                                <entry><informaltable frame="none" colsep="0">
                                        <tgroup cols="2">
                                            <colspec colwidth="2*" align="left"/>
                                            <colspec colwidth="8*" align="left"/>
                                            <tbody>
                                                <row>
                                                  <entry>Complex Type </entry>
                                                  <entry><link linkend="TestType"
                                                  >TestType</link></entry>
                                                </row>
                                            </tbody>
                                        </tgroup>
                                    </informaltable></entry>
                            </row>
                            <row>
                                <entry>Source</entry>
                                <entry><programlisting><tag class="element">&lt;xs:attribute</tag><tag class="attribute"> name=</tag><tag class="attvalue">"testAttribute1"</tag><tag class="attribute"> type=</tag><tag class="attvalue">"xs:string"</tag><tag class="element">/&gt;</tag></programlisting></entry>
                            </row>
                        </tbody>
                    </tgroup>
                </informaltable>
            </section>
        </section>
    </section>
</article>

[adrian]

Hi,

Then I have another question, why if I explicitly specify elementFormDefault= "qualified" and attributeFormDefault= "unqualified", then the result is still the same. I.e., elements have a namespace, but attributes don't.

Setting attributeFormDefault to "unqualified" doesn't make any difference because "unqualified" is the default value (even when not specified).
https://www.w3.org/TR/xmlschema-1/#declare-schema

Can I achieve the same processing for attributes as for elements. I want the attributes to fall into the namespace section when forming the document, even if they have attributeFormDefault="unqualified" or are missing. Thank you in advance!

If there is namespace information then there is also grouping by namespace, so it's not possible for elements and attributes to be together in the same namespace section, because they are from different namespaces. If you have only one namespace and this separation bothers you, you can clear the box for Namespace in the Included components details subsection (Settings tab in the XML Schema Documentation dialog). Note that this means there will be no namespace information at all.

Regards,
Adrian

[fred]

Sorry, I made a mistake in the last post. Meant that if I set both values unqualified for elements and attributes, i.e. elementFormDefault="unqualified" attributeFormDefault="unqualified", then the result would not change. I.e. elements in the documentation are displayed in sections, with the Namespace and attributes in the Namespace of the section, although for elements and attributes will stand unqualified. Ie for elements, the elementFormDefault value does not affect the output in the document (they are always output in the Namespace section), and for attributes, the attributeFormDefault value does. Why is that?

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="unqualified" attributeFormDefault="unqualified"
    targetNamespace="http://testNamespace" xmlns="http://testNamespace">
    
    <xs:element name="newElement" type="TestType"/>
    <xs:complexType name="TestType">
        <xs:attribute name="testAttribute1" type="xs:string"/>
        <xs:attribute name="testAttribute2" type="xs:string"/>
    </xs:complexType>
    <xs:simpleType name="newSimpleType">
        <xs:restriction base="xs:string"/>
    </xs:simpleType>
</xs:schema>

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="xml"?>
<!--XML Schema documentation generated by <oXygen/> XML Editor Trial Edition.-->
<article xmlns="http://docbook.org/ns/docbook" version="5.0">
    <title>Schema documentation for Untitled2.xsd</title>
    <info>
        <pubdate>april 14, 2020</pubdate>
    </info>
    <section>
        <title> Namespace: "http://testNamespace" </title>
        <section>
            <title>Element(s)</title>
            <section xml:id="newElement">
                <title>Element <literal>newElement</literal></title>
                <informaltable frame="all" colsep="1">
                    <tgroup cols="2">
                        <colspec colwidth="3*" align="left"/>
                        <colspec colwidth="25*" align="left"/>
                        <tbody>
                            <row>
                                <entry> Namespace </entry>
                                <entry>http://testNamespace</entry>
                            </row>
                            <row>
                                <entry> Diagram </entry>
                                <entry><para>
                                        <mediaobject>
                                            <imageobjectco>

                                                <areaspec xml:id="Untitled2_xsd_Element_newElement">

                                                  <area linkends="TestType_testAttribute1"
                                                  units="other" otherunits="imagemap"
                                                  coords="164,79,279,123"
                                                  xml:id="Untitled2_xsd_Element_newElement-1"/>

                                                  <area linkends="TestType_testAttribute2"
                                                  units="other" otherunits="imagemap"
                                                  coords="164,133,279,177"
                                                  xml:id="Untitled2_xsd_Element_newElement-2"/>

                                                  <area linkends="TestType" units="other"
                                                  otherunits="imagemap" coords="139,3,235,25"
                                                  xml:id="Untitled2_xsd_Element_newElement-3"/>


                                                </areaspec>
                                                <imageobject>
                                                  <imagedata
                                                  fileref="img/Untitled2_xsd_Element_newElement.jpeg"
                                                  width="148.5pt"/>
                                                  <!--If you want to use this Docbook document to generate
                                            HTML output you will have to delete the "width" attributes in order for the imagemaps to function.
                                        -->
                                                </imageobject>
                                            </imageobjectco>
                                        </mediaobject>
                                    </para></entry>
                            </row>
                            <row>
                                <entry> Type </entry>
                                <entry><link linkend="TestType">TestType</link></entry>
                            </row>
                            <row>
                                <entry> Properties </entry>
                                <entry><informaltable frame="none" colsep="0">
                                        <tgroup cols="2">
                                            <colspec colwidth="2*" align="left"/>
                                            <colspec colwidth="8*" align="left"/>
                                            <tbody>
                                                <row>
                                                  <entry>content: </entry>
                                                  <entry><literal>complex</literal></entry>
                                                </row>
                                            </tbody>
                                        </tgroup>
                                    </informaltable></entry>
                            </row>
                            <row>
                                <entry> Attributes </entry>
                                <entry><informaltable frame="none" colsep="1">
                                        <tgroup cols="6">
                                            <colspec colnum="1" colname="col1" align="left"
                                                colwidth="3*"/>
                                            <colspec colnum="2" colname="col2" align="left"
                                                colwidth="3*"/>
                                            <colspec colnum="3" colname="col3" align="left"
                                                colwidth="2*"/>
                                            <colspec colnum="4" colname="col4" align="left"
                                                colwidth="2*"/>
                                            <colspec colnum="5" colname="col5" align="left"
                                                colwidth="1*"/>
                                            <colspec colnum="6" colname="col6" align="left"
                                                colwidth="1*"/>
                                            <thead>
                                                <row>
                                                  <entry>QName</entry>
                                                  <entry>Type</entry>
                                                  <entry>Use</entry>
                                                </row>
                                            </thead>
                                            <tbody>
                                                <row>
                                                  <entry><emphasis role="bold"><link
                                                  linkend="TestType_testAttribute1"
                                                  >testAttribute1</link></emphasis></entry>
                                                  <entry>xs:string</entry>
                                                  <entry>optional</entry>
                                                </row>
                                                <row>
                                                  <entry><emphasis role="bold"><link
                                                  linkend="TestType_testAttribute2"
                                                  >testAttribute2</link></emphasis></entry>
                                                  <entry>xs:string</entry>
                                                  <entry>optional</entry>
                                                </row>
                                            </tbody>
                                        </tgroup>
                                    </informaltable></entry>
                            </row>
                            <row>
                                <entry>Source</entry>
                                <entry><programlisting><tag class="element">&lt;xs:element</tag><tag class="attribute"> name=</tag><tag class="attvalue">"newElement"</tag><tag class="attribute"> type=</tag><tag class="attvalue">"TestType"</tag><tag class="element">/&gt;</tag></programlisting></entry>
                            </row>
                        </tbody>
                    </tgroup>
                </informaltable>
            </section>
        </section>
    </section>
    <section>
        <title> Namespace: "" </title>
        <section>
            <title>Attribute(s)</title>
            <section xml:id="TestType_testAttribute1">
                <title>Attribute <literal>TestType / @testAttribute1</literal></title>
                <informaltable frame="all" colsep="1">
                    <tgroup cols="2">
                        <colspec colwidth="3*" align="left"/>
                        <colspec colwidth="25*" align="left"/>
                        <tbody>
                            <row>
                                <entry> Namespace </entry>
                                <entry>No namespace</entry>
                            </row>
                            <row>
                                <entry> Type </entry>
                                <entry>xs:string</entry>
                            </row>
                            <row>
                                <entry> Properties </entry>
                                <entry><informaltable frame="none" colsep="0">
                                        <tgroup cols="2">
                                            <colspec colwidth="2*" align="left"/>
                                            <colspec colwidth="8*" align="left"/>
                                            <tbody>
                                                <row>
                                                  <entry>content: </entry>
                                                  <entry><literal>simple</literal></entry>
                                                </row>
                                            </tbody>
                                        </tgroup>
                                    </informaltable></entry>
                            </row>
                            <row>
                                <entry> Used by </entry>
                                <entry><informaltable frame="none" colsep="0">
                                        <tgroup cols="2">
                                            <colspec colwidth="2*" align="left"/>
                                            <colspec colwidth="8*" align="left"/>
                                            <tbody>
                                                <row>
                                                  <entry>Complex Type </entry>
                                                  <entry><link linkend="TestType"
                                                  >TestType</link></entry>
                                                </row>
                                            </tbody>
                                        </tgroup>
                                    </informaltable></entry>
                            </row>
                            <row>
                                <entry>Source</entry>
                                <entry><programlisting><tag class="element">&lt;xs:attribute</tag><tag class="attribute"> name=</tag><tag class="attvalue">"testAttribute1"</tag><tag class="attribute"> type=</tag><tag class="attvalue">"xs:string"</tag><tag class="element">/&gt;</tag></programlisting></entry>
                            </row>
                        </tbody>
                    </tgroup>
                </informaltable>
            </section>
        </section>
    </section>
</article>

[fred]

I think that it is implemented now somewhat incorrectly. The elementFormDefault and attributeFormDefault values should not be taken into account when generating documentation. Since their values affect the xml, not the xsd itself. And documentation is generated for xsd. Therefore, both elements and attributes must always fall into the Namespace section, regardless of the elementFormDefault and attributeFormDefault values.

[adrian]

Sorry, I made a mistake in the last post. Meant that if I set both values unqualified for elements and attributes, i.e. elementFormDefault="unqualified" attributeFormDefault="unqualified", then the result would not change. I.e. elements in the documentation are displayed in sections, with the Namespace and attributes in the Namespace of the section, although for elements and attributes will stand unqualified. Ie for elements, the elementFormDefault value does not affect the output in the document (they are always output in the Namespace section), and for attributes, the attributeFormDefault value does. Why is that?

Because elementFormDefault and attributeFormDefault only affect local elements and attributes (the ones declared within other types), they do not affect global (top-level) elements and attributes which are always qualified (in the target namespace). Since all the elements from your schema are global, setting elementFormDefault has no effect. On the other hand all the attributes from your schema are local, so subject to attributeFormDefault.

The elementFormDefault and attributeFormDefault values should not be taken into account when generating documentation. Since their values affect the xml, not the xsd itself. And documentation is generated for xsd.

. Oxygen's schema documentation tool implementation chooses to document the element and attribute namespaces dictated by the schema, so the documentation is affected by these values. Setting elementFormDefault to "qualified" literally changes the namespace for local schema elements from "no namespace" to the schema target namespace. The same is true for attributeFormDefault with regard to local attributes. In both cases, this becomes relevant information for the schema documentation.

I do agree that for the DocBook output, if attributeFormDefault="unqualified" (which is the usual value), the namespace grouping has the unfortunate side effect of isolating the attributes in the "no namespace" (Namespace "") section away from the rest of the components from the target namespace, which is unnecessary for a simple schema. This default grouping is a lot easier to handle for the HTML output where you have an index and you can easily change the grouping. I've logged an issue to investigate and identify a better default grouping for the DocBook output.

Regards,
Adrian

[fred]

Now everything is clear. Thank you for the clarification. I hope you will do something to output attributes in the Namespace section, maybe some additional settings parameter?