Denormalize XSD

Question

I need to denormalize an XML schema to generate documentation for the people that will create documents that conform to the schema. The users have no knowledge of XSD and will most likely never learn. The tools I've seen are able to generate documentation for fellow XSD developers, but my users are not interested in the details of how the schema is constructed, they only want to know what they can and must do to create valid documents.

So, I'm looking for a way to resolve all includes and references in an XML schema and generate a denormalized version that I can use to (in turn) generate user documentation.

I´ve started to do some of this using XSLT, but a proven tool would be helpful. I also tried XSD4J, but it apparently strips all annotations that I need to generate something useful.

Update:

What I want is to resolve all references and make all definitions inline. For example, the following schema:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="AAAA" type="myComplexType"/>
  <xs:complexType name="myComplexType">
    <xs:all>
      <xs:element name="BBBB">
        <xs:complexType>
          <xs:attribute name="cccc" type="mySimpleType"/>
        </xs:complexType>
      </xs:element>
    </xs:all>
  </xs:complexType>
  <xs:simpleType name="mySimpleType">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

should be denormalized into:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="AAAA">
    <xs:complexType>
      <xs:all>
        <xs:element name="BBBB">
          <xs:complexType>
            <xs:attribute name="cccc">
              <xs:simpleType>
                <xs:restriction base="xs:string">
                  <xs:minLength value="1"/>
                </xs:restriction>
              </xs:simpleType>
            </xs:attribute>
          </xs:complexType>
        </xs:element>
      </xs:all>
    </xs:complexType>
  </xs:element>
</xs:schema>

Annotations for element and attribute definitions also need to survive the transformation.

Answer 1

This desired configuration is known as the "Russian Doll" configuration.

I do not know of any tools that include that capability, but another reader may given this known terminology.

Also, two items that may help:

• You can read more about XSD design patterns: "Schema scope: Primer and best practices"
• If you're going to write custom XSLT, you might get some ideas from the answer to this question on the reverse conversion: "Russian doll to Venetian blind xsl transformation"

---

On the other hand, many tools offer the capability to combine multiple referenced XSDs into one single XSD.

Be aware that only xsd:include references can be incorporated into an including XSD; xsd:import's cannot be flattened because an XSD file can only have a single target namespace.

Options for flattening XSDs

1. Write your own custom XSLT code.
2. Use the XSLT 2.0 XSD flattener found in W. Paul Kiel's XML SchemaLightener tool.
3. Use the flattener built into XMLSpy.
4. Use the flattener built into Oxygen XML Editor.
5. Use the "Internalize XSDs" command built into Petru Gardea's QTAssistant.

Final note: Be aware of complications that arise when the separate XSDs use different @elementFormDefault and @attributeFormDefault values.

---