xsd2svg API Usage

This page describes how to use the xsd2svg API. This requires a successful setup.

Namespace

To call the API functions add the following namespace declaration to your stylesheets:

xmlns:xsd2svg="http://www.xsd2svg.nkutsche.com/"

Functions

xsd2svg:getMasterFiles

The function xsd2svg:getMasterFiles returns a sequence of URIs of files which are identified as XSD master file in an extended XSD file set.

A master file is an XSD file which are not included (not imported!) by another XSD file in a set of XSD files.

An extended XSD file set is the union of a basic XSD file set and all XSD files which are imported or included directly and indirectly by one XSD in the basic XSD file set.

The basic XSD file set are all XSD files which are found evaluating the parameters $path $extension and $recusrive.

Parameter

Name Short Description Type Default Required
path Directory searching for XSD files. xs:string - yes
extension File name extension identifying XSD files xs:string xsd no
recursive Searching recursive for files in sub folders or not. true xs:boolean no

Return value

Type: xs:anyURI*

A sequence of abolute URIs pointing to XSD master files.

xsd2svg:getSchemaInfo

The function xsd2svg:getSchemaInfo receives an URI of an XSD file and returns a SchemaInfo object map (see below).

Parameter

Name Short Description Type Default Required
schema-url URI identifying an XSD file. xs:anyURI - yes

Return value

Type: map(*)

An instance of a SchemaInfo object map.

xsd2svg:svg-model

This function creates from an XSD main component ($xsdnode) a SVG Content Model Graphic. This SVG graphic describes the content model and the parents of the given XSD main component. The parameter $standalone indicates whether the generated SVG should include all neccassary CSS (true()) or not (false()). The XSD component have to match the described restrictions of Main Components (see below).

Parameter

Name Short Description Type Default Required
xsdnode An XSD component definition element. element() - yes
standalone File name extension identifying XSD files xs:boolean - yes

Return value

Type: node()*

The root nodes of a generated SVG Model Graphic.

Object Maps

SchemaInfo

The SchemaInfo Object Map is a XPath map describing the content of an XSD schema structure, based on a set of ComponentInfo Object Maps of all XSD Main Components. The map contains the following entries:

Key Short Description Type
schema-namespace-map A sub map associating the found target namespaces in the XSD schema structure with a sequence of the XSD root element of each XSD schema which is part of the XSD structure and bejoined to this target namespace. map(xs:string, document-node(element(xs:schema))*)
create-css A function which with no parematers. The return value is a CSS stylesheet styling the generated SVG Model Graphics. Can be used to embed it into an HTML document. function() as xs:string?
get-grouped-components A function with one parameter $grouping, expecting a sequence of strings. The function groups Component Info Object Map set depending on grouping criterias given by the $grouping parameter value and returns a nested map structure. Possible grouping criteria values are namespace, type and scope, refering the keys of the ComponentInfo Object Maps (see below). function(xs:string*) as map(xs:string, item()*)
namespaces A sequence of all distinct values of the namespace entries in the ComponentInfo Object Maps set. xs:string*
types A sequence of all distinct values of the type entries in the ComponentInfo Object Maps set. xs:string*
qnames A sequence of all distinct values of the qname entries in the ComponentInfo Object Maps set. xs:QName*
print-qname A function receives a QName as the first argument and returns a string representing this QName. The representation will be the same as it would be in the SVG Model Graphics. xs:string
components-by-id A map containing for each ComponentInfo Object Map an entry with the id as key and the ComponentInfo Object Map as value. map(xs:string, map(xs:string, item()*))
find-reference A function receives as the only argument an XSD referencing attribute (@ref, @type, @base, etc.) and returns a (sequence of) ComponentCoreInfo Object Map of all referenced types (usually only one). In case of a reference to a primitive type, a pseudo ComponentCoreInfo Object Map is returned, describing the primitive data type. function(attribute()) as map(xs:string, item()*)*

ComponentCoreInfo

The ComponentCoreInfo Object Map describes a given XSD main component with some identification informations by the following entries:

Key Short Description Type
id A unique ID for the given XSD main component. xs:string
component The XSD element declaring the given XSD main component. xs:string
type The local name of the component element. xs:string
namespace The target namespace for the given XSD main component. xs:string
scope A key word indicating whether the given XSD main component was declared on top level (global) or nested in other components (local). xs:string
qname The QName identifying the XSD main component. xs:QName

ComponentInfo

The ComponentInfo Object Map extends the ComponentCoreInfo Object Map by the following entries:

Key Short Description Type
used-by The ComponentCoreInfo Object Maps of all XSD main components which are refering the given XSD main component. map(xs:string, item()*)*
uses The ComponentCoreInfo Object Maps of all XSD main components which are refered by the given XSD main component. map(xs:string, item()*)*
nested The ComponentCoreInfo Object Maps of all XSD main components which are nested by the given XSD main components. map(xs:string, item()*)*
nested-by If the given XSD main component is nested by another XSD main component, this entry contains the ComponentCoreInfo Object Map of the next ancestor component. map(xs:string, item()*)?
get-svg-model A function creates the SVG Model Graphic for the XSD main component. The only argument $standalone indicates whether the returned SVG Model Graphic should contain all necessary CSS stylesheets or not. function(xs:boolean) as node()*

Global Parameter

config

The document root node of the configuration XML file.

link-provider-function

A function matching to the signature function(map(xs:string, item()*)) as xs:string?. This function will receive a ComponentCoreInfo Object Map and returns a string or an empty sequence.

This function is called every time when the XSD2SVG library should create a link for a referenced Component. The ComponentCoreInfo Object Map describes the target Component. If the function returns a string it will create an SVG link by this string. If the function returns an empty sequence it will not create a link.

Configuration

The configuration file is XML based and has to be valid against this RelaxNG schema.

Font Configuration

There are two different kind of text in the generated SVG Model Graphics. The configuration element emphasis configures the font of emphasized text like headings or main components. The element main configures the font of regular text - all other shown text.

There are to ways to configure a font:

By Font File

<fonts>
    <emphasis href="font/Roboto-Bold.ttf" name="Roboto Bold" type="truetype"/>
    <main href="font/Roboto-Regular.ttf" name="Roboto" type="truetype"/>
</fonts>

The href attributes references a font file in format TrueType (ttf) or WOFF. The name attributes is used to reference the given font in the custom CSS. The type attribute should match with the values truetype or woff to the format of the given fonts.

By Name Reference

<fonts>
    <emphasis name="Arial" style="bold"/>
    <main name="Arial" style="regular"/>
</fonts>

The name attribute reference with its value to an installed font. With the style attribute a font style can be choosen. Please note that this way is not recommanded in the most cases (see below).

Why do I need to configure the font separately?

The SVG format is not designed to make a proper text rendering graphics. As the generated graphics contains content dependent text, the generator needs to know the final dimensions of the text representations (after rendering) during the generation of the SVG Model Graphics. For this it is required to provide the used font for rendering the SVG graphics.

Why it is recommended to provide a font file?

Usually the rendering of the SVG files is done on client side (e.g. in a browser). In the SVG Model Graphics we want create it is important that the renderer uses the same font, as the generator has assumed (see above). If the the rendering system has the requested font not installed, it will use a fallback font and the SVG graphics may have space conflicts.

If the configured fonts are provided as font files (e.g. TTF file), these files will be embedded into the CSS of the generated files and all renderer should be able to use the correct font.

If the configuration just reference a font by the name, it is required that the SVG renderer has installed that font as well. This will lead to no issues if the SVG renderer is known.

Custom CSS

A custom CSS can be added by:

<css href="custom.css"/>

The content of the provided CSS file will be added at the end of the generated CSS.

Specific Prefix Bindings

For the QNames which are described in the SVG Model graphics the XSD2SVG library will use a static prefix binding to reference the used namespaces. By default the XSD2SVG library will look into the given XSD files and searches for namespace declarations for the given target namespaces to create such a prefix binding. If there is no namespace declaration for a given target namespace or all of them has no prefix it will generate a generic prefix. The library also checks that the prefix is unique and can be associated with a single namespace.

To make a custom specification for all or some target namespaces the configuration file can have an own prefix binding, like this:

<namespaces>
    <namespace prefix="nk" uri="http://www.nkutsche.com/xsd2svg"/>
    <namespace prefix="xsd2svg" uri="http://www.xsd2svg.nkutsche.com/"/>
</namespaces>

The library will use this prefix binding as base and generate prefixes only for target namespaces which are not covered by this binding.

XSD support/Restrictions

This section describes the XSD support of the XSD2SVG library.

Main Components

For the following components this libary is able to create SVG Model graphics:

  • xs:element
  • xs:attribute
  • xs:complexType
  • xs:simpleType
  • xs:group
  • xs:attributeGroup

In addition the following restrictions applies:

  • All components needs to be named (by a name attribute).

Content Support

The following list shows all XSD elements which are supported by this library:

  • xs:annotation
  • xs:attribute
  • xs:element
  • xs:group
  • xs:attributeGroup
  • xs:complexType
  • xs:complexContent
  • xs:simpleContent
  • xs:extension
  • xs:restriction
  • xs:sequence
  • xs:choice
  • xs:all
  • xs:union
  • xs:list
  • xs:any
  • xs:length
  • xs:pattern
  • xs:maxLength
  • xs:minLength
  • xs:whiteSpace
  • xs:fractionDigits
  • xs:totalDigits
  • xs:maxExclusive
  • xs:maxInclusive
  • xs:minInclusive
  • xs:minExclusive
  • xs:enumeration
  • xs:documentation

Any other element may are ignored.

Parenthood Recognization

In the following cases a Parenthood is detected for a main component:

  • A named component contains a reference using @ref attribute to the main component.
  • The main component is a nested declaration inside of a named component (xs:element or xs:complexType).
  • A named component (xs:element or xs:attribute) references the main component using @type attribute.