%%ItemTitle%%

Liquid XML Studio
Introduction
See Also Send Feedback

Glossary Item Box

Welcome to Liquid Studio 2019

The Liquid Studio product suite includes a graphical XML development environment that will simplify the development of XML Schema, JSON Schema and XML Documents in your enterprise. Along with a variety of graphical and text editors, it also provides Web Services tools, a Data Mapping tool for transforming Database, EDI, Text File, Web Service and XML data, and a powerful Code Generator.

Liquid Studio features include:

Graphical XML Schema (XSD) Editor

  • A graphical visualization of your XML Schema.
    • Graphical representations of all XML Schema Element and Data Type content.
    • In-place name and type editing.
  • A text representation of your XML Schema.
    • Auto-complete Intellisense.
    • Color coded syntax highlighting.
  • Global Component Locator to quickly find content across multiple included schema.
  • Property Grid to allow quick editing of the selected items properties and facets.

Graphical JSON Schema (JSON) Editor

  • A graphical visualization of your JSON Schema.
    • Graphical representations of all JSON Schema Element and Data Type content.
    • In-place name and type editing.
  • A text representation of your JSON Schema.
    • Auto-complete Intellisense.
    • Color coded syntax highlighting.
  • Property Grid to allow quick editing of the selected items properties and facets.

Graphical XML Document Editor

  • A graphical visualization of your XML Document.
    • Tree and tabular grid views.
  • A text representation of your XML Document.
    • Auto-complete Intellisense.
    • Color coded syntax highlighting.
  • XML Document validation against the XSD schema.
  • Well Formed XML Document validation.
  • XML Document formatting (pretty printing).

Graphical Web Service Definition Language (WSDL) Editor

  • A graphical visualization of your WSDL.
    • Graphical representations of all WSDL content.
  • A text representation of your XML Schema.
    • Auto-complete Intellisense.
    • Color coded syntax highlighting.

Web Service Client

  • Bind to a Web Service.
  • Supports Soap 1.1, Soap 1.2, HTTP GET & HTTP POST.
  • Creates sample requests from WSDL files.

Graphical Data Mapper

  • A graphical visualization of data mapping between multiple data sources and targets.
    • Drag and drop interface for data mapping.
  • Supports Database, EDI, Text File, Web Services and XML data transformations.
  • Generates mapping code in XSLT and C#.

XQuery and XSLT Step Through Debuggers

  • Supports XQuery 1.0 and XSLT 1.0 & 2.0.
  • Provides essential debugging functionality: breakpoints, local variables, local content, watch expressions, call stack.
  • Choice of XSLT engines.

Getting Started

The following simple Tutorial provides a quick overview to create an XML Schema using Liquid XML Studio:

Creating your first XML Schema

Get to know the Liquid XML Studio User Interface:

Liquid XML Studio User Interface Guide

View a detailed list of the Liquid XML Studio graphical notations for XML Schema:

Liquid XML Studio Graphical Notations for XML Schema

Learn about the W3C XML Schema standard:

W3C XML Schema Tutorial

See Also

WSDL Editor
WSDL Editor Overview

XML Editor
XML Editor Overview
Associating a schema with an XML Document
XML Validation
Inferring an XML Schema (XSD)
Xml InferXsd Wizard 1
Xml InferXsd Wizard 2
Associating a schema with an XML Document in Visual Studio
XML Schema Library
XML Document Text View
XML Document Split View
XML Document Graphical View
Working with large files
XPath Builder
XML Editor Context Menu
XML Grid - Cut and Paste from Excel

Web Service Test Client
Web Service Test Client Overview
Selecting a Web Service Method

XSD Editor
XSD Editor Overview
XSD Editor Toolbar

©2001-2019 Liquid Technologies Limited. All Rights Reserved.
Liquid XML Studio | XML Data Binder | XML Editor | XML Schema Editor | WSDL Editor | XPath Viewer | Web Service Tools


Copyright and Trademark Information
Send Feedback
Copyright Notice > Copyright and Trademark Information

Glossary Item Box

Information in this document is subject to changed without notice.

LIQUID TECHNOLOGIES LIMITED BEARS NO LIABILITY FOR ANY TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS, OR FOR DAMAGES RESULTING FROM USE OF THE INFORMATION IN ANY PROVIDED DOCUMENTATION AND/OR EXAMPLES.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Liquid XML™ and XML the Smart Way™ are trademarks or registered trademarks of Liquid Technologies Limited in the United States and/or other countries. Microsoft® and Visual Studio® are trademarks or registered trademarks of Microsoft® Corporation in the United States and/or other countries.

Other content may be trademarks of other companies.


XSD Tutorial - Part 1 - Elements and Attributes
Send Feedback
Tutorials > W3C XSD Schema Tutorial > XSD Tutorial - Part 1 - Elements and Attributes

Glossary Item Box

This article gives a basic overview of the building blocks of XML Schemas and how to use them. It covers:
  • Schema Overview
  • Elements
  • Cardinality
  • Simple Types
  • Complex Types
  • Compositors
  • Reuse
  • Attributes
  • Mixed Element Content

Overview

First lets look at what an XML schema is. A schema formally describes what a given XML document contains, in the same way a database schema describes the data that can be contained in a database (table structure, data types). An XML schema describes the coarse shape of the XML document, what fields an element can contain, which sub elements it can contain etc, it can also describe the values that can be placed into any element or attribute.

A Note About standards

DTD was the first formalized standard, but is rarely used anymore.
XDR was an early attempt but Microsoft to provide a more comprehensive standard than DTD. This standard has pretty much been abandoned now in favor of XSD.
XSD is currently the de facto standard for describing XML documents. There are 2 versions in use 1.0 and 1.1, which are on the whole the same (you have to dig quite deep before you notice the difference). An XSD schema is itself an XML document, there is even an a XSD schema to describe the XSD standard.
There are also a number of other standards but there take up has been patchy at best.

The XSD standard has evolved over a number of years, and is controlled by the W3C. It is extremely comprehensive, and as a result has become rather complex. For this reason it is a good idea to make use of design tools when working with XSD's (See XML Studio, a FREE XSD development tool), also when working with XML documents programmatically XML Data Binding is a much easier way to manipulate your documents (a object oriented approach see Liquid XML Data Binding).

The remainder of this tutorial guides you through the basics of the XSD standard, things you should really know even if your using a design tool like Liquid XML Studio.

Elements

Elements are the main building block of any XML document, they contain the data and determine the structure of the document. An element can be defined within an XML Schema (XSD) as follows:

<xs:element name="x" type="y"/>

An element definition within the XSD must have a name property, this is the name that will appear in the XML document. The type property provides the description of what can be contained within the element when it appears in the XML document. There are a number of predefined types, such as xs:string, xs:integer, xs:boolean or xs:date (see XSD standard for a complete list). You can also create a user defined type using the <xs:simple type> and <xs:complexType> tags, but more on these later.

If we have set the type property for an element in the XSD, then the corresponding value in the XML document must be in the correct format for its given type (failure to do this will cause a validation error). Examples of simple elements and their XML are below:

Sample XSD | Sample XML
<xs:element name="Customer_dob"
type="xs:date"/> 		<Customer_dob>
2000-01-12T12:13:14Z
</Customer_dob>
<xs:element name="Customer_address"
type="xs:string"/> 		<Customer_address>
99 London Road
</Customer_address>
<xs:element name="OrderID"
type="xs:int"/> 		<OrderID>
5756
</OrderID>
<xs:element name="Body" type="xs:string"/> | <Body> (a type can be defined as a string but not have any content, this is not true of all data types however).</Body>

The previous XSD definitions are shown graphically in Liquid XML Studio as follows

The value the element takes in the XML document can further be affected using the fixed and default properties.

Default means that if no value is specified in the XML document then the application reading the document (typically an XML parser or XML Data binding Library) should use the default specified in the XSD.
Fixed means the value in the XML document can only have the value specified in the XSD.
For this reason it does not make sense to use both default and fixed in the same element definition (in fact its illegal to do so)..

<xs:element name="Customer_name" type="xs:string" default="unknown"/>
<xs:element name="Customer_location" type="xs:string" fixed=" UK"/>

Cardinality

Specifying how many times an element can appear is referred to as cardinality, and is specified using the attributes minOccurs and maxOccurs. In this way an element can be mandatory, optional, or appear many times. minOccurs can be assigned any non-negative integer value (e.g. 0, 1, 2, 3... etc.), and maxOccurs can be assigned any non-negative integer value or the string constant "unbounded" meaning no maximum.
The default values for minOccurs and maxOccurs is 1 . So if both the minOccurs and maxOccurs attributes are absent, as in all the previous examples, the element must appear once and once only.

Sample XSD Description
<xs:element name="Customer_dob"
type="xs:date"/> 		If we don’t specify minOccurs or maxOccurs, then the default values of 1 are used, so in this case there has to be one and only one occurrence of Customer_dob
<xs:element name="Customer_order"
type="xs:integer"
minOccurs ="0"
maxOccurs="unbounded"/> 		Here, a customer can have any number of Customer_orders (even 0)
<xs:element name="Customer_hobbies"
type="xs:string"
minOccurs="2"
maxOccurs="10"/> 		In this example, the element Customer_hobbies must appear at least twice, but no more than 10 times

The previous XSD definitions are shown graphically in Liquid XML Studio as follows

.

Simple Types

So far we have touched on a few of the built in data types xs:string, xs:integer, xs:date. But you can also define your own types by modifying existing ones.

Examples of this would be;

  • Defining an ID, this may be an integer with a max limit.
  • A PostCode or Zip code could be restricted to ensure it is the correct length and complies with a regular expression.
  • A field may have a maximum length

Creating you own types is coved more thoroughly in the next section

Complex Types

A complex type is a container for other element definitions, this allows you to specify which child elements an element can contain. This allows you to provide some structure within your XML documents.

Have a look at these simple elements:

<xs:element name="Customer" type="xs:string"/>
<xs:element name="Customer_dob" type="xs:date"/>
<xs:element name="Customer_address" type="xs:string"/>

<xs:element name="Supplier" type="xs:string"/>
<xs:element name="Supplier_phone" type="xs:integer"/>
<xs:element name="Supplier_address" type="xs:string"/>

We can see that some of these elements should really be represented as child elements, "Customer_dob" and "Customer_address" belong to a parent element – "Customer". While "Supplier_phone" and "Supplier_address" belong to a parent element "Supplier". We can therefore re-write this in a more structured way:

<xs:element name="Customer">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="Dob" type="xs:date" />
                <xs:element name="Address" type="xs:string" />
            </xs:sequence>
        </xs:complexType>
</xs:element>

<xs:element name="Supplier">
    <xs:complexType>
        <xs:sequence>
            <xs:element name="Phone" type="xs:integer"/>
            <xs:element name="Address" type="xs:string"/>
        </xs:sequence>
    </xs:complexType>
</xs:element>

The previous XSD definitions are shown graphically in Liquid XML Studio as follows

Example XML

<Customer>
    <Dob> 2000-01-12T12:13:14Z </Dob>
    <Address> 34 thingy street, someplace, sometown, w1w8uu </Address>
</Customer>

<Supplier>
    <Phone>0123987654</Phone>
    <Address>22 whatever place, someplace, sometown, ss1 6gy </Address>
</Supplier>

What’s changed?

Let’s look at this in detail.

  • We created a definition for an element called "Customer".
  • Inside the <xs:element> definition we added a <xs:complexType>. This is a container for other <xs:element> definitions, allowing us to build a simple hierarchy of elements in the resulting XML document.
  • Note the contained elements for "Customer" and "Supplier" do not have a type specified as they do not extend or restrict an existing type, they are a new definition built from scratch.
  • The <xs:complexType> element contains another new element <xs:sequence>, but more on these in a minute.
  • The <xs:sequence> in turn contains the definitions for the 2 child elements "Dob" and "Address". Note the customer/supplier prefix has been removed as it is implied from its position within the parent element "Customer" or "Supplier".

So in English this is saying we can have an XML document that contains an element <Customer> which must have 2 child elements <Dob> and <Address>.

Compositors

There are 3 types of compositors <xs:sequence>, <xs:choice> and <xs:all>. These compositors allow us to determine how the child elements within them appear within the XML document.

Compositor | Description
Sequence | The child elements in the XML document MUST appear in the order they are declared in the XSD schema.
Choice | Only one of the child elements described in the XSD schema can appear in the XML document.
All | The child elements described in the XSD schema can appear in the XML document in any order.

Notes
The compositors <xs:sequence> and <xs:choice> can be nested inside other compositors, and be given there own minOccurs and maxOccurs properties. This allows for quite complex combinations to be formed.

One step further… The definition of "Customer->Address" and "Supplier->Address" are currently not very usable as they are grouped into a single field. In the real world it would be better break this out into a few fields. Lets fix this by breaking it out using the same technique shown above:

  <xs:element name="Customer">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Dob" type="xs:date" />
        <xs:element name="Address">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Line1" type="xs:string" />
              <xs:element name="Line2" type="xs:string" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name="Supplier">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Phone" type="xs:integer" />
        <xs:element name="Address">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Line1" type="xs:string" />
              <xs:element name="Line2" type="xs:string" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

The previous XSD definitions are shown graphically in Liquid XML Studio as follows

This is much better, but we now have 2 definitions for address, which are the same.

Re-use

It would make much more sense to have 1 definition of "Address", that could be used by both customer and supplier.
We can do this by defining a complexType independently of an element, and giving it a unique name :

<xs:complexType name="AddressType">
    <xs:sequence>
        <xs:element name="Line1" type="xs:string"/>
        <xs:element name="Line2" type="xs:string"/>
    </xs:sequence>
</xs:complexType>

The previous XSD definitions are shown graphically in Liquid XML Studio as follows

We have now defined a <xs:complexType> that describes our representation of an address, so lets use it.
Remember when we started looking at elements and we said you could define your own type instead of using one of the standard ones (xs:string, xs:integer), well that's exactly what were doing now.

<xs:element name="Customer">
    <xs:complexType>
        <xs:sequence>
            <xs:element name="Dob" type="xs:date"/>
            <xs:element name="Address" type="AddressType"/>
        </xs:sequence>
    </xs:complexType>
</xs:element>

<xs:element name="supplier">
    <xs:complexType>
        <xs:sequence>
            <xs:element name="address" type="AddressType"/>
            <xs:element name="phone" type="xs:integer"/>
        </xs:sequence>
    </xs:complexType>
</xs:element>

The previous XSD definitions are shown graphically in Liquid XML Studio as follows

The advantage should be obvious, instead of having to define Address twice (once for Customer and once for Supplier) we have a single definition. This makes maintenance simpler i.e. if you decide to add "Line3" or "Postcode" elements to your address you only have to add them in one place.

Example XML

<Customer>
    <Dob> 2000-01-12T12:13:14Z </Dob>
    <Address>
        <Line1>34 thingy street, someplace</Line1>
        <Line2>sometown, w1w8uu </Line2>
        </Address>
</Customer>

<Supplier>
    <Phone>0123987654</Phone>
    <Address>
        <Line1>22 whatever place, someplace</Line1>
        <Line2>sometown, ss1 6gy </Line2>
        </Address>
</Supplier>

Note: Only complex types defined globally (as children of the <xs:schema> element can have their own name and be re-used throughout the schema). If they are defined inline within an <xs:element> they can not have a name (anonymous) and can not be reused elsewhere.

Attributes

An attribute provides extra information within an element. Attributes are defined within an XSD as follows, having name and type properties.

<xs:attribute name="x" type="y"/>

An Attribute can appear 0 or 1 times within a given element in the XML document. Attributes are either optional or mandatory (by default the are optional). The " use" property in the XSD definition is used to specify if the attribute is optional or mandatory.

So the following are equivalent

<xs:attribute name="ID" type="xs:string"/>
<xs:attribute name="ID" type="xs:string" use="optional"/>

The previous XSD definitions are shown graphically in Liquid XML Studio as follows

To specify that an attribute must be present, use = "required" (Note use may also be set to "prohibited", but we'll come to that later).

An attribute is typically specified within the XSD definition for an element, this ties the attribute to the element. Attributes can also be specified globally and then referenced (but more about this later).

Sample XSD | Sample XML
<xs:element name="Order"> <xs:complexType> <xs:attribute name="OrderID" type="xs:int"/> </xs:complexType> </xs:element> | <Order OrderID="6"/> or <Order/>
<xs:element name="Order"> <xs:complexType> <xs:attribute name="OrderID" type="xs:int" use="optional"/> </xs:complexType> </xs:element> | <Order OrderID="6"/> or <Order/>
<xs:element name="Order"> <xs:complexType> <xs:attribute name="OrderID" type="xs:int" use="required"/> </xs:complexType> </xs:element> | <Order OrderID="6"/>

The default and fixed attributes can be specified within the XSD attribute specification (in the same way as they are for elements).

Mixed Element Content

So far we have seen how an element can contain data, other elements or attributes. Elements can also contain a combination of all of these. You can also mix elements and data. You can specify this in the XSD schema by setting the mixed property.

<xs:element name="MarkedUpDesc">
    <xs:complexType mixed="true">
        <xs:choice minoccurs="0" maxoccurs="unbounded">
            <xs:element name="Bold" type="xs:string" />
            <xs:element name="Italic" type="xs:string" />
        </xs:choice>
    </xs:complexType>
</xs:element>

A sample XML document could look like this.

<MarkedUpDesc>
    This is an <Bold>Example</Bold> of <Italic>Mixed</Italic> Content,
    Note there are elements mixed in with the elements data.
</MarkedUpDesc>


XSD Tutorial - Part 2 - Conventions & Recommendations
Send Feedback
Tutorials > W3C XSD Schema Tutorial > XSD Tutorial - Part 2 - Conventions & Recommendations

Glossary Item Box

This section covers conventions and recommendations, when designing your schemas.
  • When to use Elements or Attributes
  • Mixed Element Content
  • Conventions

When to use Elements or Attributes

There is often some confusion over when to use an element or an attribute. Some people say that elements describe data and attributes describe the meta data, another way to look at it, is that attributes are used for small pieces of data such as order id’s, but really it is personal taste that dictates when to use an attribute. Generally it is best to use a child element if the information feels like data. Some of the problems with using attributes are:

  • attributes cannot contain multiple values (child elements can)
  • attributes are not easily expandable (to incorporate future changes to the schema)
  • attributes cannot describe structures (child elements can)

lf you use attributes as containers for data, you end up with documents that are difficult to read and maintain. Try to use elements to describe data. What I am trying to say here is that metadata (data about data) should be stored as attributes, and that data itself should be stored as elements.

Mixed Element Content

Mixed content is something you should try to avoid as much as possible, it is used heavily on the web in the form of xHtml, but that has many limitations. It is difficult to parse and it can lead to unforeseen complexity in the resulting data. XML Data Binding has limitations associated with it making it difficult to manipulate such documents.

Conventions

  • All Element and attributes should use UCC camel case, e.g. (PostalAddress), avoid hyphens, spaces or other syntax.
  • Readability is more important than tag length. There is always a line to draw between document size and readability, wherever possible favor readability.
  • Try to avoid abbreviations and acronyms for element, attribute, and type names. Exceptions should be well known within your business area e.g. ID (Identifier), and POS (Point of Sale).
  • Postfix new types with the name 'Type'. e.g. AddressType, USAddressType.
  • Enumerations should use names not numbers, and the values should be UCC camel case.
  • Names should not include the name of the containing structure, e.g. CustomerName, should be Name within the sub element Customer.
  • Only produce complexTypes or simpleTypes for types that are likely to be re-used. If the structure only exists in one place define it inline with an anonymous complexType.
  • Avoid the use of mixed content.
  • Only define root level elements if the element is capable of being the root element in an XML document.
  • Use consistent name space aliases
    xml (defined in XML standard)
    xmlns (defined in Name spaces in XML standard)
    xs http://www.w3.org/2001/XMLSchema
    xsi http://www.w3.org/2001/XMLSchema-instance
  • Try to think about versioning early on in your schema design. If its important for a new versions of a schema to be backwardly compatible, then all additions to the schema should be optional. If it is important that existing products should be able to read newer versions of a given document, then consider adding any and anyAttribute entries to the end of your definitions. See Versioning recommendations.
  • Define a targetNamespace in your schema, this better identifies your schema, and can make things easier to modularize and re-use.
  • Set elementFormDefault="qualified" in the schema element of your schema. This makes qualifying the name spaces in the resulting XML simpler (if not more verbose).


XSD Tutorial - Part 3 - Extending Existing Types
Send Feedback
Tutorials > W3C XSD Schema Tutorial > XSD Tutorial - Part 3 - Extending Existing Types

Glossary Item Box

It is often useful to be able to take the definition for an existing entity, and extend it to add more specific information. In most development languages we would call this inheritance or sub classing. The same concepts also exist in the XSD standard. This allows us to take an existing type definition and extend it. We can also restrict an existing type (although this behavior has no real parallel in most development languages).
  • Extending a ComplexType
  • Restricting an Existing ComplexType
  • Use of Extended/Restricted Types
  • Extending Simple Types (Union, List, Restriction)

Extending an Existing ComplexType

It is possible to take an existing <xs:complexType> and extend it. Lets see how this may be useful with an example.

Looking at the AddressType that we defined earlier (in part 1), lets assume our company has now gone international and we need to capture country specific addresses. In this case we need specific information for UK addresses (County and Postcode), and for US addresses (State and ZipCode).

So we can take our existing definition of address and extend it as follows

<xs:complexType name="UKAddressType">
    <xs:complexContent>
        <xs:extension base="AddressType">
            <xs:sequence>
                <xs:element name="County" type="xs:string"/>
                <xs:element name="Postcode" type="xs:string"/>
            </xs:sequence>
        </xs:extension>
    </xs:complexContent>
</xs:complexType>

<xs:complexType name="USAddressType">
    <xs:complexContent>
        <xs:extension base="AddressType">
            <xs:sequence>
                <xs:element name="State" type="xs:string"/>
                <xs:element name="Zipcode" type="xs:string"/>
            </xs:sequence>
        </xs:extension>
    </xs:complexContent>
</xs:complexType>
This is clearer when viewed graphically. But basically it is saying - we are defining a new <xs:complexType> called "USAddressType", this extended's the existing type "AddressType", and adds to it a sequence containing the elements "State", and "Zipcode".
There are 2 new things here the <xs:extension> element and the <xs:complexContent> element, we'll get to these shortly.

We can now use these new types as follows:

<xs:element name="UKAddress" type="UKAddressType"/>
<xs:element name="USAddress" type="USAddressType"/>

Some Sample XML for these elements may look like this.

<UKAddress>
        <Line1>34 thingy street</Line1>
 <Line2>someplace</Line2>
        <County>somerset/County>
   <Postcode>w1w8uu</Postcode>
</UKAddress>

or

<USAddress>
    <Line1>234 Lancaster Av</Line1>
 <Line2>Smallville</Line2>
       <State>Florida</State>
  <Zipcode>34543</Zipcode>
</USAddress>

The last example showed how to take an existing <xs:complexType> definition, and extend it to create new types. The new construct <xs:extension> indicates that we are extending an existing type, and specifies the type itself. But there is another option here, instead of adding to the type, we could restrict it.

Restricting an Existing ComplexType

Taking the same AddressType example, we can create a new type called "InternalAddressType". Lets assume "InternalAddressType" only needs Address->Line1.

 <xs:complexType name="InternalAddressType">
    <xs:complexContent>
      <xs:restriction base="AddressType">
        <xs:sequence>
          <xs:element name="Line1" type="xs:string" />
        </xs:sequence>
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

We are defining a new type "InternalAddressType". The <xs:restriction> element says we are restricting the existing type "AddressType" , and we are only allowing the existing child element "Line1" to be used in this new definition.
Note: Because we are restricting an existing type the only definitions that can appear in the <xs:restriction> are a sub set of the ones defined in the base type "AddressType". They must also be enclosed in the same compositor (in this case a sequence) and appear in the same order.

We can now use this new type as follows:

<xs:element name="InternalAddress" type="InternalAddressType"/>

Some Sample XML for this element may look like this.

<InternalAddressType>
        <Line1>Desk 4, Second Floor/<Line1>
</InternalAddressType>

Note: The <xs:complexContent> element is just a container for the extension or restriction - we can largely ignore it for now.

Use of Extended/Restricted Types

We have just shown how we can create new types based on existing one. This in itself is pretty useful, and will potentially reduce the amount of complexity in your schemas, making them easier to maintain and understand. However there is an aspect to this that has not yet been covered. In the above examples we created 3 new types (UKAddressType, USAddressType and InternalAddressType), all based on AddressType.

So, if we have an element that specifies its of type UKAddressType, then that is what must appear in the XML document.
But if an element specifies its of type "AddressType", then any of the 4 types can appear in the XML document (UKAddressType, USAddressType, InternalAddressType or AddressType).
The thing to consider now is, how will the XML parser know which type you meant to use, surely it needs to know otherwise it can not do proper validation?

Well, it knows because if you want to use a type other than the one explicitly specified in the schema (in this case AddressType) then you have to let the parser know which type your using. This is done in the XML document using the xsi:type attribute.

Lets look at an example.

  <xs:element name="Person">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Name" type="xs:string" />
        <xs:element name="HomeAddress" type="AddressType" />
      </xs:sequence>
    </xs:complexType>
  </xs:element>

This sample XML is the kind of thing you would expect to see.

<?xml version="1.0"?>
<Person>
    <Name>Fred</Name>
    <HomeAddress>
        <Line1>22 whatever place, someplace</Line1>
        <Line2>sometown, ss1 6gy </Line2>
    </HomeAddress>
</Person>

But the following is also valid.

<?xml version="1.0"?>
<Person xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Name>Fred</Name>
    <HomeAddress xsi:type="USAddressType">
         <Line1>234 Lancaseter Av</Line1>
        <Line2>SmallsVille</Line2>
      <State>Florida</State>
          <Zipcode>34543</Zipcode>
    </HomeAddress>
</Person>

Lets look at that in more detail.

  • We have added the attribute xsi:type="USAddressType" to the "HomeAddress" element. This tells the XML parser that the element actually contains data described by "USAddressType".
  • The xmlns:xsi attribute in the root element (Person) tells the XML parser that the alias xsi maps to the name space"http://www.w3.org/2001/XMLSchema-instance".
  • The xsi: part of the xsi:type attribute is a namespace qualifier. It basically says the attribute "type" is from the namespace aliased by "xsi" which was defined earlier to mean "http://www.w3.org/2001/XMLSchema-instance".
  • The "type" attribute in this namespace is an instruction to the XML Parser to tell it which definition to use to validate the element.

But more about namespace's in the next section.

Extending Simple Types

There are 3 ways in which a simpleType can be extended; Restriction, List or Union. The most common is Restriction, but we will cover the other 2 as well.

Restriction

Restriction is a way to constrain an existing type definition. We can apply a restriction to the built in data types xs:string, xs:integer, xs:date, etc or ones we create ourselves.

Here we are defining a restriction the existing type "string", we are applying a regular expression to it, to limit the values it can take.

<xs:simpleType name="LetterType">
    <xs:restriction base="xs:string">
        <xs:pattern value="[a-zA-Z]"/>
    </xs:restriction>
</xs:simpleType>
Shown graphically in Liquid XML Studio as follows
Let’s go through this line by line.
  1. A <simpleType> tag is used to define a our new type, we must give the type a unique name - in this case "LetterType"
  2. We are restricting an existing type - so the tag is <restriction> (you can also extend an existing type - but more about this later). We are basing our new type on a string so type="xs:string"
  3. We are applying a restriction in the form of a Regular expression, this is specified using the <pattern> element. The regular expression means the data must contain a single lower or upper case letter a through to z.
  4. closing tag for the restriction
  5. closing tag for the simple type

Restrictions may also be referred to as Facets. For a complete list see the XSD Standard, but to give you an idea, here are a few to get you started.

Overview

Syntax

Syntax explained

This specifies the minimum and maximum length allowed

Must be 0 or greater

<xs:minLength value="3">
<xs:maxLength value="8">

In this example the length must be between 3 and 8

The lower and upper range for numerical values

The value must be less than or equal to, greater than or equal to

<xs:minInclusive value="0">
<xs:maxInclusive value="10">

The value must be between 0 and 10

The lower and upper range for numerical values

The value must be less than or greater than

<xs:minExclusive value="0">
<xs:maxExclusive value="10">

The value must be between 1 and 9

The exact number of characters allowed

<xs:length value="30">

The length must not be more than 30

Exact number of digits allowed

<xs:totalDigits value="9">

Can not have more than 9 digits

A list of values allowed

 <xs:enumeration value="Hippo"/> <xs:enumeration value="Zebra"/> <xs:enumeration value="Lion"/>

The only permitted values are Hippo, Zebra or Lion

The number of decimal places allowed (must be >= 0)

<xs:fractionDigits value="2"/>

The value has to be to 2 d.p.

This defines how whitespace will be handled. Whitespace is line feeds, carriage returns, tabs, spaces, etc.

 <xs:whitespace value= "preserve"/>
<xs:whitespace value= "replace"/>
<xs:whitespace value= "collapse"/>

Preserve - Keeps whitespaces
Replace - Replaces all whitespace with a space
Collapse - Replaces whitespace characters with a space, then if there are multiple spaces together then they will be reduced to one space.
Pattern determines what characters are allowed and in what order. These are regular expressions and there is a complete list at: http://www.w3.org/TR/xmlschema-2/#regexs

<xs:pattern value="[0-999]"/>

[0-999] - 1 digit only between 0 and 999

[0-99][0-99][0-99] - 3 digits all have to be between 0 and 99

[a-z][0-10][A-Z] - 1st digit has to be between a and z and 2nd digit has to be between 0 and 10 and the 3rd digit is between A and Z. These are case sensitive.

[a-zA-Z] - 1 digit that can be either lower or uppercase A – Z

[123] - 1 digit that has to be 1, 2 or 3

([a-z])* - Zero or more occurrences of a to z

([q][u])+ - Looking for a pair letters that satisfy the criteria, in this case a q followed by a u

([a-z][0-999])+ - As above, looking for a pair where the 1st digit is lowercase and between a and z, and the 2nd digit is between 0 and 999, for example a1, c99, z999, f45

[a-z0-9]{8} - Must be exactly 8 characters in a row and they must be lowercase a to z or number 0 to 9.

It is important to note that not all facets are valid for all data types - for example, maxInclusive has no meaning when applied to a string. For the combinations of facets that are valid for a given data type refer to the XSD standard.

Union

A union is a mechanism for combining 2 or more different data types into one.

The following defines 2 simple types "SizeByNumberType" all the positive integers up to 21 (e.g. 10, 12, 14), and "SizeByStringNameType" the values small, medium and large.

<xs:simpleType name="SizeByNumberType">
    <xs:restriction base="xs:positiveInteger">
        <xs:maxInclusive value="21"/>
    </xs:restriction>
</xs:simpleType>

<xs:simpleType name="SizeByStringNameType">
    <xs:restriction base="xs:string">
        <xs:enumeration value="small"/>
        <xs:enumeration value="medium"/>
        <xs:enumeration value="large"/>
    </xs:restriction>
</xs:simpleType>

We can then define a new type called "USClothingSizeType", we define this as a union of the types "SizeByNumberType" and "SizeByStringNameType" (although we can add any number of types, including the built in types - separated by whitespace).

<xs:simpleType name="USClothingSizeType">
    <xs:union memberTypes="SizeByNumberType SizeByStringNameType" />
</xs:simpleType>

This means the type can contain any of the values that the 2 members can take (e.g. 1, 2, 3, ...., 20, 21, small, medium, large).

This new type can then be used in the same way as any other <xs:simpleType>

List

A list allows the value (in the XML document) to contain a number of valid values separated by whitespace.

A List is constructed in a similar way to a Union. The difference being that we can only specify a single type. This new type can contain a list of values that are defined by the itemType property. The values must be whitespace separated. So a valid value for this type would be "5 9 21".

<xs:simpleType name="SizesinStockType">
    <xs:list itemType="SizeByNumberType" />
</xs:simpleType>


XSD Tutorial - Part 4 - Namespaces
Send Feedback
Tutorials > W3C XSD Schema Tutorial > XSD Tutorial - Part 4 - Namespaces

Glossary Item Box

Namespaces

So far we have glossed over namespaces entirely, we will hopefully address this a little now. Firstly the full namespacing rules are rather complicated, so this will just be an overview. If your working with a schema that makes use of namespaces then XML Data Binding will save you a great deal of time as it takes this complexity away. If you're not using a data binding tool then you may want to refer to the XSD standard or purchase a book!

Namespaces are a mechanism for breaking up your schemas. Up until now we have assumed that you only have a single schema file containing all your element definitions, but the XSD standard allows you to structure your XSD schemas by breaking them into multiple files. These child schemas can then be included into a parent schema.

Breaking schemas into multiple files can have several advantages. You can create re-usable definitions that can used across several projects. They make definitions easier to read and version as they break down the schema into smaller units that are simpler to manage.

In this example, the schema is broken out into 4 files.

  • CommonTypes - this could contain all your basic types, AddressType, PriceType, PaymentMethodType etc.
  • CustomerTypes - this could contain all your definitions for your customers.
  • OrderTypes - this could contain all your definitions for orders.
  • Main - this would pull all the sub schemas together into a single schema, and define your main element/s.

This all works fine without namespaces, but if different teams start working on different files, then you have the possibility of name clashes, and it would not always be obvious where a definition had come from. The solution is to place the definitions for each schema file within a distinct namespace.

We can do this by adding the attribute targetNamespace into the schema element in the XSD file, i.e.:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           targetNamespace="myNamespace">
   ...
</xs:schema>

The value of targetNamespace is just a unique identifier, typically companies use there url followed by something to qualify it. In principle the namespace has no meaning, but some companies have used the url where the schema is stored, as the targetNamespace and so some XML parsers will use this as a hint path for the schema e.g.: targetNamespace="http://www.microsoft.com/CommonTypes.xsd", but the following would be just as valid targetNamespace="my-common-types".

Placing the targetNamespace attribute at the top of your XSD schema means that all entities defined in it are part of this namespace. So in our example above each of the 4 schema files could have a distinct targetNamespace value.

Lets look at them in detail.

CommonTypes.xsd

<?xml version="1.0" encoding="utf-16"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<xs:schema targetNamespace="http://NamespaceTest.com/CommonTypes"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified">

  <xs:complexType name="AddressType">
    <xs:sequence>
      <xs:element name="Line1" type="xs:string" />
      <xs:element name="Line2" type="xs:string" />
    </xs:sequence>
  </xs:complexType>

  <xs:simpleType name="PriceType">
    <xs:restriction base="xs:decimal">
      <xs:fractionDigits value="2" />
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="PaymentMethodType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="VISA" />
      <xs:enumeration value="MasterCard" />
      <xs:enumeration value="Cash" />
      <xs:enumeration value="Amex" />
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

This schema defines some basic re-usable entities and types.
The use of the targetNamespace attribute in the <xs:schema> element ensures all the enclosed definitions (AddressType, PriceType and PaymentMethodType) are all in the namespace "http://NamespaceTest.com/CommonTypes".

CustomerTypes.xsd

<?xml version="1.0" encoding="utf-16"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<xs:schema     xmlns:cmn="http://NamespaceTest.com/CommonTypes"
               targetNamespace="http://NamespaceTest.com/CustomerTypes"
               xmlns:xs="http://www.w3.org/2001/XMLSchema"
               elementFormDefault="qualified">
    <xs:import schemaLocation="CommonTypes.xsd"
               namespace="http://NamespaceTest.com/CommonTypes"/>
  <xs:complexType name="CustomerType">
    <xs:sequence>
      <xs:element name="Name" type="xs:string" />
      <xs:element name="DeliveryAddress" type="cmn:AddressType" />
      <xs:element name="BillingAddress" type="cmn:AddressType" />
    </xs:sequence>
  </xs:complexType>
</xs:schema>

This schema defines the entity CustomerType, which makes use of the AddressType defined in the CommonTypes.xsd schema. We need to do a few things in order to use this.
First we need to import that schema into this one - so we can see it. This is done using <xs:import>.
It is worth noting the presence of the targetNamespace attribute at this point. This means that all entities defined in this schema belong to the namespace "http://NamespaceTest.com/CustomerTypes".
So in order to make use of the AddressType which is defined in CustomerTypes.xsd, and part of the namespace "http://NamespaceTest.com/CommonTypes", we must fully qualify it. In order to do this we must define an alias for the namespace "http://NamespaceTest.com/CommonTypes". Again this is done using <xs:schema>.
The line xmlns:cmn="http://NamespaceTest.com/CommonTypes" specifies that the alias cmn represents the namespace "http://NamespaceTest.com/CommonTypes".
We can now make use of the types within the CommonTypes.xsd schema. When we do this we must fully qualify them as they are not in the same targetNamespace as the schema that is using them. We do this as follows: type="cmn:AddressType".

OrderType.xsd

<?xml version="1.0" encoding="utf-16"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<xs:schema     xmlns:cmn="http://NamespaceTest.com/CommonTypes"
               targetNamespace="http://NamespaceTest.com/OrderTypes"
               xmlns:xs="http://www.w3.org/2001/XMLSchema"
               elementFormDefault="qualified">
    <xs:import namespace="http://NamespaceTest.com/CommonTypes"
               schemaLocation="CommonTypes.xsd" />
  <xs:complexType name="OrderType">
    <xs:sequence>
      <xs:element maxOccurs="unbounded" name="Item">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="ProductName" type="xs:string" />
            <xs:element name="Quantity" type="xs:int" />
            <xs:element name="UnitPrice" type="cmn:PriceType" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

This schema defines the type OrderType which is within the namespace http://NamespaceTest.com/OrderTypes.
The constructs used here are the same as those used in CustomerTypes.xsd.

Main.xsd

<?xml version="1.0" encoding="utf-16"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<xs:schema     xmlns:ord="http://NamespaceTest.com/OrderTypes"
               xmlns:pur="http://NamespaceTest.com/Purchase"
               xmlns:cmn="http://NamespaceTest.com/CommonTypes"
               xmlns:cust="http://NamespaceTest.com/CustomerTypes"
               targetNamespace="http://NamespaceTest.com/Purchase"
               xmlns:xs="http://www.w3.org/2001/XMLSchema"
               elementFormDefault="qualified">
        <xs:import schemaLocation="CommonTypes.xsd" namespace="http://NamespaceTest.com/CommonTypes" />
       <xs:import schemaLocation="CustomerTypes.xsd" namespace="http://NamespaceTest.com/CustomerTypes" />
   <xs:import schemaLocation="OrderTypes.xsd" namespace="http://NamespaceTest.com/OrderTypes" />
 <xs:element name="Purchase">
          <xs:complexType>
                      <xs:sequence>
                         <xs:element name="OrderDetail" type="ord:OrderType" />
                                <xs:element name="PaymentMethod" type="cmn:PaymentMethodType" />
                              <xs:element ref="pur:CustomerDetails"/>
                       </xs:sequence>
                </xs:complexType>
     </xs:element>
 <xs:element name="CustomerDetails" type="cust:CustomerType"/>
</xs:schema>

The elements in this schema are part of the namespace "http://NamespaceTest.com/Purchase" (see tagetNamespace attribute).
This is our main schema and defines the concrete elements "Purchase", and "CustomerDetails" .
This element builds on the other schemas, so we need to import them all, and define aliases for each namespace.
Note: The element "CustomerDetails" which is defined in main.xsd is referenced from within "Purchase".

The XML

Because the root element Purchase is in the namespace "http://NamespaceTest.com/Purchase", we must quantify the <Purchase> element within the resulting XML document. Lets look at an example:

<?xml version="1.0"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<p:Purchase xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://NamespaceTest.com/Purchase Main.xsd"
            xmlns:p="http://NamespaceTest.com/Purchase"
            xmlns:o="http://NamespaceTest.com/OrderTypes"
            xmlns:c="http://NamespaceTest.com/CustomerTypes"
            xmlns:cmn="http://NamespaceTest.com/CommonTypes">
   <p:OrderDetail>
               <o:Item>
                      <o:ProductName>Widget</o:ProductName>
                   <o:Quantity>1</o:Quantity>
                      <o:UnitPrice>3.42</o:UnitPrice>
         </o:Item>
     </p:OrderDetail>
      <p:PaymentMethod>VISA</p:PaymentMethod>
 <p:CustomerDetails>
           <c:Name>James</c:Name>
          <c:DeliveryAddress>
                   <cmn:Line1>15 Some Road</cmn:Line1>
                     <cmn:Line2>SomeTown</cmn:Line2>
         </c:DeliveryAddress>
          <c:BillingAddress>
                    <cmn:Line1>15 Some Road</cmn:Line1>
                     <cmn:Line2>SomeTown</cmn:Line2>
         </c:BillingAddress>
   </p:CustomerDetails>
</p:Purchase>

The first thing we see is the xsi:schemaLocation attribute in the root element. This tells the XML parser that elements within the namespace "http://NamespaceTest.com/Purchase" can be found in the file "Main.xsd" (Note the namespace and url are separated with whitespace - carriage return or space will do).

The next thing we do is define some aliases

  • "p" to mean the namespace "http://NamespaceTest.com/Purchase"
  • "c" to mean the namespace "http://NamespaceTest.com/CustomerTypes"
  • "o" to mean the namespace "http://NamespaceTest.com/OrderTypes"
  • "cmn" to mean the namespace "http://NamespaceTest.com/CommonTypes"

You have probably noticed that every element in the schema is qualified with one of these aliases.

The general rules for this are:

The alias must be the same as the target namespace in which the element is defined. It is important to note that this is where the element is defined - not where the complexType is defined.
So the element <OrderDetail> is actually defined in main.xsd so it is part of the namespace "http://NamespaceTest.com/Purchase", even though it uses the complexType "OrderType" which is defined in the OrderTypes.xsd. The contents of <OrderDetail> are defined within the complexType "OrderType", which is in the target namespace "http://NamespaceTest.com/OrderTypes", so the child element <Item> needs qualifying within the namespace "http://NamespaceTest.com/OrderTypes".

The Effect of elementFormDefault

You may have noticed that each schema contained an attribute elementFormDefault="qualified". This has 2 possible values, qualified, and unqualified, the default is unqualified. This attribute changes the namespacing rules considerably. It is normally easier to set it to qualified.

So to see the effects of this property, if we set it to be unqualified in all of our schemas, the resulting XML would look like this:

<?xml version="1.0"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<p:Purchase    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://NamespaceTest.com/Purchase Main.xsd"
               xmlns:p="http://NamespaceTest.com/Purchase">
    <OrderDetail>
        <Item>
            <ProductName>Widget</ProductName>
            <Quantity>1</Quantity>
            <UnitPrice>3.42</UnitPrice>
        </Item>
    </OrderDetail>
    <PaymentMethod>VISA</PaymentMethod>
    <p:CustomerDetails>
        <Name>James</Name>
        <DeliveryAddress>
            <Line1>15 Some Road</Line1>
            <Line2>SomeTown</Line2>
        </DeliveryAddress>
        <BillingAddress>
            <Line1>15 Some Road</Line1>
            <Line2>SomeTown</Line2>
        </BillingAddress>
    </p:CustomerDetails>
</p:Purchase>

This is considerably different from the previous XML document.

These general rules now apply:

  • Only root elements defined within a schema need qualifying with a namespace.
  • All types that are defined inline do NOT need to be qualified.

The first element is Purchase, this is defined globally in the Main.xsd schema, and therefore needs qualifying within the schemas target namespace "http://NamespaceTest.com/Purchase".

The first child element is <OrderDetail> and is defined inline in Main.xsd->Purchase. So it does not need to be aliased.

The same is true for all the child elements, they are all defined inline, so they do not need qualifying with a namespace.

The final child element <CustomerDetails> is a little different. As you can see we have defined this as a global element within the targetNamespace "http://NamespaceTest.com/Purchase". In the element "Purchase" we just reference it. Because we are using a reference to an element, we must take into account its namespace, thus we alias it <p:CustomerDetails>.

Summary

Namespaces provide a useful way of breaking schemas down into logical blocks, which can then be re-used throughout a company or project. The rules for namespacing in the resulting XML documents are rather complex, the rules provided here are a rough guide, things do get more complex as you dig further into it. For this reason tools to deal with these complexities are useful, see XML Data Binding.


XSD Tutorial - Part 5 - Other Useful Bits
Send Feedback
Tutorials > W3C XSD Schema Tutorial > XSD Tutorial - Part 5 - Other Useful Bits

Glossary Item Box

This section covers a few of the lesser used constructs:
  • Element and Attribute Groups
  • any (Element)
  • anyAttribute

Element and Attribute Groups

Elements and Attributes can be grouped together using <xs:group> and <xs:attributeGroup>. These groups can then be referred to elsewhere within the schema. Groups must have a unique name and be defined as children of the <xs:schema> element. When a group is referred to, it is as if its contents have been copied into the location it is referenced from.

Note: <xs:group> and <xs:attributeGroup> can not be extended or restricted in the way <xs:complexType> or <xs:simpleType> can. They are purely to group a number of items of data that are always used together. For this reason they are not the first choice of constructs for building reusable maintainable schemas, but they can have their uses.

  <xs:group name="CustomerDataGroup">
    <xs:sequence>
      <xs:element name="Forename" type="xs:string" />
      <xs:element name="Surname" type="xs:string" />
      <xs:element name="Dob" type="xs:date" />
    </xs:sequence>
  </xs:group>

  <xs:attributeGroup name="DobPropertiesGroup">
    <xs:attribute name="Day" type="xs:string" />
    <xs:attribute name="Month" type="xs:string" />
    <xs:attribute name="Year" type="xs:integer" />
  </xs:attributeGroup>

These groups can then be referenced in the definition of complex types, as shown below.

<xs:complexType name="Customer">
    <xs:sequence>
        <xs:group ref="CustomerDataGroup"/>
        <xs:element name="..." type="..."/>
    </xs:sequence>
    <xs:attributeGroup ref="DobPropertiesGroup"/>
</xs:complexType>

The <any> Element

The <xs:any> construct allows us specify that our XML document can contain elements that are not defined in this schema. A typical use for this is when you define a message envelope. For example, the message payload is unknown to the system, but we can still validate the message.

Look at the following schema:

  <xs:element name="Message">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="DateSent" type="xs:date" />
        <xs:element name="Sender" type="xs:string" />
        <xs:element name="Content">
          <xs:complexType>
            <xs:sequence>
              <xs:any />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
We have defined an element called "Message", which must have a "DateSent" child element (which is a date), a "Sender" child element (which must be a string), and a "Content" child element - which can contain any element - it doesn't even have to be described in the schema.
So the following XML would be acceptable.
<Message>
   <DateSent>2000-01-12</DateSent>
 <Sender>Admin</Sender>
  <Content>
             <AccountCreationRequest>
                      <AccountName>Fred</AccountName>
         </AccountCreationRequest>
    </Content>
</Message>

The <xs:any> construct has a number of properties that can further restrict what can be used in its place.

minOccurs and maxOccurs allows you to specify how may instances of undefined elements must be placed within the XML document.

namespace allows you to specify which that the undefined element must belong to the a given namespace. This may be a list of namespace's (space separated). There are also 3 built in values ##any, ##other, ##targetnamespace, ##local. Consult the XSD standard for more information on this.

processContents tells the XML parser how to deal with the unknown elements. The values are:

  • Skip - no validation is performed - but it must be well formed XML.
  • Lax - if there is a schema to validate the element, then it must be valid against it, if there is no schema, then that's OK.
  • Strict - There must be a definition for the element available to the parser, and it must be valid against it.

The <anyAttribute>

<xs:anyAttribute> works in exactly the same way as <xs:any>, except it allows unknown attributes to be inserted into a given element.

        <xs:element name="Sender">
          <xs:complexType>
            <xs:simpleContent>
              <xs:extension base="xs:string">
                <xs:anyAttribute />
              </xs:extension>
            </xs:simpleContent>
          </xs:complexType>
        </xs:element>

This would mean that we can add any attributes we like to the Sender element, and the XML document would still be valid

<Sender ID="7687">Fred</Sender>


Creating Your First Schema Using Liquid XML Studio
Send Feedback
Tutorials > Liquid XML Studio Tutorials > Creating Your First Schema Using Liquid XML Studio

Glossary Item Box

Creating and using an XML Schema

Why do I need a schema

A schema is a formal description of your data. It is good practice to have an XML schema to describe any XML data that you intend to share, be that with another company, or with the guy sitting next to you.

Without one your just building up problems for the future, and as we all know problems that are fixed early cost less in time, money and hair.

So what does it actually give you.

  • A formal definition of your data - not a woolly document, which can be interpreted, this is a rock solid description.
    If you've ever sent a specification off to a 3rd party, then tried to reconcile their interpretation with what you were expecting, then you'll understand. You'll get additional data creeping in because they wanted to add stuff, things are missing because they didn't understand bits.
    If you have a schema then there is none of that. If it's not valid against the schema then we are not interested in it, you can then put the onus back on them to make it correct.
  • Validation - You can take an XML document, and check that it complies with your schema. In fact, validators are now so fast that many companies will not allow data into there process flows unless its valid against the schema. This entry point validation ensures that all data moving through the system is valid, and massively lowers the overhead caused by invalid messages.
  • Less Error Handling – If you validate your XML before making use of it, then you can make more assumptions about it, which reduces the amount of error handling/checking you have to do. This is not to say you can write sloppy code, but you don’t have to re-invent the wheel and effectively hard code the validation performed by the XSD Validator.
  • Centralises Documentation – Your documentation for the schema can be placed within the schema itself. There are <annotation> tags which allow you to add human and machine readable comments into the schema. There are a number of tools for editing these annotations, including XML Studio.
  • Machine readable – Because your schema is machine readable, it can be used by a number of different tools.
    You can produce pretty documentation from it, complete with diagrams and the documentation you painstakingly added.
    You can generate code from it. Code that will read and write your XML documents making it even easier to work with.
    XML Editors can use the schema to provide intellisense when your editing your XML (even making use of the embedded documentation).

So you can either, create some XML, put a woolly document together that describes it, manually adding some hand drawn diagrams to show its structure. Then re-code all the validation rules you described in your document, before you even start to use the XML.

Or

You can write an XML Schema, add documentation into it as you go, generate some pretty documentation from it which you can put on the internet/intranet. When it comes to coding, you just run your XML through the Validator before your code even looks at it, if it isn’t valid, just send it back.

Putting the cart before the horse

Its good practice to think about your data before you design your schema, but things normally happen the other way around, we have some data, and we want to retro fit a schema to it.
So lets look at some data.

Sample XML File Used in this Example (SalesCatalogue.xml) Copy Code
<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<SalesCatalogue>
 <Product>
  <Name>Transformers T-Shirt</Name>
  <Description>
    This Transformers Autobot T-shirt is black and made from 100% cotton.
    The distressed image featured on the front of this t-shirt is of the Transformers Autobot.
  </Description>
  <Price>17.95</Price>
  <ProductCode>52-2436556</ProductCode>
  <Size>XL</Size>
 </Product>
</SalesCatalogue>
Sample XSDFile Used in this Example (SalesCatalogue.xsd) Copy Code
 <?xml version="1.0" encoding="utf-8" ?>
<!--Created with Liquid XML Studio (https://www.liquid-technologies.com)-->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" >
    <xs:element name="SalesCatalogue">
        <xs:complexType>
            <xs:sequence>
                <xs:element minOccurs="0" maxOccurs="unbounded" name="Product">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element name="Name" type="xs:string"/>
                            <xs:element name="Description" type="xs:string"/>
                            <xs:element name="Price" type="xs:string"/>
                            <xs:element name="ProductCode" type="xs:string"/>
                            <xs:element name="Size">
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:enumeration value="XXXL"/>
                                        <xs:enumeration value="XXL"/>
                                        <xs:enumeration value="XL"/>
                                        <xs:enumeration value="L"/>
                                        <xs:enumeration value="M"/>
                                        <xs:enumeration value="S"/>
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

We'll start by just building a schema for the XML above.

Step 1: One Liquid XML Studio

Liquid XML Studio Desktop Icon

Step 2: Create a new Schema.

Menu (New->File...)

Liquid XML Studio - File New

Select 'W3C XML Schema'.

Liquid XML Studio - New File Selection

Step 3: Add an element to the schema.

Right click on the "Schema Root" node, Menu (Add Child->Element)

A new element node should appear, set the name in the focused text box ("SalesCatalogue").

Step 4: Add a sequence to the 'SalesCatalogue' node

Right click on the 'SalesCatalogue' node and select the menu (Add Child->Sequence).
A Sequence is a container for other child elements, there are 2 other containers choice and all.

Step 5: Add an element to the sequence

Right click on the sequence [image] and select the menu (Add Child->Element).

Give the element the name 'Product'.

Step 6: Change the Cardinality

We want to allow lots of product elements to be present in the SalesCatalogue. To do this we can change the cardinality.

Right click on the 'product' node and select the menu (Cardinality->0..unbounded).

Step 7: Add a sequence to 'Product'

Repeat step 4 for the 'Product' node

Step 8: Add a name element to products sequence

Add a new element to the sequence attached to product, name it "Name" (see step 3).

The previous elements we have created have been containers for other child elements (i.e. 'SalesCatalogue' contains 0 or more 'Product' elements). We are now defining an element that can only contain data, in this case text.

Select the type portion of the node, on the right (contains the text '<None>'), and select from the list (or type in) 'string'.

There are a number of different built in data types which you can use, you can also define your own (See Simple Types)

Short cut, when editing the elements name, you can press 'Tab' to move to the type list.

Step 9: Add more data elements

Add the following elements in the same way as step 8.

  • 'Description' of type 'string'
  • 'Price' of type 'double'
  • 'ProductCode' of type 'string'
  • 'Size' of type 'string'

Step 10: Restrict the values for 'Size'

We may want tot element 'Size' to have a limited range of values. We can do this by setting the enumeration property.

Select the 'Size' node.

Go to the properties window (it may be hidden or closed, use the Menu (View->Properties), or F4 to make it visible).

Select the 'Enumeration' entry, and click the '...' button that appears

Add all the allowable values (one per line).

Step 11: Save your schema

Select the menu item (File->Save) or Ctrl-S. Name the schema 'SalesCatalogue.xsd'

Using your Schema

You can now make use of your schema to validate your XML document.

Step 1: Create an XML document.

Liquid XML Studio - File New Menu

Liquid XML Studio - New XML Files

Step 2: Create your XML Document

Cut and paste the xml code at the beginning of the page into the editor.

Liquid XML Studio - New XML File

Step 3: Performing validation.

The editor will automatically validate the document. However, as the editor does not know about the schema, it can not check that the data is correct (only well formed; all tag are paired and closed).

You can see that the editor has not associated a schema with the properties in the tool bar

Schema Mapping for XML Document

Step 4: Associating a schema with the document

You can set the schema that is associated with this XML document using the Validation Options Button ( Validation Options Button).

Liquid XML Studio - Schema Selection Dialog

Find your schema in the list (if it is not there use the 'Add' button). Then change the Use property to 'Use this Schema' ( Select the schema).

Now when you return to the editor you can see that your schema is associated with the document.

The validation rules for a given XML file are recorded, so when the XML file is re-loaded its associations are kept.

Step 4: Validating

Now when the validation is performed, the editor can also validate against the schema. As this document is valid you will see no errors.

Lets change things a little so it becomes invalid.

Change the value of Size from 'XL' to 'Big'.

Because the 'Size' element has a restriction on it (it can only be one of the enumerated values specified), the value 'Big' will make it invalid.

Now you should see a validation error appear in the Errors Tool Window (Press Ctrl-E, if it is not visible).

Note: double clicking on the error in the Error list will take you to the problem in the XML.

Step 5: Intellisense

Another advantage of associating a schema with your XML is you can now make use of intellisense. You will now get presented with the valid options when you start creating and element or attribute.

The formal way to associate a schema with an XML document is to use the schemaLocation an noNamespaceSchemaLocation attributes.


Creating Your First Schema Using Visual Studio Extension
Send Feedback
Tutorials > Liquid XML Studio Tutorials > Creating Your First Schema Using Visual Studio Extension

Glossary Item Box

Creating and using an XML Schema

Why do I need a schema

A schema is a formal description of your data. It is good practice to have an XML schema to describe any XML data that you intend to share, be that with another company, or with the guy sitting next to you.

Without one your just building up problems for the future, and as we all know problems that are fixed early cost less in time, money and hair.

So what does it actually give you.

  • A formal definition of your data - not a woolly document, which can be interpreted, this is a rock solid description.
    If you've ever sent a specification off to a 3rd party, then tried to reconcile their interpretation with what you were expecting, then you'll understand. You'll get additional data creeping in because they wanted to add stuff, things are missing because they didn't understand bits.
    If you have a schema then theirs none of that. If its not valid against the schema then were not interested in it, you can then put the onus back on them to make it right
  • Validation - You can take an XML document, and check that it complies with your schema. In fact validators are now so fast that many companies will not allow data into there process flows unless its valid against the schema. This entry point validation ensures that all data moving through the system is valid, and massively lowers the overheads caused by invalid messages.
  • Less Error Handling – If you validate your XML before making use of it, then you can make more assumptions about it, which reduces the amount of error handling/checking you have to do. This is not to say you can write sloppy code, but you don’t have to re-invent the wheel and effectively hard code the validation performed by the XSD Validator.
  • Centralises Documentation – Your documentation for the schema can be placed within the schema itself. There are <annotation> tags which allow you to add human and machine readable comments into the schema. There are a number of tools for editing these annotations, including XML Studio.
  • Machine readable – Because your schema is machine readable, it can be used by a number of different tools.
    You can produce pretty documentation from it, complete with diagrams and the documentation you painstakingly added.
    You can generate code from it. Code that will read and write your XML documents making it even easier to work with.
    XML Editors can use the schema to provide intellisense when your editing your XML (even making use of the embedded documentation).

So you can either, create some XML, put a woolly document together that describes it, manually adding some hand drawn diagrams to show its structure. Then re-code all the validation rules you described in your document, before you even start to use the XML.

Or

You can write an XML Schema, add documentation into it as you go, generate some pretty documentation from it which you can put on the internet/intranet. When it comes to coding, you just run your XML through the Validator before your code even looks at it, if it isn’t valid, just send it back.

Putting the cart before the horse

Its good practice to think about your data before you design your schema, but things normally happen the other way around, we have some data, and we want to retro fit a schema to it.
So lets look at some data.

Sample XML File Used in this Example (SalesCatalogue.xml) Copy Code
<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<SalesCatalogue>
 <Product>
  <Name>Transformers T-Shirt</Name>
  <Description>
    This Transformers Autobot T-shirt is black and made from 100% cotton.
    The distressed image featured on the front of this t-shirt is of the Transformers Autobot.
  </Description>
  <Price>17.95</Price>
  <ProductCode>52-2436556</ProductCode>
  <Size>XL</Size>
 </Product>
</SalesCatalogue>
Sample XSDFile Used in this Example (SalesCatalogue.xsd) Copy Code
 <?xml version="1.0" encoding="utf-8" ?>
<!--Created with Liquid XML Studio (https://www.liquid-technologies.com)-->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" >
    <xs:element name="SalesCatalogue">
        <xs:complexType>
            <xs:sequence>
                <xs:element minOccurs="0" maxOccurs="unbounded" name="Product">
                    <xs:complexType>
                        <xs:sequence>
                            <xs:element name="Name" type="xs:string"/>
                            <xs:element name="Description" type="xs:string"/>
                            <xs:element name="Price" type="xs:string"/>
                            <xs:element name="ProductCode" type="xs:string"/>
                            <xs:element name="Size">
                                <xs:simpleType>
                                    <xs:restriction base="xs:string">
                                        <xs:enumeration value="XXXL"/>
                                        <xs:enumeration value="XXL"/>
                                        <xs:enumeration value="XL"/>
                                        <xs:enumeration value="L"/>
                                        <xs:enumeration value="M"/>
                                        <xs:enumeration value="S"/>
                                    </xs:restriction>
                                </xs:simpleType>
                            </xs:element>
                        </xs:sequence>
                    </xs:complexType>
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

We'll start by just building a schema for the XML above.

Step 1: One Microsoft Visual Studio

Step 2: Create a new Schema.

Menu (New->File...)

Select 'XML Schema (XSD)' under the 'Liquid XML Schema Editor' Category.

Step 3: Add an element to the schema.

Right click on the "Schema Root" node, Menu (Add Child->Element)

A new element node should appear, set the name in the focused text box ("SalesCatalogue").

Step 4: Add a sequence to the 'SalesCatalogue' node

Right click on the 'SalesCatalogue' node and select the menu (Add Child->Sequence).
A Sequence is a container for other child elements, there are 2 other containers choice and all.

Step 5: Add an element to the sequence

Right click on the sequence [image] and select the menu (Add Child->Element).

Give the element the name 'Product'.

Step 6: Change the Cardinality

We want to allow lots of product elements to be present in the SalesCatalogue. To do this we can change the cardinality.

Right click on the 'product' node and select the menu (Cardinality->0..unbounded).

Step 7: Add a sequence to 'Product'

Repeat step 4 for the 'Product' node

Step 8: Add a name element to products sequence

Add a new element to the sequence attached to product, name it "Name" (see step 3).

The previous elements we have created have been containers for other child elements (i.e. 'SalesCatalogue' contains 0 or more 'Product' elements). We are now defining an element that can only contain data, in this case text.

Select the type portion of the node, on the right (contains the text '<None>'), and select from the list (or type in) 'string'.

There are a number of different built in data types which you can use, you can also define your own (See Simple Types)

Short cut, when editing the elements name, you can press 'Tab' to move to the type list.

Step 9: Add more data elements

Add the following elements in the same way as step 8.

  • 'Description' of type 'string'
  • 'Price' of type 'double'
  • 'ProductCode' of type 'string'
  • 'Size' of type 'string'

Step 10: Restrict the values for 'Size'

We may want tot element 'Size' to have a limited range of values. We can do this by setting the enumeration property.

Select the 'Size' node.

Go to the properties window (it may be hidden or closed, use the Menu (View->Properties), or F4 to make it visible).

Select the 'Enumeration' entry, and click the '...' button that appears

Add all the allowable values (one per line).

Step 11: Save your schema

Select the menu item (File->Save) or Ctrl-S. Name the schema 'SalesCatalogue.xsd'

Using your Schema

You can now make use of your schema to validate your XML document.

Step 1: Create an XML document.

Step 2: Create your XML Document

Cut and paste the xml code at the beginning of the page into the editor.

Step 3: Performing validation.

The editor will automatically validate the document. However, as the editor does not know about the schema, it can not check that the data is correct (only well formed; all tag are paired and closed).

You can see that the editor has not associated a schema with the properties in the tool bar

Step 4: Associating a schema with the document

If you edit the 'Schemas' property by clicking on the '...' button, then you can change the schema that is associated with this XML document.

Find your schema in the list (if it is not there use the 'Add' button). Then change the Use property to 'Use this Schema'.

Now when you return to the editor you can see that your schema is associated with the document.

Step 4: Validating

Now when the validation is performed, the editor can also validate against the schema. As this document is valid you will see no errors.

Lets change things a little so it becomes invalid.

Change the value of Size from 'XL' to 'Big'.

Because the 'Size' element has a restriction on it (it can only be one of the enumerated values specified), the value 'Big' will make it invalid.

Now you should see a validation error appear in the Errors Tool Window (Press Ctrl-W,E, if it is not visible).

Note: double clicking on the error in the Error list will take you to the problem in the XML.

Step 5: Intellisense

Another advantage of associating a schema with your XML is you can now make use of intellisense. You will now get presented with the valid options when you start creating and element or attribute.

The formal way to associate a schema with an XML document is to use the schemaLocation an noNamespaceSchemaLocation attributes.


Getting Started
Send Feedback
Tutorials > Liquid Data Mapper > Getting Started

Glossary Item Box

A new transform can be created using the File->New menu, and selecting the Data Mapper icon.

Create New Data Mapper Files

When constructing a Data Transformation its often easier to start with the output component and work back.

The XML output component can be found in the Component Palette (If its not visible it can be displayed by selecting it in the View Menu"), and can be added to the data mapper canvas by dragging it on.

XML Data Target

The XML Data Target loads its meta data (i.e. a description of the output document) from an XML Schema (XSD). If you don't have an XSD then its possible to infer one from one or more sample XML files which represent the output data you are trying to create. You could also create or modify a schema using the built in XSD Editor.

When XML Data Target is dropped on the data mapper canvas it starts a wizard which will capture all the data required to configure the new XML Data Target, we will use the Bookstore.xsd sample located in C:\Program Files\Liquid Technologies\Liquid XML Studio 2018\Examples\BookStore, the output file will be written to C:\Program Files\Liquid Technologies\Liquid XML Studio 2018\Examples\BookStore\HorrorBooks.xml.

You should supply an output file for it to write its output to. This can be done within the transform itself, but typically you would do this when creating the XML Data Target.

Once you have completed the wizard you will see the new component on the canvas. You will notice its inputs are taken from the structure of the XSD schema you provided as an input.

Now we can think about where to get our input data from. The XML Data Source component will allow us to read data from an XML file. Again we can create one by dragging an XML Data Source from the Component Palette. The XML Data Source component also gets its meta data (i.e. a description of the input document) from an XML Schema (or can be inferred from XML documents). Again we will use the Bookstore.xsd in this example. The reader also needs an input data file, we will use C:\Program Files\Liquid Technologies\Liquid XML Studio 2011\Examples\BookStore\BookStoreSample.xml.

The XML Data Source requires an input filename, this can be done within the transform itself using the Filename input connector, but typically you would set it when creating the XML Data Source in the wizard.

To start with we can connect all the input and output connection points together, this will mirror the input data in the output (not much of a transform, be we can see how things work).

The connection point hit area includes its text, so its easier to drag the connection point by clicking and dragging from its text

Data Mapper Pass Through

Pressing Shift-F5 ( Execute) will execute the transform and display the results.

Pressing F5 ( Debug) will start the debugger, we can then step through the transform seeing the way the transform is executed and watching the data move around. This gives some incite into how the transformation engine works, and understanding unexpected results easier to get to grips with.

Now we can look at making the transform do something useful, we will apply a simple filter to the data, only selecting books in the "Horror" genre.

Drag a Filter onto the canvas (in the "Set" section) and connect its "Nodes" input to the "book" output, this gives the Filter its context, i.e. its operating within the context of each book. Connect the Filters "Result" output back to the "book" input connection point on the output component. If the Filters "bool" input receives a true value then the current book object will be output via the "Result", otherwise its discarded.

Drag on an Equals component (in the Equality section) and connect its "result" to the filters "bool" input. Connect one of its inputs to the XML Sources "genre" output.

Drag on a Constant component (in the Constant section) set its type to be String and its value to be Horror (right click on it and select "Properties"). Connect its "Value" connector to the other input on the Equals component.

When we run the transform it now filters the input books only returning ones that contain a genre which equals "Horror".

XML" data-itemid="XML" data-title="XML">
The transform output Copy Code
<bookstore xmlns="https://www.liquid-technologies.com/sample/bookstore">
    <book price="4.99" publicationdate="2008-10-20T00:00:00Z" ISBN="978-0747596837">
        <title>The Graveyard Book</title>
        <author>
            <first-name>Neil</first-name>
            <last-name>Gaiman</last-name>
        </author>
        <genre>Horror</genre>
    </book>
</bookstore>

Lets look at what we have created, and how it runs. First off start the debugger (F5 Debug) and step through the transform (F-11 Step into) you'll notice that things run from right to left. Values are requested from a component, which triggers the component to pull values from its child inputs.


Properties Window
Send Feedback
User Interface Guide > Tool Windows > Properties Window

Glossary Item Box

The content of this panel is context sensitive.

XSD Editor

When the XSD Editor is the selected view, then this panel shows the properties for the selected graphical entity.

Only properties that are applicable to the current state of the object are shown.

For more information about specific properties see Diagram Notation.


Project Window
Send Feedback
User Interface Guide > Tool Windows > Project Window

Glossary Item Box

This panel shows the contents of the current project. The project contains groups of files which can be opened by double-clicking or from the right-click context menu. When an item in the project tree is selected, its related properties can be seen in the Properties Window.

Projects are useful when you have a large number of related schema and xml documents. The default groups are Documents, Output, Schema and Transforms, but any number of groups can be added and the defaults can be removed using the right-click context menu.

The groups are for convenience only and have no effect on file paths.

The Project properties include the option to make all paths absolute (the default) or relative to the project file. Making the paths relative is useful if the files reside in sub directories of the project folder as it enables the entire tree to be moved. Use absolute paths is useful if your project files reside outside of the project folder.


Error Window
Send Feedback
User Interface Guide > Tool Windows > Error Window

Glossary Item Box

This window shows a list of all the errors that have occurred within the currently selected document.
Double clicking on a given line will take you to the error.


Output Window
Send Feedback
User Interface Guide > Tool Windows > Output Window

Glossary Item Box

Liquid XML Studio Output Window

The output window is used by a number of tools and editors to display the output of the active process.

It can display the output from an number of different tools simultaneously, in which case a list of active output sources appears at the top of the window (an example of this is the output of an XQuery or XSLT that writes to multiple output files).


Find Results Window
User Interface Guide > Tool Windows > Find Results Window

Glossary Item Box

When you use the Find in Files function, the results are displayed in the Find Results tool window.

Double clicking on a line will open the file.

Liquid XML Studio Find Results Window

If a file is determined to contain binary data, then it is not searched.

See Also

User Interface
Find and Replace


Navigation Panel
Send Feedback
User Interface Guide > Tool Windows > Navigation Panel

Glossary Item Box

The content of this panel is context sensitive.

XSD Editor

When the XSD Editor is the selected view, this panel shows all the entities defined within the schema (and its include/imported schemas).
By double clicking on a given item you will be taken to the definition for it.

You can filter the view using the Filter box (which is case sensitive)


Documentation Window
Send Feedback
User Interface Guide > Tool Windows > Documentation Window

Glossary Item Box

Most elements in an XSD schema can contain an annotation. This is a human readable block that can be used to comment your schema.

When a graphical entity is selected in the XSD schema editor, any annotations for it are show in the documentation window.

If there are no annotations, then the documentation window will be empty. If you type your comment into the window then it will be added as an annotation to your selected entity.

If the AdditionalInfo Element was selected, then you would see the comment "This element is used to ...." in the documentation window.

<xs:element name="AdditionalInfo">

<xs:annotation>

<xs:documentation>This element is used to ....</xs:documentation>

</xs:annotation>

<xs:complexType>

<xs:anyAttribute />

</xs:complexType>

</xs:element>


XPath Query Builder Window
User Interface Guide > Tool Windows > XPath Query Builder Window

Glossary Item Box

The XPath Query Builder make it simple to constructing and prototype XPath expressions.

The tool automatically attaches to the active XML window, XPath Intellisense is provided based on the selected XML document, and the results of the query are shown in real time on the XML editor.

Selected Nodes

Provides a list of all the XML nodes that match the XPath Expression. You can drill down into each node.

Right clicking on a node in the tree allows you to select the XPath for the selected node

Code Snippet

Provides the source code needed to use your XML expression in C#, Java, VB.Net, Visual Basic and XSLT.
This is especially useful when namespaces are being used within the expression.

Namespaces

If the XML document uses namespaces to qualify its elements and attributes, then you must also provide aliases for all the namespaces you use. This can be done in the Namespaces tab. This is automatically populated with the namespaces from the selected XML document, so typically you don't need to change this.

Settings

Allows you to change the way in which the XPath queries are executed, and displayed.

Auto Execute

If this is checked then the expression is evaluated every time the expression or the XML file are changed (this can slow things down, see comments below)

Show Comments

Shows the comments as nodes in the "Selected Nodes" list and as highlighted entities in the XML (should they be selected).
Typically showing these just clutters the view, but it may be useful to see them.

Show White space

Shows the white space as nodes in the "Selected Nodes" list and as highlighted entities in the XML (should they be selected).
Typically showing these just clutters the view, but it may be useful to see them.

On large document the XPath Query can consume a reasonable amount of CPU time. Because the XPath expression is re-evaluated whenever the XML changes, this can slow the application down.

Un-checking the "Auto Execute", clearing the XPath Expression or closing the XPath window will prevent the expression being evaluated on every key stroke.

In Summary: When editing large XML files, it may be worth clearing your XPath expression or un-checking the "Auto Execute" Option.

See Also

XML Editor
XPath Builder
XML Editor Context Menu


Call Stack Window
User Interface Guide > Tool Windows > Call Stack Window

Glossary Item Box

Liquid XML Studio Debugger - Call Stack ToolWindow

The Call Stack window enables you to view the names of functions on the call stack, parameter types, and parameter values. Call stack information is shown only when the program being debugged is in a paused state.

Different debuggers show more detail in the call stack than others, so some stacks may seem very verbose.

When a stack frame is selected the watch and local variables windows should reflect the state from the context of the selected stack frame.

Some debuggers to not allow local variables and watch expressions to be evaluated in anything but the top level stack frame.

See Also

Debugger
Local Variables Window
Watch Window
Breakpoints ToolWindow
Options Window
Debugger Toolbar


Breakpoints ToolWindow
User Interface Guide > Tool Windows > Breakpoints ToolWindow

Glossary Item Box

Liquid XML Studio Debugger - Breakpoints ToolWindow

Breakpoints can be set on any expression within the program being debugged. They will cause the debugger to enter the paused state when the current execution line reaches them.

Breakpoints can be toggled on and off using the toolbar ( [image]), the keyboard (F9) or by clicking into the editor margin.

Breakpoints are saved within the context of the active project. If no project is loaded then they are saved against the default project.

Breakpoints can be disabled, by un checking them or right clicking and selecting disable. A disabled breakpoint is ignored by the debugger, and displayed line this Disabled Breakpoint.

See Also

Debugger
Local Variables Window
Watch Window
Call Stack Window
Options Window
Debugger Toolbar


Watch Window
User Interface Guide > Tool Windows > Watch Window

Glossary Item Box

Ad hoc expressions can be added to the Watch window. These are evaluated whenever the debugger enters the paused state.

See Also

Debugger
Local Variables Window
Breakpoints ToolWindow
Call Stack Window
Options Window
Debugger Toolbar


Local Variables Window
User Interface Guide > Tool Windows > Local Variables Window

Glossary Item Box

Liquid XML Studio Debugger - Local Variables ToolWindow

The local Variables Tool Window is only shown when the debugger is in the running or paused state. It shows the local variables within the selected Stack Frame. The type of variables shown in the window are dependant up on the currently selected debugger, but items can be expanded and drilled into depending on there type.

Right clicking on a variables allows its value or name to be copied to the clipboard.

Values are read only.

See Also

Debugger
Local Variables Window
Watch Window
Breakpoints ToolWindow
Call Stack Window
Options Window
Debugger Toolbar


Window Layout
Send Feedback
User Interface Guide > Tool Windows > Window Layout

Glossary Item Box

Docking Windows

The layout manager in Liquid XML Studio is extremely flexible allowing you to easily make the most of your work space on single or dual monitor configurations. Tool windows can either be docked, floating or unpinned. Docked windows can also be stacked up and are then accessible via tabs.

There are 4 tool windows used by the XML Schema Editor (Error List, Properties, Documentation and Global Component Locator), these can be shown via the 'View' Menu.

The Global Component Locator and the Documentation menu items are only visible when the XML Schema editor the active editor.

Liquid XML Studio View Menu

Floating Windows

Tool windows can be made to 'float' by dragging them away from there existing location and not onto a drag icon.

Pinned Windows

If you have a limited amount of space then you can un-pin docked windows. These then slide into the sides, to save space. The icons show the state of the window, and clicking them changes from pinned to unpinned.
<->
Once unpinned a window looks like this, and can be shown by clicking on the highlighted tab


File Menu
Send Feedback
User Interface Guide > Menus > File Menu

Glossary Item Box

Liquid XML Studio File Menu | Liquid XML Studio Visual Studio File Menu
Liquid XML Studio File Menu | Liquid XML Visual Studio Plugin File Menu

New

Creates a new document. The user is prompted to select the type of document that should be created.

Save As Image

Saves the selected item in the XSD diagram as an image file (png, bmp, jpg, gif). Only the child items that are visible on the diagram appear in the image.

Page Setup

Allows page settings to be configured (landscape/portrait margins etc)

Print

Prints the currently selected XSD Diagram to the printer.

Print Preview

Shows a preview of what would be printed should Print be selected.


Edit Menu
Send Feedback
User Interface Guide > Menus > Edit Menu

Glossary Item Box

XSD Editor

Liquid XML Studio - Edit Menu

Undo

Undoes the previous operation.
Note: Some steps like editing an XSD via the code, destroy the undo history in the graphical view, and visa versa).

Redo

Re does a step that has previously been undone (Not Implemented at this time).

Cut

Cuts the currently selected text or graphical element into the clipboard.

Copy

Copies the currently selected text or graphical element into the clipboard.

Paste

Pastes the contents of the clipboard, into the currently selected text or graphical view.

Delete

Deletes the selected graphical element or selected text.

Find and Replace

Find

Finds the selected text in the XSD Code view, does not search via the XSD Diagram.

Replace

Replaces text in the XSD Code view, does not search via the XSD Diagram.

Goto

Moves the specified line number in the file.


View Menu
Send Feedback
User Interface Guide > Menus > View Menu

Glossary Item Box

Liquid XML Studio View Menu | Liquid XML Studio Visual Studio View Menu
Liquid XML Studio View Menu | Visual Studio View Menu

Error List

Ensures the Error Window is visible.

Properties

Ensures the Properties Window is visible.

Global Component Locator

Ensures the Global Component Locator Window is visible.

Schema Item Documentation

Ensures the Documentation Window is visible.

XPath Query Builder

Ensures the XPath Query Builder Properties Window is visible.


Tools Menu
User Interface Guide > Menus > Tools Menu

Glossary Item Box

Liquid XML Studio Tools Menu | Liquid XML Studio Visual Studio Tools Menu
Liquid XML Studio Tools Menu | Liquid XML Studio Visual Studio Plugin Tools Menu

Generate Documentation

Uses your XML Schema to create a sample XML document. The document is a good starting point for writing your own documents or producing test data.

See Creating a Sample XML Document

Create Sample XML Document

Creates an XML document based on the schema See Creating Sample XML Files.

Validate Schema

Performs validation on the currently selected XSD Schema.
Any errors or warnings are reported in the Error Window.

Generate Code

Generates a class library from the XSD Schema. The resulting class library makes manipulating XML documents much simpler in C++, C#, VB6, VB.Net or Java.
In order for this to work correctly the XSD Code Generator plug-in must be installed. If it is not the a browser will be opened showing where it can be downloaded from.
See XML Code Generation

Browse Web Service

Allows you to make calls to a web service

See Web Service Browser

Options...

Allows the user to configure Liquid XML Studio.

See General Options

See Also

Editor
DTD Editor Options
XML Editor Intellisense Options
XSD Editor Options

Environment
General Options
Internet Options
Tip of the Day Options


General Options
User Interface Guide > Options > Environment > General Options

Glossary Item Box

Check for updates at startup

By default, the application will check the Liquid server for updates, use the option to stop the check. Note: You should then use the Check for Updates option from the Help menu to manually check for updates on a regular basis. This can not be turned off if you are using the community or trial version.

Write Banner Comment

By default, the application will write branding into files created by the application. use this option to turn of branding.

This can not be turned off if you are using the trial version.

Report anonymous usage

If this is checked then information about feature usage is periodically sent to us.
This information helps us understand how our customers are using the application, and allows us to focus our efforts on features that are used the most, ultimately improving your user experience.

What is contained in these reports

  • Basic information about the platform you are running on (Windows Version Number, Service Pack level, .Net installations)
  • The number of times key features are used within the application.
  • The number of times the application is used.
  • Whether the application closed down cleanly

What usage reports do NOT contain

  • Information that could identify you or your computer.
  • Any files or data you are working on.
  • Licensing information

Show Status Bar

Shows or hides the status bar for the application

Perform validation on load

If this is checked, then when a document is loaded for the first time, it is validated. This can slow the application down if you are working on large documents.

Perform validation when a document is selected

If this is checked, then when a tab is selected, validation is performed on it. This can slow the application down if you are working on large documents.

Show Start Page on startup

The start page contains our news feed and Most recently used projects and files.

Item Lists

The number of files remembered in the Most Recently used Files list

Default Encoding

The encoding to assume when one is not supplied. Currently always utf-8.

Write Byte Order Marker (BOM)

This is a few bytes that is added to the start of a file. Its allows other applications to determine the encoding that has been applied to the document, so that it can be interpreted correctly. Unicode files must have a BOM to identify them. The only time the BOM becomes an issue is with UTF8 files. For Utf8 there is no standard that says whether the BOM should be written or not. Most Microsoft application (and newer apps) write it out, some older apps don’t (and worse still don’t understand it when its read in). In order to accommodate this we write the BOM by default, but there is a global option to turn it off for UTF8.

See Also

DTD Editor Options
XML Editor Intellisense Options
XSD Editor Options
Internet Options
Tip of the Day Options


Performance
Send Feedback
User Interface Guide > Options > Environment > Performance

Glossary Item Box

Turn off Document Outlining for files larger than

In order to provide outlining the language parser needs to parse the entire file, in large files this can cause performance issues. So the outlining is automatically turned off when a file is opened that is larger than the threshold set.

Turn off Syntax highlighting/intellisnese for files larger than

In order to provide intellisense the language parser needs to start at the top of the file and work down to the current location, in large files this can cause performance issues. So the syntax highlighting is automatically turned off when a file is opened that is larger than the threshold set.

Open documents in large file editor if : The file is larger than

The normal text editor requires that the entire document be loaded into memory. This can cause memory and performance issues when loading very large files, in order to work around this it is possible to open very large documents in the Large File Editor, this has no limit on the size of the files it can open and opens them instantly.

Open documents in large file editor if : A single line is longer than

In order to provide syntax highlighting and other high level text editor functionality the editor operates on the file in terms of text lines, this is normally an optimal way of dealing with a document, but occasionally a document list loaded that contains very long lines (typically an XML document with no indenting, this could be MB's of data on a single line). If the normal text editor was to load a file like this then performance would be an issue.

The large file editor however has no such issues, so if the document contains a single line of text which is longer than this threshold then it is opened using the large file editor.

Wrap lines longer than

When a file is open in the large file editor, if a line exceeds this number of characters then it is wrapped.

The ↓ character indicates that the line has been wrapped.

In order to operate and edit files that are potentially Terabytes in length the large file editor has to make some compromises so the editor is more basic and has a few quirks.

Please read the Large File Editor section before editing files.


Debugger
Send Feedback
User Interface Guide > Options > Environment > Debugger

Glossary Item Box

Max output files to open when 'Execute' completes

Some transforms (XSLT/XQuery/Datamapper) can produce multiple output files, in some cases this may be 100's or 1000's of them. If the editor tried to open them all it would grind to a halt, so if an attempt is made to open more files than this, the user is asked to confirmation.


Caching
Send Feedback
User Interface Guide > Options > Environment > Caching

Glossary Item Box

The files obtained from remote web sites via HTTP or HTTPS are often very slow to retrieve (this is particularly true of the W3C which severely throttles the downloading of some files to discourage them from being downloaded).

These delays can adversely effect the usability of Liquid XML Studio, so to resolve this Liquid XML Studio now has the ability to cache W3C and other files. Every time a file is retrieved via http or https the caching rules are checked and the file is cached accordingly. Subsequent requests are served from the cache.

All W3C files are assumed to be static, so no attempts are made to freshen the cached files. If you need to do this then the files can be purged manually within this Options Dialog.


Caching Rules
Send Feedback
User Interface Guide > Options > Environment > Caching > Caching Rules

Glossary Item Box

Rules governing which files will be cached are based on the host name. Wildcards (*) are also allowed.

Only the host name should be included in the rule, leave off the leading http:// and any paths (i.e. /schemas/xml.xsd).

So if a schemas to be cached was located at http://www.lqiuid-technologies.com/schemas/xml.xsd

The host name would just be www.lqiuid-technologies.com
To cache all http/https requests just enter a * as the host rule.


XML
Send Feedback
User Interface Guide > Options > Environment > XML

Glossary Item Box

Use existing XML Data Binder Project file

When the XML Data Binder is launch from within Liquid XML Studio, setting this option will try to open an existing XML Data Binding project using the schema file name with the extension xdbproj if it exists. Otherwise, the schema file name is passed which will then try to create a new XML Data Binding project.


Internet Options
User Interface Guide > Options > Environment > Internet Options

Glossary Item Box

Some XML Schemas and Documents refer to files that are in remote locations (typically on web servers).

This sections allows you to configure the proxy settings that will be used when trying to read files over http.

See Also

DTD Editor Options
XML Editor Intellisense Options
XSD Editor Options
General Options
Tip of the Day Options


Tip of the Day Options
User Interface Guide > Options > Environment > Tip of the Day Options

Glossary Item Box

Allows you to turn back on dialogs that have previously been turned off in the UI using the "Don't show me this again" check box.

See Also

DTD Editor Options
XML Editor Intellisense Options
XSD Editor Options
General Options
Internet Options


MessageBox Options
Send Feedback
User Interface Guide > Options > Environment > MessageBox Options

Glossary Item Box

Some MessageBox prompts have the "Don't tell me again" check box in them. If this is checked when the message box is closed, then the response is saved. The next time this message box is due to be displayed the previously saved response is selected without showing the message box.

Don't Tell Me Again MessageBox

In order to have this messages displayed again or change the previously selected option the responses can be purged by selecting the response from the list and then pressing the "Reset Selected" button.


File Associations Options
User Interface Guide > Options > Environment > File Associations Options

Glossary Item Box

The editor used to edit a given file extension can be configured on this page. This makes it possible to configure the application to use a given editor for bespoke file extensions. i.e. say your project uses an xml file with the extension ".myProjectFile". Its possible to configure Liquid XML Studio to load this using the XML Editor.

When you attempt to load a file with an unknown file extension for the first time, you are asked to select an editor to use to open it. These settings are saved for later, and can be edited in this options page.

File Extension Editor Form

Selecting a file extension and pressing the Editor button (or pressing the Add button) allows you to edit/create the file extension to Editor mapping.

File Extension Editor

The built in file extensions can not be edited.

See Also

DTD Editor Options
XML Editor Intellisense Options
XSD Editor Options
General Options
Internet Options

User Interface
File Associations


Documentation
User Interface Guide > Options > Environment > Documentation

Glossary Item Box

When editing XSD or WSDL documents its possible to attach documentation to nodes within the diagrams. These options apply to the Documentation Window.

Font settings | The font used in the Documentation Window, (a fixed width font is recommended).
Word Wrap | Applies word wrapping to the Documentation Window.
Hide indent in editor

Applies smart indent to the Documentation Window.

If the documentation has been indented within the source XML document then this indent is intelligently hidden for editing.

            <xs:annotation>
                <xs:documentation>
                    docs line 1
                    List
                         Item 1
                         Item 2
                </xs:documentation>
            </xs:annotation>

If 'Hide indent ' is true then this is displayed as

docs line 1
List
    Item 1
    Item 2

If 'Hide indent' is false then it is displayed as

                    docs line 1
                    List
                         Item 1
                         Item 2

See Also

User Interface
Documentation Window


XML Catalog Options
User Interface Guide > Options > Environment > XML Catalog Options

Glossary Item Box

Liquid XML Studio supports the Oasis XML Catalog standard, these catalogs provide mappings and re-directions, allowing namespaces to be mapped to file locations, file urls to be re-directed to locally cached resources. Some schemas even use urls that are non-standard and can only be resolved with the additional information contained within an XML Catalog (see many of the OASIS standards).

If an error occurs loading an XML Catalog then it will be shown with an error icon [image] and hovering over the entry will provide a tooltip with the error.

See Also

DTD Editor Options
XML Editor Intellisense Options
XSD Editor Options
General Options
Internet Options

User Interface
File Associations


Spell Checking
Send Feedback
User Interface Guide > Options > Environment > Spell Checking

Glossary Item Box

Liquid XML Studio can perform spell checking within your XML documents using standard Open Office dictionary files.

See details below for installing additional dictionaries.

Enable Spell Checking

If this is checked then spell checking occurs in real time as the document is changed.

For large documents it can take a little while for the checking to complete.

Xml Entities to Check

Element Name

If this option is checked then the element tag names are checked

i.e. <BaddlySpeltTag> would flag up 'Baddly' as misspelled

Attribute Name

If this option is checked then the attribute names are checked
i.e. <element BaddlySpeltAttribute=""> would flag up 'Baddly' as misspelled

CDATA

If this option is checked then the content of CDATA blocks are checked

Element Text

If this option is checked then the text within a elements is checked

i.e. <element>Baddly Spelt Text</element> would flag up 'Baddly' as misspelled

Attribute Text

If this option is checked then the element tag names are checked

i.e. <element attribute="Baddly Spelt Text"> would flag up 'Baddly' as misspelled

Comments

If this option is checked then text within comment blocks is checked

Word Splitting Rules

As many XML identifies are composed from several words the spell checker attempts to split them into individual words for checking.

Words are automatically split by case, so "complexType" is seen as "complex" & "type", but other rules can be applied for more complex cases.

Check UPPER case words

If this option is checked then words that contain only upper case characters are still checked

i.e. In <ADDRESS/> the word "address" would be checked.

Check words with numbers

If this option is checked then words that contain numbers are still checked (with the numbers removed).

i.e. If the option is checked then in <Address3/> the word "address" would be checked, if it was unchecked no checking would be performed

word splitting chars

Determines the characters used to split words. This is particularly meaningful for attribute and element names.

i.e. if the split chars contained '-' and '_' then <MY-Element_Name> would be seen as 3 words (my, element & name).

Min Word Length

Any words shorter than this are ignored

Max Word Length

Any words longer than this are ignored.

Dictionary

Liquid XML Studio ships with a number of built in dictionaries. The dictionaries make use of the standard open office file format, more are dictionary files are available from http://extensions.services.openoffice.org/en/dictionaries.

To install addition dictionaries

  1. download the .oxt file from http://extensions.services.openoffice.org/en/dictionaries.
  2. Rename the .oxt file .zip
  3. Extract the .zip file
  4. Copy the .aff and the .dic files into the %ProgramFiles%\Liquid Technologies\Liquid XML Studio 2018\Dictionaries
  5. Re-start Liquid XML Studio

Custom Words

When performing spell checking you can add words to the custom dictionary, words may be removed from the custom dictionary by taking them out of this list.


Text Editor Options
Send Feedback
User Interface Guide > Options > Text Editor Options

Glossary Item Box

Determines the default behavior to use for all editors, (by default all editors will use these setting).

Indent Size

The number of columns used for a tab. This is also the number of columns XML data will be indented by.

Use

Tabs - a tab is used to for each indent.

Spaces - a number of spaces characters is used for each indent.

Show Line Numbers

Indicates if line numbers should be shown in the left hand margin

Show Whitespace

Non-visible characters like spaces and tabs are shown in the editor (default is off).

Word Wrap

Line lines are wrapped when displayed in the editor (default is off).

Can cause performance problems when line lengths are very long (typically if a large xml file is unformatted and exists as a single line of text).

Enable Macros

Enabled keyboard macros to be recorded and played back (default is enabled).

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

Ignore Significant Whitespace Formatting XML

Causes leading and trailing whitespace to be ignored (default is false). Whitespace before and after data contained within an XML Element is considered to be significant to most parsers. It will therefore be preserved when formatting your XML documents, which can cause them to look verbose. Consider the XML sample.

The following XML is formatted as follows

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
<book id="b0836217462" available="yes">
<isbn>
   08362   17462
</isbn>
</book>
</library>

Formatting and respecting the Significant whitespace (i.e. unchecked) will result in the following (note the data within the isbn element is the same, but its not cleanly formatted).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>
   08362   17462
</isbn>
    </book>
</library>

Formatting and ignoring the Significant whitespace (i.e. checked) will result in the following (note the data within the isbn element has changed, the leading and trailing whitespace has been removed).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>08362   17462</isbn>
    </book>
</library>


DTD Editor Options
User Interface Guide > Options > Editors > DTD Editor Options

Glossary Item Box

By default "Use System Default" is checked, which means the settings for the editor are taken from the Default Options page.

When this is un-checked the settings can be customized for each individual editor.

Indent Size

The number of columns used for a tab. This is also the number of columns XML data will be indented by.

Use

Tabs - a tab is used to for each indent.

Spaces - a number of spaces characters is used for each indent.

Show Line Numbers

Indicates if line numbers should be shown in the left hand margin

Show Whitespace

Non-visible characters like spaces and tabs are shown in the editor (default is off).

Word Wrap

Line lines are wrapped when displayed in the editor (default is off).

Can cause performance problems when line lengths are very long (typically if a large xml file is unformatted and exists as a single line of text).

Enable Macros

Enabled keyboard macros to be recorded and played back (default is enabled).

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

Ignore Significant Whitespace Formatting XML

Causes leading and trailing whitespace to be ignored (default is false). Whitespace before and after data contained within an XML Element is considered to be significant to most parsers. It will therefore be preserved when formatting your XML documents, which can cause them to look verbose. Consider the XML sample.

The following XML is formatted as follows

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
<book id="b0836217462" available="yes">
<isbn>
   08362   17462
</isbn>
</book>
</library>

Formatting and respecting the Significant whitespace (i.e. unchecked) will result in the following (note the data within the isbn element is the same, but its not cleanly formatted).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>
   08362   17462
</isbn>
    </book>
</library>

Formatting and ignoring the Significant whitespace (i.e. checked) will result in the following (note the data within the isbn element has changed, the leading and trailing whitespace has been removed).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>08362   17462</isbn>
    </book>
</library>

See Also

Options
Text Editor Options


XSD Code Editor Options
User Interface Guide > Options > Editors > XML > XSD Code Editor Options

Glossary Item Box

By default "Use System Default" is checked, which means the settings for the editor are taken from the Default Options page.

When this is un-checked the settings can be customized for each individual editor.

Indent Size

The number of columns used for a tab. This is also the number of columns XML data will be indented by.

Use

Tabs - a tab is used to for each indent.

Spaces - a number of spaces characters is used for each indent.

Show Line Numbers

Indicates if line numbers should be shown in the left hand margin

Show Whitespace

Non-visible characters like spaces and tabs are shown in the editor (default is off).

Word Wrap

Line lines are wrapped when displayed in the editor (default is off).

Can cause performance problems when line lengths are very long (typically if a large xml file is unformatted and exists as a single line of text).

Enable Macros

Enabled keyboard macros to be recorded and played back (default is enabled).

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

Ignore Significant Whitespace Formatting XML

Causes leading and trailing whitespace to be ignored (default is false). Whitespace before and after data contained within an XML Element is considered to be significant to most parsers. It will therefore be preserved when formatting your XML documents, which can cause them to look verbose. Consider the XML sample.

The following XML is formatted as follows

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
<book id="b0836217462" available="yes">
<isbn>
   08362   17462
</isbn>
</book>
</library>

Formatting and respecting the Significant whitespace (i.e. unchecked) will result in the following (note the data within the isbn element is the same, but its not cleanly formatted).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>
   08362   17462
</isbn>
    </book>
</library>

Formatting and ignoring the Significant whitespace (i.e. checked) will result in the following (note the data within the isbn element has changed, the leading and trailing whitespace has been removed).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>08362   17462</isbn>
    </book>
</library>

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

See Also

Options
Text Editor Options


XML Editor Intellisense Options
User Interface Guide > Options > Editors > XML > XML Editor Intellisense Options

Glossary Item Box

Enable Intellisense

When checked, intellisense is turned on within the XML Editor

Auto suggest attributes

When checked, attributes are included in the intellisense suggestions

Auto suggest attribute values

When checked, attributes values are included in the intellisense suggestions. Only enumeration values are include in the options.

Auto suggest element values

When checked, element values are included in the intellisense suggestions. Only enumeration values are include in the options.

Add <complexType>'s to element suggestions

When checked, element values are included along with all the complexType variants that are also allowed in the context.

If a complex type suggestions options are selected the xsi:type attribute is also added which identifies the complex type selected.

Expand <any> tags in element suggestions

When check this will expand and <any> elements in the XSD using all the schema currently loaded into the XSD Schema cache for the given document.

This can potentially provide 1000's of suggestions and affect performance when large schemas are used, so limiting the number of suggestions is advisable (see the Max.Suggestions property).

Add closing </element> tags element suggestions

Automatically creates the end element tag when a start element tag is completed, i.e. when the closing > tag is typed in <MyElement>, then the closing tag is added giving <MyElement></MyElement>

Max. suggestions

This is the maximum number of suggestions that will be offered in the drop down. If more options are available then they are not shown. When working with large schemas this setting can limit the results, but can prevent long delays when typing.

Auto complete elements

When checked pressing Ctrl-Space will auto complete the current element if a single option is available, i.e.

<ns:broke

Pressing Ctrl-Space after the 'e' will complete the element giving

<ns:broker></ns:broker>

If there are more than one option, then the intellisense suggestion box opens at the appropriate place.

Auto complete element end tags

When checked, the current element is automatically closed when </ is typed.

See Also

DTD Editor Options
XSD Editor Options
General Options
Internet Options
Tip of the Day Options


XSD Editor Options
User Interface Guide > Options > Editors > XSD > XSD Editor Options

Glossary Item Box

Show Tooltips

Allows the XSD Diagram tooltips to be disabled.

When tooltips are enabled hovering over any XSD element in the XSD diagram will show a tooltip.

Show Notes

Includes the "Notes" section within the tooltip.

Show Derived Items

Includes the "Derived Types" section within the tooltip.

When working with large schemas this can take a while to calculate, and slow down the showing of the tooltip

Always show the item cardinality on the diagram

If this is checked then the cardinality of an XSD diagram node is always displayed.

If this is not checked, then the cardinality is only displayed if the minOccurs or maxOccurs attributes are present in an XSD node.

Show default cardinality in braces

When this option is checked, then any cardinality values that are not present (and thus taken from the default value) are shown in [].

Show Inline Properties

Shows the properties that apply to the item inline within it

Show Inline Annotations

Shows the items annotations inline (Show Inline Properties must be checked for this to have any effect)

Font

Sets the font used in the XSD diagram

Show settings dialog when creating XML sample from an element

If this is checked, then when a sample XML file is created from the right click context menu a dialog is displayed with the sample generation settings.

If this is not checked the dialog is not shown and default options are used (this is handy for fast visualization of how an element will look).

Open imported schema when wizard completes

When an external schema is imported/included using the import wizard. This setting determines if it will be opened as soon as its been added to the current schema

See Also

DTD Editor Options
XML Editor Intellisense Options
General Options
Internet Options
Tip of the Day Options


XSD Graphical Editor Fill Colors Options
User Interface Guide > Options > Editors > XSD > Graphical Editor > XSD Graphical Editor Fill Colors Options

Glossary Item Box

Allows the colors used within the XSD editor to be edited.

See Also

Options
Text Editor Options


Text Editor Options
User Interface Guide > Options > Editors > Text Editor Options

Glossary Item Box

By default "Use System Default" is checked, which means the settings for the editor are taken from the Default Options page.

When this is un-checked the settings can be customized for each individual editor.

Indent Size

The number of columns used for a tab. This is also the number of columns XML data will be indented by.

Use

Tabs - a tab is used to for each indent.

Spaces - a number of spaces characters is used for each indent.

Show Line Numbers

Indicates if line numbers should be shown in the left hand margin

Show Whitespace

Non-visible characters like spaces and tabs are shown in the editor (default is off).

Word Wrap

Line lines are wrapped when displayed in the editor (default is off).

Can cause performance problems when line lengths are very long (typically if a large xml file is unformatted and exists as a single line of text).

Enable Macros

Enabled keyboard macros to be recorded and played back (default is enabled).

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

Ignore Significant Whitespace Formatting XML

Causes leading and trailing whitespace to be ignored (default is false). Whitespace before and after data contained within an XML Element is considered to be significant to most parsers. It will therefore be preserved when formatting your XML documents, which can cause them to look verbose. Consider the XML sample.

The following XML is formatted as follows

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
<book id="b0836217462" available="yes">
<isbn>
   08362   17462
</isbn>
</book>
</library>

Formatting and respecting the Significant whitespace (i.e. unchecked) will result in the following (note the data within the isbn element is the same, but its not cleanly formatted).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>
   08362   17462
</isbn>
    </book>
</library>

Formatting and ignoring the Significant whitespace (i.e. checked) will result in the following (note the data within the isbn element has changed, the leading and trailing whitespace has been removed).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>08362   17462</isbn>
    </book>
</library>

See Also

Options
Text Editor Options


XSLT Editor Options
User Interface Guide > Options > Editors > XSLT Editor Options

Glossary Item Box

By default "Use System Default" is checked, which means the settings for the editor are taken from the Default Options page.

When this is un-checked the settings can be customized for each individual editor.

Indent Size

The number of columns used for a tab. This is also the number of columns XML data will be indented by.

Use

Tabs - a tab is used to for each indent.

Spaces - a number of spaces characters is used for each indent.

Show Line Numbers

Indicates if line numbers should be shown in the left hand margin

Show Whitespace

Non-visible characters like spaces and tabs are shown in the editor (default is off).

Word Wrap

Line lines are wrapped when displayed in the editor (default is off).

Can cause performance problems when line lengths are very long (typically if a large xml file is unformatted and exists as a single line of text).

Enable Macros

Enabled keyboard macros to be recorded and played back (default is enabled).

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

Ignore Significant Whitespace Formatting XML

Causes leading and trailing whitespace to be ignored (default is false). Whitespace before and after data contained within an XML Element is considered to be significant to most parsers. It will therefore be preserved when formatting your XML documents, which can cause them to look verbose. Consider the XML sample.

The following XML is formatted as follows

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
<book id="b0836217462" available="yes">
<isbn>
   08362   17462
</isbn>
</book>
</library>

Formatting and respecting the Significant whitespace (i.e. unchecked) will result in the following (note the data within the isbn element is the same, but its not cleanly formatted).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>
   08362   17462
</isbn>
    </book>
</library>

Formatting and ignoring the Significant whitespace (i.e. checked) will result in the following (note the data within the isbn element has changed, the leading and trailing whitespace has been removed).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>08362   17462</isbn>
    </book>
</library>

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

See Also

Options
Text Editor Options


CSS
User Interface Guide > Options > Editors > CSS

Glossary Item Box

By default "Use System Default" is checked, which means the settings for the editor are taken from the Default Options page.

When this is un-checked the settings can be customized for each individual editor.

Indent Size

The number of columns used for a tab. This is also the number of columns XML data will be indented by.

Use

Tabs - a tab is used to for each indent.

Spaces - a number of spaces characters is used for each indent.

Show Line Numbers

Indicates if line numbers should be shown in the left hand margin

Show Whitespace

Non-visible characters like spaces and tabs are shown in the editor (default is off).

Word Wrap

Line lines are wrapped when displayed in the editor (default is off).

Can cause performance problems when line lengths are very long (typically if a large xml file is unformatted and exists as a single line of text).

Enable Macros

Enabled keyboard macros to be recorded and played back (default is enabled).

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

Ignore Significant Whitespace Formatting XML

Causes leading and trailing whitespace to be ignored (default is false). Whitespace before and after data contained within an XML Element is considered to be significant to most parsers. It will therefore be preserved when formatting your XML documents, which can cause them to look verbose. Consider the XML sample.

The following XML is formatted as follows

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
<book id="b0836217462" available="yes">
<isbn>
   08362   17462
</isbn>
</book>
</library>

Formatting and respecting the Significant whitespace (i.e. unchecked) will result in the following (note the data within the isbn element is the same, but its not cleanly formatted).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>
   08362   17462
</isbn>
    </book>
</library>

Formatting and ignoring the Significant whitespace (i.e. checked) will result in the following (note the data within the isbn element has changed, the leading and trailing whitespace has been removed).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>08362   17462</isbn>
    </book>
</library>

See Also

Options
Text Editor Options


JSON Code Editor Options
User Interface Guide > Options > Editors > JSON Code Editor Options

Glossary Item Box

By default "Use System Default" is checked, which means the settings for the editor are taken from the Default Options page.

When this is un-checked the settings can be customized for each individual editor.

Indent Size

The number of columns used for a tab. This is also the number of columns XML data will be indented by.

Use

Tabs - a tab is used to for each indent.

Spaces - a number of spaces characters is used for each indent.

Show Line Numbers

Indicates if line numbers should be shown in the left hand margin

Show Whitespace

Non-visible characters like spaces and tabs are shown in the editor (default is off).

Word Wrap

Line lines are wrapped when displayed in the editor (default is off).

Can cause performance problems when line lengths are very long (typically if a large xml file is unformatted and exists as a single line of text).

Enable Macros

Enabled keyboard macros to be recorded and played back (default is enabled).

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

Ignore Significant Whitespace Formatting XML

Causes leading and trailing whitespace to be ignored (default is false). Whitespace before and after data contained within an XML Element is considered to be significant to most parsers. It will therefore be preserved when formatting your XML documents, which can cause them to look verbose. Consider the XML sample.

The following XML is formatted as follows

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
<book id="b0836217462" available="yes">
<isbn>
   08362   17462
</isbn>
</book>
</library>

Formatting and respecting the Significant whitespace (i.e. unchecked) will result in the following (note the data within the isbn element is the same, but its not cleanly formatted).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>
   08362   17462
</isbn>
    </book>
</library>

Formatting and ignoring the Significant whitespace (i.e. checked) will result in the following (note the data within the isbn element has changed, the leading and trailing whitespace has been removed).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>08362   17462</isbn>
    </book>
</library>

See Also

Options
Text Editor Options


JSON Graphical Editor Options
User Interface Guide > Options > Editors > Code Editor > JSON Graphical Editor Options

Glossary Item Box

See Also

Options
Text Editor Options


JSON Graphical Editor Fill Colors Options
User Interface Guide > Options > Editors > Code Editor > Graphical Editor > JSON Graphical Editor Fill Colors Options

Glossary Item Box

See Also

Options
Text Editor Options


WSDL Code Editor Options
Send Feedback
User Interface Guide > Options > Editors > WSDL > WSDL Code Editor Options

Glossary Item Box

By default "Use System Default" is checked, which means the settings for the editor are taken from the Default Options page.

When this is un-checked the settings can be customized for each individual editor.

Indent Size

The number of columns used for a tab. This is also the number of columns XML data will be indented by.

Use

Tabs - a tab is used to for each indent.

Spaces - a number of spaces characters is used for each indent.

Show Line Numbers

Indicates if line numbers should be shown in the left hand margin

Show Whitespace

Non-visible characters like spaces and tabs are shown in the editor (default is off).

Word Wrap

Line lines are wrapped when displayed in the editor (default is off).

Can cause performance problems when line lengths are very long (typically if a large xml file is unformatted and exists as a single line of text).

Enable Macros

Enabled keyboard macros to be recorded and played back (default is enabled).

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

Ignore Significant Whitespace Formatting XML

Causes leading and trailing whitespace to be ignored (default is false). Whitespace before and after data contained within an XML Element is considered to be significant to most parsers. It will therefore be preserved when formatting your XML documents, which can cause them to look verbose. Consider the XML sample.

The following XML is formatted as follows

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
<book id="b0836217462" available="yes">
<isbn>
   08362   17462
</isbn>
</book>
</library>

Formatting and respecting the Significant whitespace (i.e. unchecked) will result in the following (note the data within the isbn element is the same, but its not cleanly formatted).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>
   08362   17462
</isbn>
    </book>
</library>

Formatting and ignoring the Significant whitespace (i.e. checked) will result in the following (note the data within the isbn element has changed, the leading and trailing whitespace has been removed).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>08362   17462</isbn>
    </book>
</library>

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.


WSDL Graphical Editor Options
Send Feedback
User Interface Guide > Options > Editors > WSDL > WSDL Graphical Editor Options

Glossary Item Box


Code Editor Options
Send Feedback
User Interface Guide > Options > Editors > WSDL 2 > Code Editor Options

Glossary Item Box

By default "Use System Default" is checked, which means the settings for the editor are taken from the Default Options page.

When this is un-checked the settings can be customized for each individual editor.

Indent Size

The number of columns used for a tab. This is also the number of columns XML data will be indented by.

Use

Tabs - a tab is used to for each indent.

Spaces - a number of spaces characters is used for each indent.

Show Line Numbers

Indicates if line numbers should be shown in the left hand margin

Show Whitespace

Non-visible characters like spaces and tabs are shown in the editor (default is off).

Word Wrap

Line lines are wrapped when displayed in the editor (default is off).

Can cause performance problems when line lengths are very long (typically if a large xml file is unformatted and exists as a single line of text).

Enable Macros

Enabled keyboard macros to be recorded and played back (default is enabled).

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

Ignore Significant Whitespace Formatting XML

Causes leading and trailing whitespace to be ignored (default is false). Whitespace before and after data contained within an XML Element is considered to be significant to most parsers. It will therefore be preserved when formatting your XML documents, which can cause them to look verbose. Consider the XML sample.

The following XML is formatted as follows

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
<book id="b0836217462" available="yes">
<isbn>
   08362   17462
</isbn>
</book>
</library>

Formatting and respecting the Significant whitespace (i.e. unchecked) will result in the following (note the data within the isbn element is the same, but its not cleanly formatted).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>
   08362   17462
</isbn>
    </book>
</library>

Formatting and ignoring the Significant whitespace (i.e. checked) will result in the following (note the data within the isbn element has changed, the leading and trailing whitespace has been removed).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>08362   17462</isbn>
    </book>
</library>

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.


Graphical Editor Options
Send Feedback
User Interface Guide > Options > Editors > WSDL 2 > Graphical Editor Options

Glossary Item Box


XQuery Editor Options
User Interface Guide > Options > Editors > XQuery > XQuery Editor Options

Glossary Item Box

By default "Use System Default" is checked, which means the settings for the editor are taken from the Default Options page.

When this is un-checked the settings can be customized for each individual editor.

Indent Size

The number of columns used for a tab. This is also the number of columns XML data will be indented by.

Use

Tabs - a tab is used to for each indent.

Spaces - a number of spaces characters is used for each indent.

Show Line Numbers

Indicates if line numbers should be shown in the left hand margin

Show Whitespace

Non-visible characters like spaces and tabs are shown in the editor (default is off).

Word Wrap

Line lines are wrapped when displayed in the editor (default is off).

Can cause performance problems when line lengths are very long (typically if a large xml file is unformatted and exists as a single line of text).

Enable Macros

Enabled keyboard macros to be recorded and played back (default is enabled).

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

Ignore Significant Whitespace Formatting XML

Causes leading and trailing whitespace to be ignored (default is false). Whitespace before and after data contained within an XML Element is considered to be significant to most parsers. It will therefore be preserved when formatting your XML documents, which can cause them to look verbose. Consider the XML sample.

The following XML is formatted as follows

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
<book id="b0836217462" available="yes">
<isbn>
   08362   17462
</isbn>
</book>
</library>

Formatting and respecting the Significant whitespace (i.e. unchecked) will result in the following (note the data within the isbn element is the same, but its not cleanly formatted).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>
   08362   17462
</isbn>
    </book>
</library>

Formatting and ignoring the Significant whitespace (i.e. checked) will result in the following (note the data within the isbn element has changed, the leading and trailing whitespace has been removed).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>08362   17462</isbn>
    </book>
</library>

See Also

Options
Text Editor Options


SourceControl Options
Send Feedback
User Interface Guide > Options > SourceControl Options

Glossary Item Box


Source Control SVN Options
Send Feedback
User Interface Guide > Options > Source Control > Source Control SVN Options

Glossary Item Box


Source Control VSS Options
Send Feedback
User Interface Guide > Options > Source Control > Source Control VSS Options

Glossary Item Box


Keyboard Shortcuts
User Interface Guide > Keyboard Shortcuts

Glossary Item Box

Shortcut Keys

Shortcut | Command | Category | Scope
Alt+C | Collapses the selected node | Debug |
Alt+E | Expands the selected node | Debug |
Alt+F5 | DebuggerStop | Debugger |
Alt+X | Show XSD | WSDL | WSDL Editor
Alt+X | Show XSD | WSDL2 | WSDL2 Editor
BrowserBack | Navigate Backward | View |
BrowserForward | Navigate Forward | View |
Ctrl+A | Select All | View |
Ctrl+Alt+D | Show Database Explorer | View |
Ctrl+Alt+Down Arrow | Add Below | DataMapper | Data Mapper Editor
Ctrl+Alt+L | Show Project Explorer | View |
Ctrl+Alt+O | Show Output | View |
Ctrl+Alt+Up Arrow | Add Above | DataMapper | Data Mapper Editor
Ctrl+B | Bold | XHTML | XHTML Editor
Ctrl+Break | DebuggerPause | Debugger |
Ctrl+C | Copy | Edit |
Ctrl+D | Show Documentation | View |
Ctrl+E | Show Error List | View |
Ctrl+F | Find | Edit |
Ctrl+F3 | Find Next Selected | Edit |
Ctrl+F4 | Close File | File |
Ctrl+F7 | Schema Used to Validate XML | XML | XML Editor
Ctrl+F7 | Set Validation Schema | JSON | JSON Editor
Ctrl+G | Go To | Edit |
Ctrl+H | Replace | Edit |
Ctrl+I | Italic | XHTML | XHTML Editor
Ctrl+J, Ctrl+A | Add Attribute | XSD | XSD Editor
Ctrl+J, Ctrl+A | Add Array Item with no type (any) | JsonSchema | Json Schema Editor
Ctrl+J, Ctrl+B | Add Binding | WSDL | WSDL Editor
Ctrl+J, Ctrl+B | Add Binding | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+C | Add Complex Type | XSD | XSD Editor
Ctrl+J, Ctrl+D | Add Soap Module | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+D | Add Definition with no type (any) | JsonSchema | Json Schema Editor
Ctrl+J, Ctrl+E | Add Element | XSD | XSD Editor
Ctrl+J, Ctrl+E | Add Operation | WSDL | WSDL Editor
Ctrl+J, Ctrl+E | Add Operation | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+E | Add Additional Array Items | JsonSchema | Json Schema Editor
Ctrl+J, Ctrl+G | Add Group | XSD | XSD Editor
Ctrl+J, Ctrl+G | Add Message Part | WSDL | WSDL Editor
Ctrl+J, Ctrl+H | Add Choice | XSD | XSD Editor
Ctrl+J, Ctrl+H | Add HTTP Header | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+I | Add Operation Input | WSDL | WSDL Editor
Ctrl+J, Ctrl+I | Add Operation Input | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+I | Add Additional Properties | JsonSchema | Json Schema Editor
Ctrl+J, Ctrl+J | Add Any Attribute | XSD | XSD Editor
Ctrl+J, Ctrl+K | Add Key | XSD | XSD Editor
Ctrl+J, Ctrl+K | Add Interface Fault | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+L | Add All | XSD | XSD Editor
Ctrl+J, Ctrl+L | Add Operation Fault | WSDL | WSDL Editor
Ctrl+J, Ctrl+L | Add Operation Infault | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+L | Add AllOf | JsonSchema | Json Schema Editor
Ctrl+J, Ctrl+M | Add Message | WSDL | WSDL Editor
Ctrl+J, Ctrl+M | Add Operation Outfault | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+N | Add Notation | XSD | XSD Editor
Ctrl+J, Ctrl+N | Add Not | JsonSchema | Json Schema Editor
Ctrl+J, Ctrl+O | Add Open Content | XSD | XSD Editor
Ctrl+J, Ctrl+O | Add Soap Header Block | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+O | Add OneOf | JsonSchema | Json Schema Editor
Ctrl+J, Ctrl+P | Add Attribute Group | XSD | XSD Editor
Ctrl+J, Ctrl+P | Add Port | WSDL | WSDL Editor
Ctrl+J, Ctrl+P | Add Endpoint | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+P | Add Property with no type (any) | JsonSchema | Json Schema Editor
Ctrl+J, Ctrl+Q | Add Sequence | XSD | XSD Editor
Ctrl+J, Ctrl+R | Add KeyRef | XSD | XSD Editor
Ctrl+J, Ctrl+R | Rebind All | WSDL | WSDL Editor
Ctrl+J, Ctrl+R | Rebind All | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+R | Add Required Property | JsonSchema | Json Schema Editor
Ctrl+J, Ctrl+S | Add Simple Type | XSD | XSD Editor
Ctrl+J, Ctrl+S | Add Child Schema | JsonSchema | Json Schema Editor
Ctrl+J, Ctrl+T | Add Assert | XSD | XSD Editor
Ctrl+J, Ctrl+T | Add Port Type | WSDL | WSDL Editor
Ctrl+J, Ctrl+T | Add Interface | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+T | Add Pattern Property | JsonSchema | Json Schema Editor
Ctrl+J, Ctrl+U | Add Unique | XSD | XSD Editor
Ctrl+J, Ctrl+U | Add Operation Output | WSDL | WSDL Editor
Ctrl+J, Ctrl+U | Add Operation Output | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+V | Add Alternative | XSD | XSD Editor
Ctrl+J, Ctrl+V | Add Service | WSDL | WSDL Editor
Ctrl+J, Ctrl+V | Add Service | WSDL2 | WSDL2 Editor
Ctrl+J, Ctrl+Y | Add Any | XSD | XSD Editor
Ctrl+J, Ctrl+Y | Add AnyOf | JsonSchema | Json Schema Editor
Ctrl+K, Ctrl+C | Comment Selection | Edit |
Ctrl+K, Ctrl+D | Format Document | Edit |
Ctrl+K, Ctrl+D | Auto Layout | DataMapper | Data Mapper Editor
Ctrl+K, Ctrl+F | Format Selection | Edit |
Ctrl+K, Ctrl+K | Toggle Bookmark | Edit |
Ctrl+K, Ctrl+L | Remove All Bookmarks | Edit |
Ctrl+K, Ctrl+N | Move Next Bookmark | Edit |
Ctrl+K, Ctrl+P | Move Previous Bookmark | Edit |
Ctrl+K, Ctrl+U | Uncomment Selection | Edit |
Ctrl+M, Ctrl+A | Collapse All | View |
Ctrl+M, Ctrl+D | Select None | View |
Ctrl+M, Ctrl+E | Expand Selection | View |
Ctrl+M, Ctrl+M | Toggle Expansion | View |
Ctrl+M, Ctrl+S | Collapse Selection | View |
Ctrl+M, Ctrl+V | Toggle Selection | View |
Ctrl+M, Ctrl+X | Expand All | View |
Ctrl+N | New File | File |
Ctrl+Num - | Zoom Out | View |
Ctrl+Num / | FindText | Edit |
Ctrl+Num + | Zoom In | View |
Ctrl+O | Open File | File |
Ctrl+P | Print | File |
Ctrl+R | Rebind to Port Type | WSDL | WSDL Editor
Ctrl+R | Rebind to Interface | WSDL2 | WSDL2 Editor
Ctrl+S | Save | File |
Ctrl+Shift+A | Add new project item | Project |
Ctrl+Shift+B | Compile | Debugger |
Ctrl+Shift+F | Find In Files | Edit |
Ctrl+Shift+N | New Project | File |
Ctrl+Shift+O | Open Project | File |
Ctrl+Shift+P | Macro Playback | Macro |
Ctrl+Shift+R | Macro Record Start/Stop Toggle | Macro |
Ctrl+Shift+S | Save All | File |
Ctrl+U | Underline | XHTML | XHTML Editor
Ctrl+V | Paste | Edit |
Ctrl+X | Cut | Edit |
Ctrl+Y | Redo | Edit |
Ctrl+Z | Undo | Edit |
Del | Delete | Edit |
F1 | Contents | Help |
F10 | DebuggerStepOver | Debugger |
F11 | DebuggerStepInto | Debugger |
F12 | Navigate to Definition | View |
F2 | Rename | XSD | XSD Editor
F3 | Find Next | Edit |
F4 | Show Properties | View |
F5 | DebuggerRun | Debugger |
F7 | Validate | Validation |
F9 | DebuggerToggleBreakPoint | Debugger |
F9 | Preview Document in Web Browser | XHTML | XHTML Editor
Shift+Alt+A | Add existing project item | Project |
Shift+Alt+Enter | Full Screen | View |
Shift+F11 | DebuggerStepOut | Debugger |
Shift+F12 | Find References | XSD | XSD Editor
Shift+F2 | ConfigureDebugger | Debugger |
Shift+F3 | Find Previous | Edit |
Shift+F4 | Show Properties | DataMapper | Data Mapper Editor
Shift+F5 | Execute | Debugger |

See Also

Keyboard Macros
Keyboard Shortcuts
Keyboard Shortcuts By Category


Keyboard Shortcuts By Category
User Interface Guide > Keyboard Shortcuts By Category

Glossary Item Box

File Keys

Command | Shortcut | Scope
Close File | Ctrl+F4 | File
New File | Ctrl+N | File
New Project | Ctrl+Shift+N | File
Open File | Ctrl+O | File
Open Project | Ctrl+Shift+O | File
Print | Ctrl+P | File
Save | Ctrl+S | File
Save All | Ctrl+Shift+S | File

Edit Keys

Command | Shortcut | Scope
Comment Selection | Ctrl+K, Ctrl+C | Edit
Copy | Ctrl+C | Edit
Cut | Ctrl+X | Edit
Delete | Del | Edit
Find | Ctrl+F | Edit
Find In Files | Ctrl+Shift+F | Edit
Find Next | F3 | Edit
Find Next Selected | Ctrl+F3 | Edit
Find Previous | Shift+F3 | Edit
FindText | Ctrl+Num / | Edit
Format Document | Ctrl+K, Ctrl+D | Edit
Format Selection | Ctrl+K, Ctrl+F | Edit
Go To | Ctrl+G | Edit
Move Next Bookmark | Ctrl+K, Ctrl+N | Edit
Move Previous Bookmark | Ctrl+K, Ctrl+P | Edit
Paste | Ctrl+V | Edit
Redo | Ctrl+Y | Edit
Remove All Bookmarks | Ctrl+K, Ctrl+L | Edit
Replace | Ctrl+H | Edit
Toggle Bookmark | Ctrl+K, Ctrl+K | Edit
Uncomment Selection | Ctrl+K, Ctrl+U | Edit
Undo | Ctrl+Z | Edit

View Keys

Command | Shortcut | Scope
Collapse All | Ctrl+M, Ctrl+A | View
Collapse Selection | Ctrl+M, Ctrl+S | View
Expand All | Ctrl+M, Ctrl+X | View
Expand Selection | Ctrl+M, Ctrl+E | View
Full Screen | Shift+Alt+Enter | View
Navigate Backward | BrowserBack | View
Navigate Forward | BrowserForward | View
Navigate to Definition | F12 | View
Select All | Ctrl+A | View
Select None | Ctrl+M, Ctrl+D | View
Show Database Explorer | Ctrl+Alt+D | View
Show Documentation | Ctrl+D | View
Show Error List | Ctrl+E | View
Show Output | Ctrl+Alt+O | View
Show Project Explorer | Ctrl+Alt+L | View
Show Properties | F4 | View
Toggle Expansion | Ctrl+M, Ctrl+M | View
Toggle Selection | Ctrl+M, Ctrl+V | View
Zoom In | Ctrl+Num + | View
Zoom Out | Ctrl+Num - | View

Macro Keys

Command | Shortcut | Scope
Macro Playback | Ctrl+Shift+P | Macro
Macro Record Start/Stop Toggle | Ctrl+Shift+R | Macro

Validation Keys

Command | Shortcut | Scope
Validate | F7 | Validation

Help Keys

Command | Shortcut | Scope
Contents | F1 | Help

Debugger Keys

Command | Shortcut | Scope
Compile | Ctrl+Shift+B | Debugger
ConfigureDebugger | Shift+F2 | Debugger
DebuggerPause | Ctrl+Break | Debugger
DebuggerRun | F5 | Debugger
DebuggerStepInto | F11 | Debugger
DebuggerStepOut | Shift+F11 | Debugger
DebuggerStepOver | F10 | Debugger
DebuggerStop | Alt+F5 | Debugger
DebuggerToggleBreakPoint | F9 | Debugger
Execute | Shift+F5 | Debugger

XML Keys

Command | Shortcut | Scope
Schema Used to Validate XML | Ctrl+F7 | XML

XSD Keys

Command | Shortcut | Scope
Add All | Ctrl+J, Ctrl+L | XSD
Add Alternative | Ctrl+J, Ctrl+V | XSD
Add Any | Ctrl+J, Ctrl+Y | XSD
Add Any Attribute | Ctrl+J, Ctrl+J | XSD
Add Assert | Ctrl+J, Ctrl+T | XSD
Add Attribute | Ctrl+J, Ctrl+A | XSD
Add Attribute Group | Ctrl+J, Ctrl+P | XSD
Add Choice | Ctrl+J, Ctrl+H | XSD
Add Complex Type | Ctrl+J, Ctrl+C | XSD
Add Element | Ctrl+J, Ctrl+E | XSD
Add Group | Ctrl+J, Ctrl+G | XSD
Add Key | Ctrl+J, Ctrl+K | XSD
Add KeyRef | Ctrl+J, Ctrl+R | XSD
Add Notation | Ctrl+J, Ctrl+N | XSD
Add Open Content | Ctrl+J, Ctrl+O | XSD
Add Sequence | Ctrl+J, Ctrl+Q | XSD
Add Simple Type | Ctrl+J, Ctrl+S | XSD
Add Unique | Ctrl+J, Ctrl+U | XSD
Find References | Shift+F12 | XSD
Rename | F2 | XSD

Debug Keys

Command | Shortcut | Scope
Collapses the selected node | Alt+C | Debug
Expands the selected node | Alt+E | Debug

XHTML Keys

Command | Shortcut | Scope
Bold | Ctrl+B | XHTML
Italic | Ctrl+I | XHTML
Preview Document in Web Browser | F9 | XHTML
Underline | Ctrl+U | XHTML

JSON Keys

Command | Shortcut | Scope
Set Validation Schema | Ctrl+F7 | JSON

WSDL Keys

Command | Shortcut | Scope
Add Binding | Ctrl+J, Ctrl+B | WSDL
Add Message | Ctrl+J, Ctrl+M | WSDL
Add Message Part | Ctrl+J, Ctrl+G | WSDL
Add Operation | Ctrl+J, Ctrl+E | WSDL
Add Operation Fault | Ctrl+J, Ctrl+L | WSDL
Add Operation Input | Ctrl+J, Ctrl+I | WSDL
Add Operation Output | Ctrl+J, Ctrl+U | WSDL
Add Port | Ctrl+J, Ctrl+P | WSDL
Add Port Type | Ctrl+J, Ctrl+T | WSDL
Add Service | Ctrl+J, Ctrl+V | WSDL
Rebind All | Ctrl+J, Ctrl+R | WSDL
Rebind to Port Type | Ctrl+R | WSDL
Show XSD | Alt+X | WSDL

WSDL2 Keys

Command | Shortcut | Scope
Add Binding | Ctrl+J, Ctrl+B | WSDL2
Add Endpoint | Ctrl+J, Ctrl+P | WSDL2
Add HTTP Header | Ctrl+J, Ctrl+H | WSDL2
Add Interface | Ctrl+J, Ctrl+T | WSDL2
Add Interface Fault | Ctrl+J, Ctrl+K | WSDL2
Add Operation | Ctrl+J, Ctrl+E | WSDL2
Add Operation Infault | Ctrl+J, Ctrl+L | WSDL2
Add Operation Input | Ctrl+J, Ctrl+I | WSDL2
Add Operation Outfault | Ctrl+J, Ctrl+M | WSDL2
Add Operation Output | Ctrl+J, Ctrl+U | WSDL2
Add Service | Ctrl+J, Ctrl+V | WSDL2
Add Soap Header Block | Ctrl+J, Ctrl+O | WSDL2
Add Soap Module | Ctrl+J, Ctrl+D | WSDL2
Rebind All | Ctrl+J, Ctrl+R | WSDL2
Rebind to Interface | Ctrl+R | WSDL2
Show XSD | Alt+X | WSDL2

DataMapper Keys

Command | Shortcut | Scope
Add Above | Ctrl+Alt+Up Arrow | DataMapper
Add Below | Ctrl+Alt+Down Arrow | DataMapper
Auto Layout | Ctrl+K, Ctrl+D | DataMapper
Show Properties | Shift+F4 | DataMapper

JsonSchema Keys

Command | Shortcut | Scope
Add Additional Array Items | Ctrl+J, Ctrl+E | JsonSchema
Add Additional Properties | Ctrl+J, Ctrl+I | JsonSchema
Add AllOf | Ctrl+J, Ctrl+L | JsonSchema
Add AnyOf | Ctrl+J, Ctrl+Y | JsonSchema
Add Array Item with no type (any) | Ctrl+J, Ctrl+A | JsonSchema
Add Child Schema | Ctrl+J, Ctrl+S | JsonSchema
Add Definition with no type (any) | Ctrl+J, Ctrl+D | JsonSchema
Add Not | Ctrl+J, Ctrl+N | JsonSchema
Add OneOf | Ctrl+J, Ctrl+O | JsonSchema
Add Pattern Property | Ctrl+J, Ctrl+T | JsonSchema
Add Property with no type (any) | Ctrl+J, Ctrl+P | JsonSchema
Add Required Property | Ctrl+J, Ctrl+R | JsonSchema

Project Keys

Command | Shortcut | Scope
Add existing project item | Shift+Alt+A | Project
Add new project item | Ctrl+Shift+A | Project

See Also

Keyboard Macros
Keyboard Shortcuts By Category
Keyboard Shortcuts


Keyboard Macros
User Interface Guide > Keyboard Macros

Glossary Item Box

Keyboard macros make it possible to automate repetitive tasks. You can start to record a macro, at which point each key press is recorded, this sequence can then be played back multiple times.

Recording a macro

The toolbar contains the 'Record Macro' command icon [image], this is enabled when a text editor has focus.

When clicked a macro recording is started and additional commands are shown

- Pause macro recording, temporarily stops the macro recording, pressing this again re-starts recording

- Stop macro recording, ends this macro recording, making it available to be played back.

- Cancel macro recording, cancels the recording, discarding the current recording.

The 'Record Macro' command can also be invoked using the keyboard short cut Ctrl-Shift-R.

Replaying a macro

Once a macro has been recorded the playback icon [image] is visible on the toolbar.

Pressing this will playback the previously recorded macro. The same macro can be replayed multiple times.

The 'Replay Macro' command can also be invoked using the keyboard short cut Ctrl-Shift-P.

Macro recording hints and tips

  • Become familiar with other keyboard shortcut commands
  • You can use find to get to the text you are interested in (F3)
  • Use Ctrl-Left Ctrl-Right to jump words
  • Use the clip board.
  • When recoding a macro that will be replayed for multiple lines, start the recording at the start or end of the line and ensure the cursor is returned to the start/end of the next line when the macro is complete.

See Also

Keyboard Shortcuts


Visual Studio Extension
Send Feedback
User Interface Guide > Visual Studio Extension

Glossary Item Box

The User Interface for the visual studio plug-in is much the same as the Liquid XML Studio standalone application. However some of the menu items are a little different.

This section covers the differences between the documented interface for Liquid XML Studio and the Visual Studio Environment.


Window Layout
Send Feedback
User Interface Guide > Visual Studio Extension > Window Layout

Glossary Item Box

Docking Windows

The Visual Studio layout manager is extremely flexible allowing you to easily make the most of your work space on single or dual monitor configurations.

There are 4 tool windows used by the XML Schema Editor, these can be shown via the 'View' Menu.

The Global Component Locator and the Documentation menu items are only visible when the XML Schema editor the active editor.

Fl

©2001-2019 Liquid Technologies Limited. All Rights Reserved.
Liquid XML Studio | XML Data Binder | XML Editor | XML Schema Editor | WSDL Editor | XPath Viewer | Web Service Tools


Associating a schema with an XML Document in Visual Studio
Send Feedback
User Interface Guide > Visual Studio Extension > Associating a schema with an XML Document in Visual Studio

Glossary Item Box

Validation and Intellisense

For Validation and intellisense to operate correctly Microsoft Visual Studio needs to know the XML Schema that describes your XML Document.

The rules for finding the schema are as follows.

Visual Studio shows you the schema that will be used to perform validation and provide intellisense in the Properties tool window in the "Schemas" property

In this example the schema "SalesCatalogue.xsd" will be used.

Changing the schema mappings

You can alter the schema used by selecting the '...' button.


Command Line Interface
User Interface Guide > Command Line Interface

Glossary Item Box

XML Studio supports a basic command line interface. The main use of this is to allow the generation of documentation from scripts, this can be done via the /XsdDoc options.

You can not use relative paths (all paths must be fully qualified)
Generating XSD Documentation via the Command Line Copy Code
XmlStudio c:\samples\fpml-main-4-0.xsd /close  /XsdDoc /XsdDocOut=c:\samples\FpMLDocs /XsdDocTitle="Fpml 4.0"

See Also

XSD Editor
XSD Editor Generate Documentation Cmd Line Interface

Data Mapping
Command Line Options


Tip of the Day Dialog
User Interface Guide > System Dialogs > Tip of the Day Dialog

Glossary Item Box

Tips are shown the first time you use a feature.

They are there to provide a brief overview of the item you have just selected.

You can disable then using the 'Don't show me this again' check box, or disable/re-enable all of them in the options.

See Also

Options
Tip of the Day Options


Save Files Dialog
Send Feedback
User Interface Guide > System Dialogs > Save Files Dialog

Glossary Item Box

Shows a list of all the unsaved files that are open.

'Yes' will save the changes to all the files shown.

'No' will NOT save the changes to any of the files, and will continue with the action that prompted the dialog (typically closing the application or all the windows).

'Cancel' will do nothing and cancel the action that prompted the dialog.


New Project Dialog
User Interface Guide > System Dialogs > New Project Dialog

Glossary Item Box

Allows you to create a new project. When the new project is created or an existing project is opened, the contents are shown in the Project Window.

Create Project Folder

Select this option to create a folder for the project file, using the name of the project.

Add to Source Control

Select this option to add the new project to source control using the default source control provider. Note: This option is not available if the current provider is set to 'No Source Control'.

See Also

Projects
Projects Overview
Source Control Integration


Find and Replace
User Interface Guide > System Dialogs > Find and Replace

Glossary Item Box

The Find and Replace dialog can be activated in a number of ways

Shortcut keys

Ctrl-F | Find
Ctrl-Shift-F | Find in Files
F3 | Find Next
Shift-F3 | Find Previous
Ctrl-F3 | Find next selected
Ctrl-H | Replace

Toolbar

 | Find
Find In Files | Find In Files
Replace | Replace

Menu

The find/replace dialog works in 3 modes, quick find, quick replace and find in files.

Find In Files

See Also

User Interface
Find Results Window


Goto Line Dialog
Send Feedback
User Interface Guide > System Dialogs > Goto Line Dialog

Glossary Item Box

Allows you to go to a specific line number in the file.

Line numbers on 1 based.

accessed via Ctrl-G


Feedback Dialog
Send Feedback
User Interface Guide > System Dialogs > Feedback Dialog

Glossary Item Box

Provides a means to provide us feedback about the product.

If you are reporting a bug then please try to provide a sample that shows the problem, and remember to include your email address if you want to hear back from us!


Critical Error Dialog
Send Feedback
User Interface Guide > System Dialogs > Critical Error Dialog

Glossary Item Box

If things go wrong you are likely to see this window.

Typically the application recovers from such errors, and will continue to function normally, but its always a good idea to save your work at this point!

In order to allow us to diagnose and fix the problem you have just encountered.
Please include as much information about the problem as you can.
It is much easier for use to fix the problem if we can reproduce it. So if you can consistently make the error occur tell us how you do it, and include all the files that are needed (including any imported or included ones).

An error report like this allows use to find and fix the problem.

  1. Opened the application
  2. Loaded sample1.xsd (attached)
  3. Deleted the element Address->Post code
  4. Application Crashed.

All information is now sent over the internet securely using 256bit SSL.


External Tools
User Interface Guide > System Dialogs > External Tools

Glossary Item Box

External tools allows 3rd party applications to be invoked from within the Liquid XML Studio environment. This makes it easy to shell out to Web Browsers, Html Editors, Ftp clients etc.

External Tools Menus

External tools can be invoked via the Tools->External Tools menu. They can also be placed onto other toolbars and menus by customizing the menus.

Tools containing references to the current are only available when an open document is selected

Tools can be added and edited using the "Edit External Tools" menu item.

External Tools Editor

The form allows tools to be created removed and edited. For more information about configuring external tools see the External Tools Editor.

A maximum of 10 external tools can be configured

See Also

User Interface
External Tool Editor
Editing Menus and Toolbars


External Tool Editor
User Interface Guide > System Dialogs > External Tools > External Tool Editor

Glossary Item Box

External Tools allow 3rd party applications to be invoked within the Liquid XML Studio Environment, form more information see External Tools.

Once configured external tools can be assigned shortcut keys and added to other menus and toolbars, see customizing menus and toolbars.

External Tool Exitor

Menu Text

This is the name that will appear in the drop down menu.

Executable

The executable to be invoked. This can contain Windows Environment variables (i.e. %windir%, %temp%, %homepath% etc)

Working Directory

The working directory that the executable will be run with, this can also contain Windows Environment variables.

Argument

The arguments passed to the application. This can contain Windows Environment variables, but also includes an additional set of substitutions.

Addition Substitutions

%FILE_NAME% | if the full filename is c:\temp\test.txt, then this is test.txt
%FILE_PATH% | if the full filename is c:\temp\test.txt, then this is c:\temp
%FILE_EXT% | if the full filename is c:\temp\test.txt, then this is txt
%FILE_FULLNAME% | if the full filename is c:\temp\test.txt, then this is c:\temp\test.txt
%FILE_NAME_WITHOUT_EXT% | if the full filename is c:\temp\test.txt, then this is txt
%TIME% | i.e. hhmmss
%HOUR% | i.e. hh
%MINUTE% | i.e. mm
%SECOND% | i.e. ss
%DATE% | i.e. yyyymmdd
%YEAR% | i.e. yyyy
%MONTH% | i.e. mm
%DAY% | i.e. dd

Argument Substitutions

A list of additional substitutions that can be used in the Arguments section.

Ensure that quotes are placed around path variables where applicable. If you fail to do this your path may appear to the application to be 2 arguments if it contains a space. I.e.

Using the following example :

Executable : C:\Windows\Notepad.exe
Arguments : %FILE_FULLFILENAME% (which will expand to c:\My Files\test.xml).

Resulting command Line

C:\Windows\Notepad.exe c:\My Files\test.xml

Notepad will interpret this as 2 arguments "c:\My" and "Files\test.xml".

So the Argument should be surrounded with quotes i.e. "%FILE_FULLFILENAME%".

See Also

User Interface
External Tools
Editing Menus and Toolbars


Editing Menus and Toolbars
Send Feedback
User Interface Guide > System Dialogs > Editing Menus and Toolbars

Glossary Item Box

All the menus and toolbars in the application can be customized using the customization menu on the end of each toolbar

The toolbars available in a given editor can be selected using the toolbar tab.

Menus and toolbars can be modified by dragging commands from the dialog onto the toolbar or menu where you want them.

This includes the External Tools.

Keyboard shortcuts can also be re-map using the Keyboard tab

Keyboard shortcut 'Chords' are not supported.

Changes to External Tools may not be reflected in the menu editor until after the application is re-started.


Projects Overview
Projects > Projects Overview

Glossary Item Box

Liquid XML Studio projects are contains that allow you to group related files. The project contains a Project 'Root' node that represents the physical project file, and a tree of 'Group' nodes and 'File' nodes. A representation of the project tree can be seen in the Project Window.

The 'Group' nodes represent a logical placeholder for sub-groups and files. The 'File' nodes represent physical files on disk. There are no limits as to which files can go into which groups, i.e. files from many different folders can be placed inside the same group.

The 'File' nodes are shown in the project tree with their associated image. Clicking the file node will show the files properties in the Properties Window. Double clicking the file will open it within the appropriate editor view. If the project has been associated with source control, the file status indicator will also be shown next to each file.

Project files are stored with the file extension '.lxsproj'. These files can be added to source control along with the containing project files.

Temporary hidden project option files are also created with file extension 'lxsopt'. These temporary files should not be stored in source control and can be discarded.

See Also

Source Control Integration

User Interface
Project Window
Properties Window


Source Control Integration
Projects > Source Control Integration

Glossary Item Box

Liquid XML Studio's source control integration allows you to safely store your files within a source control repository directly from within Liquid XML Studio.

Supported source control systems are Microsoft SCC API compliant systems (e.g. Microsoft SourceSafe 2005) and the TortoiseSVN Command Line.

You are asked to select a Source Control Provider the first time you create a new project. You can change the default provider using Tools->Options.

Microsoft SCC API compliant systems (e.g. Microsoft SourceSafe 2005)

Source control integration with these systems allows the following:

Create Project, Add files, Check-in files, Check-out files, and Get latest version. These options are file specific by right-clicking the files (or groups) in the Project Window.

TortoiseSVN Command Line

TortoiseSVN command line integration provides a simple wrapper over the TrotoiseSVN command line interface.

See Also

Projects Overview
Check In Files
Check Out Files

User Interface
Project Window
New Project Dialog


Debugger Overview

Glossary Item Box

Features

  • step by step debugging
  • Breakpoints
  • Local variables Tool Window
  • Watch expression Tool Window
  • Call stack Tool Window
  • Step Over
  • Step Into
  • Step Out
  • Pause

Liquid XML Studio supports a variety of Engines for different technologies, and offers a standard debugging interface and experience over all of them.

Currently supported debuggers

  • XSLT
  • XQuery

See Also

Debugger
Local Variables Window
Watch Window
Breakpoints ToolWindow
Call Stack Window
Options Window
Debugger Toolbar


Debugger Toolbar
Debugger Overview > Debugger Toolbar

Glossary Item Box

Liquid XML Studio Debugger Toolbar

The debugger toolbar is only shown then the active editor supports debugging (currently XQuery and XSLT).

The debugger has 3 states, stopped, running and paused. The Watch, Local Variable, and call stack windows are only valid when the debugger is paused.

Debugger Start | F5 | Start Debugger | Starts the Debugger. If no breakpoints are set then the execution will run to completion. While its running breakpoints can be set, and the debugger can be paused manually.
Debugger Pause | Ctrl-Break | Pause Debugger | Causes the debugger to break on the next operation and enter the paused state. Only enabled when the debugger is in a running state.
Debugger Stop | Shift-F5 | Stop Debugger | Causes the debugger to stop. Only enabled when the debugger is in a running or paused state.
Debugger Toggle Breakpoint | F9 | Toggle Breakpoint | Toggles a break point at the current cursor location. If a breakpoint already exits at this location it is removed. If a breakpoint does not exist it is created.
Debugger Step Over | F10 | Step Over | Starts the execution running, pausing it again when the execution has moved past the current operation.
Debugger Step Into | F11 | Step Into | Starts the execution running, pausing it again when the execution has moved inside the current operation. If the current operation can not be debugged, then execution stops on the next instruction.
Debugger Step Out | Shift-F11 | Step Out | Starts the execution running, pausing it again when the execution has completed all the operations in the current call stack frame, and has stepped back to the caller.
Debugger Compile | Ctrl-Shift-B | Compile | Compiles the current program, any errors are shown in the error window. This is only enabled when the debugger is stopped, and no execution is being performed.
Debugger Execute | Shift-F5 | Execute | Executes the program without the debugger.
Debugger Options | F2 | Options | Shows the options for the currently selected debugger
 |  | Engine Selection | The currently selected debugger

See Also

Debugger
Local Variables Window
Watch Window
Breakpoints ToolWindow
Call Stack Window
Options Window


Options Window
Debugger Overview > Options Window

Glossary Item Box

The options window is accessed using the Debugger Options icon on the toolbar or using the shortcut key F2.

The Dialog window displayed is specific to the Debugger engine that is selected.

  • XSLT EngineSaxon
  • XSLT Engine.Net
  • XQuery Engine Saxon

Options can only be changed when the debugger is stopped.

See Also

Debugger
Local Variables Window
Watch Window
Breakpoints ToolWindow
Call Stack Window
Debugger Toolbar


Overview
Send Feedback
Data Mapping > Overview

Glossary Item Box

Liquid Data Mapper provides an intuitive graphical interface for designing data transforms. Transforms can map multiple XML input files to multiple XML output files while performing conditional logic, filtering, string manipulation, statistical functions and much more.

Transforms can be executed within the environment or debugged by single stepping through them. The debugger allows the internal state of the engine to be viewed, and shows the path of the execution.

Data Mapper Debugger

Currently the engine supports CSV, Database, EDI, JSON, XML and Web Services.


Projects
Send Feedback
Data Mapping > Projects

Glossary Item Box

Data Mapping transforms (.dm files) can be constructed in isolation, but including them in a project has several advantages

  • Sub Functions can be created and used. Sub functions need to be resolved and this can only be done within the context of a project. Building up a library of sub functions is a good way to boost productivity and simplify the resulting transforms.
  • Files within a project can be integrated into a source control system (SourceSafe, SVN etc).
  • Makes them easier to work with and manage.


Data Types
Send Feedback
Data Mapping > Data Types

Glossary Item Box

Primitive Data types

Data Type | Range | Description
Binary |  | Binary data, an array of bytes.
Boolean | true/false | true, false
Byte | 0 to 255 | Unsigned 8-bit integer
Char | A Unicode character | Represented as an unsigned 16-bit integer
Date | January 1, 0001 to December 31, 9999 | Represents a date.
DateTime | 00:00:00.0000000, January 1, 0001 to 23:59:59.9999999, December 31, 9999 | Represents an instant in time, typically expressed as a date and time of day. With a millisecond precision.
Decimal | -79228162514264337593543950335 to 79228162514264337593543950335 (28-29 significant digits) | The decimal keyword indicates a 128-bit data type. Compared to floating-point types, the decimal type has more precision and a smaller range, which makes it appropriate for financial and monetary calculations.
Double | ±5.0 × 10−324 to ±1.7 × 10308 (15-16 significant digits) | Stores a 64-bit floating-point value.
Float | -3.4 × 1038 to +3.4 × 1038 (15-16 significant digits) | Stores a 32-bit floating-point values
Guid | 16 byte identifier | Represents a globally unique identifier (GUID).
Int16 | -32,768 to 32,767 | Signed 16-bit integer
Int32 | -2,147,483,648 to 2,147,483,647 | Signed 32-bit integer
Int64 | -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 | Signed 64-bit integer
SByte | -128 to 127 | Signed 8-bit integer
String |  | The string type represents a sequence of zero or more Unicode characters
Time | 00:00:00.0000000 to 23:59:59.9999999 | Represents a time, with a millisecond precision.
TimeSpan | -10,675,199 days to +10,675,199 days. | TimeSpan represents a duration of time, it can be negative or positive and has a millisecond precision.
UInt16 | 0 to 65,535 | Unsigned 16-bit integer
UInt32 | 0 to 4,294,967,295 | Unsigned 32-bit integer
UInt64 | 0 to 18,446,744,073,709,551,615 | Unsigned 64-bit integer

Complex Data Types

Data Type | Description
Node | A structured data container (i.e. an XML node), can also contain child Nodes. This structured data comes from a source component (XML, DB, data source).

Data Type Groups

The following types represent types of data, Any may be any type at all, Atomic maybe any primitive type, and Numeric may contain any of the numeric types. They are typically used as inputs on components where the component can deal with a number of input data types.

Data Type | Allowable Types
Any | Binary, Byte, Char, Date, DateTime, Decimal, Double, Float, Guid, Int16, Int32, Int64, Node, SByte, String, Time, TimeSpan, UInt16, UInt32, UInt64
Atomic | Binary, Byte, Char, Date, DateTime, Decimal, Double, Float, Guid, Int16, Int32, Int64, SByte, String, Time, TimeSpan, UInt16, UInt32, UInt64
Numeric | Byte, Decimal, Double, Float, Int16, Int32, Int64, SByte, UInt16, UInt32, UInt64


Using Set Functions
Data Mapping > Using Set Functions

Glossary Item Box

With Set functions, you can use the Data Mapper to sort, filter and manipulate your mapped data in various ways. Some of the Set functions vary considerably depending on the Node and Context inputs you provide. In this section we will go through an example in which we use a few of the more complex Set functions, outlining how to get effective use out of the Context and Node inputs.

Look at the following input source data, from which complies with the books_source.xsd schema:

Source XML Copy Code
<library>
 <section name="Fiction">
  <book>
   <title>War and Peace</title>
   <author>Leo Tolstoy</author>
   <publication>1869</publication>
   <isbn>1234567890</isbn>
   <note>Abridged</note>
   <note>Harper Collins</note>
   <note>Classics</note>
   <room>342</room>
   <room>12</room>
  </book>
  <book>
   <title>Pride and Prejudice</title>
   <author>Jane Austen</author>
   <publication>1813</publication>
   <isbn>2345678901</isbn>
   <note>Penguin</note>
   <room>45</room>
   <room>109</room>
   <room>45</room>
  </book>
  <book>
   <title>Animal Farm</title>
   <author>George Orwell</author>
   <publication>1945</publication>
   <isbn>3456789012</isbn>
   <note>1st Edition</note>
   <note>Random House</note>
   <room>50</room>
   <room>120</room>
  </book>
 </section>
 <section name="Non-Fiction">
  <book>
   <title>Testament of Youth</title>
   <author>Vera Brittain</author>
   <publication>1933</publication>
   <isbn>0987654321</isbn>
   <note>Biography</note>
   <room>12</room>
  </book>
  <book>
   <title>Meditations on First Philosophy</title>
   <author>Rene Descartes</author>
   <publication>1641</publication>
   <isbn>9876543210</isbn>
   <note>Philosophy</note>
   <note>Latin</note>
   <room>43</room>
   <room>67</room>
  </book>
  <book>
   <title>The Origin of Species</title>
   <author>Charles Darwin</author>
   <publication>1872</publication>
   <isbn>3456789012</isbn>
   <note>6th Edition</note>
   <note>Science</note>
   <room>11</room>
  </book>
 </section>
</library>

Notice that the source has multiple nested elements. We are going to use this data to demonstrate the Set functions in the Data Mapper, with particular focus on Filter, Sort and Distinct, although we will cover some of the other options along the way. Our target schema is books_target.xsd:

The data models library books for a school or college. Here is the Mapper with source and target imported:

Target and Source

Filter

First let's filter the data while we map it. Let's say that we only want to map items representing books published since 1800. Drag a Filter component onto the Mapper.

Filter Function Added

The Filter function takes two inputs. The Nodes input represents the items you want to filter, and the Bool input represents a boolean indicating the result of a test. Since we want to only map those books published since 1800, we need to create a conditional. Each time the Mapper iterates through the data, when it encounters a "book" element, we want it to check the "publication" value to determine whether it is at least 1800. To accomplish this, drag a Greater Than or Equal component from the Comparator section onto the Mapper.

Filter Function Added

Now we need to represent the value of 1800, so drag a Constant Value from the Data Type section onto the Mapper.

Filter Function Added

Right-click the Constant and choose Show Properties. Choose an integer type from the Data Type drop-down list and enter "1800" as the Value.

Connect the "publication" item in the XML Reader to the Value 1 input in the Greater Than or Equal function, then the Constant output to the Value 2 input.

Reader and Constant to Conditional

Now the output of the conditional Greater Than or Equal test will be true if the publication date for a book is at least 1800, false if not. Connect the output of the Greater Than or Equal function to the Bool input of the Filter function. Remember what it is that we want to filter depending on the date: the "book" element. Connect the "book" output in the XML Reader to the Nodes input in the Filter function. Notice once the Filters Nodes input is connected an output node is created which mirrors the input type.

Reader to Filter

Now the output of the Filter function is the set of "book" elements with "publication" values greater than or equal to 1800 - those elements for which the conditional test returned a true value. Each time the Mapper encounters a "book" element, it carries out the conditional test. If the test returns true for a particular item, the Filter function will pass it forward as output. If a test returns false, that item will not be mapped as output from the Filter function.

We want to carry out further transformations on the element before feeding it into the XML Writer, so don't connect its output just yet.

Sort

Let's now look at sorting the data. Assume we want to sort the "book" elements once they have been filtered. We want to sort them on the "title" item value. Drag a Sort function from the Component Palette onto the Mapper.

The Sort function takes two inputs. The Nodes input represents the nodes you want to sort, and the Sort Key represents the item you want to sort these nodes on. Since we want to sort on the title, connect the Sort Key input to the "title" output in the XML Reader. Connect the Nodes input to the Filter function output so that we sort the "book" items already filtered. We want each "title" value to determine the ordering of its parent "book" element within each "section" - but we are only going to be mapping those "book" elements we have already filtered.

Reader to Sort

Now connect the Sort output to the "volume" input in the XML Writer.

What we have done so far is mapped the "book" element in the source to the "volume" element in the target, filtering and sorting it at the same time. Although we have used the "title" and "publication" items, we have not yet mapped them. They are purely being used as reference points for the parent "book" element at this stage.

Distinct

Let's now incorporate the Distinct function. If you look back at the source XML, particularly the second "book" element, you will notice that the list of "room" elements contains duplicate values. Let's assume that this is a consequence of the source application, perhaps due to the data being corrupted in some way, but that we don't want to map any duplicates into our target data. Drag a Distinct function onto the Mapper.

Distinct Function Added

The Distinct function takes two inputs. The Value input represents the item you want to map only unique instances of. The Context input represents the context in which the Value must be unique.

We want to make sure we only map values of the "room" element that are unique within each parent "book" element. In other words, the same "room" element can appear more than once within the data, as long as it doesn't appear more than once for each "book". Connect the "book" output in the XML Reader to the Context input in the Distinct function, since this is the context that the item must be distinct within. Connect the "room" item in the XML Reader to the Value item in the Distinct function.

Now connect the Distinct output to the "used_in" input in the XML Writer, so that only unique values will be included in each "volume" item.

Distinct to Writer

Limits

Some of the Set functions allow you to limit the range or number of values that are mapped. Let's assume that we want to impose a limit on the number of "note" items we map. If we want to map only one item, we can use either the First or Last function - these map the first and last items encountered respectively. However, let's use the slightly more complex Top function here. With Top, you can map the first n items. Drag a Top function onto the Mapper.

We need to specify how many items we want to map. Drag a Constant onto the Mapper and right-click it, choosing Show Properties. Enter an integer Data Type from the drop-down list and the number 2 as the Value.

Count Constant Properties

Connect the Constant output to the Count input of the Top function, and the Nodes input to the "note" output in the XML Reader.

Connect the Top output to the "info" input in the XML Writer.

Now we are ready to map the remaining connections. Connect "library" to "dept_library", "section" to "department", "name" to "name", "title" to "title", "author" to "writer", "publication" to "year", and "isbn" to "ref".

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<dept_library>
 <department>
  <name>Fiction</name>
  <volume title="Animal Farm" writer="George Orwell">
   <year>1945</year>
   <ref>3456789012</ref>
   <info>1st Edition</info>
   <info>Random House</info>
   <used_in>50</used_in>
   <used_in>120</used_in>
  </volume>
  <volume title="Pride and Prejudice" writer="Jane Austen">
   <year>1813</year>
   <ref>2345678901</ref>
   <info>Penguin</info>
   <used_in>45</used_in>
   <used_in>109</used_in>
  </volume>
  <volume title="War and Peace" writer="Leo Tolstoy">
   <year>1869</year>
   <ref>1234567890</ref>
   <info>Abridged</info>
   <info>Harper Collins</info>
   <used_in>342</used_in>
   <used_in>12</used_in>
  </volume>
 </department>
 <department>
  <name>Non-Fiction</name>
  <volume title="Testament of Youth" writer="Vera Brittain">
   <year>1933</year>
   <ref>987654321</ref>
   <info>Biography</info>
   <used_in>12</used_in>
  </volume>
  <volume title="The Origin of Species" writer="Charles Darwin">
   <year>1872</year>
   <ref>3456789012</ref>
   <info>6th Edition</info>
   <info>Science</info>
   <used_in>11</used_in>
  </volume>
 </department>
</dept_library>

The Set functions have all been applied as part of the mapping process. Only those "volume" elements whose publication date is at least 1800 are included (Filter function). A maximum of 2 "info" elements are included per "volume" (Top function). Within each "department", the "volume" elements are sorted alphabetically by "title" (Sort function). Finally, the "used_in" elements are all unique within their parent elements (Distinct function).

The effect of some of the Set functions depends significantly on what Node or Context input you give them. When a Set function takes a Nodes or Context input, you are specifying that the action must be performed only within a certain context. For example, the "volume" elements above are sorted alphabetically within their parent "department" elements, not within the document as a whole. Similarly, the Top restriction of 2 means: 2 per "volume", not 2 per "department" or "dept_library". To gain an intuitive sense of how these functions work, it's worth experimenting by altering the Nodes and Context inputs to see the difference in output data.

See Also

Using Aggregate Functions

Set
Distinct
Filter
First
GetAt
Last
Position
Sort
Top


Dynamic Output Values
Data Mapping > Dynamic Output Values

Glossary Item Box

Some Components take an input node set, apply some processing and output the modified node set, however the structure of the input and output data remains the same.

Examples of such components include Filter, Sort, First, Last, GetAt etc.

In the diagram above we can see that the "Filter" component takes its nodes from the XML Reader->sports_club->club->member. At the point when the Filter->Nodes connection point input is connected the filters output connection point is created this takes its type from the Filter->Nodes input and so is of type "'member".

Typically any further processing is now performed against the output of the Filter component.

Referring back to the values in the XML Reader->sports_club->club->member will likely yield undesirable results.

See Also

Set
Filter
First
GetAt
Last
Sort


SubFunctions
Send Feedback
Data Mapping > SubFunctions

Glossary Item Box

Sub Functions make it possible to create and re-use your own functions. This has a number of key advantages;

Structure

Transforms can quickly become crowded with implementation detail making them difficult to read and maintain. By pushing functionality into sub functions that perform a specific task, you can keep the transforms easy to understand and simpler to maintain and edit.

Reuse

Sub functions can be used to build up a library of your own functions that can be incorporated into a number of other transforms and sub functions. Sub functions make reuse possible while keeping a project maintainable and modular enough for teams to work collaboratively on.

Creating a Sub Function

A Sub Function can be created by selecting one or more related Components and clicking on the "Create Function" ( [image]) command.

The components selected above make the first letter of a string uppercase and the rest lower case.

A Sub Function is created from them by selecting the components (drag select, or click holding down the ctrl key), the clicking the "Create Function" ( [image]) command on the toolbar or context menu.

Once a sub function has been created the new transform is much easier to understand, and our new function is simple enough to be understandable and maintainable.

Notice the inputs to the sub function are shown in green, and the outputs in red.

The inputs and outputs can be primitive types (as in this example, or they can be complex types like database tables or XML schema elements).

Once a Sub Function has been defined it can be re-used as many times as needed from any Transform or Sub Function in the project.

Sub functions can not be recursive, i.e they can not call themselves, either directly or via a nested sub function .

So the following is valid A calls B calls C, but now C can NOT call A or B.

Once a Sub Function has been created it can be seen in the Component Palette and used by dragging it onto the transform.


Combining String Functions
Data Mapping > Combining String Functions

Glossary Item Box

Using individual functions is often self-explanatory, but the Data Mapper is most useful when you combine functions. Here we are going to combine some functions to achieve a typical String transformation. For example, the Upper and Lower functions naturally convert input Strings to upper and lower case. However, you may find yourself in a position where you have to convert certain characters but not others. In such cases you can make use of multiple functions to achieve the desired result.

Let's assume that we want to map a text String so that the initial character is in upper case, but only the initial character. All other characters must be mapped in lower case. We will use school_source.xsd, a schema inferred from the following input XML for demonstration, in which the text includes a mix of upper and lower case characters:

Source XML Copy Code
<school>
 <classroom door_number="14">
  <pupil>
   <name>arTHur</name>
   <age>12</age>
  </pupil>
  <pupil>
   <name>tOby</name>
   <age>11</age>
  </pupil>
  <pupil>
   <name>joNatHON</name>
   <age>12</age>
  </pupil>
 </classroom>
 <classroom door_number="21">
  <pupil>
   <name>maRY</name>
   <age>12</age>
  </pupil>
  <pupil>
   <name>jiLL</name>
   <age>11</age>
  </pupil>
 </classroom>
</school>

We're intentionally including lower case initial letters with arbitrary upper case letters to demonstrate the function we are building here. The output XML will have the following structure, defined in school_target.xsd:

Target XML Copy Code
<institution>
 <class>
  <room>364</room>
  <child c_age="14"><c_name>Thomas</c_name></child>
  <child c_age="15"><c_name>Michael</c_name></child>
  <child c_age="14"><c_name>Sarah</c_name></child>
 </class>
 <class>
  <room>180</room>
  <child c_age="14"><c_name>Jennifer</c_name></child>
  <child c_age="15"><c_name>Claire</c_name></child>
 </class>
</institution>

First, drag your source and target onto the Mapper area, selecting sample data and inferring Schema definitions for each if necessary. Match up all items except the "pupil/child" names:

Target and Source

Everything except the first character is going to be mapped in lower case, so let's convert the whole String to lower case to begin with. Drag the Lower function into the Mapper from the String section of the Component Palette.

The Lower String Function

Connect the Lower input to the "name" output in the XML Reader. This gives us a reference to the entire String in lower case. Later we will concatenate the first character, converted to upper case, with the rest of the String, left in lower case.

The Lower Function Input

Let's handle converting the first character to upper case. Add a Left function to your Mapper, connecting the output of Lower to its String input.

Connecting Lower to Left

We only want the first character, so the length is going to be 1. To specify this, drag a Constant Value from the Data Type section. Right-click the Constant and select Show Properties. Choose one of the integer data types and enter "1" as the value.

Setting the Constant Properties

Connect the Constant output to the Left Length input.

Adding the Constant and Left

Now we have the first character, let's convert it to upper case by dragging an Upper function over and connecting its input to the Left output.

Connecting Left to Upper

Now we need to combine our upper case initial letter with the rest of the String before we can feed it into the XML Writer. To do this, drag Concat onto the Mapper and connect the Upper output to its first String input.

Connecting Upper to Concat

Now we need to retrieve the second part of the input String, i.e. the part after the first character. Let's use a Right function, connecting its output to the second String Concat input.

Connecting Right to Concat

Connect the Right String input to the output from the Lower function.

Connecting Lower to Right

Now we need to specify a length representing the original String minus one, so that we ignore the initial letter, which we are converting to upper case and feeding into the Concat function already. First get the length of the original String by dragging a Length function over and connecting its input to the Lower output.

Connecting Lower to Length

Now we need to subtract 1 from the length in order to feed the correct number into the Right function. Drag a Subtract function from the Maths section. Connect the Length output to the first Subtract input. We already have a Constant Value for the number 1, so let's connect its output to the second Subtract input.

Connecting the Subtract Inputs

Now the output of the Subtract function is the value we want to use as the length for the second part of the String. The result of the Right function is what we want the second part of our concatenation operation to use, so connect the Subtract output to the Length input of the Right function.

Connecting Subtract to Right

Finally, connect the Concat output to the XML Writer input to complete the mapping definition.

Execute the mapping ( Execute) and you should receive the following output:

Output XML Copy Code
<institution>
 <class>
  <room>14</room>
  <child c_age="12">
   <c_name>Arthur</c_name>
  </child>
  <child c_age="11">
   <c_name>Toby</c_name>
  </child>
  <child c_age="12">
   <c_name>Jonathon</c_name>
  </child>
 </class>
 <class>
  <room>21</room>
  <child c_age="12">
   <c_name>Mary</c_name>
  </child>
  <child c_age="11">
   <c_name>Jill</c_name>
  </child>
 </class>
</institution>

In the above example we could have alternatively used the SubString function instead of the Left and Right functions. With SubString, the inputs are the String, the start position and end position. This means that in the above case we would have still needed the Length function, and could have used the number 1 Constant together with an additional zero Constant to specify the start and end indices for the two parts of the String.

If you think of your data mapping actions in terms of what their inputs and outputs are in each case, you will develop and intuitive sense of how to use the functions effectively. Other String functions to try combining include Replace (which replaces every instance of a Search String in the target String), the Trim functions (which get rid of whitespace, essential when transferring data from A to B) and the CodeToChar/ CharToCode functions (which transform values between character and Unicode data).

XML data comes from many different types of source and is used in a host of application contexts, so being able to transform your text Strings in a variety of ways is often vital.

The string manipulation performed in the sample above results in a fairly complex transform. In order to simplify this is possible to convert it into one or more Sub Functions, which can then be re-used in other transforms.

See Also

Variable Function Inputs
SubFunctions

String
Lower
Upper
Length
Left
Right
Concat
SubString
Replace
Trim
CodeToChar

Values
Constant

Maths
Subtract


Analyzing Numerical Input
Data Mapping > Analyzing Numerical Input

Glossary Item Box

It goes without saying that the data mapping process often involves manipulations of data values, rather than straight translations to new Schema structures. The mapping functions are designed to facilitate this process. Among the functions, particularly in the Maths section, there are a number of options you can use to analyse numerical input. Using these, your output data can include processed information based on the content of the input data. In this section, we will demonstrate a typical case in which the output data comprises an analysis of some aspect of the input source.

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using payroll_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<payroll>
 <employee payroll_id="126">
  <rate>9.45</rate>
  <hours>35</hours>
  <bonus>70.00</bonus>
  <funding>350</funding>
 </employee>
 <employee payroll_id="129">
  <rate>10.50</rate>
  <hours>30</hours>
  <bonus>150.00</bonus>
  <funding>500</funding>
 </employee>
 <employee payroll_id="130">
  <rate>8.90</rate>
  <hours>40</hours>
  <bonus>100.00</bonus>
  <funding>550</funding>
 </employee>
 <employee payroll_id="133">
  <rate>11.20</rate>
  <hours>40</hours>
  <bonus>200.00</bonus>
  <funding>600</funding>
 </employee>
</payroll>

For our target schema we will be using payroll_target.xsd, inferred from the following XML:

Target XML Copy Code
<wages>
 <payee>
  <ref>122</ref>
  <result type="remainder">30 full hours with a remainder of £45</result>
 </payee>
 <payee>
  <ref>125</ref>
  <result type="remainder">40 full hours with a remainder or £30</result>
 </payee>
 <payee>
  <ref>126</ref>
  <result type="remainder">35 full hours with a remainder of £25</result>
 </payee>
</wages>

The XML models payroll data for temporary staff within an organisation. The output is designed to capture some value calculated from the source, using the "type" attribute to indicate what the calculation result represents. Let's assume that we want to calculate the number of full hours each employee is budgeted for, and the remainder after that. We will need to carry out division and subtraction calculations to work out the weekly funding budget, before applying the Modulus function in conjunction with Cast and String functions. Here is the Data Mapper with source and target imported:

Data Mapper Source and Target

Drag the Maths Modulus function from the Component Palette into the mapping area:

We will use the Modulus component to calculate the remainder of the budgeted funding for each employee after full hours are deducted. First, we need to calculate the weekly funding budget to work from, which will be the full funding amount minus the bonus. Drag a Subtract function onto the Mapper, connecting its first input to the "funding" output in the XML Reader and its second input to the "bonus" output.

Reader to Subtract

Connect the output of the Subtract function to the Dividend input in the Modulus function. Next connect the "rate" output in the XML Reader to the "divisor" input in the Modulus function.

Reader to Modulus

Now we want to calculate the amount of hours paid for in addition to the remainder, so drag a Divide component onto the Mapper. Connect its first input to the output of the Subtract function and its second input to the "rate" output in the XML Reader, the same as what we did for the Modulus component itself.

Modulus and Divide

Now we want to discard the fractional part of the division result, as we are only interested in full hours, with the Modulus result representing the rest of the calculation. Let's cast the division result to an integer for this reason. Drag a Cast function from the Type section onto the Mapper. Right-click it and choose Show Properties, selecting an integer type.

Connect the Cast input to the output of the Divide function.

Now let's concatenate the results of these calculations into a String. Drag a ConcatAll function onto the Mapper, connecting its first String input to the output of the Cast component.

Now for the second part of our String we want to define some text, so drag a Constant Value onto the Mapper from the Data Type section. Right-click it, choosing Show Properties. Select a String Data Type and enter the following text as the Value: " full hours with a remainder of £".

Connect the Constant output to the second ConcatAll input.

Now we need to add another String to the ConcatAll function, so right-click its second input, choosing Add Below.

ConcatAll Add Below

Connect the output of the Modulus function to the third ConcatAll input.

Now connect the ConcatAll output to the "Element Value" input in the XML Writer, so that the concatenated String containing the calculation results is written into the "result" element.

Now we need to include the "type" attribute in the source, so add a Constant Value from the Data Type section. Right-click it and choose Show Properties. Choose a String Data Type and enter "remainder" as the value.

Connect the Constant output to the "type" input in the XML Writer.

Finally let's make the remaining input and output connections. We do not want to map all data items in the source, as we are only interested in certain values. Map "payroll" to "wages", "employee" to "payee" and "payroll_id" to "ref". We don't need to map anything to the "result" element as it will be written out each time the Mapper maps the addition result to it. Although we have used some of the remaining input values for calculations, we do not need to map them individually to the target, as we only want the calculation result.

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<wages>
 <payee>
  <ref>126</ref>
  <result type="remainder">30 full hours with a remainder of £5.95</result>
 </payee>
 <payee>
  <ref>129</ref>
  <result type="remainder">33 full hours with a remainder of £3.50</result>
 </payee>
 <payee>
  <ref>130</ref>
  <result type="remainder">51 full hours with a remainder of £5.00</result>
 </payee>
 <payee>
  <ref>133</ref>
  <result type="remainder">36 full hours with a remainder of £8.00</result>
 </payee>
</wages>

The output contains a String indicating the number of full hours and remaining budget for each employee. We have analysed the input data values during mapping, with the output containing a human-readable indicator of this processing. The transform functions therefore allow you to add a level of computation into your mapping activity, for example using output data for reporting purposes.

See Also

Using Aggregate Functions

Maths
Divide
Modulus
Subtract

Values
Constant

Type
Cast


Using Aggregate Functions
Data Mapping > Using Aggregate Functions

Glossary Item Box

Many of the Data Mapper functions use context inputs, including those in the Aggregate section. The output of these function varies depending on where you place the Context inputs. For example, you may wish to apply an Aggregate function such as Max, Average or Sum within the data source as a whole or within a parent node at a particular level. In this section we will work through examples using each of these three functions from the Aggregate section, outlining the impact of the Context input connection.

We will be using data related to retail figures for a sales company. As is often the case, as well as mapping the existing data we need to use the input data to calculate new figures to be included in the output data, such as the sales for the company as a whole as well as for individual regions, the average sales within regions and so on. We will be using the retail_source.xsd, inferred from the following XML data:

Source XML Copy Code
<retail>
 <region>
  <region_ref>125</region_ref>
  <outlet>
   <manager>James Jones</manager>
   <sales>350690</sales>
  </outlet>
  <outlet>
   <manager>Mark Simpson</manager>
   <sales>450880</sales>
  </outlet>
  <outlet>
   <manager>Linda Parks</manager>
   <sales>22300</sales>
  </outlet>
 </region>
 <region>
  <region_ref>102</region_ref>
  <outlet>
   <manager>Patricia Clark</manager>
   <sales>122000</sales>
  </outlet>
  <outlet>
   <manager>Frank Graham</manager>
   <sales>321560</sales>
  </outlet>
  <outlet>
   <manager>James Yates</manager>
   <sales>22800</sales>
  </outlet>
  <outlet>
   <manager>Ken Livingston</manager>
   <sales>665430</sales>
  </outlet>
 </region>
 <region>
  <region_ref>112</region_ref>
  <outlet>
   <manager>Laura Dean</manager>
   <sales>210090</sales>
  </outlet>
  <outlet>
   <manager>Stephen Watson</manager>
   <sales>30800</sales>
  </outlet>
 </region>
</retail>

For our first example, we will use the retail_target.xsd which is inferred from the following structure:

Target XML Copy Code
<brand>
 <peak_sales>112300</peak_sales>
 <area ref="143">
  <store manager="Jill Gray">
  23400
  </store>
  <store manager="Peter Thomson">
  112300
  </store>
  <store manager="Derek Roberts">
  78900
  </store>
 </area>
 <area ref="110">
  <store manager="Tom Brown">
  33280
  </store>
  <store manager="Kay Mitchell">
  45000
  </store>
 </area>
</brand>
Max

In the first instance, we want to map the maximum sales figure for the company as a whole, writing it to the "peak_sales" item you see above. Here is the Mapper with Source and Target imported:

Reader and Writer

We drag a Max function onto the Mapper, connecting its Context input to the "retail" output in the XML Reader and its Value input to the "sales" output. The Max function output connects to the "peak_sales" input in the XML Writer. In this case the function will output the highest sales figure for any outlet listed in the data source, as "retail" is the document root element.

Max Function Connected

We can now make the remaining connections, remembering to map "retail" to "brand" and "sales" to the Element Value in the XML Writer. Although we have used these inputs to calculate the maximum sales figure, we have not yet mapped them individually.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<brand>
 <peak_sales>665430</peak_sales>
 <area ref="125">
  <store manager="James Jones">350690</store>
  <store manager="Mark Simpson">450880</store>
  <store manager="Linda Parks">22300</store>
 </area>
 <area ref="102">
  <store manager="Patricia Clark">122000</store>
  <store manager="Frank Graham">321560</store>
  <store manager="James Yates">22800</store>
  <store manager="Ken Livingston">665430</store>
 </area>
 <area ref="112">
  <store manager="Laura Dean">210090</store>
 <store manager="Stephen Watson">30800</store>
 </area>
</brand>

The output includes the highest sales figure included in the source data. If we wanted to map the highest sales figure for each region rather than the company as a whole, we would simply alter the example above to connect the Max Context input to the "region" output in the XML Reader instead, connecting the output to an appropriate input in the XML Writer - we will do this next with the Average function.

Before we move on from the Max function, in the example above, the effect would actually be identical if we left the Max Context input unconnected. Connecting the Context input is actually optional. However, if you do not specify a Context, the Mapper will apply the function across the entire input data source. In this case we are using all values in the source anyway, but of course this depends on your required context.

Max With No Context Input

Average

Let's now assume that the output needs to include an indicator of the average sales figure for each region, to match the retail_alt_target.xsd target Schema, inferred from the following XML:

Target XML Copy Code
<brand>
 <area ref="143">
  <average_sales>67850</average_sales>
  <store manager="Jill Gray">
   23400
  </store>
  <store manager="Peter Thomson">
  112300
  </store>
  <store manager="Derek Roberts">
  78900
  </store>
 </area>
 <area ref="110">
  <average_sales>18890</average_sales>
   <store manager="Tom Brown">
  33280
  </store>
  <store manager="Kay Mitchell">
  45000
  </store>
 </area>
</brand>

Here is our updated Source and Target in the Mapper:

Reader and Writer

We drag an Average component onto the Mapper, connecting its Context input to the "region" output in the XML Reader and its Value input to the "sales" output. The Average function output can be connected to the "average_sales" input in the XML Writer. This will calculate the average across each region, rather than across the data as a whole, as in the previous example.

We can now make the remaining connections, remembering to map "region" to "area" and "sales" to the Element Value input.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<brand>
 <area ref="125">
  <average_sales>274623.333333333</average_sales>
  <store manager="James Jones">350690</store>
  <store manager="Mark Simpson">450880</store>
  <store manager="Linda Parks">22300</store>
 </area>
 <area ref="102">
  <average_sales>282947.5</average_sales>
  <store manager="Patricia Clark">122000</store>
  <store manager="Frank Graham">321560</store>
  <store manager="James Yates">22800</store>
  <store manager="Ken Livingston">665430</store>
 </area>
 <area ref="112">
  <average_sales>120445</average_sales>
  <store manager="Laura Dean">210090</store>
  <store manager="Stephen Watson">30800</store>
 </area>
</brand>

The output contains an indicator of average sales for each area. Again, to output average sales for the whole company, we could have connected the Context input to the "retail" output or left it unconnected, as this makes the Mapper calculate the average across the entire data source.

Sum

Let's finally look at a slightly more complex example in which we refer to two different contexts within our Aggregate functions. We now need to observe the following target data, from which the retail_complete_target.xsd Schema has been inferred:

Target XML Copy Code
<brand>
 <total_sales>292880</total_sales>
 <area ref="143">
  <area_sales>214600</area_sales>
  <store manager="Jill Gray">
  23400
  </store>
  <store manager="Peter Thomson">
  112300
  </store>
  <store manager="Derek Roberts">
  78900
  </store>
 </area>
 <area ref="110">
  <area_sales>78280</area_sales>
  <store manager="Tom Brown">
  33280
  </store>
  <store manager="Kay Mitchell">
  45000
  </store>
 </area>
</brand>

We need to map not only the total sales for the company as a whole, but also for each area within it. Here is the Mapper with Source and Target:

Reader and Writer

Let's drag a Sum component onto the Mapper firstly to handle the total sales for the company. We connect its Context input to the "retail" output in the XML Reader, although in this case we could leave the Context unconnected. We connect the Value input to the "sales" output and the Sum function output to the "total_sales" input in the XML Writer.

Now we can do the same for the regions, dragging another Sum function over. We connect the Context input this time to the "region" output, with the Value input again connecting to the "sales" output. This time the Sum output connects to the "area_sales" input in the XML Writer.

Now we can make our remaining connections, again remembering to map those outputs we have already used in our Sum functions. The "sales" output is now connected to three different inputs: the two Sum functions and the XML Writer. This is a typical example of how one item of data in your source can be used to generate multiple values in your output.

Inputs and Outputs Connected

Let's go ahead and execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<brand>
 <total_sales>2196550</total_sales>
 <area ref="125">
  <area_sales>823870</area_sales>
  <store manager="James Jones">350690</store>
  <store manager="Mark Simpson">450880</store>
  <store manager="Linda Parks">22300</store>
 </area>
 <area ref="102">
  <area_sales>1131790</area_sales>
  <store manager="Patricia Clark">122000</store>
  <store manager="Frank Graham">321560</store>
  <store manager="James Yates">22800</store>
  <store manager="Ken Livingston">665430</store>
 </area>
 <area ref="112">
  <area_sales>240890</area_sales>
  <store manager="Laura Dean">210090</store>
  <store manager="Stephen Watson">30800</store>
 </area>
</brand>

The output contains an indicator of the total sales figures for both regional and company-wide levels. The process is essentially the same for each of the Aggregate functions.

A good way to familiarise yourself with the Aggregate Context inputs, or any function in the Mapper, is to experiment with some input data, observing the difference in output when you alter your input connections.

See Also

Using Set Functions

Aggregate
Max
Sum
Average

©2001-2019 Liquid Technologies Limited. All Rights Reserved.
Liquid XML Studio | XML Data Binder | XML Editor | XML Schema Editor | WSDL Editor | XPath Viewer | Web Service Tools


Variable Function Inputs
Data Mapping > Variable Function Inputs

Glossary Item Box

With some of the Data Mapper functions, you can add and remove inputs. Functions such as Concat and ConcatAll in the String section as well as the And and Or functions in the Logic section allow for variable inputs. This can provide a level of flexibility within your mapping operations. In this section we will look at adding and removing inputs to these functions.

In general, you can add and remove inputs by clicking an existing input in the Mapper, then choosing Add Above, Add Below or Delete.

Right-Click Menu for Inputs

In some cases the order in which the inputs are listed has an effect on how the component functions, but in some cases it does not, as we will see below.

Concatenation

Let's look first at the Concat / ConcatAll functions. These both concatenate input Strings. In both cases, the function appears by default with two inputs to concatenate, or to concatenate all instances of in the case of ConcatAll. If any of the inputs are connected to empty Strings, the function will simply ignore them, so there's no problem if you are dealing with input values which may or may not be present in your source data. Additionally, you can extend the Concat and ConcatAll functions to concatenate additional inputs by using the Add Above or Add Below options. Should you decide you no longer need an additional input in either function, simply right-click it and choose Delete.

Look at the following XML source data, which conforms to the schema staff_source.xsd:

Source XML Copy Code
<staff>
 <employee>
  <first_name>Mark</first_name>
  <second_name>Brown</second_name>
  <started>2001</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Jane</first_name>
  <second_name>Jackson</second_name>
  <started>1998</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Joe</first_name>
  <second_name>Simpson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
 <employee>
  <first_name>Lynn</first_name>
  <second_name>Nicolson</second_name>
  <started>1999</started>
  <permanent>false</permanent>
 </employee>
</staff>

This is the target we will be mapping to, staff_variable_target.xsd:

We will use the Concat function to concatenate the first and second names for each staff member. However, we need to include a space character between the names, for which we will need an additional input. Here is the Mapper with source and target imported:

Reader and Writer

Now we drag a Concat component onto the Mapper, connecting the first input to the "first_name" output in the XML Reader.

Reader to Concat

Now, to define the space character we want to appear between first and second names, we add a Constant Value and right-click to set its properties, choosing a String Data Type and entering a single space as the Value.

We connect the Constant output to the second Concat input, so that the space appears immediately following the first name.

Constant to Concat

Since we have now run out of inputs, we need to add another. By right-clicking the second input and choosing Add Below, we ensure that the new input will be concatenated after the two we have already connected.

We can now connect the new String 3 input to the "second_name" output in the XML Reader.

The result of the Concat function can now be connected to the "name" input in the XML Writer.

Concat to Writer

Finally we make the remaining input and output connections.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<human_resources>
 <staffer start_date="2001" is_perm="true">
  <name>Mark Brown</name>
 </staffer>
 <staffer start_date="1998" is_perm="true">
  <name>Jane Jackson</name>
 </staffer>
 <staffer start_date="2008" is_perm="false">
  <name>Joe Simpson</name>
 </staffer>
 <staffer start_date="1999" is_perm="false">
  <name>Lynn Nicolson</name>
 </staffer>
</human_resources>

The output contains the first and second names concatenated with a space between them. If we had needed additional inputs to the Concat function we could simply have added them in the same way. The process is exactly the same for adding new inputs to the ConcatAll function.

Logic

Now let's explore varying the inputs for the Logic functions Or and And. When the Mapper encounters either of these functions, it checks the input values as part of a conditional test. With And, all inputs must equate to true for a true output. With Or, only one input needs to equate to true for a true output. We will be using the buyer_source.xsd Schema, and the following XML data:

Input XML Copy Code
<client_base>
 <buyer>
  <name>Charles Graham</name>
  <ref>12876</ref>
  <total_bought>10599</total_bought>
  <registered>true</registered>
 <since>2003</since>
 </buyer>
 <buyer>
  <name>Amy Henderson</name>
  <ref>14332</ref>
  <total_bought>8900</total_bought>
  <registered>false</registered>
  <since>2005</since>
 </buyer>
 <buyer>
  <name>David Wright</name>
  <ref>10998</ref>
  <total_bought>13500</total_bought>
  <registered>true</registered>
  <since>2001</since>
 </buyer>
</client_base>

Our target Schema is buyer_target.xsd:

Assume that we are mapping the data as part of a targeted marketing campaign. We only want to map buyers with particular sets of input data values. To begin with, we will use the And function to map only those buyers who meet three conditions. Here is the Mapper with Source and Target imported:

Reader and Writer

We only want to map buyers whose total purchases to date amount to at least £10000, so we drag a Greater Than or Equal component out, connecting its Value 1 input to the "total_bought" output in the XML Reader.

Greater Than Or Equal

Reader to Greater Than or Equal

We use a Constant Value to define the figure of 10000 as an integer.

Connect the Constant output to the Greater Than or Equal Value 2 input.

Constant to Greater Than or Equal

We also want mapped buyers to have only been customers since after 2002, so we drag a Greater Than function over. We use a Constant to define the value of 2002, connecting it to the second input of the Greater Than function, with the first input connected to the "since" output in the XML Reader.

Greater Than Added

Now we can add the And function, connecting its inputs to the outputs of the Greater Than and Greater Than or Equal functions. However, we also want to include the buyer's registered status as part of the conditional test, so we need to add a new input by right-clicking one of the And inputs and choosing Add Below or Add Above.

Now we can connect the new input to the "registered" output in the XML Reader, since it contains a boolean value.

Reader to And

Since we are using this data to determine whether values are mapped or not, we now add a Filter function to the Mapper, connecting its Nodes input to the "buyer" output in the XML Reader and its Bool input to the output of the And function. The Filter output connects to the "client" input in the XML Writer.

Filter to Writer

This will ensure that a "buyer" element will only be mapped if its content passes the conditional tests defined as inputs to the And function. We can now make the remaining input and output connections to complete the mapping definition.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<target_clients>
 <client name="Charles Graham">
  <client_num>12876</client_num>
 </client>
</target_clients>

The "buyer" elements have only been mapped if their content met all three conditions, which in this case means only one is mapped. We can carry out the same process using the Or function if we want the buyers to be mapped if they meet any one of the conditions, simply by changing the And component to Or and adding inputs using the same process.

Inputs and Outputs Connected

The output in this case is as follows:

Output XML Copy Code
<target_clients>
 <client name="Charles Graham">
  <client_num>12876</client_num>
 </client>
 <client name="Amy Henderson">
  <client_num>14332</client_num>
 </client>
 <client name="David Wright">
  <client_num>10998</client_num>
 </client>
</target_clients>

Here all three "buyer" elements in the source have been mapped as each of them met at least one of the three specified conditions. In the above examples we have carried out three tests for each function, but we could add more if necessary, by following the same steps repeatedly until we achieve the set of chained conditionals that will result in the desired mapping output.

In some cases the order in which you list your inputs may affect what happens when the Mapper executes. With the Concat and ConcatAll functions, the concatenation result reflects the order of inputs, as in the above example where we needed the first name, space, second name order to be observed. With the Logic functions, although the output may not be affected by the order of inputs, the function of the Mapper itself will be determined by it.

For example, with the And function, as soon as the Mapper encounters a false input, it returns false without checking any of the remaining inputs, as the output must be false. Similarly, with the Or function, when the Mapper encounters a true input, it outputs true straight away, as only one input must be true for the output to be true. You can therefore plan your tests for efficiency if you know something about the input data that may affect the number of tests that may need to be carried out in each case. Naturally this is only a consideration for complex tests.

See Also

String
Concat

Logic
And
Or


Output Formatting
Data Mapping > Output Formatting

Glossary Item Box

When typed value is connected to an input connection point which takes a string, it is possible to control how the value is converted into a string

The rules are different for various data types. Custom conversion rules are enabled by setting "Format Value" to true, when enabled a * will appear next to connection points that contain custom formatting.

Some formatting rules are common to all data types, the padding rules are applied after the custom formatting rules for the specific data type

Property Name | Description
Padding Character Count | Ensures that the string ends up being at least this many characters long
Padding Character | The character that will be added to the string to ensure it is at least "Padding Character Count" long
Padding Side | The side to apply the padding to (Left or Right hand side of the string)

Examples

Padding Character Count | Padding Character | Padding Side | Value | Result
5 | X | Left | ABC | XXABC
5 | X | Right | ABC | ABCXX
5 | X | Left | ABCDE | ABCDE
5 | X | Left | ABCDEF | ABCDEF
5 | X | Left |  | XXXXX

Integer Values : Byte, Int16, Int32, Int64, SByte, UInt16, UInt32, UInt64

The rules for integer values allow the number of digits written to be controlled as well as the standard padding rules.

Property Name | Description | Example
Minimum Digits | Ensures at least this many digits will be output | Value 123 Minimum Digits 5 Result "00123" Value 123456 Minimum Digits 5 Result "123456"

Real Values : Decimal, Float, Double

The rules for real values allow the form (long or exponent form) and decimal places to be controlled as well as the standard padding rules.

Property Name | Description
As Exponential | True and the number if written in the form 1.23e4 when false its written as 12300
Decimal Places | The number of decimal places to apply to the value, if blank then the number is determined by the value (ignored if "As Exponential" is true)
Minimum Integer Digits | The minimum number of digits in the integer part of the value (ignored if "As Exponential" is true)

As Exponential | Decimal Places | Minimum Integer Digits | Value | Result
True | NA | NA | 0.0000123 | 1.23e-5
False | (Blank) | 1 | 0.0123 | 0.0123
False | 2 | 1 | 0.0123 | 0.01
False | 2 | 1 | 0.1 | 0.10
False | 2 | 4 | 12.789 | 12.79
False | 2 | 4 | 12345.6789 | 12345.68

Date Values : Date, DateTime, Time

Date values can be formatted using the .Net formatting rules described in Standard Date and Time Format Strings and Custom Date and Time Format Strings.

Timespan values : TimeSpan

Timespan values can be formatted using the .Net formatting rules described in Standard TimeSpan Format Strings and Custom TimeSpan Format Strings

See Also

In place casting


Output Components
Send Feedback
Data Mapping > Output Components

Glossary Item Box

Data Mapping transforms are run from an output component. All the connections to the output component are then queried, which causes data be drawn from other components, this is done recursively until the output component is constructed, execution then halts.

If a component contains multiple output component then each one is effectively treated as a separate transforms and executed sequentially. The order in which they are executed is determined by the property "Execution Order", the lowest being executed first (if 2 output components have the same "Execution Order" then the order in which they are executed is arbitory.'

Only output components with nothing connected to there outputs are executed, so if the data from an XML Writer is written out using a WriteFile, then the WriteFile is executed and the XML Writer will be processed as part of that execution.

The following are output components

Component | Notes
Database Target |
EDI Target | Unless it has a connector to its Data output
JSON Target | Unless it has a connector to its Data output
Text File Target | Unless it has a connector to its Data output
Xml Target File | Unless it has a connector to its Data output
Web Service | Unless it has a connector to its Output Connection Points
OutputParameter |
WriteFile |


Command Line Options
Send Feedback
Data Mapping > Command Line Options

Glossary Item Box

The Data Mapper can be invoked from the command line. The following options apply.

/DmFile <filename> Executes the specified Data Mapping Transform, the <filename> parameter should be the fully qualified filename of the Transform (.dm) file to execute.
/DmAction

The action to perform:

  • Compile - Compiles the transform for the platform
  • Execute - Compiles and executes the transform for the platform
/DmPlatform

The target platform to execute the mapping using:

  • CS - .Net C# Engine
  • XSLT2 - XSLT 2.0 Engine

Example Usage Copy Code
XmlStudio /DmFile "c:\My Transforms\My Report.dm" /DmAction=Compile /DmPlatform=CS


Generated Data Mapper Code for C#
Data Mapping > Generated Data Mapper Code for C#

Glossary Item Box

Once you have created a transform its possible to compile it to C#. The generated code is split into 2 projects, a class library containing the transform and an executable stub that can be used to run the transform from the command line.

Example

Lets walk through an example and look at the options and investigate the code.

First of all we need a transform. I'm using the "Filter By Price" sample form the Booktstore project.

The compilation settings can be accessed via the "Configure Debugger" button on the toolbar. These settings allow you to control the target .Net framework, file locations, namespaces, as well as giving you the option of just generating the dll/exe without outputting the code. For a full description of the settings see the C# Debugger Options help page.

For this example we will go with the default settings, this will output the source code for a dll and exe for the latest version of visual studio.

To start the compilation use the compile button.

This should also give you the option of automatically opening the project in visual studio.

Once in the visual studio environment you will notice the 2 projects (dll and exe).

The executable is just a stub which processes command line arguments and invokes the transform code in the dll.

The dll contains the actual code which performs the transform, it contain a class which implements the IExecutableTransform interface, in this example the class is called GeneratedTransform.

Assumption about the structure of the GeneratedTransform class should not be made as it may change in future releases, however by convention it will always have a default constructor and one that accepts a ParameterCollection, and will implement the IExecutableTransform interface which will have an execute method.

As you can see if you examine the code in the class GeneratedTransform, it defines 2 variables _OutputFileName & _SourceFileName which are given a default value taken from the source transform. These values can be overridden by setting properties in the ParameterCollection passed to the constructor, you can find the names of the parameters in the InitializeParameterVariables function.

The parameters that a transform uses depends on the components used within it. SourceFileName comes from the default source filename specified in the XML Source document and OutputFileName comes from the default output filename specified in the xml file writer. In some cases transforms are created that have input parameters that are mandatory, a transform will throw an exception if a mandatory input field is not specified.

A transform can be executed via the IExecutableTransform.Execute method. If an error is encountered an exception is raised and execution is stopped.

Once a transform is completed and is no longer needed (even if it failed) it MUST be Disposed of. Failure to do this could tie up file and database handles longer than required.

See Also

DataMapper Debugger Options C#


DataMapper Debugger Options C#
Send Feedback
Data Mapping > Generated Data Mapper Code for C# > DataMapper Debugger Options C#

Glossary Item Box

Controls the generation of C# code from a Data Mapper File.

Generate C# Application - if this is checked then a source or compiled library will be generated that can execute the transform. If this is not checked, no source or compiled code will be produced.

Generate C# Source Code - If selected then source code is generated that will perform the transform.

Include Test Application Source Code - if checked code is also generated for an command line executable stub which will invoke the transform.

Generate a Compiled application - If selected then a command line executable and transform dll library are generated allowing the transform to be executed from the command line or via code.

Generate a Compiled Library - If selected then only a library containing an implementation of the transform is compiled. This can be invoked from source code in your application.

Application Name - the name of the command line program that will invoke the transform

Library Name - the name of the transform library (dll) that will contain the implementation of the transform.

Library Namespace - the C# namespace that the transform classes are placed into.

Project Folder - the folder the source code or compiled code will be written to.

Development Environment - the version of Visual Studio to create any Project/Solution files for

Target Platform - The version of .Net the code should target

The source/compiled code is generated when the compile button is pressed ( [image]).


Database Source
Data Mapping > Data Mapper Functions > By Category > Database > Database Source

Glossary Item Box

Function Name
 Database Source
Category
 Database
Icon
Description
 Defines the data that will be read from a relational database.
Inputs
Outputs
Data Items in source Tables and columns from the underlying database.
Properties

General | Specify the name of the Source component
Structure | Specify the Schema, root element and type for source structure
Source Data | Specify filename to use as source XML when mapping executes

Usage

The Data Mapper allows you to map from source to target data structures, applying transformations to your data at the same time. When embarking on a mapping project, the first thing you need to do is define the source and target data structures you are working with. The Database Source component allows you to specify all aspects of your data source.

To begin, drag the Database Source component from the Database section of the Component Palette onto a new Data Mapper file.

This will cause the data source wizard to launch

In order to bind to a database it must be configure as a global Database Connection. Database connections can be created via the Database Explorer Window or via the 'New Connection' button on the wizard.

The database creation screens are standard windows functionality, refer to online sources for configuring them.

Once a data base connection is selected, we can move onto the next wizard page with the next button.

The next page shows all the user tables within the database. This is a starting point for the data you will be loading.

Pick a table that is at the root of the output data you are trying to extract, so if you want to extract all the orders for each customer then select the Customer table.

By default the DataSource will read all the data from the source data table and any linked tables. In a large database this can be huge amounts of data. In order to reduce the data read an SQL WHERE clause can be used which will reduce the quantity of data read.

The 'WHERE SQL' must start with keyword 'WHERE' and MUST use the name 'TableAlias' when referencing columns within the source table.
Failure to use the TableAlias will result in errors (i.e. "WHERE Country = 'USA'" could fail you should use "WHERE TableAlias.Country = 'USA'")

The WHERE clause can also be parameterized to allow values to be taken from within the transform.

Once you have completed your WHERE Clause it can be tested with the Test button, the results are shown in dialog.

It is advisable to test the query before exiting the wizard.
If you want to test the query then you need to provide default values for all of the parameters as you define them.

For complex queries it is recommended that you build and test them in your standard database tools, and then cut and paste the SQL into this dialog.

When the wizard is complete pressing the Finish button will created the Database Source on the transform.

If your database is well structured with constraints then all the associated tables are added as child elements, so there is no need to manually join in other related tables.

If you database does not contains the constraint you need to model then you can create multiple database sources and join them manually.

Once on the transform the Database source can be used like any other data source.

See Also

Connection Selector (Database Wizard)
Source Selector (Database Wizard)
Where Clause (Database Source Wizard)
Database Target

Data Mapping
Overview
Getting Started
Projects
Component Palette Window

Xml
Xml Source File
Xml Target File

Text
Text File Source
Text File Target


Database Target
Send Feedback
Data Mapping > Data Mapper Functions > By Category > Database > Database Target

Glossary Item Box

Function Name
 Database Target
Category
 Database
Icon
Description
 Allows data to be written to a relational database.
Inputs
Outputs
Data Items in target Tables and columns from the underlying database.
Properties

General | Specify the name of the Target component
Structure | Specify the Schema, root table and type for source structure
Source Data | Specify filename to use as source XML when mapping executes

Usage

The Data Mapper allows you to map from source to target data structures, applying transformations to your data at the same time. When embarking on a mapping project, the first thing you need to do is define the source and target data structures you are working with. The Database Target component allows you to specify all aspects of your data target.

To begin, drag the Database Target component from the Database section of the Component Palette onto a new Data Mapper file.

This will cause the database target wizard to launch

In order to bind to a database it must be configure as a global Database Connection. Database connections can be created via the Database Explorer Window or via the 'New Connection' button on the wizard.

The database creation screens are standard windows functionality, refer to online sources for configuring them.

Once a data base connection is selected, we can move onto the next wizard page with the next button.

The next page shows all the user tables within the database. This is a starting point for the data you will be loading.

Pick a table that is at the root of the output data you are trying to extract, so if you want to extract all the orders for each customer then select the Customer table.

When the wizard is complete pressing the Finish button will created the Database target on the transform.

If your database is well structured with constraints then all the associated tables are added as child elements, so there is no need to manually join in other related tables.

If you database does not contains the constraint you need to model then you can create multiple database sources and join them manually.

Once on the transform the Database target can be used like any other data source.

The database target only inserts data, it does not update existing rows.


EDI Target
Data Mapping > Data Mapper Functions > By Category > EDI > EDI Target

Glossary Item Box

Function Name
 EDI Data Target
Category
 EDI
Icon
Description
 Allows data to be written to an EDI document.
Inputs

Filename | Source file to read data from, if this input is not connected then the filename provided in the 'Default Source File' property
EDI data Items | Segments and element corresponding to the structure of the selected EDI standard.
Outputs
Data The raw EDI data (does not need to be connected)
Properties

Default Target Uri | The filename the EDI document will be written to (Ignored if the Filename input is connected or the Data output is connected).
Execution Order | If the transform contains multiple Output Components then this determines the order in which they are executed

Usage

The EDI Data target makes it possible to create EDI documents within the Data Mapper.

Creating an EDI data source

To begin, drag the EDI Source component from the EDI section of the Component Palette onto a new Data Mapper file.

This will cause the wizard to launch

This wizard page makes it possible to select the required EDI standard.

Once a standard has been selected the next button is enabled and we can move onto the next wizard page.

The default terminators and separators will be selected based on the standard selected on the previous page.

These are common default values, however the files you need to write may use different values and so you should change these values as appropriate.

These values are set when you first run the Wizard, however you can change them inside the Data Mapper by selecting the Component and selecting Properties from the right click menu.

Write End of Line

When checked, each segment is written to a new line.

If it is not checked, the entire EDI document is written onto a single line.

Write Missing Trailing Components

When checked, separators are added for all empty components within an element.

If it is not checked, then trailing empty components are omitted.

Write Missing Trailing Elements

When checked, empty fields and separators are added for all empty Elements within a segment.

If it is not checked, then trailing empty elements are omitted.

Pad Fields to Minimum Length (0s and spaces)

When checked, all fields (Elements and Components) are padded to the Minimum Length specified in the standard. Text fields are right padded with spaces, and numeric fields are left padded with zeros.

If it is not checked, then the fields are written using the specified values and any padding should be done using components within the Data Mapper transform before connecting to the EDI Target Component.

Pad Empty Fields to Minimum Length

When checked, all empty fields (Elements and Components) are padded to the Minimum Length specified in the standard using spaces.

If it is not checked, then the fields are written with empty values and any padding should be done using components within the Data Mapper transform before connecting to the EDI Target Component.

Truncate Fields to Minimum Length (0s and spaces)

When checked, all fields (Elements and Components) are truncated by removing zeros and spaces to the Minimum Length specified in the standard. Text fields have trailing spaces truncated from the right, and numeric fields have leading zeros truncated from the left.

If it is not checked, then the fields are written using the specified values and any truncating should be done using components within the Data Mapper transform before connecting to the EDI Target Component.

Truncate Fields to Maximum Length

When checked, all fields (Elements and Components) are truncated to the Maximum Length specified in the standard. Text fields are truncated from the right, and numeric fields are truncated from the left.

If it is not checked, then the fields are written using the specified values and any truncating should be done using components within the Data Mapper transform before connecting to the EDI Target Component.

Caution, truncating values may lead to loss of data.

When the wizard is complete pressing the Finish button will created the EDI Source on the transform.

Inputs

The component has a root input called 'Filename', each value provided to this is treated as a filename and a new EDI document is created.

If the 'Filename' input (and the 'Data' Output) is not connected then the "Default Target Uri" is used (see properties window).

The child inputs are all specific to the EDI standard you selected when the component was created.

Outputs

The Data output returns the resulting EDI document as a string. This allows it to be consumed by other components rather than just being written to a file.

If the Data output is connected the Default Target Uri property is ignored.

It is an error to have connections to BOTH the Data output and the Filename input.

See Also

EDI Source


EDI Source
Data Mapping > Data Mapper Functions > By Category > EDI > EDI Source

Glossary Item Box

Function Name
 EDI Data Source
Category
 EDI
Icon
Description
 Allows data to be read from an EDI file.
Inputs

Filename | The value will be treated as a filename and loaded into the EDI Document. (can not be connected if 'EDI String' is connected)
EDI String | The value will be treated as raw EDI data and parsed into the EDI Document. (can not be connected if 'Filename' is connected)
Outputs
Data Items in source Segments and element corresponding to the structure of the selected EDI standard.
Properties

General | Specify the name of the Source component
Structure | Specify the EDI standard represented
Source Data | Specify default filename to load if neither of the inputs are connected

Usage

The EDI Data source allows EDI documents to be used as a data source within the Data Mapper.

Inputs

The component has 2 inputs, 'Filename' and 'EDI String', only one of these can be used at a time (you can only connect one of them within a given transform).

If the 'Filename' input is connected then the value read from the connector will be treated as the filename for the EDI document to load (if the connector provides a sequence of filenames, then multiple EDI documents are loaded).

If the 'EDI String' input is connected then the value read from the connector will be treated as raw EDI data and loaded into the document (if the connector provides a sequence of values, then each is treated as a separate EDI document and multiple documents are loaded).

If neither of the inputs are connected then the filename is taken from the default filename (accessible via the properties window).

Creating an EDI data source

To begin, drag the EDI Source component from the EDI section of the Component Palette onto a new Data Mapper file.

This will cause the wizard to launch

This wizard page makes it possible to select the required EDI standard.

Once a standard has been selected the next button is enabled and we can move onto the next wizard page.

The default terminators and separators will be selected based on the standard selected on the previous page (i.e. EDIFACT or X12).

These are common default values, however the files you need to process may use different values. If you receive errors when reading the EDI documents you may wish to investigate changing these values as appropriate.

These values are set when you first run the Wizard, however you can change them inside the Data Mapper by selecting the Component and selecting Properties from the right click menu.

Ignore File Declared Markers

When checked, the parser exclusively uses the values set in this dialog and ignores any terminator and separator characters declared in the EDI document.

If it is not checked, the parser will use any terminator and separator characters declared in the EDI document and fall back to use the values set in this dialog if the markers are not found in the EDI document.

When the wizard is complete pressing the Finish button will created the EDI Source on the transform.

If multiple inputs files are opened (if multiple 'Filename' or 'EDI String' values are provided), then the root item will contain a sequence of documents, each one corresponding to the input source.

See Also

EDI Target
Standard Selector (EDI Wizard)
Syntax (EDI Wizard)

EDI
EDI Target


JSON Target
Data Mapping > Data Mapper Functions > By Category > JSON > JSON Target

Glossary Item Box

Function Name
 JSON Data Target
Category
 JSON
Icon
Description
 Allows data to be written to a JSON file.
Inputs

Filename | If this connection point is connected then each value is used as the filename for the JSON document. Filenames must be local or UNC paths. Not visible in Simple View.
Document | A container for all the types of data the JSON Document can contain. Should not be connected to. Not visible in Simple View.
Root (TYPE) | The root node within the JSON document. Some JSON schemas allow the root node to be different type the root entry will exist for each allowable type. For each Document only one root should be provided with a value (as a document can not have more than one root node).
Outputs
Data The raw JSON data (does not need to be connected)
Properties

Default Target Uri | The filename the JSON document will be written to (Ignored if the Filename input is connected or the Data output is connected).
Encoding | The text encoding applied to the JSON document
Formatting | The formatting applied to the JSON document
Execution Order | If the transform contains multiple Output Components then this determines the order in which they are executed

Usage

Allows JSON documents to created within the Data Mapper.

Creating an JSON data target

To begin, drag the JSON Target component from the JSON section of the Component Palette onto a new Data Mapper file.

This will cause the wizard to launch

In order to write data to a JSON document, the Data Mapper needs to be aware of its structure.

JSON Schema (IEFT drat 4)

Loads the JSON Schema from the file specified.

Infer a JSON Schema from a sample JSON document.

If you don't have a JSON Schema then you can infer one from a sample JSON document, select this option and press next.

This wizard page allows you to infer a JSON Schema from a sample JSON document.

Sample JSON filename

A JSON file containing data that is representative of the data you intend to load. The better the sample data the better the results.

As far as possible ensure that the file contains all the possible combinations of data you expect to see, and try to show objects with and without optional fields.

If your data is very complex you may need to refine the results afterwards using the JSON Schema Editor.

JSON Schema filename

The generated JSON Schema fill be written here.

JSON Schema Encoding

The encoding used to write the JSON Schema.

Force Required

Makes objects definitions required/mandatory if it that has not been identified as optional. If this is not set then all objects are declared as optional.

Infer Enums

When checked the values within objects and arrays are generated as Enumerated values using the unique values in the sample document.

so if an array contained ["true", "false", "false", "false", "true" ] this would be inferred as an enumeration with the values "true", "false".

This option works well on large sample documents, but on small sample sets it can cause the creation of values as enumerations, when in fact they should contain free text.

Infer Enum Tolerance

A tolerance factor for determining if a set of values can be considered an enumeration or free text.

They will be considered an enumeration if (NoOfSamples/UniqueValues) > InferEnumTolorence.

Array Rules

  • AllowAnything - Any kind of item is allowed into the array (not recommended as untyped values are difficult to work with in the Data Mapper)
  • ListValidation - All items comply to the same schema. Each item in the array is considered to be of the same type, and the definition of that type is derived from all the items in the array.
  • TupleTyping - Each item in the array is described using its own schema based on its index in the array (this is rarely how data is formatted in real world documents).

Default Additional Items

Indicates if additional items are allowed within the schemas definitions produced. This is a 3 state field.

  • If checked additional items are allowed
  • If unchecked additional items are NOT allowed
  • Else the 'additionalItems' property is omitted (in which case it defaults to true)

Default Additional Properties

Indicates if additional properties are allowed within the schemas definitions produced. This is a 3 state field.

  • If checked additional properties are allowed
  • If unchecked additional properties are NOT allowed
  • Else the 'additionalProperties' property is omitted (in which case it defaults to true)

Allows you to select the output location for the JSON data that this components represents.

No default JSON Data

No output filename has been provided so one must be provided within the transform using the 'Filename' input, the resulting JSON data will be written to the filename taken from the value of this input.

Write JSON data to this file

JSON Data is written to the filename provided (the filename can be an absolute path or can be a relative path which will be evaluated relative to the transform file)

When the wizard is complete pressing the Finish button will created the JSON Target on the transform.

To better understand the way in which the JSON schema is translated into the JSON Writer component, see How a JSON Schema is translated into a Data Mapper Component.

The quality of the source JSON schema has a significant effect on the resulting JSON Writer Component, if the schema is poorly typed, then you will see a lot of duplicate entries (differing only by type).

Simple View

By default some of the lesser used properties of the writer are hidden, these can be shown again by right clicking and selecting "Toggle Simple View".

Inputs

The component has a root input called 'Filename', each value provided to this is treated as a filename and a new JSON document is created.

If the 'Filename' input (and the 'Data' Output) is not connected then the "Default Target Uri" is used (see properties window).

The child inputs are all specific to the JSON standard you selected when the component was created.

Outputs

The Data output returns the resulting JSON document as a string. This allows it to be consumed by other components rather than just being written to a file.

If the Data output is connected the Default Target Uri property is ignored.

It is an error to have connections to BOTH the Data output and the Filename input.

See Also

How a JSON Schema is translated into a Data Mapper Component


JSON Source
Data Mapping > Data Mapper Functions > By Category > JSON > JSON Source

Glossary Item Box

Function Name
 JSON Data Source
Category
 JSON
Icon
Description
 Allows data to be read from a JSON file.
Inputs

Filename | The value will be treated as a filename and loaded into a JSON Document. (can not be connected if 'JSON String' is connected)
JSON String | The value will be treated as raw JSON data and parsed into the JSON Document. (can not be connected if 'Filename' is connected)
Outputs
Data Items in source The items reflect the contents of the JSON Schema selected.
Properties

General | Specify the name of the Source component
Structure | Specify the JSON Schema.
Source Data | Specify default filename to load if neither of the inputs are connected

Usage

Allows JSON documents to be used as a data source within the Data Mapper.

Inputs

The component has 2 inputs, 'Filename' and 'JSON String', only one of these can be used at a time (you can only connect one of them within a given transform).

If the 'Filename' input is connected then the value read from the connector will be treated as the filename for the JSON document to load (if the connector provides a sequence of filenames, then multiple JSON documents are loaded).

If the 'JSON String' input is connected then the value read from the connector will be treated as raw JSON data and loaded into the document (if the connector provides a sequence of values, then each is treated as a separate JSON document and multiple documents are loaded).

If neither of the inputs are connected then the filename is taken from the default filename (accessible via the properties window).

Creating an JSON data source

To begin, drag the JSON Source component from the JSON section of the Component Palette onto a new Data Mapper file.

This will cause the wizard to launch

In order to read data from a JSON document, the Data Mapper needs to be aware of its structure.

Json Schema (IEFT drat 4)

Loads the JSON Schema from the file specified.

Infer a JSON Schema from a sample JSON document.

If you don't have a JSON Schema then you can infer one from a sample JSON document, select this option and press next.

This wizard page allows you to infer a JSON Schema from a sample JSON document.

Sample JSON filename

A JSON file containing data that is representative of the data you intend to load. The better the sample data the better the results.

As far as possible ensure that the file contains all the possible combinations of data you expect to see, and try to show objects with and without optional fields.

If your data is very complex you may need to refine the results afterwards using the JSON Schema Editor.

JSON Schema filename

The generated JSON Schema fill be written here.

JSON Schema Encoding

The encoding used to write the JSON Schema.

Force Required

Makes objects definitions required/mandatory if it that has not been identified as optional. If this is not set then all objects are declared as optional.

Infer Enums

When checked the values within objects and arrays are generated as Enumerated values using the unique values in the sample document.

so if an array contained ["true", "false", "false", "false", "true" ] this would be inferred as an enumeration with the values "true", "false".

This option works well on large sample documents, but on small sample sets it can cause the creation of values as enumerations, when in fact they should contain free text.

Infer Enum Tolerance

A tolerance factor for determining if a set of values can be considered an enumeration or free text.

They will be considered an enumeration if (NoOfSamples/UniqueValues) > InferEnumTolorence.

Array Rules

  • AllowAnything - Any kind of item is allowed into the array (not recommended as untyped values are difficult to work with in the Data Mapper)
  • ListValidation - All items comply to the same schema. Each item in the array is considered to be of the same type, and the definition of that type is derived from all the items in the array.
  • TupleTyping - Each item in the array is described using its own schema based on its index in the array (this is rarely how data is formatted in real world documents).

Default Additional Items

Indicates if additional items are allowed within the schemas definitions produced. This is a 3 state field.

  • If checked additional items are allowed
  • If unchecked additional items are NOT allowed
  • Else the 'additionalItems' property is omitted (in which case it defaults to true)

Default Additional Properties

Indicates if additional properties are allowed within the schemas definitions produced. This is a 3 state field.

  • If checked additional properties are allowed
  • If unchecked additional properties are NOT allowed
  • Else the 'additionalProperties' property is omitted (in which case it defaults to true)

Allows you to select the JSON data that this components represents.

No default JSON Data

No data is associated with the JSON Reader, it is expected that either the 'Filename' or 'JSON String' input values will be connected within the transform.

Read the default JSON data from a file

JSON Data is read from the filename provided (the filename can be an absolute path or can be a relative path which will be evaluated relative to the transform file)

Generate a default JSON file

A sample JSON document is generated from the JSON Schema.

Complex rules within the schema may mean this will not be 100% compliant with the schema

When the wizard is complete pressing the Finish button will created the EDI Source on the transform.

To better understand the way in which the JSON schema is translated into the JSON Reader component, see How a JSON Schema is translated into a Data Mapper Component.

The quality of the source JSON schema has a significant effect on the resulting JSON Reader Component, if the schema is poorly typed, then you will see a lot of duplicate entries (differing only by type).

If multiple inputs files are opened (if multiple 'Filename' or 'JSON String' values are provided), then the root item will be a sequence (each holding a document corresponding to the input source).

See Also

How a JSON Schema is translated into a Data Mapper Component


Text File Source
Data Mapping > Data Mapper Functions > By Category > Text > Text File Source

Glossary Item Box

Function Name
 Text File Data Source
Category
 Text
Icon
Description
 Reads data from a delimitated or fixed width format file (CSV etc).
Inputs
Filename Source file to read data from, if this input is not connected then the filename provided in the 'Default Source File' property
Outputs

Row | A row is create for each line read form the source file
Child Items | Row contain a number of child items that reflect the fields defined when the component is created.
Properties

Default Source File | The default data file to read from. This is used if the input connection point 'Filename' is not connected.
Store Relative | Indicates if paths should be stored relative to the transform, or as absolute paths.

Creating an Text File Source

When the Text Reader component is dragged onto a transform a setup wizard is launched to guide you through the creation of the data source.

Flat File Data

The first wizard page give you the option of basing the reader on an existing data file, or defining the data source from scratch.

While it possible to describe a data source from scratch, its much easier to infer it from an existing data file.

If you selected a to infer the structure from an existing file then the next page allows you to define the field delimiters.

Delimiter Type

There are 2 forms of file delimited and fixed width, delimited files use a special character to separate fields, fixed width pad all the fields so they take up the same amount of space.

Some files also contain the column names on the first row.

Select the options that are applicable and press Next.

Delimited File Configuration

If your file was delimitated, then the next screen allows you to define the rules used to read each field.

The delimiters break the fields, its possible to select a number of delimiters, but in practice the file normally only uses a tab or a comma.

The "Fields are enclosed in quotes" property means that if the first char within a field is a quote then the value is considered to be everything up to the next quote. This makes it possible for a field to contain the delimiter character. If the field also needs to contain a quote char then 2 quote chars in a row are interpreted as a single quote.

Data | Field 1 Value | Field 3 Value | Field 3 Value | Field 4 Value
abc,123,xyz | abc | 123 | xyz |
abc,"123",xyz | abc | 123 | xyz |
abc,"1,23",xyz | abc | 1,23 | xyz |
abc,1,23,xyz | abc | 1 | 2 | xyz
abc,"1""23",xyz | abc | 1"23 | xyz |
abc,"1"23",xyz | ERROR |  |  |
abc,1"23,xyz | abc | 1"23 | xyz |
abc,"1""2,3",xyz | abc | 1"2,3 | xyz |

Fixed Field Width Delimiter

If you selected "Fixed Width" on the delimiter page then the delimiter setup page is next, this allows you to graphically determine where the breaks in the fields are, just click on the display area where the delimiters should be, if you make a mistake just click it again to remove it.

Here you can see the delimiters have been added at the appropriate positions.

Column Details Page

If your source data contained column headings then you may well be finished at this stage, however if the data contains no column information, or you don't like the names in the file then you can change them on this page.

Simply select the column to edit and set the name (if you are working on a fixed width file then you also get the option to set the column width).

If you did not provide a source document to infer the structure from then you must define it here by hand.

Once you press Finish the new Text Data source is added to the transform and can be used as any other data source is.

Property Pages

Name

The name of the component, must be unique within the transform

Default Encoding

The encoding used to decode the data read from the file into text if the encoding is not specifically identified within the file (see BOM).

First line contains field headings

If checked then the first line in the data file is ignored as it is assumed to contain the names of the columns

Ignore invalid rows

The transform does not stop when an invalid row is encounters, it just ignores it and moves onto the next line.

Remove leading and trailing whitespace from each field

If checked leading and trailing whitespace is removed from the field value i.e.

Col1 , Col2 , Col3

if checked the values are "Col1", "Col2", "Col3"

if unchecked the values are "Col1 ", " Col2 ", " Col3"

Fields are enclosed in quotes

When checked quotes are considered to be enclosing characters, i.e.

"col 1 has a coma, would normally be seen as a separator", col 2

By enclosing column 1 in quotes the ',' is treated as data not a separator.

Delimiters

All the delimiters selected are treated as column separators unless they are enclosed in quotes (see Fields are enclosed in quotes).

Edit Columns

Allows the column definitions to be manually edited.

Default input filename

If the reader component does not have a connector to the 'Filename' or ' Text Source' then the filename is read from this property.

If the connection point 'Filename' or ' Text Source' is connected, then this is ignored (and can be blank)

Store as relative path

Indicates that the filename is to be resolved relative to the data mapping file (.dm). If the transform is compiled the filename will be resolved relative to the compiled exe.

See Also

Source File (Flat File Reader Wizard)
Structure (Flat File Reader Wizard)
Delimiters (Flat File Reader Wizard)
Fixed Length Delimiters (Flat File Reader Wizard)
Columns (Flat File Reader Wizard)
Text File Target

Data Mapping
Overview
Getting Started
Projects
Component Palette Window

Xml
Xml Source File
Xml Target File

Database
Database Source
Database Target


Text File Target
Data Mapping > Data Mapper Functions > By Category > Text > Text File Target

Glossary Item Box

Function Name
 Text File Data Target
Category
 Text
Icon
Description
 Writes data from to a delimitated or fixed width format file (CSV etc).
Inputs

Filename | Source file to read data from, if this input is not connected then the filename provided in the 'Default Source File' property
Row | A row is create for each line read form the source file
Child Items | Row contain a number of child items that reflect the fields defined when the component is created.
Outputs
Data The raw Text data (does not need to be connected)
Properties

Default Source File | The default data file to read from. This is used if the input connection point 'Filename' is not connected.
Store Relative | Indicates if paths should be stored relative to the transform, or as absolute paths.
Execution Order | If the transform contains multiple Output Components then this determines the order in which they are executed
Default Target Uri | The filename the Text document will be written to (Ignored if the Filename input is connected or the Data output is connected).

Creating an Text File Target

When the Text Writer component is dragged onto a transform a setup wizard is launched to guide you through the creation of the data target.

If you already have an example of an output file then you can use this to define the structure that will be used for your writer.

The "Read structure from existing sample document" runs another wizard that allows you to define the structure of your document based on an existing file format.

Delimiter Type

There are 2 forms of file delimited and fixed width, delimited files use a special character to separate fields, fixed width pad all the fields so they take up the same amount of space.

Some files also contain the column names on the first row.

Select the options that are applicable and press Next.

Delimited File Configuration

If your file was delimitated, then the next screen allows you to define the rules used to read each field.

The delimiters break the fields, its possible to select a number of delimiters, but in practice the file normally only uses a tab or a comma.

The "Fields are enclosed in quotes" property means that if the first char within a field is a quote then the value is considered to be everything up to the next quote. This makes it possible for a field to contain the delimiter character. If the field also needs to contain a quote char then 2 quote chars in a row are interpreted as a single quote.

Data | Field 1 Value | Field 3 Value | Field 3 Value | Field 4 Value
abc,123,xyz | abc | 123 | xyz |
abc,"123",xyz | abc | 123 | xyz |
abc,"1,23",xyz | abc | 1,23 | xyz |
abc,1,23,xyz | abc | 1 | 2 | xyz
abc,"1""23",xyz | abc | 1"23 | xyz |
abc,"1"23",xyz | ERROR |  |  |
abc,1"23,xyz | abc | 1"23 | xyz |
abc,"1""2,3",xyz | abc | 1"2,3 | xyz |

Column Details Page

If your source data contained column headings then you may well be finished at this stage, however if the data contains no column information, or you don't like the names in the file then you can change them on this page.

Simply select the column to edit and set the name (if you are working on a fixed width file then you also get the option to set the column width).

If you did not provide a source document to infer the structure from then you must define it here by hand.

The default filename that will be used to write out the new text file. If this is not specified then the input connection point 'Filename' must be connected.

This provides a simple way to write to a single file, if you need to create multiple files or construct the filename dynamically, then leave this blank.

Once you press Finish the new Text Data target is added to the transform and can be used as any other data target is.

Property Pages

Name

The name of the component, must be unique within the transform

Edit Columns

Allows the column definitions to be manually edited.

Default output filename

If the writer component does not have a connector to the 'Filename' input then the filename the data is written to is taken from this property.

If the connection point 'Filename' is connected, then this property is ignored (and can be blank)

Store as relative path

Indicates that the filename is to be resolved relative to the data mapping file (.dm). If the transform is compiled the filename will be resolved relative to the compiled exe.

Default Encoding

The encoding used to write the text data to a file.

Write column heading on first line

If checked then all the column headings are written onto the first line of the file.

Inputs

The component has a root input called 'Filename', each value provided to this is treated as a filename and a new Text document is created.

If the 'Filename' input (and the 'Data' Output) is not connected then the "Default Target Uri" is used (see properties window).

The child inputs are all specific to the Text standard you selected when the component was created.

Outputs

The Data output returns the resulting Text document as a string. This allows it to be consumed by other components rather than just being written to a file.

If the Data output is connected the Default Target Uri property is ignored.

It is an error to have connections to BOTH the Data output and the Filename input.

See Also

Text File Source

Xml
Xml Source File
Xml Target File

Database
Database Source
Database Target


Xml Source File
Data Mapping > Data Mapper Functions > By Category > XML > Xml Source File

Glossary Item Box

Function Name
 XML Data Source
Category
 XML
Icon
 XML Source
Description
 Define the XML source data for mapping
Inputs

Filename | The value will be treated as a filename and loaded into a XML Document. (can not be connected if 'XML String' is connected)
XML String | The value will be treated as raw XML data and parsed into the XML Document. (can not be connected if 'Filename' is connected)
Outputs
Data Items in source Nodes, attributes and values in the source XML data
Properties

General | Specify the name of the Source component
Structure | Specify the Schema, root element and type for source structure
Source Data | Specify filename to use as source XML when mapping executes

Usage

Allows XML documents to be used as a data source within the Data Mapper.

Inputs

The component has 2 inputs, 'Filename' and 'XML String', only one of these can be used at a time (you can only connect one of them within a given transform).

If the 'Filename' input is connected then the value read from the connector will be treated as the filename for the XML document to load (if the connector provides a sequence of filenames, then multiple XML documents are loaded).

If the 'XML String' input is connected then the value read from the connector will be treated as raw XML data and loaded into the document (if the connector provides a sequence of values, then each is treated as a separate XML document and multiple documents are loaded).

If neither of the inputs are connected then the filename is taken from the default filename (accessible via the properties window).

Creating an XML data source

To begin, drag the XML Source component from the XML section of the Component Palette onto a new Data Mapper file.

XML Data Source Component

As soon as you drag the component over, the XML Source Wizard will open, guiding you through the process of defining your mapping source.

You need to provide a schema to describe the data that you will be mapping, you can do this using by providing an XSD, DTD or XDR.

If you don't have a schema (i.e. you just have an xml data file) then you can infer a schema from the XML data file (see Inferring an XML Schema (XSD)).

If you infer an XSD from an XML document, then you may have to finesse the XSD manually in the XSD Editor.

The second page contains options relating to the inferring process.

Schema Name

The name of the schema that will be produced (there is no need to add the .xsd extension).
If more than 1 schema file needs to be created, then the schema files will be named <Schema Name>1.xsd, <Schema Name>2.xsd etc

Output Directory

The location where your schema file/files will be written.

Encoding

The encoding that will be applied to your XML Schema (UTF-8 or UTF-16 are the most commonly used, only change this if you understand encoding).

Occurrence Options

If the Occurrence property is set to Restricted, the first time elements are encountered in the XML document, the schema declaration is inferred as minOccurs="1".
When attributes are encountered, the schema declaration is inferred as use="required". If the Occurrence property is set to Relaxed, element schema declarations are inferred as minOccurs="0", and attribute schema declarations are inferred as use="optional".

Type Inference Option

If the TypeInference property is set to Relaxed, the inferred type of elements and attributes in the XML document with simple content is always xs:string.
If the TypeInference property is set to Restricted, more specific types are inferred, such as xs:date, xs:decimal, xs:unsignedByte, and so on.

When you have selected a Schema, the next part of the Wizard will allow you to select the root element or complex type.

Types that are abstract are disabled and grayed out.

The next section allows you to specify where you want your source data to come from. This is the data that will be mapped when your transform executes. If you inferred a Schema from source XML, you may wish to use this here. If you specified an XSD you already had before starting your mapping project, you can use it to generate default XML data to use in the Mapper.

Properties

You can alter the Properties of an XML Reader in the Mapper by right-clicking it and choosing Show Properties. These properties can all be set in the Wizard when you add a Source Data component to the Mapper, but if you need to alter any of them you can do so here.

XML Reader Properties

The General tab allows you to alter the name of the component within your mapping project.

The Structure tab allows you to select a Schema, root element and type for your source data, as well as instructing the Mapper to validate the Schema when it loads it.

The Source Data tab allows you to select a file to use as source data when the Mapper executes.

Source Data Properties

By right-clicking the output items in your XML Reader, you can control Layout and View properties.

Examples

Now your XML Source Data component should appear in the Mapper as the XML Reader.

You can click to expand and collapse items in the XML Reader as it appears in the Mapper.

You can make connections between the XML Reader and XML Writer once you have them both imported, by clicking and dragging between items.

XML Reader to XML Writer

These connections define which data items in the source are mapped to items in the target.

Connection Between Reader and Writer

See Also

Xml Target File

Data Mapping
Overview
Getting Started
Projects
Component Palette Window
Overview
Getting Started
Projects
Component Palette Window

Text
Text File Source
Text File Target

Database
Database Source
Database Target


Xml Target File
Data Mapping > Data Mapper Functions > By Category > XML > Xml Target File

Glossary Item Box

Function Name
 XML Data Target
Category
 XML
Icon
 XML Target
Description
 Define the XML target data for mapping
Inputs

Filename | If this connection point is connected then each value is used as the filename for the JSON document. Filenames must be local or UNC paths. Not visible in Simple View.
Child Elements | Nodes; Elements, Attributes and Values in the target XML data
Outputs
Data The raw XML data (does not need to be connected)
Properties

Encoding | The text encoding applied to the XML document
Formatting | The formatting applied to the XML document
Write XML Declaration | When true the XML declaration ( <?xml version="1.0" ... > ) is added to the output XML data
Execution Order | If the transform contains multiple Output Components then this determines the order in which they are executed

Usage

Allows XML documents to created within the Data Mapper.

Creating an XML data target

To begin, drag the XML Target component from the XML section of the Component Palette onto a new Data Mapper file.

XML Data Target Component

This will cause the wizard to launch

You need to provide a schema to describe the data that you will be mapping, you can do this using by providing an XSD, DTD or XDR.

If you don't have a schema (i.e. you just have an xml data file) then you can infer a schema from the XML data file (see Inferring an XML Schema (XSD)).

If you infer an XSD from an XML document, then you may have to finesse the XSD manually in the XSD Editor.

The second page contains options relating to the inferring process.

Schema Name

The name of the schema that will be produced (there is no need to add the .xsd extension).
If more than 1 schema file needs to be created, then the schema files will be named <Schema Name>1.xsd, <Schema Name>2.xsd etc

Output Directory

The location where your schema file/files will be written.

Encoding

The encoding that will be applied to your XML Schema (UTF-8 or UTF-16 are the most commonly used, only change this if you understand encoding).

Occurrence Options

If the Occurrence property is set to Restricted, the first time elements are encountered in the XML document, the schema declaration is inferred as minOccurs="1".
When attributes are encountered, the schema declaration is inferred as use="required". If the Occurrence property is set to Relaxed, element schema declarations are inferred as minOccurs="0", and attribute schema declarations are inferred as use="optional".

Type Inference Option

If the TypeInference property is set to Relaxed, the inferred type of elements and attributes in the XML document with simple content is always xs:string.
If the TypeInference property is set to Restricted, more specific types are inferred, such as xs:date, xs:decimal, xs:unsignedByte, and so on.

When you have selected a Schema, the next part of the Wizard will allow you to select the root element or complex type.

Types that are abstract are disabled and grayed out.

Allows you to select the output location for the XML data that this components represents.

No default XML Data

No output filename has been provided so one must be provided within the transform using the 'Filename' input, the resulting XML data will be written to the filename taken from the value of this input.

Write XML data to this file

XML Data is written to the filename provided (the filename can be an absolute path or can be a relative path which will be evaluated relative to the transform file)

Properties

You can alter the Properties of an XML Writer in the Mapper by right-clicking it and choosing Show Properties. These properties can all be set in the Wizard when you add a Target Data component to the Mapper, but if you need to alter any of them you can do so here.

XML Writer Properties

The General tab allows you to alter the name of the component within your mapping project.

The Structure tab allows you to select a Schema, root element and type for your source data, as well as instructing the Mapper to validate the Schema when it loads it.

The Output tab allows you to select a file to write your mapped data to by default when the Mapper executes. Here you can also specify various aspects of the Mapper output, including tabs, spaces, indentation and encoding.

By right-clicking the input items in your XML Writer, you can control Layout and View properties.

Example

Now your XML Target Data component should appear in the Mapper as the XML Writer.

You can click to expand and collapse items in the XML Writer as it appears in the Mapper.

You can make connections between the XML Reader and XML Writer once you have them both imported, by clicking and dragging between items.

XML Reader to XML Writer

These connections define which data items in the source are mapped to items in the target.

Connection Between Reader and Writer

Inputs

The component has a root input called 'Filename', each value provided to this is treated as a filename and a new XML document is created.

If the 'Filename' input (and the 'Data' Output) is not connected then the "Default Target Uri" is used (see properties window).

The child inputs are all specific to the XML standard you selected when the component was created.

Outputs

The Data output returns the resulting XML document as a string. This allows it to be consumed by other components rather than just being written to a file.

If the Data output is connected the Default Target Uri property is ignored.

It is an error to have connections to BOTH the Data output and the Filename input.

See Also

Xml Source File

Data Mapping
Projects
Component Palette Window

Text
Text File Source
Text File Target

Database
Database Source
Database Target


Web Service
Send Feedback
Data Mapping > Data Mapper Functions > By Category > Web Service > Web Service

Glossary Item Box

Function Name
 Web Service
Category
 Web Service
Icon
 XML Source
Description
 Define a call to a Web Service
Inputs

Filename | The value will be treated as a filename and loaded into a XML Document. (can not be connected if 'XML String' is connected)
XML String | The value will be treated as raw XML data and parsed into the XML Document. (can not be connected if 'Filename' is connected)
Outputs
Data Items in source Nodes, attributes and values in the source XML data
Properties

General | Specify the name of the Source component
Structure | Specify the Schema, root element and type for source structure
Source Data | Specify filename to use as source XML when mapping executes

Usage

Allows Web Service calls to be made within the Data Mapper.

Because it is possible to call a web service in the following ways

  • Request Only - data is sent to the web service but no data is returned.
  • Response Only - no data is required in the web service request but data is returned.
  • Request/Response - data is passed in the request and data is received in the response.

The Web Service component is unlike many of the other components as it can behave as a data source and data target.

Creating an XML data source

To begin, drag the Web Service component from the Component Palette onto a new Data Mapper file.

XML Data Source Component

As soon as you drag the component over, the Web Service Wizard will open, guiding you through the process of defining your mapping source.

Select a WSDL or WADL File

First you must select the web service type you want to look at (WSDL, WADL or User Defined Web Service - see below) using the radio buttons at the top of the page.

You then need to specify the URL that returns the WSDL or WADL for the web service.

For .Net web services, this of the form http://ServerName/Service.asmx?WSDL

You can also select a local file e.g C:\temp\Service.wsdl

You can test the web service your have specified is valid using the "Test" button.

For those just curious about the tool, we have supplied a simple web service which allows you to explore the functionality of the Web Service Test Client. To use this web service, click the "Use Liquid Technologies Sample Web Service" link button.

If the service requires authentication, then you can add a user name and password.

If you save the web service call then the password is not encrypted in the file.

The Wizard will not allow you to move on until the web service URL is pointing at a valid WSDL file.

Selecting a Web Method

You can now select the Web method you wish to call. Web services typically offer the ability call there methods using a number of protocols. The browser shows all the supported protocols and all the methods exposed for each of them (Note Not all methods can be called via HTTP POST & GET).

The Web Service Test Client supports 4 protocols, Soap 1.1, Soap 1.2, HTTP GET & HTTP POST. Any other protocols are ignored.

Once you select your method, and press Finish, and request is constructed for you.
You can then modify the request and call the web method. See Web Service Test Client.

Select option to create a User Defined Web Service

If your Web Service does not have a WSDL or WADL file, you can choose the option to create a User Defined Web Service on the first page of the Wizard.

When you click 'Next >' you are then presented with the following screen which allows you to specify a service, URI, method (GET or POST) and method parameters.

Clicking 'Finish' then allows you to save the User Defined Web Service as a WADL file.

The next time you want to access the service, you can then select the WADL file you just created.


Constant
Data Mapping > Data Mapper Functions > By Category > Values > Constant

Glossary Item Box

Function Name
 Constant Value
Category
 Data Type
Icon
 Constant
Description
 Defines a Constant data value
Inputs
None -
Outputs
Value The data value defined within the Constant
Properties

Name | String name to display within the Mapper
Data Type | Data type for the Constant Value
Value | The value represented by the Constant

Usage

The Data Type Constant Value component defines a single data value for use within mapping functions. When you carry out transformations on your data, it is common to input data values such as characters, Strings and numbers. The Constant Value component allows you to do this. You can define many different types of Constant Value and typically the component is used in conjunction with other mapping functions. Although the Constant component is simple to use, we will look at a relatively complex example here, using two constants, one of type String and the other numerical. The process is as follows:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using library_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<library>
 <journal>
  <section>y</section>
  <section>r</section>
  <section>t</section>
  <title>Journal of Medical Science</title>
  <note>-abridged</note>
  <note>-1998</note>
 </journal>
 <journal>
  <section>f</section>
  <section>k</section>
  <title>Advancements in Linguistics</title>
  <note>-2010</note>
 </journal>
</library>

For our target schema we will be using library_alt_target.xsd, inferred from the following XML:

Target XML Copy Code
<academic_texts>
 <volume name="Journal of Physiology">
  <sections>nhj_4</sections>
  <metadata>-2005-Updated</metadata>
 </volume>
 <volume name="Philosophy Today">
  <sections>gs_3</sections>
  <metadata>-2002</metadata>
 </volume>
</academic_texts>

The data models library journals. If you look at the target XML, you will see that the "sections" element contains a series of characters, followed by an underscore character and a number. We are going to build this String by concatenating all "section" elements within a given parent, then concatenating this with an underscore character and an integer representing the number of sections in the parent element plus one. We will use Constants to represent the underscore String and the number 1, to add to the number of sections. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag two Constant Values from the Component Palette onto the mapping area:

We need to set the properties for each, by right-clicking, then choosing Show Properties. For the first one, enter "underscore" as the Name, select String from the Data Type drop-down list and enter a single underscore character ("_") as the Value. Altering the name will make the Constants easier to work with in the Mapper.

For the second Constant, enter "one" as the Name, choose an integer type from the Data Type drop-down list and enter "1" as the Value.

Now you can see which Constant is which in the Mapper.

Since we want to concatenate the "section" items with an underscore and their total number plus one, let's drag a Count function from the Aggregate section of the Component Palette. Connect its Context input to the "journal" output of the XML Reader, since we want the number of "sections" per "journal". Connect the Value input of the Count function to the "section" output of the XML Reader, since this is the element we want to count.

Reader to Count

Now we have the number of items, but we also need to add a value of 1 to it. Drag an Add function from the Maths section, connecting its first Value input to the Count output and its second Value input to the output of the "one" Constant we created.

Now we need to concatenate all "section" items within each parent, so drag a ConcatAll function onto the Mapper. Connect the "section" item to the first String input of the ConcatAll function. We do not need to supply a second input to the function in this case - you can remove the second input from display if you prefer, by right-clicking it and choosing Delete, although it will still function if you leave it intact.

Now we need to concatenate the combined "section" items with the underscore and number. Start by dragging a Concat function onto the Mapper. Connect its first String input to the output of the ConcatAll function, with its second String input connected to the "underscore" Constant we created.

Now we can combine the concatenated "section" items plus underscore character with the number we have arrived at. Drag another Concat function over, connecting its first String input to the output of the previous Concat, and its second input to the output of the Add function.

Now we can connect the output from this second Concat function to the "sections" input in the XML Writer.

Data Type Constant Reader to Writer

Finally, connect the remaining inputs and outputs, with the "journal" and "section" items both connecting to two different inputs:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<academic_texts>
 <volume name="Journal of Medical Science">
  <sections>yrt_4</sections>
  <metadata>-abridged</metadata>
  <metadata>-1998</metadata>
 </volume>
 <volume name="Advancements in Linguistics">
  <sections>fk_3</sections>
  <metadata>-2010</metadata>
 </volume>
</academic_texts>

The "sections" element now contains the combined elements together with an underscore and count value plus one. In practice, you can use the Constant Value function in many different ways. As well as allowing you to insert specific items of data into your mapping projects, it lets you perform calculations on your data.

Possible data types for Constant Values include: Binary, Boolean, Byte, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int16, Int32, Int64, SByte, String, Time and Node.

See Also

InputParameter

Type
Cast
NodeType

String
Concat

Maths
Add

Aggregate
Count


InputParameter
Data Mapping > Data Mapper Functions > By Category > Values > InputParameter

Glossary Item Box

Function Name
 Input Parameter
Category
 Data Type
Icon
 Constant
Description
 Defines an input parameter to the transform.
Inputs
None -
Outputs
Value The data value provided to the transform
Properties

Name | String name to display within the Mapper
Parameter Name | The name of the parameter name used when setting the it in code or via a command line argument
Parameter Description | The description of the parameter added as a comment or provided as documentation via the command line /help
Parameter Type | The data type of the parameter value
Parameter Cardinality | Required/Optional indicates if the parameter must be specified by the calling code or the via the command line. If the parameter is optional then a default value may be supplied which is used if the parameter is not specified by the caller. If it is marked Required then the transform will fail if the parameter is not supplied by the caller.
Default Value | The value used if the caller does not supply a value (only applies when the parameter is marked as optional).

Usage

The Input Parameter Value component allows the caller to provide a single data value for use within mapping functions. Depending on the target platform for the transform the input parameter may be passed in the form of an argument via a C# call or as an XSLT input parameter or as a command line argument.

Possible data types for Constant Values include: Binary, Boolean, Byte, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int16, Int32, Int64, SByte, String, Time and Node.

See Also

Constant
OutputParameter


Average
Data Mapping > Data Mapper Functions > By Category > Aggregate > Average

Glossary Item Box

Function Name
 Average
Category
 Aggregate
Icon
 Average
Description
 Retrieve the average value within a context
Inputs

Context | Context within which to determine average value [optional]
Value | Value to retrieve average of
Outputs
Result Average value within context
Properties
None -

Usage

The Data Mapper Aggregate Average function allows you to retrieve average values within specific contexts. The Context input is optional, so you can simply retrieve the average value for the whole data source by not connecting it. If you do connect the Context input, the average is taken within the specified parent node. To apply the Aggregate Average function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using sellers_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<sellers>
 <salesperson>
  <name>John Davidson</name>
  <sales>12800</sales>
 </salesperson>
 <salesperson>
  <name>Jane Johnson</name>
  <sales>23050</sales>
 </salesperson>
 <salesperson>
  <name>Mark Smith</name>
  <sales>18200</sales>
 </salesperson>
</sellers>

For our target schema we will be using sellers_target.xsd, inferred from the following XML:

Target XML Copy Code
<sales_staff>
 <sales_data type="average">28430</sales_data>
 <sales_assistant seller_name="Ken Jameson">
  <amount>34050</amount>
 </sales_assistant>
 <sales_assistant seller_name="Lisa Matthews">
  <amount>27540</amount>
 </sales_assistant>
 <sales_assistant seller_name="Paul Norton">
  <amount>23700</amount>
 </sales_assistant>
</sales_staff>

The data models sales for individual salespeople within a retail organisation. Let's assume that, as well as mapping the salespeople and their data, we also want to determine the average sales figure across all staff members. We will record this in the "sales_data" element together with a String indicating the type of data we are recording, as in the target data above. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Aggregate Average function from the Component Palette into the mapping area:

Aggregate Average Component

The Average function takes two inputs, representing the value to retrieve the average instance of and the context in which it should be calculated as the average. The output of the function is the sum of all input values divided by the number of values. Both inputs and output of the Average function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Connect the Context input of the Average function to the "sellers" output in the XML Reader and the Value input to the "sales" output.

Reader to Average

This will output the average of sales across all sellers. In this case, the effect would be the same if we did not connect the Context input, however if we had categories of sellers, for example in different stores, we would perhaps want to calculate the average sales for each store, in which case the Context input would be different. Connect the Average output to the Element Value within the "sales_data" element in the XML Writer.

Average to Writer

This will ensure that the "sales_data" element is written out with the average sales value inside it each time the data is mapped.

Now we need to define the type of data we are including in the "sales_data" element. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Choose a String Data Type and enter "average" as the Value, or anything else you prefer.

Connect the Constant output to the "type" input in the XML Writer.

Constant to Writer

Finally let's make the remaining input and output connections. Remember to map "sellers" to "sales_staff" and "sales" to "amount" - although we have used these as references we have not yet mapped them. We do not need to map anything to the "sales_data" element input as the Element Value will ensure the element itself is mapped.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<sales_staff>
 <sales_data type="average">18016.6666666667</sales_data>
 <sales_assistant seller_name="John Davidson">
  <amount>12800</amount>
 </sales_assistant>
 <sales_assistant seller_name="Jane Johnson">
  <amount>23050</amount>
 </sales_assistant>
 <sales_assistant seller_name="Mark Smith">
  <amount>18200</amount>
 </sales_assistant>
</sales_staff>

The output contains the data values mapped from the source and the average sales figure across sellers, included in the "sales_data" element, together with a String indicating the meaning of the value.

If you do not connect the Context input of the Average function, the result will be the average for the data source as a whole.
The Average function divides the total of all values in the context then divides this by the number of values included in the sum. This means that the output may be a different numerical type than the input values.

See Also

Count
Min
Max
Sum

Values
Constant

Data Mapping
Using Aggregate Functions
Analyzing Numerical Input


Count
Data Mapping > Data Mapper Functions > By Category > Aggregate > Count

Glossary Item Box

Function Name
 Count
Category
 Aggregate
Icon
 Count
Description
 Retrieve the number of values within a context
Inputs

Context | Context within which to count values [optional]
Value | Value to count instances of
Outputs
Result Number of values found within context
Properties
None -

Usage

The Data Mapper Aggregate Count function allows you to retrieve the number of values within specific contexts. The Context input is optional, so you can simply retrieve the count of values in the whole data source by not connecting it. If you do connect the Context input, the count is taken within the specified parent node. To apply the Aggregate Count function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using sellers_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<sellers>
 <salesperson>
  <name>John Davidson</name>
  <sales>12800</sales>
 </salesperson>
 <salesperson>
  <name>Jane Johnson</name>
  <sales>23050</sales>
 </salesperson>
 <salesperson>
  <name>Mark Smith</name>
  <sales>18200</sales>
 </salesperson>
</sellers>

For our target schema we will be using sellers_target.xsd, inferred from the following XML:

Target XML Copy Code
<sales_staff>
 <sales_data type="count">3</sales_data>
 <sales_assistant seller_name="Ken Jameson">
  <amount>34020</amount>
 </sales_assistant>
 <sales_assistant seller_name="Lisa Matthews">
  <amount>27500</amount>
 </sales_assistant>
 <sales_assistant seller_name="Paul Norton">
  <amount>23700</amount>
 </sales_assistant>
</sales_staff>

The data models sales for individual salespeople within a retail organisation. Let's assume that, as well as mapping the salespeople and their data, we also want to determine the number of sales figures we are dealing with across all staff members. We will record this in the "sales_data" element together with a String indicating the type of data we are recording as in the target above. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Aggregate Count function from the Component Palette into the mapping area:

Aggregate Count Component

The Count function takes two inputs, representing the value to retrieve the count of and the context in which it should be counted. Both inputs and output of the Count function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Connect the Context input of the Count function to the "sellers" output in the XML Reader and the Value input to the "sales" output.

Reader to Count

This will output the number of sales figures across all sellers. In this case, the effect would be the same if we did not connect the Context input, however if we had categories of sellers, for example in different stores, we would perhaps want to calculate the number of sales figures for each store, in which case the Context input would be different. Connect the Count output to the "Element Value" within the "sales_data" element in the XML Writer.

Count to Writer

This will ensure that the "sales_data" element is written out with the number of sales figures inside it each time the data is mapped.

Now we need to define the type of data we are including in the "sales_data" element. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Choose a String Data Type enter "count" as the Value, or anything else you prefer.

Connect the Constant output to the "type" input in the XML Writer.

Constant to Writer

Finally let's make the remaining input and output connections. Remember to map "sellers" to "sales_staff" and "sales" to "amount" - although we have used these as references we have not yet mapped them. We do not need to map anything to the "sales_data" element input as the Element Value will ensure the element itself is mapped.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<sales_staff>
 <sales_data type="count">3</sales_data>
 <sales_assistant seller_name="John Davidson">
  <amount>12800</amount>
 </sales_assistant>
 <sales_assistant seller_name="Jane Johnson">
  <amount>23050</amount>
 </sales_assistant>
 <sales_assistant seller_name="Mark Smith">
  <amount>18200</amount>
 </sales_assistant>
</sales_staff>

The output contains the data values mapped from the source and the number of sales figures, included in the "sales_data" element, together with a String indicating the meaning of the value.

If you do not connect the Context input of the Count function, the result will be the number of values in the data source as a whole.

See Also

Average
Min
Max
Sum

Values
Constant

Data Mapping
Analyzing Numerical Input
Using Aggregate Functions


Max
Data Mapping > Data Mapper Functions > By Category > Aggregate > Max

Glossary Item Box

Function Name
 Max
Category
 Aggregate
Icon
 Max
Description
 Retrieve the maximum value within a context
Inputs

Context | Context within which to determine maximum value [optional]
Value | Value to retrieve maximum instance of
Outputs
Result Maximum value found within context
Properties
None -

Usage

The Data Mapper Aggregate Max function allows you to retrieve maximum values within specific contexts. The Context input is optional, so you can simply retrieve the maximum value for the whole data source by not connecting it. If you do connect the Context input, the maximum is taken within the specified parent node. To apply the Aggregate Max function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using sellers_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<sellers>
 <salesperson>
  <name>John Davidson</name>
  <sales>12800</sales>
 </salesperson>
 <salesperson>
  <name>Jane Johnson</name>
  <sales>23050</sales>
 </salesperson>
 <salesperson>
  <name>Mark Smith</name>
  <sales>18200</sales>
 </salesperson>
</sellers>

For our target schema we will be using sellers_target.xsd, inferred from the following XML:

Target XML Copy Code
<sales_staff>
 <sales_data type="max">34020</sales_data>
 <sales_assistant seller_name="Ken Jameson">
  <amount>34020</amount>
 </sales_assistant>
 <sales_assistant seller_name="Lisa Matthews">
  <amount>27500</amount>
 </sales_assistant>
 <sales_assistant seller_name="Paul Norton">
  <amount>23700</amount>
 </sales_assistant>
</sales_staff>

The data models sales for individual salespeople within a retail organisation. Let's assume that, as well as mapping the salespeople and their data, we also want to determine the maximum sales figure across all staff members. We will record this in the "sales_data" element together with a String indicating the type of data we are recording as in the target above. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Aggregate Max function from the Component Palette into the mapping area:

Aggregate Max Component

The Max function takes two inputs, representing the value to retrieve the maximum instance of and the context in which it should be calculated as maximum. Both inputs and output of the Max function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Connect the Context input of the Max function to the "sellers" output in the XML Reader and the Value input to the "sales" output.

Reader to Max

This will output the maximum sales across all sellers. In this case, the effect would be the same if we did not connect the Context input, however if we had categories of sellers, for example in different stores, we would perhaps want to calculate the maximum sales for each store, in which case the Context input would be different. Connect the Max output to the Element Value input within the "sales_data" element in the XML Writer.

Max to Writer

This will ensure that the "sales_data" element is written out with the maximum sales value inside it each time the data is mapped.

Now we need to define the type of data we are including in the "sales_data" element. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Choose a String Data Type enter "max" as the Value, or anything else you prefer.

Connect the Constant output to the "type" input in the XML Writer.

Constant to Writer

Finally let's make the remaining input and output connections. Remember to map "sellers" to "sales_staff" and "sales" to "amount" - although we have used these as references we have not yet mapped them. We do not need to map anything to the "sales_data" element input as the Element Value will ensure the element itself is mapped.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<sales_staff>
 <sales_data type="max">23050</sales_data>
 <sales_assistant seller_name="John Davidson">
  <amount>12800</amount>
 </sales_assistant>
 <sales_assistant seller_name="Jane Johnson">
  <amount>23050</amount>
 </sales_assistant>
 <sales_assistant seller_name="Mark Smith">
  <amount>18200</amount>
 </sales_assistant>
</sales_staff>

The output contains the data values mapped from the source and the maximum sales value included in the new "sales_data" element, together with a String indicating the meaning of the value.

If you do not connect the Context input of the Max function, the result will be the maximum for the data source as a whole.

See Also

Min
Average
Count
Sum

Values
Constant

Data Mapping
Analyzing Numerical Input
Using Aggregate Functions


Min
Data Mapping > Data Mapper Functions > By Category > Aggregate > Min

Glossary Item Box

Function Name
 Min
Category
 Aggregate
Icon
 Min
Description
 Retrieve the minimum value within a context
Inputs

Context | Context within which to determine minimum value [optional]
Value | Value to retrieve minimum instance of
Outputs
Result Minimum value found within context
Properties
None -

Usage

The Data Mapper Aggregate Min function allows you to retrieve minimum values within specific contexts. The Context input is optional, so you can simply retrieve the minimum value for the whole data source by not connecting it. If you do connect the Context input, the minimum is taken within the specified parent node. To apply the Aggregate Min function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using sellers_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<sellers>
 <salesperson>
  <name>John Davidson</name>
  <sales>12800</sales>
 </salesperson>
 <salesperson>
  <name>Jane Johnson</name>
  <sales>23050</sales>
 </salesperson>
 <salesperson>
  <name>Mark Smith</name>
  <sales>18200</sales>
 </salesperson>
</sellers>

For our target schema we will be using sellers_target.xsd, inferred from the following XML:

Target XML Copy Code
<sales_staff>
 <sales_data type="min">23700</sales_data>
 <sales_assistant seller_name="Ken Jameson">
  <amount>34020</amount>
 </sales_assistant>
 <sales_assistant seller_name="Lisa Matthews">
  <amount>27500</amount>
 </sales_assistant>
 <sales_assistant seller_name="Paul Norton">
  <amount>23700</amount>
 </sales_assistant>
</sales_staff>

The data models sales for individual salespeople within a retail organisation. Let's assume that, as well as mapping the salespeople and their data, we also want to determine the minimum sales figure across all staff members. We will record this in the "sales_data" element together with a String indicating the type of data we are recording as in the target above. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Aggregate Min function from the Component Palette into the mapping area:

Aggregate Min Component

The Min function takes two inputs, representing the value to retrieve the minimum instance of and the context in which it should be calculated as minimum. Both inputs and output of the Min function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Connect the Context input of the Min function to the "sellers" output in the XML Reader and the Value input to the "sales" output.

Reader to Min

This will output the minimum sales across all sellers. In this case, the effect would be the same if we did not connect the Context input, however if we had categories of sellers, for example in different stores, we would perhaps want to calculate the minimum sales for each store. Connect the Min output to the "Element Value" within the "sales_data" element in the XML Writer.

Min to Writer

This will ensure that the "sales_data" element is written out with the minimum sales value inside it each time the data is mapped.

Now we need to define the type of data we are including in the "sales_data" element. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Choose a String Data Type enter "min" as the Value, or anything else you prefer.

Connect the Constant output to the "type" input in the XML Writer.

Constant to Writer

Finally let's make the remaining input and output connections. Remember to map "sellers" to "sales_staff" and "sales" to "amount" - although we have used these as references we have not yet mapped them. We do not need to map anything to the "sales_data" element input as the Element Value will ensure the element itself is mapped.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<sales_staff>
 <sales_data type="min">12800</sales_data>
 <sales_assistant seller_name="John Davidson">
  <amount>12800</amount>
 </sales_assistant>
 <sales_assistant seller_name="Jane Johnson">
  <amount>23050</amount>
 </sales_assistant>
 <sales_assistant seller_name="Mark Smith">
  <amount>18200</amount>
 </sales_assistant>
</sales_staff>

The output contains the data values mapped from the source and the minimum sales value included in the new "sales_data" element, together with a String indicating the meaning of the value.

If you do not connect the Context input of the Min function, the result will be the minimum for the data source as a whole.

See Also

Average
Count
Sum
Max

Values
Constant

Data Mapping
Using Aggregate Functions
Analyzing Numerical Input


Sum
Data Mapping > Data Mapper Functions > By Category > Aggregate > Sum

Glossary Item Box

Function Name
 Sum
Category
 Aggregate
Icon
 Sum
Description
 Retrieve the sum of values within a context
Inputs

Context | Context within which to determine sum of values [optional]
Value | Value to retrieve sum of
Outputs
Result Sum of values within context
Properties
None -

Usage

The Data Mapper Aggregate Sum function allows you to retrieve the sum of a set of values within a specific context. The Context input is optional, so you can simply retrieve the sum of the specified values for the whole data source by not connecting it. If you do connect the Context input, the sum is taken within the specified parent node context. To apply the Aggregate Sum function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using sellers_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<sellers>
 <salesperson>
  <name>John Davidson</name>
  <sales>12800</sales>
 </salesperson>
 <salesperson>
  <name>Jane Johnson</name>
  <sales>23050</sales>
 </salesperson>
 <salesperson>
  <name>Mark Smith</name>
  <sales>18200</sales>
 </salesperson>
</sellers>

For our target schema we will be using sellers_target.xsd, inferred from the following XML:

Target XML Copy Code
<sales_staff>
 <sales_data type="sum">85220</sales_data>
 <sales_assistant seller_name="Ken Jameson">
  <amount>34020</amount>
 </sales_assistant>
 <sales_assistant seller_name="Lisa Matthews">
  <amount>27500</amount>
 </sales_assistant>
 <sales_assistant seller_name="Paul Norton">
  <amount>23700</amount>
 </sales_assistant>
</sales_staff>

The data models sales for individual salespeople within a retail organisation. Let's assume that, as well as mapping the salespeople and their data, we also want to determine the sum of sales across all staff members. We will record this in the "sales_data" element together with a String indicating the type of data we are recording as in the target above. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Aggregate Sum function from the Component Palette into the mapping area:

Aggregate Sum Component

The Sum function takes two inputs, representing the value to retrieve the sum of and the context in which it should be calculated. Both inputs and output of the Sum function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Connect the Context input of the Sum function to the "sellers" output in the XML Reader and the Value input to the "sales" output.

Reader to Sum

This will output the sum of sales across all sellers. In this case, the effect would be the same if we did not connect the Context input, however if we had categories of sellers, for example in different stores, we would perhaps want to calculate the sum of sales for each store, in which case the Context input would be different. Connect the Sum output to the Element Value input within the "sales_data" element in the XML Writer.

Sum to Writer

This will ensure that the "sales_data" element is written out with the sum of sales inside it each time the data is mapped.

Now we need to define the type of data we are including in the "sales_data" element. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Choose a String Data Type enter "sum" as the Value, or anything else you prefer.

Connect the Constant output to the "type" input in the XML Writer.

Constant to Writer

Finally let's make the remaining input and output connections. Remember to map "sellers" to "sales_staff" and "sales" to "amount" - although we have used these as references we have not yet mapped them. We do not need to map anything to the "sales_data" element input as the Element Value will ensure the element itself is mapped.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<sales_staff>
 <sales_data type="sum">54050</sales_data>
 <sales_assistant seller_name="John Davidson">
  <amount>12800</amount>
 </sales_assistant>
 <sales_assistant seller_name="Jane Johnson">
  <amount>23050</amount>
 </sales_assistant>
 <sales_assistant seller_name="Mark Smith">
  <amount>18200</amount>
 </sales_assistant>
</sales_staff>

The output contains the data values mapped from the source and the sum of sales included in the "sales_data" element, together with a String indicating the meaning of the value.

If you do not connect the Context input of the Sum function, the result will be the sum for the data source as a whole.
Due to type promotion, the output of the Sum function may be a value of a different type to the input values.

See Also

Average
Count
Min
Max

Values
Constant

Data Mapping
Analyzing Numerical Input
Using Aggregate Functions


Equals
Data Mapping > Data Mapper Functions > By Category > Comparator > Equals

Glossary Item Box

Function Name
 Equal
Category
 Comparator
Icon
 Equal
Description
 Determine whether one value is equal to another
Inputs

Value 1 | Value that must be equal to Value 2 for a true output
Value 2 | Value to check Value 1 against
Outputs
Result Boolean indicator - true if Value 1 is equal to Value 2, false otherwise
Properties
None -

Usage

The Data Mapper Comparator Equal function allows you to determine whether one value is equal to another. The values in question may be from the input data source or components within the Mapper, such as Constants or function outputs. Since the Equal function outputs a boolean value, it is most usefully used in conjunction with other functions such as Set and Logic components. To apply the Comparator Equal function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using staff_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<staff>
 <employee>
  <first_name>Mark</first_name>
  <second_name>Brown</second_name>
  <started>2001</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Jane</first_name>
  <second_name>Jackson</second_name>
  <started>1998</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Joe</first_name>
  <second_name>Simpson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
 <employee>
  <first_name>Lynn</first_name>
  <second_name>Nicolson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
</staff>

For our target schema we will be using staff_target.xsd, inferred from the following XML:

Target XML Copy Code
<company>
 <staff_member since="2000" contract="false">
  <f_name>Ken</f_name>
  <s_name>Jones</s_name>
 </staff_member>
 <staff_member since="2003" contract="true">
  <f_name>Linda</f_name>
  <s_name>Lee</s_name>
 </staff_member>
 <staff_member since="1998" contract="false">
  <f_name>Paul</f_name>
  <s_name>Mitchell</s_name>
 </staff_member>
</company>

The data models employees within an organisation. Let's assume that, rather than mapping all data values, we only want to map "employee" elements representing staff members who started working at the company in one particular year, i.e. whose "started" values are 2008. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Comparator Equal function from the Component Palette into the mapping area:

Comparator Equal Component

The Equal function takes two inputs representing the values you want to compare. The function output will indicate true if Value 1 is equal to Value 2, and false if it is not. Both inputs and output of the Equal function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Since we want to map only elements whose "started" values are 2008, connect the "started" output in the XML Reader to the Value 1 input in the Equal function.

Reader to Equal

Now we need to define the value to match the "started" output to. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Enter an integer type as the Data Type and 2008 as the Value.

Connect the Constant output to the Value 2 input in the Equal function.

Constant to Equal

Now each time the Mapper encounters the "started" element, it will check whether it is equal to 2008. If it is, the function will output a value of true, otherwise it will output a value of false. Let's now use this information to filter our data. Drag a Filter function from the Set section onto the Mapper. Connect its Bool input to the output of the Equal function and its Nodes input to the "employee" output in the XML Reader.

Now connect the output of the Filter function to the "staff_member" input in the XML Writer. This will ensure that an "employee" element is only mapped if its "started" value is 2008.

Filter to Writer

Finally let's make the remaining input and output connections. Remember to map "started" to "since" - although we have used this value from the source we have not yet instructed the Mapper to map it.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<company>
 <staff_member since="2008" contract="false">
  <f_name>Joe</f_name>
  <s_name>Simpson</s_name>
 </staff_member>
 <staff_member since="2008" contract="false">
  <f_name>Lynn</f_name>
  <s_name>Nicolson</s_name>
 </staff_member>
</company>

The output only contains those "staff_member" records who started in 2008. Most of the Comparator functions are particularly useful when you need to filter or transform your data depending on an unknown range of input values.

The Equal function can handle various different data types including numbers and Strings.

See Also

GreaterThan
LessThan
LessThanOrEqual
GreaterThanOrEqual
NotEqual

Set
Filter

Data Mapping
Using Set Functions
Using Aggregate Functions


GreaterThan
Data Mapping > Data Mapper Functions > By Category > Comparator > GreaterThan

Glossary Item Box

Function Name
 Greater Than
Category
 Comparator
Icon
 Greater Than
Description
 Determine whether one value is greater than another
Inputs

Value 1 | Value that must be greater than Value 2 for a true output
Value 2 | Value to check Value 1 against
Outputs
Result Boolean indicator - true if Value 1 is greater than Value 2, false otherwise
Properties
None -

Usage

The Data Mapper Comparator Greater Than function allows you to determine whether one value is greater than another. The values in question may be from the input data source or components within the Mapper, such as Constants or function outputs. Since the Greater Than function outputs a boolean value, it is most usefully used in conjunction with other functions such as Set, Aggregate and Logic components. To apply the Comparator Greater Than function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using staff_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<staff>
 <employee>
  <first_name>Mark</first_name>
  <second_name>Brown</second_name>
  <started>2001</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Jane</first_name>
  <second_name>Jackson</second_name>
  <started>1998</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Joe</first_name>
  <second_name>Simpson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
 <employee>
  <first_name>Lynn</first_name>
  <second_name>Nicolson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
</staff>

For our target schema we will be using staff_target.xsd, inferred from the following XML:

Target XML Copy Code
<company>
 <staff_member since="2000" contract="false">
  <f_name>Ken</f_name>
  <s_name>Jones</s_name>
 </staff_member>
 <staff_member since="2003" contract="true">
  <f_name>Linda</f_name>
  <s_name>Lee</s_name>
 </staff_member>
 <staff_member since="1998" contract="false">
  <f_name>Paul</f_name>
  <s_name>Mitchell</s_name>
 </staff_member>
</company>

The data models employees within an organisation. Let's assume that, rather than mapping all data values, we only want to map "employee" elements representing staff members with surnames within the second half of the alphabet - whose "second_name" values start from "N" to "Z". Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Comparator Greater Than function from the Component Palette into the mapping area:

Comparator Greater Than Component

Greater Than Added

The Greater Than function takes two inputs representing the values you want to compare. The function output will indicate true if Value 1 is greater than Value 2, and false if it is not (including if the values are equal). Both inputs and output of the Greater Than function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Since we want to map only elements whose "second_name" value comes from the second half of the alphabet, connect its output in the XML Reader to the Value 1 input in the Greater Than function.

Reader to Greater Than

Now we need to define the value to compare the input surname to. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Enter a String as the Data Type and "N" as the value.

Connect the Constant output to the Value 2 input in the Greater Than function.

Constant to Greater Than

Now each time the Mapper encounters the "second_name" element, it will check whether the name is after "N" in the alphabet (which includes names starting with "N"). If a name is greater than "N", the function will output a value of true, otherwise it will output a value of false. Let's now use this information to filter our data. Drag a Filter function from the Set section onto the Mapper. Connect its Bool input to the output of the Greater Than function and its Nodes input to the "employee" output in the XML Reader.

Now connect the output of the Filter function to the "staff_member" input in the XML Writer. This will ensure that an "employee" element is only mapped if its "second_name" element comes from the second half of the alphabet.

Filter to Writer

Finally let's make the remaining input and output connections. Remember to map "second_name" to "s_name" - although we have used this value from the source we have not yet instructed the Mapper to map it.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<company>
 <staff_member since="2008" contract="false">
  <f_name>Joe</f_name>
  <s_name>Simpson</s_name>
 </staff_member>
 <staff_member since="2008" contract="false">
  <f_name>Lynn</f_name>
  <s_name>Nicolson</s_name>
 </staff_member>
</company>

The output only contains those "staff_member" elements with surnames from "N" onwards. Most of the Comparator functions are particularly useful when you need to filter or transform your data depending on an unknown range of input values.

The Greater Than function can handle various different data types including numbers and Strings.
The Greater Than function will return false if Value 1 and Value 2 are equal. The Greater Than or Equal function will return true if the Values are equal.

See Also

LessThan
LessThanOrEqual
GreaterThanOrEqual
NotEqual
Equals

Set
Filter

Data Mapping
Using Set Functions


GreaterThanOrEqual
Data Mapping > Data Mapper Functions > By Category > Comparator > GreaterThanOrEqual

Glossary Item Box

Function Name
 Greater Than or Equal
Category
 Comparator
Icon
 Greater Than or Equal
Description
 Determine whether one value is greater than or equal to another
Inputs

Value 1 | Value that must be greater than or equal to Value 2 for a true output
Value 2 | Value to check Value 1 against
Outputs
Result Boolean indicator - true if Value 1 is greater than or equal to Value 2, false otherwise
Properties
None -

Usage

The Data Mapper Comparator Greater Than or Equal function allows you to determine whether one value is either greater than or equal to another. The values in question may be from the input data source or components within the Mapper, such as Constants or function outputs. Since the Greater Than or Equal function outputs a boolean value, it is most usefully used in conjunction with other functions such as Set, Aggregate and Logic components. To apply the Comparator Greater Than or Equal function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using staff_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<staff>
 <employee>
  <first_name>Mark</first_name>
  <second_name>Brown</second_name>
  <started>2001</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Jane</first_name>
  <second_name>Jackson</second_name>
  <started>1998</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Joe</first_name>
  <second_name>Simpson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
 <employee>
  <first_name>Lynn</first_name>
  <second_name>Nicolson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
</staff>

For our target schema we will be using staff_target.xsd, inferred from the following XML:

Target XML Copy Code
<company>
 <staff_member since="2000" contract="false">
  <f_name>Ken</f_name>
  <s_name>Jones</s_name>
 </staff_member>
 <staff_member since="2003" contract="true">
  <f_name>Linda</f_name>
  <s_name>Lee</s_name>
 </staff_member>
 <staff_member since="1998" contract="false">
  <f_name>Paul</f_name>
  <s_name>Mitchell</s_name>
 </staff_member>
</company>

The data models employees within an organisation. Let's assume that, rather than mapping all data values, we only want to map "employee" elements representing staff members who began working at the company in 2000 or later, i.e. those employees who started at the company no earlier than 2000. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Comparator Greater Than or Equal function from the Component Palette into the mapping area:

Comparator Greater Than or Equal Component

Greater Than or Equal Added

The Greater Than or Equal function takes two inputs representing the values you want to compare. The function output will indicate true if Value 1 is greater than or equal to Value 2, and false if it is not. Both inputs and output of the Greater Than or Equal function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Since we want to map only elements whose "started" value is at least 2000, connect its output in the XML Reader to the Value 1 input in the Greater Than or Equal function.

Reader to Greater Than or Equal

Now we need to define the value to compare the input start date to. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Enter an integer as the Data Type and the number 2000 as the value.

Connect the Constant output to the Value 2 input in the Greater Than or Equal function.

Constant to Greater Than or Equal

Now each time the Mapper encounters the "started" element, it will check whether the number is at least 2000. If a date is greater than or equal to 2000, the function will output a value of true, otherwise it will output a value of false. Let's now use this information to filter our data. Drag a Filter function from the Set section onto the Mapper. Connect its Bool input to the output of the Greater Than or Equal function and its Nodes input to the "employee" output in the XML Reader.

Now connect the output of the Filter function to the "staff_member" input in the XML Writer. This will ensure that an "employee" element is only mapped if its "started" element is at least 2000.

Filter to Writer

Finally let's make the remaining input and output connections. Remember to map "started" to "since" - although we have used this value from the source we have not yet instructed the Mapper to map it.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<company>
 <staff_member since="2001" contract="true">
  <f_name>Mark</f_name>
  <s_name>Brown</s_name>
 </staff_member>
 <staff_member since="2008" contract="false">
  <f_name>Joe</f_name>
  <s_name>Simpson</s_name>
 </staff_member>
 <staff_member since="2008" contract="false">
  <f_name>Lynn</f_name>
  <s_name>Nicolson</s_name>
 </staff_member>
</company>

The output only contains those "staff_member" elements with start dates from 2000 onwards. Most of the Comparator functions are particularly useful when you need to filter or transform your data depending on an unknown range of input values.

The Greater Than or Equal function can handle various different data types including numbers and Strings.
Unlike the Greater Than or Equal function, the alternative Greater Than function will return false if the values are equal.

See Also

GreaterThan
LessThan
LessThanOrEqual
NotEqual
Equals

Set
Filter

Data Mapping
Using Set Functions


LessThan
Data Mapping > Data Mapper Functions > By Category > Comparator > LessThan

Glossary Item Box

Function Name
 Less Than
Category
 Comparator
Icon
 Less Than
Description
 Determine whether one value is less than another
Inputs

Value 1 | Value that must be less than Value 2 for a true output
Value 2 | Value to check Value 1 against
Outputs
Result Boolean indicator - true if Value 1 is less than Value 2, false otherwise
Properties
None -

Usage

The Data Mapper Comparator Less Than function allows you to determine whether one value is less than another. The values in question may be from the input data source or components within the Mapper, such as Constants or function outputs. Since the Less Than function outputs a boolean value, it is most usefully used in conjunction with other functions such as Set and Logic components. To apply the Comparator Less Than function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using staff_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<staff>
 <employee>
  <first_name>Mark</first_name>
  <second_name>Brown</second_name>
  <started>2001</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Jane</first_name>
  <second_name>Jackson</second_name>
  <started>1998</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Joe</first_name>
  <second_name>Simpson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
 <employee>
  <first_name>Lynn</first_name>
  <second_name>Nicolson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
</staff>

For our target schema we will be using staff_target.xsd, inferred from the following XML:

Target XML Copy Code
<company>
 <staff_member since="2000" contract="false">
  <f_name>Ken</f_name>
  <s_name>Jones</s_name>
 </staff_member>
 <staff_member since="2003" contract="true">
  <f_name>Linda</f_name>
  <s_name>Lee</s_name>
 </staff_member>
 <staff_member since="1998" contract="false">
  <f_name>Paul</f_name>
  <s_name>Mitchell</s_name>
 </staff_member>
</company>

The data models employees within an organisation. Let's assume that, rather than mapping all data values, we only want to map "employee" elements representing staff members with surnames within the first half of the alphabet - whose "second_name" values run from "A" to "M". Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Comparator Less Than function from the Component Palette into the mapping area:

Comparator Less Than Component

Less Than Added

The Less Than function takes two inputs representing the values you want to compare. The function output will indicate true if Value 1 is less than Value 2, and false if it is not (including if the values are equal). Both inputs and output of the Less Than function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Since we want to map only elements whose "second_name" value comes from the first half of the alphabet, connect its output in the XML Reader to the Value 1 input in the Less Than function.

Reader to Less Than

Now we need to define the value to compare the input surname to. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Enter a String as the Data Type and "N" as the value.

Connect the Constant output to the Value 2 input in the Less Than function.

Constant to Less Than

Now each time the Mapper encounters the "second_name" element, it will check whether the name is before "N" in the alphabet. If a name is less than "N", the function will output a value of true, otherwise it will output a value of false.

Let's now use this information to filter our data. Drag a Filter function from the Set section onto the Mapper. Connect its Bool input to the output of the Less Than function and its Nodes input to the "employee" output in the XML Reader.

Now connect the output of the Filter function to the "staff_member" input in the XML Writer. This will ensure that an "employee" element is only mapped if its "second_name" element comes from the first half of the alphabet.

Filter to Writer

Finally let's make the remaining input and output connections. Remember to map "second_name" to "s_name" - although we have used this value from the source we have not yet instructed the Mapper to map it.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<company>
 <staff_member since="2001" contract="true">
  <f_name>Mark</f_name>
  <s_name>Brown</s_name>
 </staff_member>
 <staff_member since="1998" contract="true">
  <f_name>Jane</f_name>
  <s_name>Jackson</s_name>
 </staff_member>
</company>

The output only contains those "staff_member" elements with surnames from "A" to "M". Most of the Comparator functions are particularly useful when you need to filter or transform your data depending on an unknown range of input values.

The Less Than function can handle various different data types including numbers and Strings.
The Less Than function will return false if Value 1 and Value 2 are equal. The Less Than or Equal function will return true if the Values are equal.

See Also

GreaterThan
Equals
LessThanOrEqual
NotEqual
GreaterThanOrEqual

Set
Filter

Data Mapping
Using Set Functions


LessThanOrEqual
Data Mapping > Data Mapper Functions > By Category > Comparator > LessThanOrEqual

Glossary Item Box

Function Name
 Less Than or Equal
Category
 Comparator
Icon
 Less Than or Equal
Description
 Determine whether one value is less than or equal to another
Inputs

Value 1 | Value that must be less than or equal to Value 2 for a true output
Value 2 | Value to check Value 1 against
Outputs
Result Boolean indicator - true if Value 1 is less than or equal to Value 2, false otherwise
Properties
None -

Usage

The Data Mapper Comparator Less Than or Equal function allows you to determine whether one value is either less than or equal to another. The values in question may be from the input data source or components within the Mapper, such as Constants or function outputs. Since the Less Than or Equal function outputs a boolean value, it is most usefully used in conjunction with other functions such as Set and Logic components. To apply the Comparator Less Than or Equal function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using staff_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<staff>
 <employee>
  <first_name>Mark</first_name>
  <second_name>Brown</second_name>
  <started>2001</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Jane</first_name>
  <second_name>Jackson</second_name>
  <started>1998</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Joe</first_name>
  <second_name>Simpson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
 <employee>
  <first_name>Lynn</first_name>
  <second_name>Nicolson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
</staff>

For our target schema we will be using staff_target.xsd, inferred from the following XML:

Target XML Copy Code
<company>
 <staff_member since="2000" contract="false">
  <f_name>Ken</f_name>
  <s_name>Jones</s_name>
 </staff_member>
 <staff_member since="2003" contract="true">
  <f_name>Linda</f_name>
  <s_name>Lee</s_name>
 </staff_member>
 <staff_member since="1998" contract="false">
  <f_name>Paul</f_name>
  <s_name>Mitchell</s_name>
 </staff_member>
</company>

The data models employees within an organisation. Let's assume that, rather than mapping all data values, we only want to map "employee" elements representing staff members who have been working at the company since before 2000, i.e. those employees who started at the company in 1999 or earlier. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Comparator Less Than or Equal function from the Component Palette into the mapping area:

Comparator Less Than or Equal Component

Less Than or Equal Added

The Less Than or Equal function takes two inputs representing the values you want to compare. The function output will indicate true if Value 1 is less than or equal to Value 2, and false if it is not. Both inputs and output of the Less Than or Equal function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Since we want to map only elements whose "started" value is a maximum of 1999, connect its output in the XML Reader to the Value 1 input in the Less Than or Equal function.

Reader to Less Than or Equal

Now we need to define the value to compare the input start date to. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Enter an integer as the Data Type and the number 1999 as the value.

Connect the Constant output to the Value 2 input in the Less Than or Equal function.

Constant to Less Than or Equal

Now each time the Mapper encounters the "started" element, it will check whether the number is at most 1999. If a date is less than or equal to 1999, the function will output a value of true, otherwise it will output a value of false. Let's now use this information to filter our data. Drag a Filter function from the Set section onto the Mapper. Connect its Bool input to the output of the Less Than or Equal function and its Nodes input to the "employee" output in the XML Reader.

Now connect the output of the Filter function to the "staff_member" input in the XML Writer. This will ensure that an "employee" element is only mapped if its "since" element is at most 1999.

Filter to Writer

Finally let's make the remaining input and output connections. Remember to map "started" to "since" - although we have used this value from the source we have not yet instructed the Mapper to map it.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<company>
 <staff_member since="1998" contract="true">
  <f_name>Jane</f_name>
  <s_name>Jackson</s_name>
 </staff_member>
</company>

The output only contains those "staff_member" elements with start dates up to and including 1999. Most of the Comparator functions are particularly useful when you need to filter or transform your data depending on an unknown range of input values.

The Less Than or Equal function can handle various different data types including numbers and Strings.
Unlike the Less Than or Equal function, the alternative Less Than function will return false if the values are equal.

See Also

Equals
GreaterThan
LessThan
GreaterThanOrEqual
NotEqual

Set
Filter

Data Mapping
Using Set Functions


NotEqual
Data Mapping > Data Mapper Functions > By Category > Comparator > NotEqual

Glossary Item Box

Function Name
 Not Equal
Category
 Comparator
Icon
 Not Equal
Description
 Determine whether one value is not equal to another
Inputs

Value 1 | Value that must not be equal to Value 2 for a true output
Value 2 | Value to check Value 1 against
Outputs
Result Boolean indicator - true if Value 1 is not equal to Value 2, false otherwise
Properties
None -

Usage

The Data Mapper Comparator Not Equal function allows you to determine whether one value is not equal to another. The values in question may be from the input data source or components within the Mapper, such as Constants or function outputs. Since the Not Equal function outputs a boolean value, it is most usefully used in conjunction with other functions such as Set and Logic components. To apply the Comparator Not Equal function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using staff_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<staff>
 <employee>
  <first_name>Mark</first_name>
  <second_name>Brown</second_name>
  <started>2001</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Jane</first_name>
  <second_name>Jackson</second_name>
  <started>1998</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Joe</first_name>
  <second_name>Simpson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
 <employee>
  <first_name>Lynn</first_name>
  <second_name>Nicolson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
</staff>

For our target schema we will be using staff_target.xsd, inferred from the following XML:

Target XML Copy Code
<company>
 <staff_member since="2000" contract="false">
  <f_name>Ken</f_name>
  <s_name>Jones</s_name>
 </staff_member>
 <staff_member since="2003" contract="true">
  <f_name>Linda</f_name>
  <s_name>Lee</s_name>
 </staff_member>
 <staff_member since="1998" contract="false">
  <f_name>Paul</f_name>
  <s_name>Mitchell</s_name>
 </staff_member>
</company>

The data models employees within an organisation. Let's assume that, rather than mapping all data values, we only want to map "employee" elements representing staff members who did not start working at the company in a particular year. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Comparator Not Equal function from the Component Palette into the mapping area:

Comparator Not Equal Component

Not Equal Added

The Not Equal function takes two inputs representing the values you want to compare. The function output will indicate true if Value 1 is not equal to Value 2, and false if the values are equal. Both inputs and output of the Not Equal function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Since we want to map only elements whose "started" value is not a particular year, let's say 1998, connect the "started" output in the XML Reader to the Value 1 input in the Not Equal function.

Reader to Not Equal

Now we need to define the value to check against the "started" value. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Enter an integer Data Type and 1998 as the Value.

Connect the Constant output to the Value 2 input in the Not Equal function.

Constant to Not Equal

Now each time the Mapper encounters the "started" element, it will check whether it is not equal to 1998. If it is not equal to it, the function will output a value of true, otherwise it will output a value of false. Let's now use this information to filter our data. Drag a Filter function from the Set section onto the Mapper. Connect its Bool input to the output of the Not Equal function and its Nodes input to the "employee" output in the XML Reader.

Now connect the output of the Filter function to the "staff_member" input in the XML Writer. This will ensure that an "employee" element is only mapped if its "started" value is not 1998.

Filter to Writer

Finally let's make the remaining input and output connections. Remember to map "started" to "since" - although we have used this value from the source we have not yet instructed the Mapper to map it.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<company>
 <staff_member since="2001" contract="true">
  <f_name>Mark</f_name>
  <s_name>Brown</s_name>
 </staff_member>
 <staff_member since="2008" contract="false">
  <f_name>Joe</f_name>
  <s_name>Simpson</s_name>
 </staff_member>
 <staff_member since="2008" contract="false">
  <f_name>Lynn</f_name>
  <s_name>Nicolson</s_name>
 </staff_member>
</company>

The output only contains those "staff_member" elements with start dates other than 1998. Most of the Comparator functions are particularly useful when you need to filter or transform your data depending on an unknown range of input values.

The Not Equal function can handle various different data types including numbers and Strings.

See Also

Equals
GreaterThan
LessThan
LessThanOrEqual
GreaterThanOrEqual

Set
Filter

Data Mapping
Using Set Functions


CreateDate
Data Mapping > Data Mapper Functions > By Category > Date Time > CreateDate

Glossary Item Box

Function Name
 CreateDate
Category
 DateTime
Icon
 Day
Description
 Creates a Date type from year/month/day values
Inputs

Year | The year part of the date (required)
Month | The month part of the date (1-12 required)
Day | The day part of the date (1-31 required)
Outputs
Date The resulting date
Properties
None -

Usage

Creates a Date value from the 3 component parts. The date must be a real date (i.e. 31st of Feb is invalid), if an invalid date is entered then a runtime error is raised and the transform terminates.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

CreateDateTime
CreateTime
Day
Hour
Millisecond
Minute
Month
Now
Second
Today
Year
ToLocal
ToUTC
SetTimezone
DateAdd


CreateDateTime
Data Mapping > Data Mapper Functions > By Category > Date Time > CreateDateTime

Glossary Item Box

Function Name
 CreateDateTime
Category
 DateTime
Icon
 Day
Description
 Creates a DateTime from a Date and a Time value
Inputs

Date | The year part of the DateTime value (required)
Time | The time part of the DateTime value (optional defaults to 00:00:00)
Outputs
Date The resulting DateTime value
Properties
None -

Usage

Creates a DateTime value from a date and a time value.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

CreateDate
CreateTime
Day
Hour
Millisecond
Minute
Month
Now
Second
Today
Year
ToLocal
ToUTC
SetTimezone
DateAdd


CreateTime
Data Mapping > Data Mapper Functions > By Category > Date Time > CreateTime

Glossary Item Box

Function Name
 CreateTime
Category
 DateTime
Icon
 Day
Description
 Creates a Time type from hour/minute/second/millisecond/timezone values
Inputs

Hour | The hour part of the time (0-23 optional, defaults to 0)
Minute | The minute part of the time (0-59 optional, defaults to 0)
Second | The second part of the time (0-59 optional, defaults to 0)
Milliseconds | The second part of the time (0-999 optional, defaults to 0)
Outputs
Time The resulting time value
Properties
None -

Usage

Creates a Time value from its component parts. The input pars of the time must be valid otherwise a runtime error is raised and the transform terminates.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

CreateDate
CreateDateTime
Day
Hour
Millisecond
Minute
Month
Now
Second
Today
Year
ToLocal
ToUTC
SetTimezone
DateAdd


DateAdd
Data Mapping > Data Mapper Functions > By Category > Date Time > DateAdd

Glossary Item Box

Function Name
 DateAdd
Category
 DateTime
Icon
 DateAdd
Description
 Adds or subtracts a number of days/hours/minutes/seconds from an Date/Datetime
Inputs

Date | The Date/DateTime/Time to add to
Days | The number of days to add (can be a negative number)
Hours | The number of hours to add (can be a negative number)
Minutes | The number of minutes to add (can be a negative number)
Seconds | The number of seconds to add (can be a negative number)
Milliseconds | The number of milliseconds to add (can be a negative number)
Outputs
Result A Date time with the days/hours/minutes/seconds added to it
Properties
None -

Usage

The Data Mapper DateAdd function takes an existing Date/DateTime/Time value and adds on a number of days/hours/minutes/seconds, the resulting DateTime is then returned.

In order to subtract, use negative number for days/hours/minutes/seconds.

See Also

Hour
Millisecond
Minute
Month
Year
Second


Day
Data Mapping > Data Mapper Functions > By Category > Date Time > Day

Glossary Item Box

Function Name
 Day
Category
 DateTime
Icon
 Day
Description
 Retrieve the day portion of a DateTime value
Inputs
DateTime DateTime value to retrieve day from
Outputs
Day Day value from DateTime input
Properties
None -

Usage

The Data Mapper DateTime Day function returns the day portion of a DateTime value. Many applications use DateTime values to record information about events, for example retail or other account transactions. It is often necessary to retrieve particular portions of a DateTime value, such as the day, or to separate the DateTime into its component parts for the target application. To apply the DateTime Day function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using sales_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<sales>
 <purchase>
  <sale_id>9099879823</sale_id>
  <item_ref>ab65gh7hh7</item_ref>
  <customer_id>34522</customer_id>
  <transaction>2003-01-20T07:15:32.42</transaction>
 </purchase>
 <purchase>
  <sale_id>2390865748</sale_id>
  <item_ref>g7hy65tfd3</item_ref>
  <customer_id>12009</customer_id>
  <transaction>2007-06-12T23:35:10.09</transaction>
 </purchase>
 <purchase>
  <sale_id>8250987123</sale_id>
  <item_ref>d4rf54r0op</item_ref>
  <customer_id>28769</customer_id>
  <transaction>2006-11-27T17:20:09.88</transaction>
 </purchase>
</sales>

For our target schema we will be using sales_alt_target.xsd, inferred from the following XML:

Target XML Copy Code
<transactions>
 <sale id="8987612312" item="y6yt5i93e4">
  <cust_id>14398</cust_id>
  <day>20</day>
  <month>10</month>
 </sale>
 <sale id="2090176549" item="i8u7b45f7y">
  <cust_id>23112</cust_id>
  <day>12</day>
  <month>8</month>
 </sale>
 <sale id="2819283722" item="y6yt5i93e4">
  <cust_id>34309</cust_id>
  <day>9</day>
  <month>6</month>
 </sale>
</transactions>

The data models retail transactions, including the DateTime for when a sale was made. Let's assume that in this case we want to map the day and month during which each transaction took place, perhaps for marketing purposes. We will therefore need to retrieve both the day and month values from the input DateTime value, mapping these two to separate elements in the target. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the DateTime Day function from the Component Palette into the mapping area:

Day Transform Added

The Day function takes a single input, the DateTime in question, giving an output comprising the day portion. The input should be connected to the source item, which will normally be an item in the XML Reader. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper, for example if you plan on using the Day value to sort or filter the data in terms of purchases made throughout the months in a year.

Connect the Day function input to the "transaction" output in the XML Reader and the Day output to the "day" input in the XML Writer.

Let's now map the month value as well. Drag a Month component from the DateTime section onto the Mapper. Connect it also to the "transaction" output in the XML Reader and to the "month" input in the XML Writer.

Now the Mapper will retrieve two values from each DateTime input in the source data. Each transaction will include elements for both the day and the month.

Finally, connect the remaining inputs and outputs:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<transactions>
 <sale id="9099879823" item="ab65gh7hh7">
  <cust_id>34522</cust_id>
  <day>20</day>
  <month>1</month>
 </sale>
 <sale id="2390865748" item="g7hy65tfd3">
  <cust_id>12009</cust_id>
  <day>12</day>
  <month>6</month>
 </sale>
 <sale id="8250987123" item="d4rf54r0op">
  <cust_id>28769</cust_id>
  <day>27</day>
  <month>11</month>
 </sale>
</transactions>

The output contains indicators of the days and months during which each transaction was made, with day represented as a number between 1 and 31.

If you pass a value to the Day function that is not a DateTime, the Mapper will attempt to parse it. If you pass the Day function a DateTime value which does not contain a day portion, the function will output a value of 1 by default.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Hour
Millisecond
Minute
Month
Year
Second


Hour
Data Mapping > Data Mapper Functions > By Category > Date Time > Hour

Glossary Item Box

Function Name
 Hour
Category
 DateTime
Icon
 Hour
Description
 Retrieve the hour portion of a DateTime value
Inputs
DateTime DateTime value to retrieve hour from
Outputs
Hour Hour value from DateTime input
Properties
None -

Usage

The Data Mapper DateTime Hour function returns the hour portion of a DateTime value. Many applications use DateTime values to record information about events, for example retail or other account transactions. It is often necessary to retrieve particular portions of a DateTime value, such as the hour, or to separate the DateTime into its component parts for the target application. To apply the DateTime Hour function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using sales_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<sales>
 <purchase>
  <sale_id>9099879823</sale_id>
  <item_ref>ab65gh7hh7</item_ref>
  <customer_id>34522</customer_id>
  <transaction>2003-01-20T07:15:32.42</transaction>
 </purchase>
 <purchase>
  <sale_id>2390865748</sale_id>
  <item_ref>g7hy65tfd3</item_ref>
  <customer_id>12009</customer_id>
  <transaction>2007-06-12T23:35:10.09</transaction>
 </purchase>
 <purchase>
  <sale_id>8250987123</sale_id>
  <item_ref>d4rf54r0op</item_ref>
  <customer_id>28769</customer_id>
  <transaction>2006-11-27T17:20:09.88</transaction>
 </purchase>
</sales>

For our target schema we will be using sales_target.xsd, inferred from the following XML:

Target XML Copy Code
<transactions>
 <sale id="8987612312" item="y6yt5i93e4">
  <cust_id>14398</cust_id>
  <bought_time>20</bought_time>
 </sale>
 <sale id="2090176549" item="i8u7b45f7y">
  <cust_id>23112</cust_id>
  <bought_time>11</bought_time>
 </sale>
 <sale id="2819283722" item="y6yt5i93e4">
  <cust_id>34309</cust_id>
  <bought_time>09</bought_time>
 </sale>
</transactions>

The data models retail transactions, including the DateTime for when a sale was made. Let's assume that in this case we only want to map the hour at which each transaction took place, perhaps for marketing purposes. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the DateTime Hour function from the Component Palette into the mapping area:

Hour Transform Added

The Hour function takes a single input, the DateTime in question, giving an output comprising the hour portion. The input should be connected to the source item, which will normally be an item in the XML Reader. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper, for example if you plan on using the Hour value to sort or filter the data in terms of purchases made at different times of day.

Connect the Hour function input to the "transaction" output in the XML Reader and the Hour output to the "bought_time" input in the XML Writer.

Now the only portion of the DateTime mapped will be the hour value. If you want to map more than one part of a DateTime, you can use the other DateTime functions, connecting them each to your source DateTime input and mapping them forward as necessary.

Finally, connect the remaining inputs and outputs:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<transactions>
 <sale id="9099879823" item="ab65gh7hh7">
  <cust_id>34522</cust_id>
  <bought_time>7</bought_time>
 </sale>
 <sale id="2390865748" item="g7hy65tfd3">
  <cust_id>12009</cust_id>
  <bought_time>23</bought_time>
 </sale>
 <sale id="8250987123" item="d4rf54r0op">
  <cust_id>28769</cust_id>
  <bought_time>17</bought_time>
 </sale>
</transactions>

The "bought_time" contains an indicator of the hour at which each transaction was made, represented as a number between 0 and 23.

If you pass a value to the Hour function that is not a DateTime, the Mapper will attempt to parse it. If you pass the Hour function a DateTime value which does not contain an hour portion, the function will output a value of zero by default.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Day
Millisecond
Minute
Month
Second
Year


Millisecond
Data Mapping > Data Mapper Functions > By Category > Date Time > Millisecond

Glossary Item Box

Function Name
 Millisecond
Category
 DateTime
Icon
 Millisecond
Description
 Retrieve the millisecond portion of a DateTime value
Inputs
DateTime DateTime value to retrieve millisecond from
Outputs
Millisecond Millisecond value from DateTime input
Properties
None -

Usage

The Data Mapper DateTime Millisecond function returns the millisecond portion of a DateTime value. Many applications use DateTime values to record information about events, for example to process data such as weather incidents. It is often necessary to retrieve particular portions of a DateTime value, such as the millisecond, or to separate the DateTime into its component parts for the target application. To apply the DateTime Millisecond function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using weather_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<events>
 <weather_event>
  <incident_type>Tidal Wave</incident_type>
  <severity>5</severity>
  <recorded>2005-10-23T08:20:45.57</recorded>
 </weather_event>
 <weather_event>
  <incident_type>Hurricane</incident_type>
  <severity>9</severity>
  <recorded>2007-09-14T11:40:12.44</recorded>
 </weather_event>
</events>

For our target schema we will be using weather_alt_target.xsd, inferred from the following XML:

Target XML Copy Code
<weather>
 <incident type="lightning" severity="7">
  <min>12</min>
  <sec>31</sec>
  <mil>325</mil>
 </incident>
 <incident type="tornado" severity="10">
  <min>23</min>
  <sec>45</sec>
  <mil>778</mil>
 </incident>
</weather>

The data models weather events, including the DateTime for when an incident was recorded. Let's assume that in this case we want to map the millisecond within the second and minute that each event occurred. We will map all three parts of the DateTime to dedicated elements in the target as above. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the DateTime Millisecond function from the Component Palette into the mapping area:

Millisecond Transform Added

The Millisecond function takes a single input, the DateTime in question, giving an output comprising the millisecond portion. The input should be connected to the source item, which will normally be an item in the XML Reader. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper, for example if you plan on using the millisecond value to sort or filter the data.

Connect the Millisecond function input to the "recorded" output in the XML Reader and the Millisecond output to the "mil" input in the XML Writer.

Now let's do the same for the minute portion of the DateTime. Drag a Minute component onto the Mapper, connecting its input to the "recorded" output in the XML Reader and its output to the "min" input in the XML Writer.

Do the same for the Second function now, connecting it to the "recorded" output in the XML Reader and the "sec" input in the XML Writer.

Finally, connect the remaining inputs and outputs:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<weather>
 <incident type="Tidal Wave" severity="5">
  <min>20</min>
  <sec>45</sec>
  <mil>570</mil>
 </incident>
 <incident type="Hurricane" severity="9">
  <min>40</min>
  <sec>12</sec>
  <mil>440</mil>
 </incident>
</weather>

The output contains the millisecond portion of each DateTime value for a single incident, represented as a number between 0 and 999, along with the minute and second data in each case.

If you pass a value to the Millisecond function that is not a DateTime, the Mapper will attempt to parse it. If you pass the Millisecond function a DateTime value which does not contain a millisecond portion, the function will output a value of 0 by default.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Day
Hour
Minute
Month
Year
Second


Minute
Data Mapping > Data Mapper Functions > By Category > Date Time > Minute

Glossary Item Box

Function Name
 Minute
Category
 DateTime
Icon
 Minute
Description
 Retrieve the minute portion of a DateTime value
Inputs
DateTime DateTime value to retrieve minute from
Outputs
Minute Minute value from DateTime input
Properties
None -

Usage

The Data Mapper DateTime Minute function returns the minute portion of a DateTime value. Many applications use DateTime values to record information about events, for example to process data such as weather incidents. It is often necessary to retrieve particular portions of a DateTime value, such as the minute, or to separate the DateTime into its component parts for the target application. To apply the DateTime Minute function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using weather_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<events>
 <weather_event>
  <incident_type>Tidal Wave</incident_type>
  <severity>5</severity>
  <recorded>2005-10-23T08:20:45.57</recorded>
 </weather_event>
 <weather_event>
  <incident_type>Hurricane</incident_type>
  <severity>9</severity>
  <recorded>2007-09-14T11:40:12.44</recorded>
 </weather_event>
</events>

For our target schema we will be using weather_target.xsd, inferred from the following XML:

Target XML Copy Code
<weather>
 <incident type="lightning" severity="7">
  <time type="minute">12</time>
 </incident>
 <incident type="tornado" severity="10">
  <time type="minute">39</time>
 </incident>
</weather>

The data models weather events, including the DateTime for when an incident was recorded. Let's assume that in this case we want to map the minute within the hour that each event occurred. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the DateTime Minute function from the Component Palette into the mapping area:

Minute Transform Added

The Minute function takes a single input, the DateTime in question, giving an output comprising the minute portion. The input should be connected to the source item, which will normally be an item in the XML Reader. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper, for example if you plan on using the minute value to sort or filter the data.

We want to map the "recorded" DateTime value to the "time" element in our target, so connect these between Reader and Writer.

Reader to Writer

Now connect the Minute function input also to the "recorded" output in the XML Reader and the Minute output to the Element Value for the "time" element in the XML Writer, so that the content of the element will be the minute part of the DateTime.

Remember that the target XML has an attribute in the "time" element indicating the type of time data in question. To add this, let's drag a Constant Value from the Data Type section onto the Mapper. Right-click it, choosing Show Properties. Select a String Data Type and enter "minute" as the value.

Now connect the Constant output to the "type" attribute input for the "time" element in the XML Writer.

Finally, connect the remaining inputs and outputs:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<weather>
 <incident type="Tidal Wave" severity="5">
  <time type="minute">20</time>
 </incident>
 <incident type="Hurricane" severity="9">
  <time type="minute">40</time>
 </incident>
</weather>

The output contains the minute portion of each DateTime value for a single incident, represented as a number between 0 and 59.

If you pass a value to the Minute function that is not a DateTime, the Mapper will attempt to parse it. If you pass the Minute function a DateTime value which does not contain a minute portion, the function will output a value of 0 by default.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Day
Hour
Millisecond
Month
Second
Year


Month
Data Mapping > Data Mapper Functions > By Category > Date Time > Month

Glossary Item Box

Function Name
 Month
Category
 DateTime
Icon
 Month
Description
 Retrieve the month portion of a DateTime value
Inputs
DateTime DateTime value to retrieve month from
Outputs
Month Month value from DateTime input
Properties
None -

Usage

The Data Mapper DateTime Month function returns the month portion of a DateTime value. Many applications use DateTime values to record information about events, for example retail or other account transactions. It is often necessary to retrieve particular portions of a DateTime value, such as the month, or to separate the DateTime into its component parts for the target application. To apply the DateTime Month function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using sales_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<sales>
 <purchase>
  <sale_id>9099879823</sale_id>
  <item_ref>ab65gh7hh7</item_ref>
  <customer_id>34522</customer_id>
  <transaction>2003-01-20T07:15:32.42</transaction>
 </purchase>
 <purchase>
  <sale_id>2390865748</sale_id>
  <item_ref>g7hy65tfd3</item_ref>
  <customer_id>12009</customer_id>
  <transaction>2007-06-12T23:35:10.09</transaction>
 </purchase>
 <purchase>
  <sale_id>8250987123</sale_id>
  <item_ref>d4rf54r0op</item_ref>
  <customer_id>28769</customer_id>
  <transaction>2006-11-27T17:20:09.88</transaction>
 </purchase>
</sales>

For our target schema we will be using sales_target.xsd, inferred from the following XML:

Target XML Copy Code
<transactions>
 <sale id="8987612312" item="y6yt5i93e4">
  <cust_id>14398</cust_id>
  <bought_time>8</bought_time>
 </sale>
 <sale id="2090176549" item="i8u7b45f7y">
  <cust_id>23112</cust_id>
  <bought_time>11</bought_time>
 </sale>
 <sale id="2819283722" item="y6yt5i93e4">
  <cust_id>34309</cust_id>
  <bought_time>9</bought_time>
 </sale>
</transactions>

The data models retail transactions, including the DateTime for when a sale was made. Let's assume that in this case we only want to map the month during which each transaction took place, perhaps for marketing purposes. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the DateTime Month function from the Component Palette into the mapping area:

Month Transform Added

The Month function takes a single input, the DateTime in question, giving an output comprising the month portion. The input should be connected to the source item, which will normally be an item in the XML Reader. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper, for example if you plan on using the Month value to sort or filter the data in terms of purchases made at different times of year.

Connect the Month function input to the "transaction" output in the XML Reader and the Month output to the "bought_time" input in the XML Writer.

Now the only portion of the DateTime mapped will be the month value. If you want to map more than one part of a DateTime, you can use the other DateTime functions, connecting them each to your source DateTime input and mapping them forward as necessary.

Finally, connect the remaining inputs and outputs:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<transactions>
 <sale id="9099879823" item="ab65gh7hh7">
  <cust_id>34522</cust_id>
  <bought_time>1</bought_time>
 </sale>
 <sale id="2390865748" item="g7hy65tfd3">
  <cust_id>12009</cust_id>
  <bought_time>6</bought_time>
 </sale>
 <sale id="8250987123" item="d4rf54r0op">
  <cust_id>28769</cust_id>
  <bought_time>11</bought_time>
 </sale>
</transactions>

The "bought_time" contains an indicator of the month during which each transaction was made, represented as a number between 1 and 12.

If you pass a value to the Month function that is not a DateTime, the Mapper will attempt to parse it. If you pass the Month function a DateTime value which does not contain a month portion, the function will output a value of 1 by default.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Day
Hour
Millisecond
Minute
Second
Year


Now
Data Mapping > Data Mapper Functions > By Category > Date Time > Now

Glossary Item Box

Function Name
 Now
Category
 DateTime
Icon
 Now
Description
 Return the current DateTime
Inputs
None -
Outputs
Result DateTime when mapping occurs
Properties
None -

Usage

The Data Mapper DateTime Now function returns the current DateTime value. When mapping data from one application to another, developers often record information related to the mapping activity itself as well as the data. For example, you may wish to use the mapping time as a record of the last time the data was considered valid within the application context. By using the Now function, you provide a log of the time at which the mapping process was executed, which your target application can then refer to. To apply the DateTime Now function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using client_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<clients>
 <customer business="false">
  <name>Mary Smith</name>
 </customer>
 <customer business="true">
  <name>Steve Jackson</name>
 </customer>
</clients>

For our target schema we will be using client_alt_target.xsd, inferred from the following XML:

Target XML Copy Code
<current_customers>
 <client>
  <is_business>false</is_business>
  <contact_name>Jim Brown</contact_name>
  <transferred>2004-03-22T08:20:45.57</transferred>
 </client>
 <client>
  <is_business>true</is_business>
  <contact_name>Jack Taylor</contact_name>
  <transferred>2009-10-15T10:38:23.11</transferred>
 </client>
</current_customers>

The data models client records, with the target including an indicator of a DateTime, which will be the date and time the source data is mapped. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the DateTime Now function from the Component Palette into the mapping area:

Now Transform Added

The Now function has no inputs and one output, the current DateTime. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper, for example if you plan on using the Now value as input to some other function.

Connect the Now function output to the "transferred" input in the XML Writer.

Now, when mapping occurs, the Mapper will write the current DateTime to a "transferred" element within each "client" parent element in the output.

Finally, connect the remaining inputs and outputs:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<current_customers>
 <client>
  <is_business>false</is_business>
  <contact_name>Mary Smith</contact_name>
  <transferred>2012-05-03T09:13:52.296875Z</transferred>
 </client>
 <client>
  <is_business>true</is_business>
  <contact_name>Steve Jackson</contact_name>
  <transferred>2012-05-03T09:13:52.296875Z</transferred>
 </client>
</current_customers>

The output contains the DateTime for when the data was mapped.

The Now function outputs the full DateTime value, including the day, month, year and time (including hour, minute, second and millisecond). If you only need to record the day on which mapping occurred, you can opt for the Today function as an alternative.

See Also

Today


Second
Data Mapping > Data Mapper Functions > By Category > Date Time > Second

Glossary Item Box

Function Name
 Second
Category
 DateTime
Icon
 Second
Description
 Retrieve the second portion of a DateTime value
Inputs
DateTime DateTime value to retrieve second from
Outputs
Second Second value from DateTime input
Properties
None -

Usage

The Data Mapper DateTime Second function returns the second portion of a DateTime value. Many applications use DateTime values to record information about events, for example to process data such as weather incidents. It is often necessary to retrieve particular portions of a DateTime value, such as the second, or to separate the DateTime into its component parts for the target application. To apply the DateTime Second function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using weather_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<events>
 <weather_event>
  <incident_type>Tidal Wave</incident_type>
  <severity>5</severity>
  <recorded>2005-10-23T08:20:45.57</recorded>
 </weather_event>
 <weather_event>
  <incident_type>Hurricane</incident_type>
  <severity>9</severity>
  <recorded>2007-09-14T11:40:12.44</recorded>
 </weather_event>
</events>

For our target schema we will be using weather_target.xsd, inferred from the following XML:

Target XML Copy Code
<weather>
 <incident type="lightning" severity="7">
  <time type="second">12</time>
 </incident>
 <incident type="tornado" severity="10">
  <time type="second">39</time>
 </incident>
</weather>

The data models weather events, including the DateTime for when an incident was recorded. Let's assume that in this case we want to map the second within the minute that each event occurred. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the DateTime Second function from the Component Palette into the mapping area:

Second Transform Added

The Second function takes a single input, the DateTime in question, giving an output comprising the second portion. The input should be connected to the source item, which will normally be an item in the XML Reader. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper, for example if you plan on using the Second value to sort or filter the data.

We want to map the "recorded" DateTime value to the "time" element in our target, so connect these between Reader and Writer.

Reader to Writer

Now connect the Second function input also to the "recorded" output in the XML Reader and the Second output to the Element Value for the "time" element in the XML Writer, so that the content of the element will be the second part of the DateTime.

Remember that the target XML has an attribute in the "time" element indicating the type of time data in question. To add this, let's drag a Constant Value from the Data Type section onto the Mapper. Right-click it, choosing Show Properties. Select a String Data Type and enter "second" as the value.

Now connect the Constant output to the "type" attribute input for the "time" element in the XML Writer.

Finally, connect the remaining inputs and outputs between Reader and Writer:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<weather>
 <incident type="Tidal Wave" severity="5">
  <time type="second">45</time>
 </incident>
 <incident type="Hurricane" severity="9">
  <time type="second">12</time>
 </incident>
</weather>

The output contains the second portion of each DateTime value for a single incident, represented as a number between 0 and 59.

If you pass a value to the Second function that is not a DateTime, the Mapper will attempt to parse it. If you pass the Second function a DateTime value which does not contain a second portion, the function will output a value of 0 by default.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Day
Hour
Millisecond
Minute
Month
Year


Today
Data Mapping > Data Mapper Functions > By Category > Date Time > Today

Glossary Item Box

Function Name
 Today
Category
 DateTime
Icon
 Today
Description
 Return the DateTime for the current date
Inputs
None -
Outputs
Result DateTime for date when mapping occurs
Properties
None -

Usage

The Data Mapper DateTime Today function returns the current date value. When mapping data from one application to another, developers often record information related to the mapping activity itself as well as the data. For example, you may wish to use the mapping time as a record of the last time the data was considered valid within the application context. By using the Today function, you provide a log of the date on which the mapping process was executed, which your target application can then refer to. To apply the DateTime Today function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using client_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<clients>
 <customer business="false">
  <name>Mary Smith</name>
 </customer>
 <customer business="true">
  <name>Steve Jackson</name>
 </customer>
</clients>

For our target schema we will be using client_alt_target.xsd, inferred from the following XML:

Target XML Copy Code
<current_customers>
 <client>
  <is_business>false</is_business>
  <contact_name>Jim Brown</contact_name>
  <transferred>2004-03-22</transferred>
 </client>
 <client>
  <is_business>true</is_business>
  <contact_name>Jack Taylor</contact_name>
  <transferred>2009-10-15</transferred>
 </client>
</current_customers>

The data models client records, with the target including an indicator of a DateTime, which in this case will be the date on which the source data is mapped. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the DateTime Today function from the Component Palette into the mapping area:

Today Transform Added

The Today function has no inputs and one output, the current date value in DateTime format. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper, for example if you plan on using the Today value as input to some other function.

Connect the Today function output to the "transferred" input in the XML Writer.

Now, when mapping occurs, the Mapper will write the current DateTime date to a "transferred" element within each "client" parent element in the output.

Finally, connect the remaining inputs and outputs between Reader and Writer:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<current_customers>
 <client>
  <is_business>false</is_business>
  <contact_name>Mary Smith</contact_name>
  <transferred>2012-05-02T23:00:00Z</transferred>
 </client>
 <client>
  <is_business>true</is_business>
  <contact_name>Steve Jackson</contact_name>
  <transferred>2012-05-02T23:00:00Z</transferred>
 </client>
</current_customers>

The output contains the DateTime for when the day the data was mapped. The time portion is provided although its content is only a placeholder - this allows your target processing to alter the time portion if you require.

The Today function outputs the DateTime value, including the day, month and year, with a placeholder for the time portion. If you need to record the full DateTime on which mapping occurred, including the time (hours, minutes, seconds and milliseconds), you can opt for the Now function as an alternative.

See Also

Now


Year
Data Mapping > Data Mapper Functions > By Category > Date Time > Year

Glossary Item Box

Function Name
 Year
Category
 DateTime
Icon
 Year
Description
 Retrieve the year portion of a DateTime value
Inputs
DateTime DateTime value to retrieve year from
Outputs
Year Year value from DateTime input
Properties
None -

Usage

The Data Mapper DateTime Year function returns the year portion of a DateTime value. Many applications use DateTime values to record information about events, for example retail or other account transactions. It is often necessary to retrieve particular portions of a DateTime value, such as the year, or to separate the DateTime into its component parts for the target application. To apply the DateTime Year function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using sales_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<sales>
 <purchase>
  <sale_id>9099879823</sale_id>
  <item_ref>ab65gh7hh7</item_ref>
  <customer_id>34522</customer_id>
  <transaction>2003-01-20T07:15:32.42</transaction>
 </purchase>
 <purchase>
  <sale_id>2390865748</sale_id>
  <item_ref>g7hy65tfd3</item_ref>
  <customer_id>12009</customer_id>
  <transaction>2007-06-12T23:35:10.09</transaction>
 </purchase>
 <purchase>
  <sale_id>8250987123</sale_id>
  <item_ref>d4rf54r0op</item_ref>
  <customer_id>28769</customer_id>
  <transaction>2006-11-27T17:20:09.88</transaction>
 </purchase>
</sales>

For our target schema we will be using sales_target.xsd, inferred from the following XML:

Target XML Copy Code
<transactions>
 <sale id="8987612312" item="y6yt5i93e4">
  <cust_id>14398</cust_id>
  <bought_time>2009</bought_time>
 </sale>
 <sale id="2090176549" item="i8u7b45f7y">
  <cust_id>23112</cust_id>
  <bought_time>2011</bought_time>
 </sale>
 <sale id="2819283722" item="y6yt5i93e4">
  <cust_id>34309</cust_id>
  <bought_time>2007</bought_time>
 </sale>
</transactions>

The data models retail transactions, including the DateTime for when a sale was made. Let's assume that in this case we only want to map the year during which each transaction took place, perhaps for marketing purposes. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the DateTime Year function from the Component Palette into the mapping area:

Year Transform Added

The Year function takes a single input, the DateTime in question, giving an output comprising the year portion. The input should be connected to the source item, which will normally be an item in the XML Reader. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper, for example if you plan on using the Year value to sort or filter the data in terms of purchases made over a period of several years.

Connect the Year function input to the "transaction" output in the XML Reader and the Year output to the "bought_time" input in the XML Writer.

Now the only portion of the DateTime mapped will be the year value. If you want to map more than one part of a DateTime, you can use the other DateTime functions, connecting them each to your source DateTime input and mapping them forward as necessary.

Finally, connect the remaining inputs and outputs:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<transactions>
 <sale id="9099879823" item="ab65gh7hh7">
  <cust_id>34522</cust_id>
  <bought_time>2003</bought_time>
 </sale>
 <sale id="2390865748" item="g7hy65tfd3">
  <cust_id>12009</cust_id>
  <bought_time>2007</bought_time>
 </sale>
 <sale id="8250987123" item="d4rf54r0op">
  <cust_id>28769</cust_id>
  <bought_time>2006</bought_time>
 </sale>
</transactions>

The "bought_time" contains an indicator of the year during which each transaction was made, represented as a number.

If you pass a value to the Year function that is not a DateTime, the Mapper will attempt to parse it. If you pass the Year function a DateTime value which does not contain a year portion, the function will output the current year by default.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Day
Hour
Millisecond
Minute
Month
Second


CombinePath
Data Mapping > Data Mapper Functions > By Category > File > CombinePath

Glossary Item Box

Function Name
 CombinePath
Category
 File
Icon
Description
 Combines several path parts together adding the \ separator
Inputs

Path Part 1 | The first part of the path to add
Path Part 2 | The second part of the path to add
... | More inputs can be added see Variable Function Inputs
Outputs
Path The combined path string.
Properties
None -

Reads all the values from the inputs and combines them to form a path, adding the path separator \ if required.

Unconnected inputs are ignored.

Sample output

Input Path Part 1 | Input Path Part 2 | Input Path Part 3 | Output
c:\temp\ | Folder | test.txt | c:\temp\Folder\test.txt
c:\temp | Folder | test.txt | c:\temp\Folder\test.txt
c:\temp | \Folder | test.txt | \Folder\test.txt
c:\temp | Folder\ | test.txt | c:\temp\Folder\test.txt
c:\ | temp | \Folder\test.txt | \Folder\test.txt
c:\ | temp | Folder\test.txt | c:\temp\Folder\test.txt
temp | Folder | test.txt | temp\Folder\test.txt
.\temp | Folder | test.txt | temp\Folder\test.txt
..\temp | Folder | test.txt | temp\Folder\test.txt
c:\temp | .\Folder | test.txt | c:\temp\.\Folder\test.txt
c:\temp | ..\Folder | test.txt | c:\temp\..\Folder\test.txt
..\temp |  | test.txt | ..\temp\test.txt

Output in XSLT may differ slightly

Example

A range of functions are provided for working with Uri's and Path's. The following example demonstrates how these can be used.

In the following example we have a directory c:\UriExamples\ that contains the files Bookstore.xsd, Input001.xml, Input002.xml & ResolvedUri.Output.xml.

In our transform we have configured "ListFiles" to operate on the directory "c:\UriExamples\" and use the pattern "Input*.xml"

As you can see the ListFiles component gets the full paths of all the files that match the pattern. These filenames are then fed into the various Uri functions and output into an XML writer.

The result of the transform is as follows

Transform Output Copy Code
<FileProperties>
  <File>
    <FullFilename>C:\UriExamples\Input001.xml</FullFilename>
    <Filename>Input001.xml</Filename>
    <Extension>.xml</Extension>
    <Path>C:\UriExamples</Path>
    <AltFullFilename>C:\UriExamples\Backup\Input001.xml</AltFullFilename>
    <BackupFilename>C:\UriExamples\Input001.xml.bak</BackupFilename>
  </File>
  <File>
    <FullFilename>C:\UriExamples\Input002.xml</FullFilename>
    <Filename>Input002.xml</Filename>
    <Extension>.xml</Extension>
    <Path>C:\UriExamples</Path>
    <AltFullFilename>C:\UriExamples\Backup\Input002.xml</AltFullFilename>
    <BackupFilename>C:\UriExamples\Input002.xml.bak</BackupFilename>
  </File>
</FileProperties>

Lets examine the output in more detail

  • FullFilename value is what's returned from the ListFiles component, note its the full path to the file.
  • Filename has come via the GetFilename function, which has stripped off the path leaving just the filename.
  • Extension has come via the GetExtension function, which has left us with just the extension (note the leading . is preserved).
  • Path has come via the GetDirectoryName, this strips the filename leaving just the path (note its the whole path, not just he parent directory name).
  • AltFullFilename demonstrates how alternative paths can be constructed, in this case we take the files path, add the directory name 'Backup' and re-add the filename.
  • BackupFilename shows how the ResolveUri method can be used to build filenames based on an existing filename/path. We use the Concat function to append .bak onto the existing filename (giving us Input001.xml.bak), we then resolve this relative to the original file c:\UriExamples\Input001.xml.

Compatibility

Native Execution Engine, XSLT 2.0, C#

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

GetDirectoryName
GetExtension
GetFileName
List Files
ResolvePath
ReadFile
WriteFile

Data Mapping
Variable Function Inputs


GetDirectoryName
Data Mapping > Data Mapper Functions > By Category > File > GetDirectoryName

Glossary Item Box

Function Name
 GetDirectoryName
Category
 File
Icon
Description
 Return the index of the current item within its containing sequence
Inputs
Path The path of a file or directory.
Outputs
Directory Directory information for path.
Properties
None -

Sample output

Sample Path | Output extension
c:\temp\test.txt | c:\temp
c:\test.txt | c:\
.\temp\test.txt | \temp
test.txt |
c:\temp\test | c:\temp
c:\temp\ | c:\temp
"!InvalidPath' | [ERROR]

Example

A range of functions are provided for working with Uri's and Path's. The following example demonstrates how these can be used.

In the following example we have a directory c:\UriExamples\ that contains the files Bookstore.xsd, Input001.xml, Input002.xml & ResolvedUri.Output.xml.

In our transform we have configured "ListFiles" to operate on the directory "c:\UriExamples\" and use the pattern "Input*.xml"

As you can see the ListFiles component gets the full paths of all the files that match the pattern. These filenames are then fed into the various Uri functions and output into an XML writer.

The result of the transform is as follows

Transform Output Copy Code
<FileProperties>
  <File>
    <FullFilename>C:\UriExamples\Input001.xml</FullFilename>
    <Filename>Input001.xml</Filename>
    <Extension>.xml</Extension>
    <Path>C:\UriExamples</Path>
    <AltFullFilename>C:\UriExamples\Backup\Input001.xml</AltFullFilename>
    <BackupFilename>C:\UriExamples\Input001.xml.bak</BackupFilename>
  </File>
  <File>
    <FullFilename>C:\UriExamples\Input002.xml</FullFilename>
    <Filename>Input002.xml</Filename>
    <Extension>.xml</Extension>
    <Path>C:\UriExamples</Path>
    <AltFullFilename>C:\UriExamples\Backup\Input002.xml</AltFullFilename>
    <BackupFilename>C:\UriExamples\Input002.xml.bak</BackupFilename>
  </File>
</FileProperties>

Lets examine the output in more detail

  • FullFilename value is what's returned from the ListFiles component, note its the full path to the file.
  • Filename has come via the GetFilename function, which has stripped off the path leaving just the filename.
  • Extension has come via the GetExtension function, which has left us with just the extension (note the leading . is preserved).
  • Path has come via the GetDirectoryName, this strips the filename leaving just the path (note its the whole path, not just he parent directory name).
  • AltFullFilename demonstrates how alternative paths can be constructed, in this case we take the files path, add the directory name 'Backup' and re-add the filename.
  • BackupFilename shows how the ResolveUri method can be used to build filenames based on an existing filename/path. We use the Concat function to append .bak onto the existing filename (giving us Input001.xml.bak), we then resolve this relative to the original file c:\UriExamples\Input001.xml.

Compatibility

Native Execution Engine, XSLT 2.0, C#

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

CombinePath
GetExtension
GetFileName
List Files
ResolvePath
ReadFile
WriteFile


GetExtension
Data Mapping > Data Mapper Functions > By Category > File > GetExtension

Glossary Item Box

Function Name
 GetExtension
Category
 File
Icon
Description
 Returns the extension of the specified path string.
Inputs
Filename The path string from which to get the extension.
Outputs
Extension The extension of the specified path (including the period "."), or null, or String.Empty. If path is null, GetExtension returns null. If path does not have extension information, GetExtension returns Empty string.
Properties
None -

Sample output

Sample Path | Output extension
c:\temp\test.txt | .txt
c:\test.txt | .txt
.\temp\test.txt | .txt
test.txt | .txt
c:\temp\test |
c:\temp\ |
"!InvalidPath' | [ERROR]

Example

A range of functions are provided for working with Uri's and Path's. The following example demonstrates how these can be used.

In the following example we have a directory c:\UriExamples\ that contains the files Bookstore.xsd, Input001.xml, Input002.xml & ResolvedUri.Output.xml.

In our transform we have configured "ListFiles" to operate on the directory "c:\UriExamples\" and use the pattern "Input*.xml"

As you can see the ListFiles component gets the full paths of all the files that match the pattern. These filenames are then fed into the various Uri functions and output into an XML writer.

The result of the transform is as follows

Transform Output Copy Code
<FileProperties>
  <File>
    <FullFilename>C:\UriExamples\Input001.xml</FullFilename>
    <Filename>Input001.xml</Filename>
    <Extension>.xml</Extension>
    <Path>C:\UriExamples</Path>
    <AltFullFilename>C:\UriExamples\Backup\Input001.xml</AltFullFilename>
    <BackupFilename>C:\UriExamples\Input001.xml.bak</BackupFilename>
  </File>
  <File>
    <FullFilename>C:\UriExamples\Input002.xml</FullFilename>
    <Filename>Input002.xml</Filename>
    <Extension>.xml</Extension>
    <Path>C:\UriExamples</Path>
    <AltFullFilename>C:\UriExamples\Backup\Input002.xml</AltFullFilename>
    <BackupFilename>C:\UriExamples\Input002.xml.bak</BackupFilename>
  </File>
</FileProperties>

Lets examine the output in more detail

  • FullFilename value is what's returned from the ListFiles component, note its the full path to the file.
  • Filename has come via the GetFilename function, which has stripped off the path leaving just the filename.
  • Extension has come via the GetExtension function, which has left us with just the extension (note the leading . is preserved).
  • Path has come via the GetDirectoryName, this strips the filename leaving just the path (note its the whole path, not just he parent directory name).
  • AltFullFilename demonstrates how alternative paths can be constructed, in this case we take the files path, add the directory name 'Backup' and re-add the filename.
  • BackupFilename shows how the ResolveUri method can be used to build filenames based on an existing filename/path. We use the Concat function to append .bak onto the existing filename (giving us Input001.xml.bak), we then resolve this relative to the original file c:\UriExamples\Input001.xml.

Compatibility

Native Execution Engine, XSLT 2.0, C#

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

CombinePath
GetDirectoryName
GetFileName
List Files
ResolvePath
ReadFile
WriteFile


GetFileName
Data Mapping > Data Mapper Functions > By Category > File > GetFileName

Glossary Item Box

Function Name
 GetDirectoryName
Category
 File
Icon
Description
 Return the index of the current item within its containing sequence
Inputs
Path The path of a file or directory.
Outputs
Filename Directory information for path.
Properties
None -

Sample output

Sample Path | Output extension
c:\temp\test.txt | test.txt
c:\test.txt | test.txt
.\temp\test.txt | test.txt
test.txt | test.txt
c:\temp\test | test
c:\temp\ |
"!InvalidPath' | [ERROR]

Example

A range of functions are provided for working with Uri's and Path's. The following example demonstrates how these can be used.

In the following example we have a directory c:\UriExamples\ that contains the files Bookstore.xsd, Input001.xml, Input002.xml & ResolvedUri.Output.xml.

In our transform we have configured "ListFiles" to operate on the directory "c:\UriExamples\" and use the pattern "Input*.xml"

As you can see the ListFiles component gets the full paths of all the files that match the pattern. These filenames are then fed into the various Uri functions and output into an XML writer.

The result of the transform is as follows

Transform Output Copy Code
<FileProperties>
  <File>
    <FullFilename>C:\UriExamples\Input001.xml</FullFilename>
    <Filename>Input001.xml</Filename>
    <Extension>.xml</Extension>
    <Path>C:\UriExamples</Path>
    <AltFullFilename>C:\UriExamples\Backup\Input001.xml</AltFullFilename>
    <BackupFilename>C:\UriExamples\Input001.xml.bak</BackupFilename>
  </File>
  <File>
    <FullFilename>C:\UriExamples\Input002.xml</FullFilename>
    <Filename>Input002.xml</Filename>
    <Extension>.xml</Extension>
    <Path>C:\UriExamples</Path>
    <AltFullFilename>C:\UriExamples\Backup\Input002.xml</AltFullFilename>
    <BackupFilename>C:\UriExamples\Input002.xml.bak</BackupFilename>
  </File>
</FileProperties>

Lets examine the output in more detail

  • FullFilename value is what's returned from the ListFiles component, note its the full path to the file.
  • Filename has come via the GetFilename function, which has stripped off the path leaving just the filename.
  • Extension has come via the GetExtension function, which has left us with just the extension (note the leading . is preserved).
  • Path has come via the GetDirectoryName, this strips the filename leaving just the path (note its the whole path, not just he parent directory name).
  • AltFullFilename demonstrates how alternative paths can be constructed, in this case we take the files path, add the directory name 'Backup' and re-add the filename.
  • BackupFilename shows how the ResolveUri method can be used to build filenames based on an existing filename/path. We use the Concat function to append .bak onto the existing filename (giving us Input001.xml.bak), we then resolve this relative to the original file c:\UriExamples\Input001.xml.

Compatibility

Native Execution Engine, XSLT 2.0, C#

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

CombinePath
GetDirectoryName
GetExtension
List Files
ResolvePath
ReadFile
WriteFile


List Files
Data Mapping > Data Mapper Functions > By Category > File > List Files

Glossary Item Box

Function Name
 List Files
Category
 File
Icon
Description
 Gets a all the files in a directory that match a given pattern
Inputs
Path

The directory that function will enumerate all the files within (optional)
If its not connected the the value is read from the internal property "File Path".
Outputs
Filename A list of all the files in the "File Path" that match the "pattern".
This is the full path to the file
Properties

File Path | If the input connection point "FilePath" is not connected then this directory is the one enumerated.
Pattern | A standard DOS style pattern to filter files i.e. *.xml
Recursive | true/false if this is true then all the child directories are also searched.

Usage

The Data Mapper ListFiles function converts reads all the files matching the provided pattern. This is useful for reading multiple input files :

In the following example the filenames taken from the ListFiles component are fed into the XML Readers Filename input. So every filename that ListFiles returns is opened as an XML document:

If we have the following input files in the target folder

Input001.xml Copy Code
<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<bookstore xmlns="https://www.liquid-technologies.com/sample/bookstore">
 <book price="4.99" publicationdate="2008-10-20" ISBN="978-0747596837">
  <title>The Graveyard Book</title>
  <author>
   <first-name>Neil</first-name>
   <last-name>Gaiman</last-name>
  </author>
  <genre>Horror</genre>
 </book>
 <book price="21.99" publicationdate="2002-05-14" ISBN="0-596-00252-1">
  <title>XML Schemas</title>
  <author>
   <first-name>Eric</first-name>
   <last-name>van der Vlist</last-name>
  </author>
  <genre>Reference</genre>
 </book>
</bookstore>
Input002.xml Copy Code
<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<bookstore xmlns="https://www.liquid-technologies.com/sample/bookstore">
 <book price="5.99" publicationdate="1999-05-02" ISBN="0-945-16546-1">
  <title>The Portable Door</title>
  <author>
   <first-name>Tom</first-name>
   <last-name>Holt</last-name>
  </author>
  <genre>Fiction</genre>
 </book>
</bookstore>

The if the ListFiles function is configured with a pattern say "input*.xml" then the 2 files will be read into the XML Reader and passed onto the writer resulting in;

Output XML Copy Code
<bookstore xmlns="https://www.liquid-technologies.com/sample/bookstore">
  <book>
    <title>The Graveyard Book</title>
  </book>
  <book>
    <title>XML Schemas</title>
  </book>
  <book>
    <title>The Portable Door</title>
  </book>
</bookstore>
Properties

The ListFiles properties values can be edited using the Properties Window.

Example

A range of functions are provided for working with Uri's and Path's. The following example demonstrates how these can be used.

In the following example we have a directory c:\UriExamples\ that contains the files Bookstore.xsd, Input001.xml, Input002.xml & ResolvedUri.Output.xml.

In our transform we have configured "ListFiles" to operate on the directory "c:\UriExamples\" and use the pattern "Input*.xml"

As you can see the ListFiles component gets the full paths of all the files that match the pattern. These filenames are then fed into the various Uri functions and output into an XML writer.

The result of the transform is as follows

Transform Output Copy Code
<FileProperties>
  <File>
    <FullFilename>C:\UriExamples\Input001.xml</FullFilename>
    <Filename>Input001.xml</Filename>
    <Extension>.xml</Extension>
    <Path>C:\UriExamples</Path>
    <AltFullFilename>C:\UriExamples\Backup\Input001.xml</AltFullFilename>
    <BackupFilename>C:\UriExamples\Input001.xml.bak</BackupFilename>
  </File>
  <File>
    <FullFilename>C:\UriExamples\Input002.xml</FullFilename>
    <Filename>Input002.xml</Filename>
    <Extension>.xml</Extension>
    <Path>C:\UriExamples</Path>
    <AltFullFilename>C:\UriExamples\Backup\Input002.xml</AltFullFilename>
    <BackupFilename>C:\UriExamples\Input002.xml.bak</BackupFilename>
  </File>
</FileProperties>

Lets examine the output in more detail

  • FullFilename value is what's returned from the ListFiles component, note its the full path to the file.
  • Filename has come via the GetFilename function, which has stripped off the path leaving just the filename.
  • Extension has come via the GetExtension function, which has left us with just the extension (note the leading . is preserved).
  • Path has come via the GetDirectoryName, this strips the filename leaving just the path (note its the whole path, not just he parent directory name).
  • AltFullFilename demonstrates how alternative paths can be constructed, in this case we take the files path, add the directory name 'Backup' and re-add the filename.
  • BackupFilename shows how the ResolveUri method can be used to build filenames based on an existing filename/path. We use the Concat function to append .bak onto the existing filename (giving us Input001.xml.bak), we then resolve this relative to the original file c:\UriExamples\Input001.xml.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

CombinePath
GetDirectoryName
GetExtension
GetFileName
ResolvePath
ReadFile
WriteFile


ReadFile
Data Mapping > Data Mapper Functions > By Category > File > ReadFile

Glossary Item Box

Function Name
 ReadFile
Category
 File
Icon
Description
 Reads the contents of a text file and returns it as a string
Inputs
Filename The name of the text file to read
Outputs
String The contents of the file as a string
Properties
Encoding The text encoding to apply to the file

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

CombinePath
GetDirectoryName
GetExtension
GetFileName
List Files
ResolvePath
WriteFile


ResolvePath
Data Mapping > Data Mapper Functions > By Category > File > ResolvePath

Glossary Item Box

Function Name
 ResolvePath
Category
 File
Icon
Description
 Resolves the absolute Path from the base path and relative filename
Inputs

BasePath | The base Path used to resolve the relative path.
RelativePath | The Path to resolve. The Path can be absolute or relative. If absolute, this value effectively replaces the basePath value. If relative, it combines with the basePath to make an absolute aPath.
Outputs
Filename The absolute URI.
Properties

Usage

The Data Mapper ResolvePath function resolves a filename or path relative to the base path provided:

In the following example the filenames taken from the ListFiles component are fed into the XML Readers Filename input. So every filename that ListFiles returns is opened as an XML document:

If we have the following input files in the target folder

Input001.xml Copy Code
<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<bookstore xmlns="https://www.liquid-technologies.com/sample/bookstore">
 <book price="4.99" publicationdate="2008-10-20" ISBN="978-0747596837">
  <title>The Graveyard Book</title>
  <author>
   <first-name>Neil</first-name>
   <last-name>Gaiman</last-name>
  </author>
  <genre>Horror</genre>
 </book>
 <book price="21.99" publicationdate="2002-05-14" ISBN="0-596-00252-1">
  <title>XML Schemas</title>
  <author>
   <first-name>Eric</first-name>
   <last-name>van der Vlist</last-name>
  </author>
  <genre>Reference</genre>
 </book>
</bookstore>
Input002.xml Copy Code
<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<bookstore xmlns="https://www.liquid-technologies.com/sample/bookstore">
 <book price="5.99" publicationdate="1999-05-02" ISBN="0-945-16546-1">
  <title>The Portable Door</title>
  <author>
   <first-name>Tom</first-name>
   <last-name>Holt</last-name>
  </author>
  <genre>Fiction</genre>
 </book>
</bookstore>

The if the ListFiles function is configured with a pattern say "input*.xml" then the 2 files will be read into the XML Reader and passed onto the writer resulting in;

Output XML Copy Code
<bookstore xmlns="https://www.liquid-technologies.com/sample/bookstore">
  <book>
    <title>The Graveyard Book</title>
  </book>
  <book>
    <title>XML Schemas</title>
  </book>
  <book>
    <title>The Portable Door</title>
  </book>
</bookstore>
Properties

The ListFiles properties values can be edited using the Properties Window.

When used in an XSLT transform the output will be in Uri format

Example

A range of functions are provided for working with Uri's and Path's. The following example demonstrates how these can be used.

In the following example we have a directory c:\UriExamples\ that contains the files Bookstore.xsd, Input001.xml, Input002.xml & ResolvedUri.Output.xml.

In our transform we have configured "ListFiles" to operate on the directory "c:\UriExamples\" and use the pattern "Input*.xml"

As you can see the ListFiles component gets the full paths of all the files that match the pattern. These filenames are then fed into the various Uri functions and output into an XML writer.

The result of the transform is as follows

Transform Output Copy Code
<FileProperties>
  <File>
    <FullFilename>C:\UriExamples\Input001.xml</FullFilename>
    <Filename>Input001.xml</Filename>
    <Extension>.xml</Extension>
    <Path>C:\UriExamples</Path>
    <AltFullFilename>C:\UriExamples\Backup\Input001.xml</AltFullFilename>
    <BackupFilename>C:\UriExamples\Input001.xml.bak</BackupFilename>
  </File>
  <File>
    <FullFilename>C:\UriExamples\Input002.xml</FullFilename>
    <Filename>Input002.xml</Filename>
    <Extension>.xml</Extension>
    <Path>C:\UriExamples</Path>
    <AltFullFilename>C:\UriExamples\Backup\Input002.xml</AltFullFilename>
    <BackupFilename>C:\UriExamples\Input002.xml.bak</BackupFilename>
  </File>
</FileProperties>

Lets examine the output in more detail

  • FullFilename value is what's returned from the ListFiles component, note its the full path to the file.
  • Filename has come via the GetFilename function, which has stripped off the path leaving just the filename.
  • Extension has come via the GetExtension function, which has left us with just the extension (note the leading . is preserved).
  • Path has come via the GetDirectoryName, this strips the filename leaving just the path (note its the whole path, not just he parent directory name).
  • AltFullFilename demonstrates how alternative paths can be constructed, in this case we take the files path, add the directory name 'Backup' and re-add the filename.
  • BackupFilename shows how the ResolveUri method can be used to build filenames based on an existing filename/path. We use the Concat function to append .bak onto the existing filename (giving us Input001.xml.bak), we then resolve this relative to the original file c:\UriExamples\Input001.xml.

Compatibility

Native Execution Engine, XSLT 2.0, C#

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

CombinePath
GetDirectoryName
GetExtension
GetFileName
List Files
ReadFile
WriteFile


WriteFile
Data Mapping > Data Mapper Functions > By Category > File > WriteFile

Glossary Item Box

Function Name
 WriteFile
Category
 File
Icon
Description
 Writes a text to a file
Inputs
Filename The name of the file to write data to
Outputs
Data The text to write to the file
Properties

Append | When true the data in the file is appended to, when false the contents of the file is replaced by the string in Data.
Encoding | The encoding used to write the text into the file
EOL Type | The end of line char to use when writing to the file (CR/LF/CRLF)
Execution Order | If the transform contains multiple Output Components then this determines the order in which they are executed

See Also

CombinePath
GetDirectoryName
GetExtension
GetFileName
List Files
ResolvePath
ReadFile


And
Data Mapping > Data Mapper Functions > By Category > Logic > And

Glossary Item Box

Function Name
 And
Category
 Logic
Icon
 And
Description
 Return the logical "and" of multiple input values
Inputs

Input 1 | First input value to test as a boolean
Input 2 | Second input value to test as a boolean
Outputs
Result Boolean indicator - true only if all inputs evaluate to true
Properties
None -

Usage

The Data Mapper Logic And function allows you to carry out conditional "and" tests on your input data and on information processed from it. By default the function tests two inputs, but you can add additional inputs as you require. The And function allows you to implement conditional control on the set of data items you map and the details of how you map it. The And function will output a value of true if all input values are true. If any of the And inputs are false, the function will output a false result. As soon as the Mapper encounters a false input, it stops testing and outputs false.

Since the And function outputs a boolean value, you are perhaps likely to use it in conjunction with other functions in the Set, Logic and Comparator categories. To apply the Logic And function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using staff_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<staff>
 <employee>
  <first_name>Mark</first_name>
  <second_name>Brown</second_name>
  <started>2001</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Jane</first_name>
  <second_name>Jackson</second_name>
  <started>1998</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Joe</first_name>
  <second_name>Simpson</second_name>
  <started>2008</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Lynn</first_name>
  <second_name>Nicolson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
</staff>

For our target schema we will be using staff_target.xsd, inferred from the following XML:

Target XML Copy Code
<company>
 <staff_member since="2000" contract="false">
  <f_name>Ken</f_name>
  <s_name>Jones</s_name>
 </staff_member>
 <staff_member since="2003" contract="true">
  <f_name>Linda</f_name>
  <s_name>Lee</s_name>
 </staff_member>
 <staff_member since="1998" contract="false">
  <f_name>Paul</f_name>
  <s_name>Mitchell</s_name>
 </staff_member>
</company>

The data models employees within an organisation. Let's assume that, rather than mapping all data values, we only want to map "employee" elements representing staff members who have permanent contracts and who began working at the company in 2000 or later. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Logic And function from the Component Palette into the mapping area:

The And function takes two inputs by default, but you can add extra inputs by right-clicking any of the existing inputs as the component appears in the Mapper, choosing Add Above or Add Below. If any of your inputs are not connected, the Mapper will simply ignore them. The inputs all represent boolean values, or values that the Mapper can cast to booleans. The function output will only be true if all inputs are evaluated as true. The function output will be false if any of the inputs are false. Both inputs and output of the And function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Since we want to map only "employee" elements for permanent staff, connect the "permanent" output in the XML Reader to one of the And inputs.

Reader to And

We also only want records to be mapped for employees who started in 2000 or later, so drag a Greater Than or Equal component from the Comparator section onto the Mapper. Connect its Value 1 input to the "started" output in the XML Reader, since this is the value we want to be at least 2000.

Reader to Greater Than or Equal

Now we need to define the value to compare the input start date to. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Enter an integer as the Data Type and the number 2000 as the value.

Connect the Constant output to the Value 2 input in the Greater Than or Equal function.

Constant to Greater Than or Equal

Now each time the Mapper encounters the "started" element for this part of the conditional test, it will check whether the number is at least 2000. If a date is greater than or equal to 2000, the function will output a value of true, otherwise it will output a value of false. Connect the Greater Than or Equal function output to the second input of the And function.

Greater Than or Equal to And

Now the And output will only be true if the "started" element is at least 2000 and the "permanent" value is true. Let's now use this information to filter our data. Drag a Filter function from the Set section onto the Mapper. Connect its Bool input to the output of the And function and its Nodes input to the "employee" output in the XML Reader.

Now connect the output of the Filter function to the "staff_member" input in the XML Writer. This will ensure that an "employee" element is only mapped if its "started" element is at least 2000 and its "permanent" value is true. No other "employee" elements will be mapped.

Filter to Writer

Finally let's make the remaining input and output connections. Remember to map "started" to "since" and "permanent" to "contract" - although we have used these values from the source we have not yet instructed the Mapper to map them.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<company>
 <staff_member since="2001" contract="true">
  <f_name>Mark</f_name>
  <s_name>Brown</s_name>
 </staff_member>
 <staff_member since="2008" contract="true">
  <f_name>Joe</f_name>
  <s_name>Simpson</s_name>
 </staff_member>
</company>

The output only contains those "staff_member" elements with start dates from 2000 onwards and permanent contracts.

If you are adding extra inputs to the And function by right-clicking an existing input and selecting Add Above or Add Below, you can control the order in which the Mapper carries out the conditional tests. When the Mapper encounters a false input, it does not check any remaining inputs as the output value must be false. In each case, the Mapper will only reach the final test defined if all preceding inputs have returned true.
If the And function receives an input value that is not a boolean, it will attempt to cast it.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Or
Not

Set
Filter

Values
Constant

Comparator
GreaterThanOrEqual

Data Mapping
Variable Function Inputs


False
Data Mapping > Data Mapper Functions > By Category > Logic > False

Glossary Item Box

Function Name
 False
Category
 Logic
Icon
 False
Description
 A boolean false value
Inputs
None -
Outputs
Result A constant boolean value of false
Properties
None -

Usage

The Data Mapper Logic False component allows you to feed a literal boolean value directly into your Mapping functions and output. Since the False function outputs a boolean, you may also use it in conjunction with other functions in the Set, Logic and Comparator categories. To apply the Logic False function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using staff_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<staff>
 <employee>
  <first_name>Mark</first_name>
  <second_name>Brown</second_name>
  <started>2001</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Jane</first_name>
  <second_name>Jackson</second_name>
  <started>1998</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Joe</first_name>
  <second_name>Simpson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
 <employee>
  <first_name>Lynn</first_name>
  <second_name>Nicolson</second_name>
  <started>1999</started>
  <permanent>false</permanent>
 </employee>
</staff>

For our target schema we will be using staff_alt_target.xsd, inferred from the following XML:

Target XML Copy Code
<company>
 <staff_member since="2000" contract="false" certified="true">
  <f_name>Ken</f_name>
  <s_name>Jones</s_name>
 </staff_member>
 <staff_member since="2003" contract="true" certified="false">
  <f_name>Linda</f_name>
  <s_name>Lee</s_name>
 </staff_member>
 <staff_member since="1998" contract="false" certified="true">
  <f_name>Paul</f_name>
  <s_name>Mitchell</s_name>
 </staff_member>
</company>

The data models employees within an organisation. Notice that the target data model contains a value that is not in the source: the "certified" attribute of the "staff_member" element, representing some sort of work-related certification status. Let's assume that we are mapping data records for employees we know are not certified, perhaps due to which department they are in or where the data has been retrieved from. This means that we know all records should be output with a value of false for the attribute, and can use the False component to define this. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Logic False function from the Component Palette into the mapping area:

The False component has no inputs, and a single output which is always a boolean false value. The output of the False function may be connected to items in the XML Writer or other components in the Mapper.

Connect the output of the False function to the "certified" input in the XML Writer.

Now each boolean value in the "certified" element will be false for the data being mapped. Finally let's make the remaining input and output connections.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<company>
 <staff_member since="2001" contract="true" certified="false">
  <f_name>Mark</f_name>
  <s_name>Brown</s_name>
 </staff_member>
 <staff_member since="1998" contract="true" certified="false">
  <f_name>Jane</f_name>
  <s_name>Jackson</s_name>
 </staff_member>
 <staff_member since="2008" contract="false" certified="false">
  <f_name>Joe</f_name>
  <s_name>Simpson</s_name>
 </staff_member>
 <staff_member since="1999" contract="false" certified="false">
  <f_name>Lynn</f_name>
  <s_name>Nicolson</s_name>
 </staff_member>
</company>

The output contains the input data plus a false value for each staff member "certified" attribute.

See Also

True

Values
Constant


Not
Data Mapping > Data Mapper Functions > By Category > Logic > Not

Glossary Item Box

Function Name
 Not
Category
 Logic
Icon
 Not
Description
 Negate an input value, returning its logical "not"
Inputs
Input Input boolean value to negate
Outputs
Result Logical "not" value of input
Properties
None -

Usage

The Data Mapper Logic Not function allows you to negate boolean values from your input data. If the Not function receives an input value of true it will output false. If it receives a false input value it will output true. The Not function can be useful in cases where the data model differs logically within the target application. Since the Not function outputs a boolean value, you may also use it in conjunction with other functions in the Set, Logic and Comparator categories. To apply the Logic Not function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using staff_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<staff>
 <employee>
  <first_name>Mark</first_name>
  <second_name>Brown</second_name>
  <started>2001</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Jane</first_name>
  <second_name>Jackson</second_name>
  <started>1998</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Joe</first_name>
  <second_name>Simpson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
 <employee>
  <first_name>Lynn</first_name>
  <second_name>Nicolson</second_name>
  <started>1999</started>
  <permanent>false</permanent>
 </employee>
</staff>

For our target schema we will be using staff_target.xsd, inferred from the following XML:

Target XML Copy Code
<company>
 <staff_member since="2000" contract="false">
  <f_name>Ken</f_name>
  <s_name>Jones</s_name>
 </staff_member>
 <staff_member since="2003" contract="true">
  <f_name>Linda</f_name>
  <s_name>Lee</s_name>
 </staff_member>
 <staff_member since="1998" contract="false">
  <f_name>Paul</f_name>
  <s_name>Mitchell</s_name>
 </staff_member>
</company>

The data models employees within an organisation. Let's assume that, in the source data, "permanent" refers to whether or not an employee has a permanent contract, but in the target, "contract" refers to whether employees have temporary contracts. In effect, we are mapping values which equate to the opposite in source and target. For this reason we want to negate the incoming "permanent" value and write it to the "contract" output. I.E. if someone does not have a permanent contract, they have a temporary one, so they have a false "permanent" value in the source, but a true "contract" value in the target. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Logic Not function from the Component Palette into the mapping area:

The Not function takes a single input, the boolean value to negate. The output contains the "not" of the input value. Both input and output of the Not function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Connect the input of the Not function to the "permanent" output in the XML Reader, and the Not output to the "contract" input in the XML Writer.

Now each boolean value in the "permanent" inputs will be output as "contract" attributes containing the opposite value. Finally let's make the remaining input and output connections.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<company>
 <staff_member since="2001" contract="false">
  <f_name>Mark</f_name>
  <s_name>Brown</s_name>
 </staff_member>
 <staff_member since="1998" contract="false">
  <f_name>Jane</f_name>
  <s_name>Jackson</s_name>
 </staff_member>
 <staff_member since="2008" contract="true">
  <f_name>Joe</f_name>
  <s_name>Simpson</s_name>
 </staff_member>
 <staff_member since="1999" contract="true">
  <f_name>Lynn</f_name>
  <s_name>Nicolson</s_name>
 </staff_member>
</company>

The output contains the negated version of each boolean value in the input.

You can combine the Not function with other Comparator and Logic functions to create complex chains of conditional tests.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

And
Or


Or
Data Mapping > Data Mapper Functions > By Category > Logic > Or

Glossary Item Box

Function Name
 Or
Category
 Logic
Icon
 Or
Description
 Return the logical "or" of multiple input values
Inputs

Input 1 | First input value to test as a boolean
Value 2 | Second input value to test as a boolean
Outputs
Result Boolean indicator - true if any of the inputs evaluate to true
Properties
None -

Usage

The Data Mapper Logic Or function allows you to carry out conditional "or" tests on your input data and on information processed from it. By default the function tests two inputs, but you can add additional inputs as you require. The Or function allows you to implement conditional control on the set of data items you map and the details of how you map it. The Or function will output a value of true if any of the input values are true. Only one input value has to be true for the Or function to output a true value - it will only output a false value if all input values are false. As soon as the Mapper encounters a true input, it stops testing and outputs true. Since the Or function outputs a boolean value, you are likely to use it in conjunction with other functions in the Set, Logic and Comparator categories. To apply the Logic Or function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using staff_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<staff>
 <employee>
  <first_name>Mark</first_name>
  <second_name>Brown</second_name>
  <started>2001</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Jane</first_name>
  <second_name>Jackson</second_name>
  <started>1998</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Joe</first_name>
  <second_name>Simpson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
 <employee>
  <first_name>Lynn</first_name>
  <second_name>Nicolson</second_name>
  <started>1999</started>
  <permanent>false</permanent>
 </employee>
</staff>

For our target schema we will be using staff_target.xsd, inferred from the following XML:

Target XML Copy Code
<company>
 <staff_member since="2000" contract="false">
  <f_name>Ken</f_name>
  <s_name>Jones</s_name>
 </staff_member>
 <staff_member since="2003" contract="true">
  <f_name>Linda</f_name>
  <s_name>Lee</s_name>
 </staff_member>
 <staff_member since="1998" contract="false">
  <f_name>Paul</f_name>
  <s_name>Mitchell</s_name>
 </staff_member>
</company>

The data models employees within an organisation. Let's assume that, rather than mapping all data values, we only want to map "employee" elements representing staff members who either have permanent contracts or who began working at the company before 2000. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Logic Or function from the Component Palette into the mapping area:

The Or function takes two inputs by default, but you can add extra inputs by right-clicking any of the existing inputs as the component appears in the Mapper, choosing Add Above or Add Below. If any of your inputs are not connected, the Mapper will simply ignore them. The inputs all represent boolean values, or values that the Mapper can cast to booleans. The function output will be true if any inputs are evaluated as true. The function output will be false only if all of the inputs are false. Both inputs and output of the Or function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Since we want to map "employee" elements if they represent permanent staff, connect the "permanent" output in the XML Reader to one of the Or inputs.

Reader to Or

We also want to map records for employees who started before 2000, so drag a Less Than component from the Comparator section onto the Mapper. Connect its Value 1 input to the "started" output in the XML Reader, since this is the value we want to be less than 2000 for this particular part of the conditional test.

Reader to Less Than

Now we need to define the value to compare the input start date to. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Enter an integer as the Data Type and the number 2000 as the Value.

Connect the Constant output to the Value 2 input in the Less Than function.

Constant to Less Than

Now each time the Mapper encounters the "started" element when it carries out this part of the test, it will check whether the number is less than 2000. If a start date is before 2000, the function will output a value of true, otherwise it will output a value of false. Connect the Less Than function output to the second input of the Or function.

Less Than to Or

Now the Or output will be true either if the "started" element is less than 2000 or the "permanent" value is true. Let's now use this information to filter our data. Drag a Filter function from the Set section onto the Mapper. Connect its Bool input to the output of the Or function and its Nodes input to the "employee" output in the XML Reader.

Now connect the output of the Filter function to the "staff_member" input in the XML Writer. This will ensure that an "employee" element is mapped if its "started" element is less than 2000 or its "permanent" value is true. No other "employee" elements will be mapped.

Filter to Writer

Finally let's make the remaining input and output connections. Remember to map "started" to "since" and "permanent" to "contract" - although we have used these values from the source we have not yet instructed the Mapper to map them.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<company>
 <staff_member since="2001" contract="true">
  <f_name>Mark</f_name>
  <s_name>Brown</s_name>
 </staff_member>
 <staff_member since="1998" contract="true">
  <f_name>Jane</f_name>
  <s_name>Jackson</s_name>
 </staff_member>
 <staff_member since="1999" contract="false">
  <f_name>Lynn</f_name>
  <s_name>Nicolson</s_name>
 </staff_member>
</company>

The output only contains those "staff_member" elements with start dates before 2000 or permanent contracts (or both).

If you are adding extra inputs to the Or function by right-clicking an existing input and selecting Add Above or Add Below, you can control the order in which the Mapper carries out the conditional tests. When the Mapper encounters a true input, it does not check any remaining inputs as the output value must be true. In each case, the Mapper will only reach the final test defined if all preceding inputs have returned false.
If the Or function receives an input value that is not a boolean, it will attempt to cast it.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

And
Not

Set
Filter

Values
Constant

Comparator
LessThan

Data Mapping
Variable Function Inputs


True
Data Mapping > Data Mapper Functions > By Category > Logic > True

Glossary Item Box

Function Name
 True
Category
 Logic
Icon
 True
Description
 A boolean true value
Inputs
None -
Outputs
Result A constant boolean value of true
Properties
None -

Usage

The Data Mapper Logic True component allows you to feed a literal boolean value directly into your Mapping functions and output. Since the True function outputs a boolean, you may also use it in conjunction with other functions in the Set, Logic and Comparator categories. To apply the Logic True function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using staff_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<staff>
 <employee>
  <first_name>Mark</first_name>
  <second_name>Brown</second_name>
  <started>2001</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Jane</first_name>
  <second_name>Jackson</second_name>
  <started>1998</started>
  <permanent>true</permanent>
 </employee>
 <employee>
  <first_name>Joe</first_name>
  <second_name>Simpson</second_name>
  <started>2008</started>
  <permanent>false</permanent>
 </employee>
 <employee>
  <first_name>Lynn</first_name>
  <second_name>Nicolson</second_name>
  <started>1999</started>
  <permanent>false</permanent>
 </employee>
</staff>

For our target schema we will be using staff_alt_target.xsd, inferred from the following XML:

Target XML Copy Code
<company>
 <staff_member since="2000" contract="false" certified="true">
  <f_name>Ken</f_name>
  <s_name>Jones</s_name>
 </staff_member>
 <staff_member since="2003" contract="true" certified="false">
  <f_name>Linda</f_name>
  <s_name>Lee</s_name>
 </staff_member>
 <staff_member since="1998" contract="false" certified="true">
  <f_name>Paul</f_name>
  <s_name>Mitchell</s_name>
 </staff_member>
</company>

The data models employees within an organisation. Notice that the target data model contains a value that is not in the source: the "certified" attribute of the "staff_member" element, representing some sort of work-related certification status. Let's assume that we are mapping data records for employees we know are all certified, perhaps due to which department they are in or where the data has been retrieved from. This means that we know all records should be output with a value of true for the attribute, and can use the True component to define this. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Logic True function from the Component Palette into the mapping area:

The True component has no inputs, and a single output which is always a boolean true value. The output of the True function may be connected to items in the XML Writer or other components in the Mapper.

Connect the output of the True function to the "certified" input in the XML Writer.

Now each boolean value in the "certified" element will be true for the data being mapped. Finally let's make the remaining input and output connections.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<company>
 <staff_member since="2001" contract="true" certified="true">
  <f_name>Mark</f_name>
  <s_name>Brown</s_name>
 </staff_member>
 <staff_member since="1998" contract="true" certified="true">
  <f_name>Jane</f_name>
  <s_name>Jackson</s_name>
 </staff_member>
 <staff_member since="2008" contract="false" certified="true">
  <f_name>Joe</f_name>
  <s_name>Simpson</s_name>
 </staff_member>
 <staff_member since="1999" contract="false" certified="true">
  <f_name>Lynn</f_name>
  <s_name>Nicolson</s_name>
 </staff_member>
</company>

The output contains the input data plus a true value for each staff member "certified" attribute.

See Also

False

Values
Constant


Abs
Send Feedback
Data Mapping > Data Mapper Functions > By Category > Maths > Abs

Glossary Item Box

Function Name
 ABS
Category
 Maths
Icon
 ABS
Description
 Returns the absolute value of a specified number.
Inputs
Value The numeric value to get the absolute value for
Outputs
Result The absolute value
Remarks

Takes a numeric value and removes the sign from it.

If the value is not numeric then an error is raised (unless an in place cast is defined).

Examples

Source Data Copy Code
<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<Decimals xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="..\Common\Numbers.xsd">
    <Decimal>7194.954905803945093</Decimal>
    <Decimal>7570.634905803945093</Decimal>
    <Decimal>5754.914905803945093</Decimal>
    <Decimal>-7480.925094196054907</Decimal>
    <Decimal>-6851.065094196054907</Decimal>
</Decimals>

Output Data Copy Code
<Decimals>
    <Decimal>7194.954905803945093</Decimal>
    <Decimal>7570.634905803945093</Decimal>
    <Decimal>5754.914905803945093</Decimal>
    <Decimal>7480.925094196054907</Decimal>
    <Decimal>6851.065094196054907</Decimal>
</Decimals>

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.


Add
Data Mapping > Data Mapper Functions > By Category > Maths > Add

Glossary Item Box

Function Name
 Add
Category
 Maths
Icon
 Add
Description
 Add two numeric values
Inputs

Value 1 | First value to add
Value 2 | Second value to add
Outputs
Result Sum result of adding value 1 and value 2
Properties
None -

Usage

The Data Mapper Maths Add function allows you to carry out addition on input values. You can use the Add function with input source data or in conjunction with other arithmetic functions in the Maths section. To apply the Maths Add function, use the following process:

Create a new Data Mapper file, dragging your XML data source and target into the editor area. For this example we are using payroll_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<payroll>
 <employee payroll_id="126">
  <rate>9.45</rate>
  <hours>35</hours>
  <bonus>50.00</bonus>
  <funding>350</funding>
 </employee>
 <employee payroll_id="129">
  <rate>10.50</rate>
  <hours>40</hours>
  <bonus>150.00</bonus>
  <funding>500</funding>
 </employee>
 <employee payroll_id="130">
  <rate>8.90</rate>
  <hours>35</hours>
  <bonus>100.00</bonus>
  <funding>400</funding>
 </employee>
 <employee payroll_id="133">
  <rate>11.20</rate>
  <hours>40</hours>
  <bonus>200.00</bonus>
  <funding>600</funding>
 </employee>
</payroll>

For our target schema we will be using payroll_target.xsd, inferred from the following XML:

Target XML Copy Code
<wages>
 <payee>
  <ref>122</ref>
  <result type="cost">500.00</result>
 </payee>
 <payee>
  <ref>125</ref>
  <result type="cost">475.50</result>
 </payee>
 <payee>
  <ref>126</ref>
  <result type="cost">600.20</result>
 </payee>
</wages>

The data models payroll data for temporary staff within an organisation. The output is designed to capture some value calculated from the source, using the "type" attribute to indicate what the calculation result represents. Let's assume that we want to calculate the weekly cost of employing each staff member, including their bonus payment. To calculate this we will need to multiply the hourly rate by the number of hours worked, then add the bonus to the result. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Maths Add function from the Component Palette into the mapping area:

The Add component has two inputs, representing the values to add. Both inputs and output of the Add function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Connect the first Add input to the "bonus" output in the XML Reader.

Reader to Add

For the second Add input, we need to carry out another calculation. Drag a Multiply component onto the Mapper, connecting its inputs to the "rate" and "hours" outputs in the XML Reader.

Reader to Multiply

Connect the output of the Multiply function to the remaining Add input.

Multiply to Add

Now connect the Add output to the "Element Value" input in the XML Writer, so that the addition result is written into the "result" element.

Now we need to include the "type" attribute in the source, so add a Constant Value from the Data Type section. Right-click it and choose Show Properties. Choose a String Data Type and enter "cost" as the value.

Connect the Constant output to the "type" input in the XML Writer.

Finally let's make the remaining input and output connections. We do not want to map all data items in the source, as we are only interested in certain values. Map "payroll" to "wages", "employee" to "payee" and "payroll_id" to "ref". We don't need to map anything to the "result" input as the element will be written out each time the Mapper maps the addition result to "Element Value".

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<wages>
 <payee>
  <ref>126</ref>
  <result type="cost">380.75</result>
 </payee>
 <payee>
  <ref>129</ref>
  <result type="cost">570.00</result>
 </payee>
 <payee>
  <ref>130</ref>
  <result type="cost">411.50</result>
 </payee>
 <payee>
  <ref>133</ref>
  <result type="cost">648.00</result>
 </payee>
</wages>

The output contains an indicator of the weekly cost for each employee, comprising their bonus plus rate multiplied by hours worked.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Subtract
Multiply

Values
Constant

Data Mapping
Analyzing Numerical Input


Divide
Data Mapping > Data Mapper Functions > By Category > Maths > Divide

Glossary Item Box

Function Name
 Divide
Category
 Maths
Icon
 Divide
Description
 Divide one numeric value by another
Inputs

Dividend | Value to divide
Divisor | Value to divide by
Outputs
Result Result of dividing first input by second
Properties
None -

Usage

The Data Mapper Maths Divide function allows you to carry out division on input values. You can use the Divide function with input source data or in conjunction with other arithmetic functions in the Maths section. To apply the Maths Divide function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using payroll_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<payroll>
 <employee payroll_id="126">
  <rate>9.45</rate>
  <hours>35</hours>
  <bonus>70.00</bonus>
  <funding>350</funding>
 </employee>
 <employee payroll_id="129">
  <rate>10.50</rate>
  <hours>30</hours>
  <bonus>150.00</bonus>
  <funding>500</funding>
 </employee>
 <employee payroll_id="130">
  <rate>8.90</rate>
  <hours>40</hours>
  <bonus>100.00</bonus>
  <funding>550</funding>
 </employee>
 <employee payroll_id="133">
  <rate>11.20</rate>
  <hours>40</hours>
  <bonus>200.00</bonus>
  <funding>600</funding>
 </employee>
</payroll>

For our target schema we will be using payroll_target.xsd, inferred from the following XML:

Target XML Copy Code
<wages>
 <payee>
  <ref>122</ref>
  <result type="hourly">7.90</result>
 </payee>
 <payee>
  <ref>125</ref>
  <result type="hourly">8.45</result>
 </payee>
 <payee>
  <ref>126</ref>
  <result type="hourly">9.10</result>
 </payee>
</wages>

The data models payroll data for temporary staff within an organisation. The output is designed to capture some value calculated from the source, using the "type" attribute to indicate what the calculation result represents. Let's assume that we want to calculate the actual hourly rate for each employee, including their bonus. We will need to carry out an addition calculation in conjunction with the division. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Maths Divide function from the Component Palette into the mapping area:

The Divide component has two inputs, representing the value to divide and the value to divide it with. Both inputs and output of the Divide function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Connect the Dividend input in the Divide component to the "bonus" output in the XML Reader. Then connect the Divisor input to the "hours" output, so that the result will be the bonus amount per hour.

Reader to Divide

Now we need to add the division result to the basic hourly rate for each employee. Drag an Add component onto the Mapper, connecting its inputs to the "rate" output in the XML Reader and the output of the Divide function.

Now connect the Add output to the Element Value input in the XML Writer, so that the addition result is written into the "result" element.

Now we need to include the "type" attribute in the source, so add a Constant Value from the Data Type section. Right-click it and choose Show Properties. Choose a String Data Type and enter "hourly" as the value.

Connect the Constant output to the "type" input in the XML Writer.

Finally let's make the remaining input and output connections. We do not want to map all data items in the source, as we are only interested in certain values. Map "payroll" to "wages", "employee" to "payee" and "payroll_id" to "ref". We don't need to map anything to the "result" element as it will be written out each time the Mapper maps the addition result to its Element Value. Although we have used some of the remaining input values for calculations, we do not need to map them individually to the target, as we are mainly interested in the calculation result.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<wages>
 <payee>
  <ref>126</ref>
  <result type="hourly">11.45</result>
 </payee>
 <payee>
  <ref>129</ref>
  <result type="hourly">15.50</result>
 </payee>
 <payee>
  <ref>130</ref>
  <result type="hourly">11.40</result>
 </payee>
 <payee>
  <ref>133</ref>
  <result type="hourly">16.20</result>
 </payee>
</wages>

The output contains an indicator of the actual hourly rate paid to each employee.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Modulus
Multiply
Add

Values
Constant

Data Mapping
Analyzing Numerical Input


IsEven
Send Feedback
Data Mapping > Data Mapper Functions > By Category > Maths > IsEven

Glossary Item Box

Function Name
 IsEven
Category
 Maths
Icon
Description
 Returns true if the value is even.
Inputs
Value A numeric value.
Outputs
Result boolean : true if the input value is even, otherwise false.

Remarks

Takes a numeric value strips off any fractional part and determines if its is an odd or even number (0 is even).

If the input value is not numeric then an error is raised (unless an in place cast is defined).

Examples
Source Data Copy Code
<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<Decimals xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="..\Common\Numbers.xsd">
    <Decimal>7194.954905803945093</Decimal>
    <Decimal>7570.634905803945093</Decimal>
    <Decimal>5754.914905803945093</Decimal>
    <Decimal>-7480.925094196054907</Decimal>
    <Decimal>-6851.065094196054907</Decimal>
</Decimals>

Output Data Copy Code
<Booleans>
    <Boolean>true</Boolean>
    <Boolean>true</Boolean>
    <Boolean>true</Boolean>
    <Boolean>true</Boolean>
    <Boolean>false</Boolean>
</Booleans>

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.


IsOdd
Send Feedback
Data Mapping > Data Mapper Functions > By Category > Maths > IsOdd

Glossary Item Box

Function Name
 IsOdd
Category
 Maths
Icon
Description
 Returns true if the value is odd.
Inputs
Value A numeric value.
Outputs
Result boolean : true if the input value is odd, otherwise false.

Remarks

Takes a numeric value strips off any fractional part and determines if its is an odd or even number (0 is even).

If the input value is not numeric then an error is raised (unless an in place cast is defined).

Examples

Source Data Copy Code
<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<Decimals xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="..\Common\Numbers.xsd">
    <Decimal>7194.954905803945093</Decimal>
    <Decimal>7570.634905803945093</Decimal>
    <Decimal>5754.914905803945093</Decimal>
    <Decimal>-7480.925094196054907</Decimal>
    <Decimal>-6851.065094196054907</Decimal>
</Decimals>

Output Data Copy Code
<Booleans>
    <Boolean>false</Boolean>
    <Boolean>false</Boolean>
    <Boolean>false</Boolean>
    <Boolean>false</Boolean>
    <Boolean>true</Boolean>
</Booleans>

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.


Modulus
Data Mapping > Data Mapper Functions > By Category > Maths > Modulus

Glossary Item Box

Function Name
 Modulus
Category
 Maths
Icon
 Modulus
Description
 Return modulus (remainder) of a division calculation
Inputs

Dividend | Value to divide
Divisor | Value to divide by
Outputs
Result Remainder after dividing first input by second
Properties
None -

Usage

The Data Mapper Maths Modulus function allows you to calculate remainders after division on input values. You can use the Modulus function with input source data or in conjunction with other arithmetic functions in the Maths section. To apply the Maths Modulus function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using bookclub_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<bookclub>
 <group>
  <group_number>12</group_number>
  <books>57</books>
  <members>17</members>
 </group>
 <group>
  <group_number>10</group_number>
  <books>43</books>
  <members>12</members>
 </group>
 <group>
  <group_number>5</group_number>
  <books>79</books>
  <members>30</members>
 </group>
</bookclub>

For our target schema we will be using bookclub_target.xsd, inferred from the following XML:

Target XML Copy Code
<club>
 <section ref="14" joined="27">
  <volumes_each>4</volumes_each>
  <volumes_left>7</volumes_left>
 </section>
 <section ref="7" joined="35">
  <volumes_each>2</volumes_each>
  <volumes_left>19</volumes_left>
 </section>
 <section ref="15" joined="18">
  <volumes_each>5</volumes_each>
  <volumes_left>2</volumes_left>
 </section>
</club>

The data models the members and books for a book club. Each group within the club has a certain number of books to share between the members. As you can see from the target data, as well as mapping the source data values, we need to include an indicator of how many books we can allocate to each member, plus a figure representing how many are left over - we will use the modulus to calculate this. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Maths Modulus function from the Component Palette into the mapping area:

The Modulus component has two inputs, representing the value to divide and the value to divide it with. The output represents the remainder following this division operation. Both inputs and output of the Modulus function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Connect the Dividend input in the Modulus function to the "books" output in the XML Reader and the divisor input to the "members" output.

Reader to Modulus

Now connect the Modulus output to the "volumes_left" input in the XML Reader.

Modulus Function Mapped

That's the remainder part of the calculation completed, but we also need to indicate how many books there are per person, so drag a Divide function onto the Mapper. As with the Modulus function, connect the Dividend input to the "books" output in the XML Reader and the Divisor input to the "members" output.

Reader to Divide

Now, we need the number of books per person to be a whole number, so let's cast the division result to an integer. Drag a Cast function from the Type section onto the Mapper. Right-click it and choose Show Properties. Choose an integer type from the drop-down list.

Now connect the Cast input to the Divide function output.

Now we can connect the Cast output to the "volumes_each" input in the XML Writer.

Cast to Writer

Finally let's make the remaining input and output connections. Remember to map "members" to "joined" - although we have used the members value for our division and modulus calculations, we have not yet mapped them to the output.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<club>
 <section ref="12" joined="17">
  <volumes_each>3</volumes_each>
  <volumes_left>6</volumes_left>
 </section>
 <section ref="10" joined="12">
  <volumes_each>3</volumes_each>
  <volumes_left>7</volumes_left>
 </section>
 <section ref="5" joined="30">
  <volumes_each>2</volumes_each>
  <volumes_left>19</volumes_left>
 </section>
</club>

The output contains an indicator of how many books can be allocated to each member in a group / section as well as how many are left over in each case.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Divide

Type
Cast

Data Mapping
Analyzing Numerical Input


Multiply
Data Mapping > Data Mapper Functions > By Category > Maths > Multiply

Glossary Item Box

Function Name
 Multiply
Category
 Maths
Icon
 Multiply
Description
 Multiply two numeric values
Inputs

Value 1 | First value to multiply
Value 2 | Second value to multiply
Outputs
Result Result of multiplying value 1 and value 2
Properties
None -

Usage

The Data Mapper Maths Multiply function allows you to carry out multiplication on input values. You can use the Multiply function with input source data or in conjunction with other arithmetic functions in the Maths section. To apply the Maths Multiply function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using payroll_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<payroll>
 <employee payroll_id="126">
  <rate>9.45</rate>
  <hours>35</hours>
  <bonus>50.00</bonus>
  <funding>350</funding>
 </employee>
 <employee payroll_id="129">
  <rate>10.50</rate>
  <hours>40</hours>
  <bonus>150.00</bonus>
  <funding>500</funding>
 </employee>
 <employee payroll_id="130">
  <rate>8.90</rate>
  <hours>35</hours>
  <bonus>100.00</bonus>
  <funding>400</funding>
 </employee>
 <employee payroll_id="133">
  <rate>11.20</rate>
  <hours>40</hours>
  <bonus>200.00</bonus>
  <funding>600</funding>
 </employee>
</payroll>

For our target schema we will be using payroll_target.xsd, inferred from the following XML:

Target XML Copy Code
<wages>
 <payee>
  <ref>122</ref>
  <result type="wage">500.50</result>
 </payee>
 <payee>
  <ref>125</ref>
  <result type="wage">475.40</result>
 </payee>
 <payee>
  <ref>126</ref>
  <result type="wage">600.80</result>
 </payee>
</wages>

The data models payroll data for temporary staff within an organisation. The output is designed to capture some value calculated from the source, using the "type" attribute to indicate what the calculation result represents. Let's assume that we want to calculate the basic weekly wage for each staff member, not including their bonus. To calculate this we will need to multiply the hourly rate by the number of hours worked. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Maths Multiply function from the Component Palette into the mapping area:

The Multiply component has two inputs, representing the values to multiply. Both inputs and output of the Multiply function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Connect the Multiply inputs to the "rate" and "hours" outputs in the XML Reader.

Reader to Multiply

Now connect the Multiply output to the Element Value input in the XML Writer, so that the multiplication result is written into the "result" element.

Now we need to include the "type" attribute in the source, so add a Constant Value from the Data Type section. Right-click it and choose Show Properties. Choose a String Data Type and enter "wage" as the value.

Connect the Constant output to the "type" input in the XML Writer.

Finally let's make the remaining input and output connections. We do not want to map all data items in the source, as we are only interested in certain values. Map "payroll" to "wages", "employee" to "payee" and "payroll_id" to "ref". We don't need to map anything to the "result" element as it will be written out each time the Mapper maps the multiplication result to it.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<wages>
 <payee>
  <ref>126</ref>
  <result type="wage">330.75</result>
 </payee>
 <payee>
  <ref>129</ref>
  <result type="wage">420.00</result>
 </payee>
 <payee>
  <ref>130</ref>
  <result type="wage">311.50</result>
 </payee>
 <payee>
  <ref>133</ref>
  <result type="wage">448.00</result>
 </payee>
</wages>

The output contains an indicator of the weekly wage for each employee, comprising the result of the multiplication.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Divide

Values
Constant

Data Mapping
Analyzing Numerical Input


Subtract
Data Mapping > Data Mapper Functions > By Category > Maths > Subtract

Glossary Item Box

Function Name
 Subtract
Category
 Maths
Icon
 Subtract
Description
 Subtract one numeric value from another
Inputs

Minuend | Value to subtract from
Subtrahend | Value to subtract
Outputs
Result Result of subtracting second input from first
Properties
None -

Usage

The Data Mapper Maths Subtract function allows you to carry out subtraction on input values. You can use the Subtract function with input source data or in conjunction with other arithmetic functions in the Maths section. To apply the Maths Subtract function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using payroll_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<payroll>
 <employee payroll_id="126">
  <rate>9.45</rate>
  <hours>35</hours>
  <bonus>50.00</bonus>
  <funding>350</funding>
 </employee>
 <employee payroll_id="129">
  <rate>10.50</rate>
  <hours>40</hours>
  <bonus>150.00</bonus>
  <funding>500</funding>
 </employee>
 <employee payroll_id="130">
  <rate>8.90</rate>
  <hours>35</hours>
  <bonus>100.00</bonus>
  <funding>500</funding>
 </employee>
 <employee payroll_id="133">
  <rate>11.20</rate>
  <hours>40</hours>
  <bonus>200.00</bonus>
  <funding>600</funding>
 </employee>
</payroll>

For our target schema we will be using payroll_target.xsd, inferred from the following XML:

Target XML Copy Code
<wages>
 <payee>
  <ref>122</ref>
  <result type="balance">50.00</result>
 </payee>
 <payee>
  <ref>125</ref>
  <result type="balance">47.50</result>
 </payee>
 <payee>
  <ref>126</ref>
  <result type="balance">60.30</result>
 </payee>
</wages>

The data models payroll data for temporary staff within an organisation. The output is designed to capture some value calculated from the source, using the "type" attribute to indicate what the calculation result represents. Let's assume that we want to calculate the balance after the cost of employing each staff member. To calculate this we will need to subtract the weekly wage plus bonus for an employee from the funding allocated to them. We will need to carry out multiplication and addition calculations to work out the weekly wage before we can subtract it, so our final mapping process will involve a few functions working in conjunction with one another. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Maths Subtract function from the Component Palette into the mapping area:

The Subtract component has two inputs, representing the value to subtract from and the value to subtract. Both inputs and output of the Subtract function may be connected to items in the XML Reader/ Writer or other components in the Mapper.

Connect the first Subtract input to the "funding" output in the XML Reader.

Reader to Subtract

For the second Subtract input, we need to carry out another couple of calculations. Drag an Add function onto the Mapper, connecting its first input to the "bonus" output in the XML Reader.

Now drag a Multiply function onto the Mapper, connecting its inputs to the "rate" and "hours" outputs in the XML Reader.

Connect the output of the Multiply function to the second input in the Add function. Then connect the output of the Add function to the second input in the Subtract function.

Add to Subtract

Now connect the Subtract output to the Element Value input in the XML Writer, so that the addition result is written into the "result" element.

Now we need to include the "type" attribute in the source, so add a Constant Value from the Data Type section. Right-click it and choose Show Properties. Choose a String Data Type and enter "balance" as the value.

Connect the Constant output to the "type" input in the XML Writer.

Finally let's make the remaining input and output connections. We do not want to map all data items in the source, as we are only interested in certain values. Map "payroll" to "wages", "employee" to "payee" and "payroll_id" to "ref". We don't need to map anything to the "result" element as it will be written out each time the Mapper maps the addition result to it. Although we have used the remaining input values for calculations, we do not need to map them individually to the target, as we only want the calculation result.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<wages>
 <payee>
  <ref>126</ref>
  <result type="balance">-30.75</result>
 </payee>
 <payee>
  <ref>129</ref>
  <result type="balance">-70.00</result>
 </payee>
 <payee>
  <ref>130</ref>
  <result type="balance">88.50</result>
 </payee>
 <payee>
  <ref>133</ref>
  <result type="balance">-48.00</result>
 </payee>
</wages>

The output contains a positive or negative indicator of the balance after employing each staff member.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Add
Multiply

Values
Constant

Data Mapping
Analyzing Numerical Input


Annotation
Send Feedback
Data Mapping > Data Mapper Functions > By Category > Misc > Annotation

Glossary Item Box

This is just a comment, it performs no function (does not affect the transform).

Its a convenient way to make notes on your transform.


Join
Send Feedback
Data Mapping > Data Mapper Functions > By Category > Misc > Join

Glossary Item Box

Function Name
 Join
Category
 Misc
Icon
Description
 Allows 2 sets of data to be associated with each other.
Inputs
Value The value to be mapped
Outputs
Result The mapped value
Properties
None -

Usage

When we have 2 separate data sources that are related to each other, we can use the Join component to establish a relationship between them and construct a hierarchy.

In the following example we have 2 simple CSV data sets, one describing Album information, the other Tracks. They are related to each other via the Albums.AlbumID and the Tracks.AlbumID. By using a Join component we can build a hierarchy where an Album 'has' 0-n Tracks. We can then use this structured hierarchical data just as we would any other structured data source.

When we come to connect the Join component, the 'Table A' input will form the outer data (container), and 'Table B' the inner data (nested). On the output side a 'Track' connection point corresponding to 'Table B' will be added into the Album, corresponding with 'Table A'. When the value read from 'Table A -> Join Value 1' is equal to 'Table B -> Join Value 1' the Node read from 'Table B' will be available in the output, in this way its possible for an album to have 0-n tracks.

Albums.csv

AlbumID | Artist Name | Album Name | Publisher | Year
1 | Nirvana | Nevermind | DGC Records | 1991
2 | Beatles | Abbey Road | Apple Records | 1969

Tracks.csv

AlbumID | Track Number | Name | Length
1 | 1 | Smells Like Teen Spirit | 05:01
1 | 2 | In Bloom | 04:14
1 | 3 | Come as You Are | 03:39
1 | 4 | Breed | 03:03
1 | 5 | Lithium | 04:17
1 | 6 | Polly | 02:57
1 | 7 | Territorial | 02:22
1 | 8 | Drain You | 03:43
1 | 9 | Lounge Act | 02:36
1 | 10 | Stay Away | 03:32
1 | 11 | On a Plain | 03:16
1 | 12 | Something in the Way | 20:35
2 | 1 | Come Together | 04:19
2 | 2 | Something | 03:02
2 | 3 | Maxwell's Silver Hammer | 03:27
2 | 4 | Oh! Darling | 03:27
2 | 5 | Octopus's Garden | 02:51
2 | 6 | I Want You (She's So Heavy) | 07:47

Output : Library.xml Copy Code
<!--Created by Liquid Data Mapper Libraries (www.liquid-technologies.com) for Liquid Technologies Ltd -->
<Library>
    <Album>
        <Artist>Nirvana</Artist>
        <Album>Nevermind</Album>
        <Publisher>DGC Records</Publisher>
        <Published>1991</Published>
        <Track>
            <TrackNo>1</TrackNo>
            <Name>Smells Like Teen Spirit</Name>
            <Length>05:01</Length>
        </Track>
        <Track>
            <TrackNo>2</TrackNo>
            <Name>In Bloom</Name>
            <Length>04:14</Length>
        </Track>
        <Track>
            <TrackNo>3</TrackNo>
            <Name>Come as You Are</Name>
            <Length>03:39</Length>
        </Track>
        <Track>
            <TrackNo>4</TrackNo>
            <Name>Breed</Name>
            <Length>03:03</Length>
        </Track>
        <Track>
            <TrackNo>5</TrackNo>
            <Name>Lithium</Name>
            <Length>04:17</Length>
        </Track>
        <Track>
            <TrackNo>6</TrackNo>
            <Name>Polly</Name>
            <Length>02:57</Length>
        </Track>
        <Track>
            <TrackNo>7</TrackNo>
            <Name>Territorial</Name>
            <Length>02:22</Length>
        </Track>
        <Track>
            <TrackNo>8</TrackNo>
            <Name>Drain You</Name>
            <Length>03:43</Length>
        </Track>
        <Track>
            <TrackNo>9</TrackNo>
            <Name>Lounge Act</Name>
            <Length>02:36</Length>
        </Track>
        <Track>
            <TrackNo>10</TrackNo>
            <Name>Stay Away</Name>
            <Length>03:32</Length>
        </Track>
        <Track>
            <TrackNo>11</TrackNo>
            <Name>On a Plain</Name>
            <Length>03:16</Length>
        </Track>
        <Track>
            <TrackNo>12</TrackNo>
            <Name>Something in the Way</Name>
            <Length>20:35</Length>
        </Track>
    </Album>
    <Album>
        <Artist>Beatles</Artist>
        <Album>Abbey Road</Album>
        <Publisher>Apple Records</Publisher>
        <Published>1969</Published>
        <Track>
            <TrackNo>1</TrackNo>
            <Name>Come Together</Name>
            <Length>04:19</Length>
        </Track>
        <Track>
            <TrackNo>2</TrackNo>
            <Name>Something</Name>
            <Length>03:02</Length>
        </Track>
        <Track>
            <TrackNo>3</TrackNo>
            <Name>Maxwell's Silver Hammer</Name>
            <Length>03:27</Length>
        </Track>
        <Track>
            <TrackNo>4</TrackNo>
            <Name>Oh! Darling</Name>
            <Length>03:27</Length>
        </Track>
        <Track>
            <TrackNo>5</TrackNo>
            <Name>Octopus's Garden</Name>
            <Length>02:51</Length>
        </Track>
        <Track>
            <TrackNo>6</TrackNo>
            <Name>I Want You (She's So Heavy)</Name>
            <Length>07:47</Length>
        </Track>
    </Album>
</Library>

Naming the Tables makes the transform much more readable.

Simply select the Join component and set the 'Table A Name' and 'Table B Name' properties in the property grid.

Composite Keys

If your data sets require more than one value to be matched in order to relate them, then you can add more Join Values by right clicking on them and selecting 'Add Above' or 'Add Below'.

Nested Joins

The example above demonstrates relating 2 data sets together, but it's possible to relate as many datasets as you need together in order to construct a hierarchical structure from many datasets. The following examples show how this has been done using extracts from the SQL Server NorthWind Sample Database.


Lookup
Send Feedback
Data Mapping > Data Mapper Functions > By Category > Misc > Lookup

Glossary Item Box

Function Name
 Lookup
Category
 Misc
Icon
 Subtract
Description
 Maps one set of values to another
Inputs
Value The value to be mapped
Outputs
Result The mapped value
Properties
None -

Usage

The lookup component replaces one value with another, so for example you may need to change ISO 2 letter country codes into ISO 3 letter country codes, or Currency names into currency characters etc.

The Lookup components properties (right click on the lookup component and select the 'properties' menu item), allow the key to value mappings to be configured.

Values can be added individually via the Add button or the entire mapping can be edited via the Import button (allows editing as a CSV formatted list).

The only other options effect how the lookup behaves when an attempt is made to map a value that is not present in the keys. There are 3 options.

Use key (Input) value

The value returned for an input value that has no corresponding key value will be the input value itself.

Use Default Value

The value returned for an input value that has no corresponding key value will be a default value specified by in the field below.

Raise Error

If an input value has no corresponding key value, then a runtime error is raised and the transform stops.

The Key Value must be unique, and error will be raised if duplicates exist.

Examples

The following examples assume the following mapping data values have been set up

Key | Value
US | USA
GB | GBR
FR | FRA
DE | DEU

Example 1

If Mapping Failures is set to 'Use Key (input) Value'.

Value | Result
US | USA
AU | AU
FR | FRA

Example 2

If Mapping Failures is set to 'Use Default' and the default value is set to '???'

Value | Result
US | USA
AU | ???
FR | FRA

Example 3

If Mapping Failures is set to 'Raise Error'

Value | Result
US | USA
AU | Runtime Error


NewGuid
Send Feedback
Data Mapping > Data Mapper Functions > By Category > Misc > NewGuid

Glossary Item Box

Function Name
 NewGuid
Category
 Misc
Icon
 Subtract
Description
 Creates a new Guid value
Outputs
Guid The new unique guide value
Properties
None -

Usage

Create a new globally unique identifier in the form 6B29FC40-CA47-1067-B31D-00DD010662DA.


CharToCode
Data Mapping > Data Mapper Functions > By Category > String > CharToCode

Glossary Item Box

Function Name
 CharToCode
Category
 String
Icon
 CharToCode
Description
 Convert character data to Unicode
Inputs
String String containing character
Outputs
Result Input character represented in Unicode
Properties
None -

Usage

The Data Mapper String CharToCode function returns the Unicode representation of a single character input String, or the first character in a longer String. Often, XML data is mapped for use between differing Web and desktop applications, so the ability to convert data to different formats is essential. Converting character data to Unicode is therefore a useful facility. To apply the String ChartoCode transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using document_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<docs>
 <document>
  <title>My Data File</title>
  <content>Here is my content</content>
  <type>b</type>
 </document>
 <document>
  <title>Another File</title>
  <content>Here is some more content</content>
  <type>r</type>
 </document>
</docs>

For our target schema we will be using document_target.xsd, inferred from the following XML:

Target XML Copy Code
<data_files>
 <file type="99" name="My File">Here is my content</file>
 <file type="115" name="His File">Here is his content</file>
</data_files>

The data models documents, with the "type" item using a single character. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the String CharToCode function from the Component Palette into the mapping area:

String CharToCode Component

String CharToCode Transform Added

The String CharToCode function takes a single input and gives a single output. The input should be connected to the source text String item to retrieve the Unicode representation of. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper. In this case we are mapping from an element in the source to an attribute in the target, converting to Unicode at the same time. Connect the XML Reader "type" output to the CharToCode input:

XML Reader to CharToCode

Now connect the CharToCode output to the "type" item in the XML Writer:

CharToCode to XML Writer

Finally, connect the remaining inputs and outputs:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<data_files>
 <file type="98" name="My Data File">Here is my content</file>
 <file type="114" name="Another File">Here is some more content</file>
</data_files>

The "type" items have been converted from character to Unicode data as part of the mapping process. The result is that the characters are now represented numerically.

If the CharToCode function receives an input String with more than one character in it, it will output the code for the first character.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

CodeToChar

Type
Cast
NodeType


CodeToChar
Data Mapping > Data Mapper Functions > By Category > String > CodeToChar

Glossary Item Box

Function Name
 CodeToChar
Category
 String
Icon
 CodeToChar
Description
 Convert Unicode value to character
Inputs
Char Code Unicode representation of character
Outputs
Result Character represented by Unicode input
Properties
None -

Usage

The Data Mapper String CodeToChar function returns the character representation of a single Unicode value input. Often, XML data is mapped for use between differing Web and desktop applications, so the ability to convert data to different formats is essential. Converting Unicode to character data is therefore a useful facility. To apply the String CodeToChar transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using document_alt_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<docs>
<document>
 <title>My Data File</title>
 <content>Here is my content</content>
 <type>98</type>
</document>
<document>
 <title>Another File</title>
 <content>Here is some more content</content>
 <type>114</type>
</document>
</docs>

For our target schema we will be using document_alt_target.xsd, inferred from the following XML:

Target XML Copy Code
<data_files>
 <file type="c" name="My File">Here is my content</file>
 <file type="s" name="His File">Here is his content</file>
</data_files>

The data models documents, with the "type" item using a single character. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the String CodeToChar function from the Component Palette into the mapping area:

String CodeToChar Component

String CodeToChar Transform Added

The String CodeToChar function takes a single input and gives a single output. The input should be connected to the source Unicode value to retrieve the character representation from. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper. In this case we are mapping from an element in the source to an attribute in the target, converting to character at the same time. Connect the XML Reader "type" output to the CodeToChar input:

XML Reader to CodeToChar

Now connect the CodeToChar output to the "type" item in the XML Writer:

CodeToChar to XML Writer

Finally, connect the remaining inputs and outputs:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<data_files>
 <file type="b" name="My Data File">Here is my content</file>
 <file type="r" name="Another File">Here is some more content</file>
</data_files>

The "type" items have been converted from Unicode to character data as part of the mapping process. The result is that the characters are now represented as text Strings rather than numerically.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

CharToCode

Type
Cast
NodeType


Concat
Data Mapping > Data Mapper Functions > By Category > String > Concat

Glossary Item Box

Function Name
 Concat
Category
 String
Icon
 Concat
Description
 Concatenate two or more input Strings
Inputs

String 1 | First String to concatenate
String 2 | Second String to concatenate
... | More inputs can be added see Variable Function Inputs
Outputs
Result Text String comprising input Strings concatenated
Properties
None -

Usage

The Data Mapper String Concat function concatenates two input Strings. If you need to combine two items from your source XML into a single item in the target, you can use the Concat function. When mapping XML data, it is common to find that your source and target Schemas use differing numbers of elements and attributes -concatenation is therefore common. By default, the Concat function appears with two inputs, however, you can add and remove inputs by right-clicking them within the mapper if you need to alter the range of values you are concatenating. To apply the String Concat function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using office_alt_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<office>
 <file type="corporate">
  <num>12345</num>
  <code>abcde</code>
  <title>Smith and Mitchell</title>
 </file>
 <file type="individual">
  <num>54321</num>
  <code>fghij</code>
  <title>James Black</title>
 </file>
</office>

For our target schema we will be using office_target.xsd, inferred from the following XML:

Target XML Copy Code
<associates>
 <account reference="98765hijkl">
  <category>Organisation</category>
  <contact>Jane Johnson</contact>
 </account>
 <account reference="56789rstuv">
  <category>Corporate</category>
  <contact>Mary Simpson</contact>
 </account>
</associates>

The data models office files for an organisation. Here is the Data Mapper with Source and Target imported:

String Concat Reader and Writer

Let's assume that we want to combine the "num" and "code" elements in the source, mapping these two concatenated to the "reference" attribute in the target. Drag the String Concat function from the Component Palette into the mapping area:

String Concat Component

String Concat Transform Added

The String Concat function takes two (or optionally more) inputs and gives a String output. The String 1 input should be connected to the input String you want to use as the first part of the new String. The String 2 input should be connected to the String you want to use as a the second part of the result String, and so on. The output should be connected to the target item, which may be in the XML Writer or another mapping component if you need to apply further transformations. Connect the String 1 String input to the "num" output in the XML Reader, and the String 2 input to the "code" item. Connect the Concat output to the "reference" input in the XML Writer.

String Concat Transform Mapped

Finally let's connect the remaining input and output connections:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<associates>
 <account reference="12345abcde">
  <category>corporate</category>
  <contact>Smith and Mitchell</contact>
 </account>
 <account reference="54321fghij">
  <category>individual</category>
  <contact>James Black</contact>
 </account>
</associates>

The input Strings have been combined as part of the mapping process. You can also use Concat to add additional characters to Strings by applying the Concat function to an input String and a Constant representing the characters you wish to add. If you need to concatenate multiple instances of input values, try the ConcatAll function.

You can add and remove inputs from the Concat function. Right-click an existing input in the Mapper and choose Add Below, Add Above or Delete.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Data Mapping
Variable Function Inputs
Combining String Functions


EmptyToNull
Send Feedback
Data Mapping > Data Mapper Functions > By Category > String > EmptyToNull

Glossary Item Box

Function Name
 Empty To Null
Category
 String
Icon
 Subtract
Description
 If a value is null it is treated as an empty sequence (or null)
Inputs
Value The value to be tested
Outputs
Result The resulting value
Properties
None -

Usage

In some systems a string that is empty can be considered to be missing (or null), this function allows you to formalize that assumption.

The behavior of the function is simple, if the input string value is not empty, then the input string is returned. If the input string is an empty it is ignored.

Example

Its easier to use an example to see how this can be useful.

Input Data Copy Code
James,Paul,McCartney
Liv,,Tyler
William,Bradley,Pitt
Björk,,
George,,Clooney

Given the above transform and input data. the resulting XML would look like this

Output XML Copy Code
<Celebrity>
 <Name>
  <Forename>James</Forename>
  <MiddleName>Paul</MiddleName>
  <Surname>McCartney</Surname>
 </Name>
 <Name>
  <Forename>Liv</Forename>
  <MiddleName></MiddleName>
  <Surname>Tyler</Surname>
 </Name>
 <Name>
  <Forename>William</Forename>
  <MiddleName>Bradley</MiddleName>
  <Surname>Pitt</Surname>
 </Name>
 <Name>
  <Forename>Björk</Forename>
  <MiddleName></MiddleName>
  <Surname></Surname>
 </Name>
 <Name>
  <Forename>George</Forename>
  <MiddleName></MiddleName>
  <Surname>Clooney</Surname>
 </Name>
</Celebrity>

As you can see we create a <MiddleName> and <Surname> element even if the source field was empty.

In this example we are getting the data from a CSV file and the CSV format does not have a concept of null so empty fields are common.

Now suppose we only want the <MiddleName> and <Surname> element to be written out if they contain a value.

The following transform would allow us to do this

This would produce the following XML

Output XML Copy Code
<Celebrity>
 <Name>
  <Forename>James</Forename>
  <MiddleName>Paul</MiddleName>
  <Surname>McCartney</Surname>
 </Name>
 <Name>
  <Forename>Liv</Forename>
  <Surname>Tyler</Surname>
 </Name>
 <Name>
  <Forename>William</Forename>
  <MiddleName>Bradley</MiddleName>
  <Surname>Pitt</Surname>
 </Name>
 <Name>
  <Forename>Björk</Forename>
 </Name>
 <Name>
  <Forename>George</Forename>
  <Surname>Clooney</Surname>
 </Name>
</Celebrity>


IndexOf
Data Mapping > Data Mapper Functions > By Category > String > IndexOf

Glossary Item Box

Function Name
 IndexOf
Category
 String
Icon
 Upper
Description
 Return the index of an input search String within a target String
Inputs

String | Text String to search within
Search String | Text String to search for
Start Index | Index to search from within target String
Outputs
Result Index of the search String within the target String
Properties
None -

Usage

The Data Mapper String IndexOf function returns the index of a given search String within a target String. If you need to carry out transformations on your input data, you may need to calculate the indices of particular items as part of that process. For example, you may wish to retrieve a particular section of a String but may not know in advance what length the resulting String will be. For this reason, the IndexOf function is most likely to be used in conjunction with other mapping functions. To apply the String IndexOf transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using record_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<catalog>
<record>
 <file_no>nmjhgfd-654</file_no>
 <section>Administration</section>
</record>
<record>
 <file_no>gtby-7840</file_no>
 <section>Marketing</section>
</record>
</catalog>

For our target schema we will be using record_target.xsd, inferred from the following XML:

Target XML Copy Code
<record_data>
<resource type="Finance">
 998
</resource>
<resource type="Human Resources">
 5455
</resource>
</record_data>

The data models records for an organisation. Notice that the target element content comprises a few numbers. Let's assume that we only want the map the numerical part of the "file_no" element, which appears after a dash character in the source. We will use the IndexOf function to work out what index the dash is at, then use that information to retrieve the portion of the String following it. We have no knowledge of how long each String section will be in advance, or the length of the String as a whole.

Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the String IndexOf function from the Component Palette into the mapping area:

String IndexOf Component

String IndexOf Transform Added

The String IndexOf function takes three inputs and gives a numerical output. The String input should be connected to the target String element, with the Search String input connected to the String you want to retrieve the index of. The Start Index needs to be connected to a number representing the index you want to search from. We will use Constants to represent the Search String and Start Index. The output should be connected to the target item, in many cases this will be another function rather than an item in the XML Writer.

Connect the "file_no" output in the XML Reader to the String input in the IndexOf component:

Reader to IndexOf

Now we need a String representing the dash character. Drag a Constant component onto the Mapper and right-click it, choosing Show Properties. Select String from the Data Type drop-down list and enter a single dash character in the Value field - click OK.

String Constant Properties

Connect the Constant output to the IndexOf Search String input.

Constant to IndexOf

Now we need another Constant to represent the Start Index, so drag one onto the Mapper and right-click to set its properties. Choose an integer Data Type and enter 0 as the Value, so that we search the entire String.

Int Constant Properties

Connect the new integer Constant output to the Start Index input in the IndexOf component.

Int Constant to IndexOf

Since the numerical part of the input String is at the section after the dash character, we can use the Right function to retrieve it, so drag one onto the Mapper and connect the "file_no" output in the XML Reader to its String input.

IndexOf to Right

The Right function needs to know the length of the right String section we wish to retrieve, which we are going to use the IndexOf function to calculate. By subtracting the index of the dash character from the length of the target String, then subtracting 1 from the result, we will arrive at the length of the String section following the dash. Drag a Length function onto the Mapper and connect its input to the target "file_no" output in the XML Reader.

Reader to Length

Drag a Subtract function from the Maths section onto the Mapper and connect its first input to the Length output, with its second input connected to the result of the IndexOf function.

IndexOf to Subtract

Now we need to subtract 1, so drag another Constant onto the Mapper and right-click to set the Properties. Choose an integer type and enter 1 as the Value.

Int Constant Properties

Drag another Subtract function onto the Mapper, connecting its first input to the previous Subtract output, and the second input to the Constant just added.

String IndexOf Second Subtraction

Connect the output of this second Subtract function to the Length input of the Right function, connecting the output of the Right function to the Element Value in the XML Writer.

String IndexOf Right to Writer

Finally, complete the remaining connections between Reader and Writer:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<record_data>
 <resource type="Administration">654</resource>
 <resource type="Marketing">7840</resource>
</record_data>

The file reference value has been restricted to the characters following the dash as part of the mapping process. The IndexOf function may not always be used with such complex mapping processes, but it is most likely to be used in conjunction with other functions.

If the Search String is not found, the IndexOf function will output a value of -1. You can use this value in conjunction with the Comparator functions, for example to determine whether it is less than zero, in which case the Search String is not present.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Length
Right

Data Mapping
Combining String Functions

Maths
Subtract

Values
Constant


Join String
Data Mapping > Data Mapper Functions > By Category > String > Join String

Glossary Item Box

Function Name
 JoinString
Category
 String
Icon
 CodeToChar
Description
 Convert Unicode value to character
Inputs
Values A sequence of string values that will be joined together to form a single string
Outputs
String The string resulting from joining all the input Values and placing the Separator between them.
Properties
Separator The string that is inserted between each Value entry in order to produce the output String

Usage

Concatenates all the string values in the input sequence, using the specified separator between each value.

Example

If the input Value contains the following values

A
B
C
D
E

And the separator string is ', ' then the resulting output string is

A, B, C, D, E

See Also

CharToCode
CodeToChar
Concat
EmptyToNull
IndexOf
Left
Length
Lower
Replace
Right
SplitString
SubString
Trim
TrimEnd
TrimStart
Upper


Left
Data Mapping > Data Mapper Functions > By Category > String > Left

Glossary Item Box

Function Name
 Left
Category
 String
Icon
 Left
Description
 Retrieve left-most section of a String to a particular length
Inputs

String | Text String to retrieve left part of
Length | Length of result String
Outputs
Result Text String comprising the left-most characters from the input String, with number of characters specified by Length input
Properties
none -

Usage

The Data Mapper String Left function retrieves the left-most section of an input String, with the length also specified as input. In other words, the Left function retrieves the first n characters in the input String, creating a substring containing these characters. The Left function is useful if your target data model involves size restrictions, allowing you to limit the length of particular mapped String items. To apply the String Left transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using product_source.xsd, an XML Schema Definition inferred from the following source:

Colorized Example Code
Source XML XML Copy Code
<catalogue>
<product>
<name>Kitchen Chair</name>
<category>Furniture</category>
<description>This lovely chair has lots of fantastic qualities ag65d4hn78</description>
</product>
<product>
<name>Table Lamp</name>
<category>Lighting</category>
<description>This beautiful lamp is a very special item h76gfr45v2</description>
</product>
</catalogue>

For our target schema we will be using product_target.xsd, inferred from the following XML:

Colorized Example Code
Target XML XML Copy Code
<goods>
<item category="Electrical">
<item_name>Toaster</item_name>
<item_overview>This is a high performance, reliable toaster.</item_overview>
</item>
<item category="Gardening">
<item_name>Shovel</item_name>
<item_overview>This sturdy but lightweight shovel is great..</item_overview>
</item>
</goods>

The data models produce for a retail service. Here is the Data Mapper with Source and Target imported:

Data Mapper String Left Function

Let's drag the String Left function from the Component Palette into the mapping area:

String Left Component

String Left Transform Added

The String Left function takes two inputs and gives a single output. The String input should be connected to the source text String item to retrieve the result text from. The Length input requires a number input indicating the length of the desired left String section. The Left function output should be connected to the target item, in the XML Writer or another function. First connect the "description" item in the XML Reader to the String input of the Left function:

Reader to Left String Input

Next connect the Left output to the "item_overview" item in the XML Writer:

Left Output to Writer Input

Now we need to specify the length of the desired left String portion. To do this, we need a Constant Value. Drag one from the Data Type section in the Component Palette onto the mapping area:

Constant Value Added

We need to specify the value we want the Constant to have. To do so, right-click it and choose Show Properties. Select one of the integer types from the drop-down Data Type menu and enter your chosen number in the Value field.

For this example we are limiting the output String to the first 15 characters of the input String. Connect the Constant output to the Left function Length input:

Constant to Left Input

Now when the source item is mapped to the target item the values will be restricted to the 15 left-most characters.

Finally let's make the remaining input and output connections:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Colorized Example Code
Output XML XML Copy Code
<goods>
<item category="Furniture">
<item_name>Kitchen Chair</item_name>
<item_overview>This lovely cha</item_overview>
</item>
<item category="Lighting">
<item_name>Table Lamp</item_name>
<item_overview>This beautiful </item_overview>
</item>
</goods>

The input element value has been limited to the first 15 characters as part of the mapping process. Often, XML mapping involves converting from legacy systems to new applications in which you may have restrictions in terms of storage space. The Left function can also be useful for other types of String content, for example non-human-readable Strings comprising data items in which you do not need all characters to be preserved when mapping to a new model.

Tip Box
The SubString function is an alternative option if you need to specify the start and length of your required characters within a String.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Right
SubString


Length
Data Mapping > Data Mapper Functions > By Category > String > Length

Glossary Item Box

Function Name
 Length
Category
 String
Icon
 Length
Description
 Return the length of a String
Inputs
String Text String to calculate length of
Outputs
Result Number of characters in the input String
Properties
None -

Usage

The Data Mapper String Length function calculates the length of an input String. If you need to carry out transformations on your input data, you may need to calculate the length of particular items as part of that process. For this reason, the Length function is most likely to be used in conjunction with other mapping functions. To apply the String Length transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using office_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<office>
 <file type="corporate">
  <ref>12345abcde</ref>
  <title>Smith and Mitchell</title>
 </file>
 <file type="individual">
  <ref>54321fghij</ref>
  <title>James Black</title>
 </file>
</office>

For our target schema we will be using office_target.xsd, inferred from the following XML:

Target XML Copy Code
<associates>
 <account reference="98765klmno">
  <category>Organisation</category>
  <contact>Jane Johnson</contact>
 </account>
 <account reference="56789pqrst">
  <category>Corporate</category>
  <contact>Mary Simpson</contact>
 </account>
</associates>

The data models contact files for an organisation. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the String Length function from the Component Palette into the mapping area:

String Length Component

String Length Transform Added

The String Length function takes a single input and gives a single numerical output. The input should be connected to the source text String item to calculate the length of. The output should be connected to the target item, in most cases another function rather than an item in the XML Writer. Let's assume in this case that we want all but the first 5 characters in the String, for demonstration. Add a Constant to the Mapper:

Alter the Constant properties by right-clicking it, choosing show Properties. Select an integer type from the drop-down list and enter 5 as the Value.

We will use the Right function to retrieve all of the input String except the first 5 characters. Drag a Right function onto the Mapper:

Right Function Added

Assuming we know nothing about the length of the input String except that we don't want the first 5 characters, we need to calculate the length of the String we want the Right function to return. To achieve this, we need a Subtract function added to the Mapper:

Subtract Function Added

Let's start making some connections. First, connect the "ref" item in the XML Reader to the Length function input and the Length output to the first Subtract input:

Length and Subtract Connected

Next connect the Constant output to the second Subtract input:

Constant to Subtract

Now the output of the Subtract function is what we want to use as the Length input for the Right function, so connect it, also connecting the "ref" item in the XML Reader to the String input of the Right function:

Subtract to Right

Finally, connect the Right function output to the "reference" input in the XML Writer and complete the remaining connections between Reader and Writer:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<associates>
 <account reference="abcde">
  <category>corporate</category>
  <contact>Smith and Mitchell</contact>
 </account>
 <account reference="fghij">
  <category>individual</category>
  <contact>James Black</contact>
 </account>
</associates>

The reference attribute value has been restricted to all but the first 5 characters as part of the mapping process. In this case we knew that the String as a whole was length 10, but in reality you may not always know the total length of your input data Strings, which is when the Length function may prove useful.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Right

Values
Constant

Maths
Subtract

Data Mapping
Combining String Functions


Lower
Data Mapping > Data Mapper Functions > By Category > String > Lower

Glossary Item Box

Function Name
 Lower
Category
 String
Icon
 Lower
Description
 Convert text string characters to lower case
Inputs
String Text String to convert to lower case
Outputs
Result Text String with all characters converted to lower case
Properties
Culture Set culture for language data

Usage

The Data Mapper String Lower function converts text String characters to lower case. If your source XML contains characters you wish to be stored entirely in lower case within the target, you can apply this transform when mapping the data. Whether the characters are within element content or within attribute values, the transform will execute on them. To apply the String Lower transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using comment_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<comment contributor="Mary">
 I really like this
</comment>

For our target schema we will be using comment_target.xsd, inferred from the following XML:

Target XML Copy Code
<user_comment>
 <user>john</user>
 <content>I absolutely love this</content>
</user_comment>

The data models user comments for a product or website. Here is the Data Mapper with Source and Target imported:

Data Mapper String Lower Function

Let's drag the String Lower function from the Component Palette into the mapping area:

String Lower Component

String Lower Transform Added

The String Lower function takes a single input and gives a single output. The input should be connected to the source text String item to be converted to lower case. The output should be connected to the target item. In this case we are mapping from an attribute to an element:

String Lower Transform Mapped

We map the "contributor" attribute in the XML Reader to the "user" element in the XML Writer, converting to lower case at the same time. Finally let's make the remaining input and output connections:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<user_comment>
 <user>mary</user>
 <content>
  I really like this
 </content>
</user_comment>

The input attribute value has been converted to lower case as part of the mapping process.

Properties

If you happen to be dealing with different languages, the Lower function can also be tailored to suit. Within the mapping area, right-click the Lower function and choose Show Properties. You can choose languages from the Culture drop-down list and the Mapper will select lower case characters accordingly.

Choosing a Language for the Lower Function

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Upper

Data Mapping
Combining String Functions


Replace
Data Mapping > Data Mapper Functions > By Category > String > Replace

Glossary Item Box

Function Name
 Replace
Category
 String
Icon
 Upper
Description
 Replace a Search String with a replacement String in an input String
Inputs

String | Text String to replace part of
Search String | String to replace in input
Replace String | String to replace Search String with in input
Outputs
Result Input String with Search String replaced by Replace String
Properties
None -

Usage

The Data Mapper String Replace function returns an input String with a particular search String replaced. If you need to carry out transformations on your input data, you may need to replace characters or substrings as part of that process. In some cases, you may wish to remove a character or substring from an input String - here you can also use the Replace function, by supplying an empty String as the Replace String input. To apply the String Replace transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using record_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<catalog>
<record>
 <file_no>nmjhgfd-654</file_no>
 <section>Administration</section>
</record>
<record>
 <file_no>gtby-7840</file_no>
 <section>Marketing</section>
</record>
</catalog>

For our target schema we will be using record_target.xsd, inferred from the following XML:

Target XML Copy Code
<record_data>
<resource type="Finance">
 hju_998
</resource>
<resource type="Human Resources">
 trfd_5455
</resource>
</record_data>

The data models records for an organisation. Notice that the target element content contains a dash character, which appears to act as a separator within the data item, while the target XML contains an underscore. Let's assume that we need to replace the dash character with the underscore character for our target application.

Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the String Replace function from the Component Palette into the mapping area:

String Replace Component

String Replace Transform Added

The String Replace function takes three inputs and gives a String output. The first input should be connected to the input String. The Search String input should be connected to a String defining the character or substring you wish to replace. The Replace String input should be connected to a String defining the characters or substring you want to replace the Search String with. The output should be connected to the target item, which may be in the XML Writer or another function.

Connect the "file_no" output in the XML Reader to the String input in the Replace component and the Replace Result output to the Element Value in the XML Writer:

Replace to Reader and Writer

Now we need two Strings, one representing the dash character and another representing the underscore. Drag two Constant components onto the Mapper and right-click each one in turn, choosing Show Properties. In the first, select String from the Data Type drop-down list and enter a single dash character in the Value field. So that we can see at a glance which String Constant is which, let's alter the Name field to "search".

Search Constant Properties

Now set the Properties of the Replace String Constant, entering "replace" as the Name, String as the Data Type and an underscore character as the Value.

Replace Constant Properties

Now the purpose of the Constants is clear when you see them in the Mapper.

String Replace Constants Added

Connect the search Constant to the Search String input in the Replace function and the replace Constant to the Replace String input.

String Replace Constants Connected

Finally, complete the remaining connections between Reader and Writer:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<record_data>
 <resource type="Administration">nmjhgfd_654</resource>
 <resource type="Marketing">gtby_7840</resource>
</record_data>

The file reference value has been altered to include an underscore in place of the dash character as part of the mapping process. You can also use the Replace function with substrings containing multiple characters as either Search or Replace String input.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Data Mapping
Combining String Functions

Values
Constant


Right
Data Mapping > Data Mapper Functions > By Category > String > Right

Glossary Item Box

Function Name
 Right
Category
 String
Icon
 Right
Description
 Retrieve right-most section of a String to a particular length
Inputs

String | Text String to retrieve right part of
Length | Length of result String
Outputs
Result Text String comprising the right-most characters from the input String, with number of characters specified by Length input
Properties
none -

Usage

The Data Mapper String Right function retrieves the right-most section of an input String, with the length also specified as input. In other words, the Right function retrieves the last n characters in the input String, creating a substring containing these characters. The Right function is useful if your target data model involves size restrictions, allowing you to limit the length of particular mapped String items. To apply the String Right transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using product_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<catalogue>
 <product>
  <name>Kitchen Chair</name>
  <category>Furniture</category>
  <description>This lovely chair has lots of fantastic qualities ag65d4hn78</description>
 </product>
 <product>
  <name>Table Lamp</name>
  <category>Lighting</category>
  <description>This beautiful lamp is a very special item h76gfr45v2</description>
 </product>
</catalogue>

For our target schema we will be using product_target.xsd, inferred from the following XML:

Target XML Copy Code
<goods>
 <item category="Electrical">
  <item_name>Toaster</item_name>
  <item_overview>jkg7jh543d</item_overview>
 </item>
 <item category="Gardening">
  <item_name>Shovel</item_name>
  <item_overview>nj87hg10kj</item_overview>
 </item>
</goods>

The data models produce for a retail service. For demonstration, let's assume that the "description" item in the input contains a code as its final 10 characters - this code is all we want to map to the output Schema, perhaps to use it as a reference within this or another data source. Here is the Data Mapper with Source and Target imported:

Data Mapper String Right Function

Let's drag the String Right function from the Component Palette into the mapping area:

String Right Component

String Right Transform Added

The String Right function takes two inputs and gives a single output. The String input should be connected to the source text String item to retrieve the result text from. The Length input requires a number input indicating the length of the desired right String section. The Right function output should be connected to the target item in the XML Writer or another component. First connect the "description" item in the XML Reader to the String input of the Right function:

Reader to Right String Input

Next connect the Right output to the "item_overview" item in the XML Writer:

Right Output to Writer Input

Now we need to specify the length of the desired right String portion. To do this, we need a Constant Value. Drag one from the Data Type section in the Component Palette onto the mapping area:

Constant Value Added

We need to specify the value we want the Constant to have. To do so, right-click it and choose Show Properties. Select one of the integer types from the drop-down Data Type menu and enter your chosen number in the Value field.

For this example we are limiting the output String to the last 10 characters of the input String. Connect the Constant output to the Right function Length input:

Constant to Right Input

Now when the source item is mapped to the target item the values will be restricted to the 10 right-most characters.

Finally let's make the remaining input and output connections:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<goods>
 <item category="Furniture">
  <item_name>Kitchen Chair</item_name>
  <item_overview>ag65d4hn78</item_overview>
 </item>
 <item category="Lighting">
  <item_name>Table Lamp</item_name>
  <item_overview>h76gfr45v2</item_overview>
 </item>
</goods>

The input element value has been limited to the last 10 characters as part of the mapping process. Often, XML mapping involves converting from legacy systems to new applications in which you may have restrictions in terms of storage space. The Right function can therefore be useful for both human-readable and non-human-readable Strings comprising data items in which you do not need all characters to be preserved when mapping to a new model.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Left

Data Mapping
Combining String Functions


SplitString
Send Feedback
Data Mapping > Data Mapper Functions > By Category > String > SplitString

Glossary Item Box

Function Name
 SplitString
Category
 String
Icon
 CodeToChar
Description
 SplitString is used to break a delimited string into substrings.
Inputs
String The string to be split (whenever a separator character is found)
Outputs
Values A sequence of strings, each being a part of the input String being split
Properties

Separator | A character that delimits the substrings in the input String
Ignore Empty | Omits empty values from the sequence being returned

Usage

Splits a string into the maximum number of substrings delimited by the characters specified in the Separators property. Empty values can be ignored by setting the appropriate property.

Example 1

Input String = "A,B,C,,D,E"

Separator = ','

Ignore Empty = false

Result

A
B
C
D
E
Example 2

Input String = "A,B,C,,D,E"

Separator = ','

Ignore Empty = true

Result

A
B
C
D
E

Example 3

In this example the input String is a sequence of strings. The result is the combination of all the split parts from each input value.

Input Strings

A,B,C,,D,E
1,2,3
X
Separator = ','

Ignore Empty = false

Result

A
B
C
D
E
1
2
3
X


SubString
Data Mapping > Data Mapper Functions > By Category > String > SubString

Glossary Item Box

Function Name
 SubString
Category
 String
Icon
 SubString
Description
 Retrieve section of input String
Inputs

String | Text String to retrieve SubString from
Start | String index to start the SubString from
Length | Length of desired SubString
Outputs
Result Text String representing SubString from input String
Properties
None -

Usage

The Data Mapper String SubString function retrieves a portion of a source String as a SubString. Often, when mapping data, you may face limitations in terms of storage or differing application logic within the target context which requires you to map only a portion of selected input Strings. The SubString function allows you to map sections of input Strings by defining start position and length. To apply the String SubString transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using office_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<office>
 <file type="corporate">
  <ref>12345abcde</ref>
  <title>Smith and Mitchell</title>
 </file>
 <file type="individual">
  <ref>54321fghij</ref>
  <title>James Black</title>
 </file>
</office>

For our target schema we will be using office_target.xsd, inferred from the following XML:

Target XML Copy Code
<associates>
 <account reference="98765">
  <category>Organisation</category>
  <contact>Jane Johnson</contact>
 </account>
 <account reference="56789">
  <category>Corporate</category>
  <contact>Mary Simpson</contact>
 </account>
</associates>

The data models office files for an organisation. Here is the Data Mapper with Source and Target imported:

Data Mapper String Upper Function

Let's assume that we only want to map the numerical part of the "ref" item in the source, which represents the first 5 characters in the String. Drag the String SubString function from the Component Palette into the mapping area:

String SubString Component

String SubString Transform Added

The String SubString function takes three inputs and gives a String output. The String input should be connected to the source String you want to retrieve part of. The Start and Length inputs should be connected to numbers, for which we will use Constants. The output should be connected to the target item, which may be in the XML Writer or another mapping component if you need to apply further transformations.

Connect the SubString String input to the "ref" output in the XML Reader, and the SubString output to the "reference" item in the XML Writer.

String SubString Transform Mapped

Now we need to represent the Start and Length numbers, so drag 2 Constants from the Component Palette onto the Mapper. For each one, we need to right-click and choose Show Properties. For the first one, enter "start" as the Name, choose an integer Data Type from the drop-down list and enter 0 as the Value, so that we start the SubString at the beginning of the source String. Setting the name is not strictly necessary but it does help when working with the Mapper.

Start Constant Properties

For the second Constant, set "length" as the Name, an integer Data Type and 5 as the Value.

Length Constant Properties

Now you can see clearly which Constant is which without having to view the properties.

String SubString Constants Added

Now let's map the Constants. Connect the "start" Constant output to the Start input of the SubString function, and the "length" Constant output to the Length input.

String SubString Constants Connected

Finally let's connect the remaining input and output connections:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<associates>
 <account reference="12345">
  <category>corporate</category>
  <contact>Smith and Mitchell</contact>
 </account>
 <account reference="54321">
  <category>individual</category>
  <contact>James Black</contact>
 </account>
</associates>

The input item has been restricted to the first 5 characters as part of the mapping process. If the SubStrings you need are either at the start or end of an input String, you can alternatively use the Left and Right functions.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Left
Right

Values
Constant

Data Mapping
Combining String Functions


Trim
Data Mapping > Data Mapper Functions > By Category > String > Trim

Glossary Item Box

Function Name
 Trim
Category
 String
Icon
 Trim
Description
 Trim leading and trailing whitespace from an input String
Inputs
String Text String to trim whitespace from
Outputs
Result Text String trimmed with whitespace characters removed from the start and end
Properties
none -

Usage

The Data Mapper String Trim function returns an input String with any whitespace characters removed from the start and end. Since much XML data comes from unpredictable sources such as user input with a system, it is often necessary to trim whitespace characters during mapping, ensuring that the mapped data is ready for use and does not waste any unnecessary storage space. To apply the String Trim transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using review_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<product_reviews>
 <review>
  <product_id>123</product_id>
  <content>

    I thought this was a really excellent product.

  </content>
 </review>
 <review>
  <product_id>234</product_id>
  <content>

     I really hate this product.

  </content>
 </review>
</product_reviews>

We are intentionally including additional whitespace characters at the start and end of the content for demonstration. For our target schema we will be using review_target.xsd, inferred from the following XML:

Target XML Copy Code
<user_reviews>
 <review_item product="456">
  This is a wonderful item.
 </review_item>
 <review_item product="567">
  This item has good points and bad points.
 </review_item>
</user_reviews>

The data models feedback reviews for products. Here is the Data Mapper with Source and Target imported:

Data Mapper String Trim Function

Let's drag the String Trim function from the Component Palette into the mapping area:

String Trim Component

String Trim Transform Added

The String Trim function takes one input and gives one output. The String input should be connected to the source text String item to trim leading and trailing whitespace characters from. The String Trim function output should be connected to the target item in the XML Writer or another component. First connect the "content" item in the XML Reader to the String input of the Trim function:

Reader to Trim String Input

Next connect the Trim output to the Element Value item in the XML Writer:

Trim Output to Writer Input

Notice that we are mapping an element in the source XML to an element value in the target XML. The Mapper maps freely between elements, attributes and values.

Finally let's make the remaining input and output connections:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<user_reviews>
 <review_item product="123">I thought this was a really excellent product.</review_item>
 <review_item product="234">I really hate this product.</review_item>
</user_reviews>

The input element value has been mapped without the leading and trailing whitespace we had in the XML source within the element content. When text Strings come from varied sources such as text files and other data stores, it is common to end up with whitespace characters such as new lines, carriage returns and spaces being appended at one or both ends. For this reason the Trim function can save considerable time spent carrying out manual alterations. Trimming your Strings means that your mapped text is immediately ready for user display and other uses.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

TrimStart
TrimEnd

Data Mapping
Combining String Functions


TrimEnd
Data Mapping > Data Mapper Functions > By Category > String > TrimEnd

Glossary Item Box

Function Name
 Trim End
Category
 String
Icon
 Trim Start
Description
 Trim trailing whitespace from the end of an input String
Inputs
String Text String to trim trailing whitespace from
Outputs
Result Text String trimmed with whitespace characters removed from the end
Properties
none -

Usage

The Data Mapper String Trim End function returns an input String with any whitespace characters removed from the end. Since much XML data comes from unpredictable sources such as user input with a system, it is often necessary to trim whitespace characters during mapping, ensuring that the mapped data is ready for use and does not waste any unnecessary storage space. To apply the String Trim End transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using review_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<product_reviews>
 <review>
  <product_id>123</product_id>
  <content>

   I thought this was a really excellent product.

  </content>
 </review>
 <review>
  <product_id>234</product_id>
  <content>

   I really hate this product.

  </content>
 </review>
</product_reviews>

We are intentionally including additional whitespace characters around the the content for demonstration. For our target schema we will be using review_target.xsd, inferred from the following XML:

Target XML Copy Code
<user_reviews>
 <review_item product="456">
  This is a wonderful item.
 </review_item>
 <review_item product="567">
  This item has good points and bad points.
 </review_item>
</user_reviews>

The data models feedback reviews for products. Here is the Data Mapper with Source and Target imported:

Data Mapper String Trim End Function

Let's drag the String Trim End function from the Component Palette into the mapping area:

String Trim End Component

String Trim End Transform Added

The String Trim End function takes one input and gives one output. The String input should be connected to the source text String item to trim trailing whitespace characters from. The String Trim End function output should be connected to the target item in the XML Writer or another component. First connect the "content" item in the XML Reader to the String input of the Trim End function:

Reader to Trim End String Input

Next connect the Trim End output to the Element Value item in the XML Reader:

Trim End Output to Writer Input

Notice that we are mapping an element in the source XML to an element value in the target XML. The Mapper maps freely between elements, attributes and values.

Finally let's make the remaining input and output connections:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<user_reviews>
    <review_item product="123">

   I thought this was a really excellent product.</review_item>
    <review_item product="234">

   I really hate this product.</review_item>
</user_reviews>

The input element value has been mapped without the trailing whitespace we had on the right in the XML source within the element content. Notice that the whitespace from the start of the input String has been preserved, with whitespace only removed from the right hand side. If you need whitespace trimmed from the left, use the Trim Start function or the Trim function if you need it trimmed from both ends.

When text Strings come from varied sources such as text files and other data stores, it is common to end up with whitespace characters such as new lines, carriage returns and spaces being appended at one or both ends. For this reason the Trim functions can save considerable time spent carrying out manual alterations. Trimming your Strings means that your mapped text is immediately ready for user display and other uses.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Trim
TrimStart

Data Mapping
Combining String Functions


TrimStart
Data Mapping > Data Mapper Functions > By Category > String > TrimStart

Glossary Item Box

Function Name
 Trim Start
Category
 String
Icon
 Trim Start
Description
 Trim leading whitespace from the start of an input String
Inputs
String Text String to trim leading whitespace from
Outputs
Result Text String trimmed with whitespace characters removed from the start
Properties
none -

Usage

The Data Mapper String Trim Start function returns an input String with any whitespace characters removed from the start. Since much XML data comes from unpredictable sources such as user input with a system, it is often necessary to trim whitespace characters during mapping, ensuring that the mapped data is ready for use and does not waste any unnecessary storage space. To apply the String Trim Start transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using review_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<product_reviews>
 <review>
  <product_id>123</product_id>
  <content>

      I thought this was a really excellent product.

  </content>
 </review>
 <review>
  <product_id>234</product_id>
  <content>

   I really hate this product.

  </content>
 </review>
</product_reviews>

We are intentionally including additional whitespace characters around the content for demonstration. For our target schema we will be using review_target.xsd, inferred from the following XML:

Target XML Copy Code
<user_reviews>
 <review_item product="456">
  This is a wonderful item.
 </review_item>
 <review_item product="567">
  This item has good points and bad points.
 </review_item>
</user_reviews>

The data models feedback reviews for products. Here is the Data Mapper with Source and Target imported:

Data Mapper String Trim Start Function

Let's drag the String Trim Start function from the Component Palette into the mapping area:

String Trim Start Component

String Trim Start Transform Added

The String Trim Start function takes one input and gives one output. The String input should be connected to the source text String item to trim leading whitespace characters from. The String Trim Start function output should be connected to the target item in the XML Writer or another component. First connect the "content" item in the XML Reader to the String input of the Trim Start function:

Reader to Trim Start String Input

Next connect the Trim Start output to the Element Value item in the XML Reader:

Trim Start Output to Writer Input

Notice that we are mapping an element in the source XML to an element value in the target XML. The Mapper maps freely between elements, attributes and values.

Finally let's make the remaining input and output connections:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<user_reviews>
    <review_item product="123">I thought this was a really excellent product.

  </review_item>
    <review_item product="234">I really hate this product.
  </review_item>
</user_reviews>

The input element value has been mapped without the leading whitespace we had on the left in the XML source within the element content. Notice that the whitespace from the end of the input String has been preserved, with whitespace only removed from the left side. If you need whitespace trimmed from the right, use the Trim End function or the Trim function if you need it trimmed from both ends.

When text Strings come from varied sources such as text files and other data stores, it is common to end up with whitespace characters such as new lines, carriage returns and spaces being appended at one or both ends. For this reason the Trim functions can save considerable time spent carrying out manual alterations. Trimming your Strings means that your mapped text is immediately ready for user display and other uses.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Trim
TrimEnd

Data Mapping
Combining String Functions


Upper
Data Mapping > Data Mapper Functions > By Category > String > Upper

Glossary Item Box

Function Name
 Upper
Category
 String
Icon
 Upper
Description
 Convert text string characters to upper case
Inputs
String Text String to convert to upper case
Outputs
Result Text String with all characters converted to upper case
Properties
Culture Set culture for language data

Usage

The Data Mapper String Upper function converts text String characters to upper case. If your source XML contains characters you wish to be stored entirely in upper case within the target, you can apply this transform when mapping the data. Whether the characters are within element content or within attribute values, the transform will execute on them. To apply the String Upper transform function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using comment_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<comment contributor="mary">
 I really like this
</comment>

For our target schema we will be using comment_target.xsd, inferred from the following XML:

Target XML Copy Code
<user_comment>
 <user>john</user>
 <content>I absolutely love this</content>
</user_comment>

The data models user comments for a product or website. Here is the Data Mapper with Source and Target imported:

Data Mapper String Upper Function

Let's drag the String Upper function from the Component Palette into the mapping area:

String Upper Component

String Upper Transform Added

The String Upper function takes a single input and gives a single output. The input should be connected to the source text String item to be converted to upper case. The output should be connected to the target item. In this case we are mapping from an attribute to an element:

String Upper Transform Mapped

We map the "contributor" attribute in the XML Reader to the "user" element in the XML Writer, converting to upper case at the same time. Finally let's connect the remaining input and output connections:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<user_comment>
 <user>MARY</user>
 <content>
  I really like this
 </content>
</user_comment>

The input attribute value has been converted to upper case as part of the mapping process.

Properties

If you happen to be dealing with different languages, the Upper function can also be tailored to suit. Within the mapping area, right-click the Upper function and choose Show Properties. You can choose languages from the Culture drop-down list and the Mapper will select upper case characters accordingly.

Choosing a Language for the Upper Function

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

Lower

Data Mapping
Combining String Functions


Combine
Send Feedback
Data Mapping > Data Mapper Functions > By Category > Set > Combine

Glossary Item Box

Function Name
 Combine
Category
 Set
Icon
 CodeToChar
Description
 Combines a number of sequences into a single sequence.
Inputs
Value N The input sequence to be combined.
The number of input values is dynamic
Outputs
Sequence A sequence containing all the values in all the input Values.
Properties
None -

Usage

Combines the values from all the inputs into a single sequence. All the input values must be of the same type (or castable to a common type).

The type of the output sequence is derived from a type common to all the inputs.

The number of input values can be changed to suite the usage.
Example 1

The following example combines 5 constant values into a sequence of strings.

The result would look like

A
B
C
D
E

Example 2

The "Combine 1" function creates the following sequence

1
2
3

The input values presented to "Combine 2" are

Input Name | Value
Value 1 | A
Value 2 | B
Value 3 | 1,2,3
Value 4 | D
Value 5 | E

The output sequence from "Combine 2" is

A
B
1
2
3
D
E

Note: the input sequence (1,2,3) is flattened in the output.


Distinct
Data Mapping > Data Mapper Functions > By Category > Set > Distinct

Glossary Item Box

Function Name
 Distinct
Category
 Set
Icon
 Distinct
Description
 Map only unique values
Inputs

Context | Context in which the values should be unique
Value | Values which must be unique within the context in order to be mapped
Outputs
Distinct Values Those values that are unique within the context.
The output dynamically takes its type from the input 'Value'.
Properties
None -

Usage

The Data Mapper Set Distinct function allows you to ensure only items that are unique within a certain context are mapped. Often, data sources contain duplicate values, sometimes intentionally and sometimes due to data corruption. If your target application requires only unique values of a particular item within a specific context, you can use the Distinct function. To apply the Set Distinct function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using clubs_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<sport_clubs>
 <club>
  <name>New Town Football Club</name>
  <member>
   <active>Yes</active>
   <member_name>Chris Black</member_name>
   <member_since>2005</member_since>
   <won>Cup 2007</won>
   <won>League 2009</won>
   <won>Cup 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Jim Thomson</member_name>
   <member_since>2003</member_since>
   <won>League 2010</won>
  </member>
  <member>
   <active>No</active>
   <member_name>Barry Jones</member_name>
   <member_since>1996</member_since>
   <won>League 1999</won>
   <won>Cup 1999</won>
   <won>League 2000</won>
  </member>
 </club>
 <club>
  <name>City Netball Team</name>
  <member>
   <active>No</active>
   <member_name>Jacqueline Johnson</member_name>
   <member_since>1999</member_since>
   <won>National Championship 2001</won>
   <won>National Championship 2001</won>
   <won>Regional Championship 2002</won>
   <won>National Championship 2002</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Joanne Smith</member_name>
   <member_since>2005</member_since>
   <won>Regional Championship 2007</won>
   <won>National championship 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Mary Owens</member_name>
   <member_since>2007</member_since>
   <won>National Championship 2008</won>
  </member>
 </club>
</sport_clubs>

For our target schema we will be using clubs_target.xsd:

The data models sporting clubs and their members. Some of the elements can appear multiple times. Notice that, in the source data, a couple of the "won" elements have duplicate values within their parent "member" elements. Let's assume that we want to eliminate this duplication when we map the data. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Set Distinct function from the Component Palette into the mapping area:

Set Distinct Component

Distinct Transform Added

The Set Distinct function takes two inputs, representing the value and the context in which it should be unique. The Value input should be connected to the item you only want to map unique instances of. The Context item should be connected to the item you want the values to be unique within. In this case, we want the "won" items to be unique within each "member" element. This means that the same "won" value can appear more than once within a single "club" element or within the document as a whole, but not within a single "member" element - we only want to list each title the member has won once for their entry in the data. The Context input is often connected to the parent of the unique value as in this case. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper.

Connect the Context input of the Distinct function to the "member" output in the XML Reader and the Value input to the "won" output:

Reader to Distinct

Now we can connect the Distinct output to the "title" input in the XML Writer. We connect it to the "title" input because that is the value we are mapping only unique values of.

Reader and Writer to Distinct

Now items will only be mapped if they are not duplicates. Finally, connect the remaining inputs and outputs. Remember to map "member" to "player". Although we have used the item as a reference for the Distinct function, we have not yet mapped it.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<clubs>
 <team t_name="New Town Football Club">
  <player p_name="Chris Black" is_active="Yes">
   <joined>2005</joined>
   <title>Cup 2007</title>
   <title>League 2009</title>
  </player>
  <player p_name="Jim Thomson" is_active="Yes">
   <joined>2003</joined>
   <title>League 2010</title>
  </player>
  <player p_name="Barry Jones" is_active="No">
   <joined>1996</joined>
   <title>League 1999</title>
   <title>Cup 1999</title>
   <title>League 2000</title>
  </player>
 </team>
 <team t_name="City Netball Team">
  <player p_name="Jacqueline Johnson" is_active="No">
   <joined>1999</joined>
   <title>National Championship 2001</title>
   <title>Regional Championship 2002</title>
   <title>National Championship 2002</title>
  </player>
  <player p_name="Joanne Smith" is_active="Yes">
   <joined>2005</joined>
   <title>Regional Championship 2007</title>
   <title>National championship 2007</title>
  </player>
  <player p_name="Mary Owens" is_active="Yes">
   <joined>2007</joined>
   <title>National Championship 2008</title>
  </player>
 </team>
</clubs>

The "player" elements only contain unique instances of the "title" element, as the duplicates have not been mapped.

You may find the Distinct function particularly useful in conjunction with other Set and Aggregate functions such as Sort.

See Also

Sort

Data Mapping
Using Set Functions
Using Aggregate Functions


Filter
Data Mapping > Data Mapper Functions > By Category > Set > Filter

Glossary Item Box

Function Name
 Filter
Category
 Set
Icon
 Filter
Description
 Filter mapped nodes based on a condition
Inputs

Nodes | Nodes to filter
Bool | Boolean value indicating whether the node meets a condition
Outputs
Result Filtered nodes representing only those returning true results after conditional test.
The output takes its type from the input Nodes, see Dynamic Output Values.
Properties
None -

Usage

The Data Mapper Set Filter function allows you to restrict the nodes mapped using a conditional test. Filtering allows you to only map data items that meet a certain condition. By filtering, you can make sure you map only those input values you want mapped, for example those with a particular value, or range of values, within a child element or attribute. To apply the Set Filter function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using clubs_source.xsd, an XML Schema Definition and the following XML data:

Source XML Copy Code
<sport_clubs>
 <club>
  <name>New Town Football Club</name>
  <member>
   <active>Yes</active>
   <member_name>Chris Black</member_name>
   <member_since>2005</member_since>
   <won>League 2009</won>
   <won>Cup 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Jim Thomson</member_name>
   <member_since>2003</member_since>
   <won>League 2010</won>
  </member>
  <member>
   <active>No</active>
   <member_name>Barry Jones</member_name>
   <member_since>1996</member_since>
   <won>League 1999</won>
   <won>Cup 1999</won>
   <won>League 2000</won>
  </member>
 </club>
 <club>
  <name>City Netball Team</name>
  <member>
   <active>No</active>
   <member_name>Jacqueline Johnson</member_name>
   <member_since>1999</member_since>
   <won>National Championship 2001</won>
   <won>Regional Championship 2002</won>
   <won>National Championship 2002</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Joanne Smith</member_name>
   <member_since>2005</member_since>
   <won>Regional Championship 2007</won>
   <won>National championship 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Mary Owens</member_name>
   <member_since>2007</member_since>
   <won>National Championship 2008</won>
  </member>
 </club>
</sport_clubs>

For our target schema we will be using clubs_target.xsd

The data models sporting clubs and their members. Some of the elements can appear multiple times. Let's assume that we only want to map active members within each club. To achieve this, we will need to test the "active" value for each "member" element to determine whether it reads "Yes" or not. We will use an Equal function and Constant Value in conjunction with the Filter component. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Set Filter function from the Component Palette into the mapping area:

Set Filter Component

The Set Filter function takes two inputs, representing the nodes to filter and the boolean value.

The filter component initially has not output node, this is dynamically created based on what the Nodes input is connected to.

The Nodes input should be connected to the source item you want to filter, and the Bool input should be connected to the output of the conditional test or a boolean value, which will be either true or false. The output comprises the input nodes that meet the condition, and should be connected to the target item, whether an item in the XML Writer or another component in the Mapper.

Before we can connect our Filter function, we need to carry out the conditional test. Drag an Equal function from the Comparator section onto the Mapper. Connect the "active" output in the XML Reader to the Value 1 input in the Equal function.

Now we need to define the value we want the "active" item to match, so drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Choose String from the Data Type drop-down list and enter "Yes" as the value.

Connect the Constant output to the Value 2 input in the Equal function.

Connect the Result output of the Equal function to the Bool input of the Filter function.

Now connect the Nodes input of the Filter function to the "member" output in the XML Reader, since this is the item we want to filter.

Notice that as you do this the output connection points on the Filter are created. These are the filtered values.

Now the Filter output is only going to contain those "member" elements whose "active" value matched the "Yes" Constant. Connect the Filter output to the "player" input in the XML Writer.

Finally, connect the remaining inputs and outputs.

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<clubs>
 <team t_name="New Town Football Club">
  <player p_name="Chris Black" is_active="Yes">
   <joined>2005</joined>
   <title>League 2009</title>
   <title>Cup 2007</title>
  </player>
  <player p_name="Jim Thomson" is_active="Yes">
   <joined>2003</joined>
   <title>League 2010</title>
  </player>
 </team>
 <team t_name="City Netball Team">
  <player p_name="Joanne Smith" is_active="Yes">
   <joined>2005</joined>
   <title>Regional Championship 2007</title>
   <title>National championship 2007</title>
  </player>
  <player p_name="Mary Owens" is_active="Yes">
   <joined>2007</joined>
   <title>National Championship 2008</title>
  </player>
 </team>
</clubs>

The only "player" items in the output are those with "Yes" as their "is_active" value. It is common when mapping data to cut out redundant items, perhaps when upgrading systems and minimizing on storage resources.

Since the Filter function receives a Boolean input, you can use it in conjunction with the range of Comparator functions, allowing you to filter data on various conditions.
The Filter function reads only the first value it receives through the Bool input for each Nodes input context.

See Also

Data Mapping
Using Set Functions
Getting Started
Dynamic Output Values

Comparator
Equals

Values
Constant


First
Data Mapping > Data Mapper Functions > By Category > Set > First

Glossary Item Box

Function Name
 First
Category
 Set
Icon
 First
Description
 Map only the first in a sequence of values
Inputs
Nodes Sequence to map the first value of
Outputs
Result First in the specified input sequence
Properties
None -

Usage

The Data Mapper Set First function allows you to map the first in a set of sibling items in your XML source. There are many possible reasons for mapping only the first in a set of data values. For example, you may be subject to storage limitations in your target application, or may be sorting your data and mapping the first in a set of resulting values. To apply the Set First function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area.

For this example we are using clubs_source.xsd, an XML Schema Definition

The following source XML will be used:

Source XML Copy Code
<sport_clubs>
 <club>
  <name>New Town Football Club</name>
  <member>
   <active>Yes</active>
   <member_name>Chris Black</member_name>
   <member_since>2005</member_since>
   <won>League 2009</won>
   <won>Cup 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Jim Thomson</member_name>
   <member_since>2003</member_since>
   <won>League 2010</won>
  </member>
  <member>
   <active>No</active>
   <member_name>Barry Jones</member_name>
   <member_since>1996</member_since>
   <won>League 1999</won>
   <won>Cup 1999</won>
   <won>League 2000</won>
  </member>
 </club>
 <club>
  <name>City Netball Team</name>
  <member>
   <active>No</active>
   <member_name>Jacqueline Johnson</member_name>
   <member_since>1999</member_since>
   <won>National Championship 2001</won>
   <won>Regional Championship 2002</won>
   <won>National Championship 2002</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Joanne Smith</member_name>
   <member_since>2005</member_since>
   <won>Regional Championship 2007</won>
   <won>National championship 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Mary Owens</member_name>
   <member_since>2007</member_since>
   <won>National Championship 2008</won>
  </member>
 </club>
</sport_clubs>

For our target schema we will be using clubs_target.xsd

The data models sporting clubs and their members. Some of the elements can appear multiple times.

Let's assume that we want the member from each club that has been their the longest. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Set First function from the Component Palette into the mapping area:

Set First Component

We will use a sort to get the member with the longest time at the club at the top, then we will take only the first entry for each club.

So add a 'Sort' and a 'First' sub component to the transform.

We can now connect the 'Xml source->member' to the 'Sort' functions 'Nodes' input, notice when you do this the the Sort functions output nodes appear.

You can now use the Sort output 'member' to feed into the 'First' components 'Nodes' input, again the First functions outputs are created when you do this.

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<clubs>
  <team t_name="New Town Football Club">
    <player p_name="Barry Jones" is_active="No">
      <joined>1996</joined>
      <title>League 1999</title>
      <title>Cup 1999</title>
      <title>League 2000</title>
    </player>
  </team>
  <team t_name="City Netball Team">
    <player p_name="Jacqueline Johnson" is_active="No">
      <joined>1999</joined>
      <title>National Championship 2001</title>
      <title>Regional Championship 2002</title>
      <title>National Championship 2002</title>
    </player>
  </team>
</clubs>

The longest serving player for each team is now shown.

If the First function receives an empty input sequence, it will output nothing.

See Also

Last
GetAt
Filter
Sort

Data Mapping
Using Set Functions


GetAt
Data Mapping > Data Mapper Functions > By Category > Set > GetAt

Glossary Item Box

Function Name
 Get At
Category
 Set
Icon
 Get At
Description
 Get the value at a specified index within a sequence
Inputs

Nodes | Sequence to retrieve output from
Index | Index of value to retrieve within nodes (zero-based)
Outputs
Result Item at given index within nodes sequence.
The output takes its type from the input Nodes, see Dynamic Output Values.
Properties
None -

Usage

The Data Mapper Set Get At function allows you to map items at a particular index within a set of nodes in your XML source. As with many of the Set functions, you may find the Get At function particularly useful when used with other functions. For example, the Get At function in conjunction with the Sort function allows you to retrieve items at particular points in a sorted set. To apply the Set Get At function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using clubs_source.xsd and the following XML source:

Source XML Copy Code
<sport_clubs>
 <club>
  <name>New Town Football Club</name>
  <member>
   <active>Yes</active>
   <member_name>Chris Black</member_name>
   <member_since>2005</member_since>
   <won>League 2009</won>
   <won>Cup 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Jim Thomson</member_name>
   <member_since>2003</member_since>
   <won>League 2010</won>
  </member>
  <member>
   <active>No</active>
   <member_name>Barry Jones</member_name>
   <member_since>1996</member_since>
   <won>League 1999</won>
   <won>Cup 1999</won>
   <won>League 2000</won>
  </member>
 </club>
 <club>
  <name>City Netball Team</name>
  <member>
   <active>No</active>
   <member_name>Jacqueline Johnson</member_name>
   <member_since>1999</member_since>
   <won>National Championship 2001</won>
   <won>Regional Championship 2002</won>
   <won>National Championship 2002</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Joanne Smith</member_name>
   <member_since>2005</member_since>
   <won>Regional Championship 2007</won>
   <won>National championship 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Mary Owens</member_name>
   <member_since>2007</member_since>
   <won>National Championship 2008</won>
  </member>
 </club>
</sport_clubs>

For our target schema we will be using clubs_target.xsd

The data models sporting clubs and their members. Some of the elements can appear multiple times. Let's assume that, for each "club" element, we want to map the "member" with the second earliest "member_since" date value, i.e. the second longest standing member. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Set Get At function from the Component Palette into the mapping area:

Set Get At Component

Get At Transform Added

The Set 'Get At' function takes two inputs, representing the nodes to retrieve the item from and the index to retrieve it from. The Nodes input should be connected to the item you are looking to map an instance of, while the Index input should be connected to a numerical indicator of the index you need.

Before we can use the 'Get At' function, we need to sort the "member" items on their join dates.

Drag a Sort function onto the Mapper, connecting its Nodes input to the "member" output in the XML Reader and its Sort Key input to the "member_since" output, notice as you do this its output connection point is created and mirrors the input "member" data.

Now the Sort Values output contains the "member" items for a "club" sorted according to join date.

Connecting the output from the "Sort" to the 'Nodes' input on the "Get At" will cause the output connection point on the "Get At" to be created (see Dynamic Output Values).

The "Get At" output should be connected to the "player" connection point on the XML Writer.

Reader to Sort

Now we need to represent the second position within the sorted sequence, since we want the second earliest "member" item. Drag a Constant Value from the Data Type section onto the Mapper and right-click it, choosing Show Properties. Enter an integer type from the Data Type drop-down list and the number 1 as the Value, since we are working with a zero-based index, so the second position is at index 1.

Connect the Constant output to the Index input in the Get At function.

Now we can connect the Get At output to the "player" input in the XML Writer.

Finally let's connect the remaining input and output connections. Remember to map "member_since" to "joined" - although we have used the item as a reference, we have not yet mapped it from Reader to Writer.

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<clubs>
 <team t_name="New Town Football Club">
  <player p_name="Jim Thomson" is_active="Yes">
  <joined>2003</joined>
  <title>League 2010</title>
  </player>
 </team>
 <team t_name="City Netball Team">
  <player p_name="Joanne Smith" is_active="Yes">
   <joined>2005</joined>
   <title>Regional Championship 2007</title>
   <title>National championship 2007</title>
  </player>
 </team>
</clubs>

Each "team" element only contains a single "player" element - the "player" with the second earliest "joined" value from the source. Since the Get At function takes a numerical input representing the index value you are interested in, this input can come from a variety of other sources. Although we used a Constant to represent it here, you may need to determine the index you require using other functions, such as those from the Maths and Aggregate sections.

In order to use the Get At function successfully, you should make sure you only feed it index values that are actually within the range of values in your source data.

See Also

Sort
Position
First
Last

Data Mapping
Using Set Functions
Dynamic Output Values


GroupBy
Send Feedback
Data Mapping > Data Mapper Functions > By Category > Set > GroupBy

Glossary Item Box

Function Name
 GroupBy
Category
 Set
Icon
Description
 Groups a number of records according to one or more fields
Inputs

Nodes | The nodes to be grouped
Group By Value x | The values to group the Nodes by (dynamic, right click to add more)
Outputs

Group | An entry for each distinct set of 'Group By Value x' values
Group By Value x | The distinct grouping values for this parent 'Group'
Row | All the input 'Node' entries that have matching 'Group By Value x' values
Properties
None -

Usage

The Data Mapper Group By function makes it possible to impose a hierarchy over data delivered in a flat format. This is typically most useful when working with CSV data, but can be used on any data source. The function works by taking an input set of nodes, the values that the nodes are to be grouped by are then specified by connecting values to the 'Group By Value' inputs. If more than one value is to be grouped by then additional entries can be added by using the right click context menu. All the input nodes are then read grouped according to the values in the 'Group By Value' inputs. The result is a Group entry for each distinct set of 'Group By Value' values, within this are all the values being grouped, and all the rows that match the group values.

Example 1 - building a single level hierarchy

Given the following CSV data.

Source Data Copy Code
Customer ID,    Customer Name,  Order ID,   Order Price
1,              Fred,           100,        0.55
1,              Fred,           101,        3.48
2,              Jane,           102,        2.10
2,              Jane,           103,        1.93

If we wanted to represent it as a hierarchical structure in XML, then we would first need to group the values 'Customer ID' & 'Customer Name'.

This would give us give us a Group entry for each distinct 'Customer ID', 'Customer Name' value in the source data, and a Row entry for every source node that has the corresponding 'Customer ID', 'Customer Name' values. This allows us to construct the simple hierarchy.

Resulting XML Copy Code
<!--Created by Liquid Data Mapper Libraries (www.liquid-technologies.com) for Liquid Technologies Ltd -->
<Breakfast>
    <Customer ID="1">
        <Name>Fred</Name>
        <Order ID="100">
            <Price>0.55</Price>
        </Order>
        <Order ID="101">
            <Price>3.48</Price>
        </Order>
    </Customer>
    <Customer ID="2">
        <Name>Jane</Name>
        <Order ID="102">
            <Price>2.10</Price>
        </Order>
        <Order ID="103">
            <Price>1.93</Price>
        </Order>
    </Customer>
</Breakfast>

Example 2 - building a multi level hierarchy

If the source data contains detail about each item in an order then we can create a second level in the hierarchy.

Source Data Copy Code
Customer ID,    Customer Name,  Order ID,   Item Description,   Item Price
1,              Fred,           100,        Bread,              0.35
1,              Fred,           100,        Jam,                0.20
1,              Fred,           101,        Pancakes,           1.99
1,              Fred,           101,        Bacon,              0.99
1,              Fred,           101,        Syrup,              0.50
2,              Jane,           102,        Granola,            1.35
2,              Jane,           102,        Milk,               0.75
2,              Jane,           103,        Bread,              0.35
2,              Jane,           103,        Bacon,              0.99
2,              Jane,           103,        Sausage,            0.59

We still need to group the values 'Customer ID' & 'Customer Name'. This gives us all the orders for each customer, we then need to group the remaining entries by Order ID to give us the items in each order.

The resulting XML is a hierarchical model of the data.

Resulting XML Copy Code
<Breakfast>
    <Customer ID="1">
        <Name>Fred</Name>
        <Order ID="100">
            <Item>
                <Description>Bread</Description>
                <Price>0.35</Price>
            </Item>
            <Item>
                <Description>Jam</Description>
                <Price>0.20</Price>
            </Item>
        </Order>
        <Order ID="101">
            <Item>
                <Description>Pancakes</Description>
                <Price>1.99</Price>
            </Item>
            <Item>
                <Description>Bacon</Description>
                <Price>0.99</Price>
            </Item>
            <Item>
                <Description>Syrup</Description>
                <Price>0.50</Price>
            </Item>
        </Order>
    </Customer>
    <Customer ID="2">
        <Name>Jane</Name>
        <Order ID="102">
            <Item>
                <Description>Granola</Description>
                <Price>1.35</Price>
            </Item>
            <Item>
                <Description>Milk</Description>
                <Price>0.75</Price>
            </Item>
        </Order>
        <Order ID="103">
            <Item>
                <Description>Bread</Description>
                <Price>0.35</Price>
            </Item>
            <Item>
                <Description>Bacon</Description>
                <Price>0.99</Price>
            </Item>
            <Item>
                <Description>Sausage</Description>
                <Price>0.59</Price>
            </Item>
        </Order>
    </Customer>
</Breakfast>


Last
Data Mapping > Data Mapper Functions > By Category > Set > Last

Glossary Item Box

Function Name
 Last
Category
 Set
Icon
 Last
Description
 Map only the last in a sequence of values
Inputs
Nodes Sequence to map the last value of
Outputs
Result Last in the specified input sequence
Properties
None -

Usage

The Data Mapper Set Last function allows you to map the last in a set of sibling items in your XML source. There are many possible reasons for mapping only the last in a set of data values. For example, you may be subject to storage limitations in your target application, or may be sorting your data and mapping the last in a set of resulting values. To apply the Set last function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area.

For this example we are using clubs_source.xsd, an XML Schema Definition

The following source XML will be used:

Source XML Copy Code
<sport_clubs>
 <club>
  <name>New Town Football Club</name>
  <member>
   <active>Yes</active>
   <member_name>Chris Black</member_name>
   <member_since>2005</member_since>
   <won>League 2009</won>
   <won>Cup 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Jim Thomson</member_name>
   <member_since>2003</member_since>
   <won>League 2010</won>
  </member>
  <member>
   <active>No</active>
   <member_name>Barry Jones</member_name>
   <member_since>1996</member_since>
   <won>League 1999</won>
   <won>Cup 1999</won>
   <won>League 2000</won>
  </member>
 </club>
 <club>
  <name>City Netball Team</name>
  <member>
   <active>No</active>
   <member_name>Jacqueline Johnson</member_name>
   <member_since>1999</member_since>
   <won>National Championship 2001</won>
   <won>Regional Championship 2002</won>
   <won>National Championship 2002</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Joanne Smith</member_name>
   <member_since>2005</member_since>
   <won>Regional Championship 2007</won>
   <won>National championship 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Mary Owens</member_name>
   <member_since>2007</member_since>
   <won>National Championship 2008</won>
  </member>
 </club>
</sport_clubs>

For our target schema we will be using clubs_target.xsd

The data models sporting clubs and their members. Some of the elements can appear multiple times.

Let's assume that we want the member from each club that has been their the longest. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Set Last function from the Component Palette into the mapping area:

Set Last Component

We will use a sort to get the member with the longest time at the club at the top, then we will take only the last entry for each club.

So add a 'Sort' and a 'Last' sub component to the transform.

We can now connect the 'Xml source->member' to the 'Sort' functions 'Nodes' input, notice when you do this the the Sort functions output nodes appear.

You can now use the Sort output 'member' to feed into the 'Last' components 'Nodes' input, again the Last functions outputs are created when you do this.

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<clubs>
  <team t_name="New Town Football Club">
    <player p_name="Chris Black" is_active="Yes">
      <joined>2005</joined>
      <title>League 2009</title>
      <title>Cup 2007</title>
    </player>
  </team>
  <team t_name="City Netball Team">
    <player p_name="Mary Owens" is_active="Yes">
      <joined>2007</joined>
      <title>National Championship 2008</title>
    </player>
  </team>
</clubs>

The longest serving player for each team is now shown.

If the Last function receives an empty input sequence, it will output nothing.

See Also

First

Data Mapping
Using Set Functions


Position
Data Mapping > Data Mapper Functions > By Category > Set > Position

Glossary Item Box

Function Name
 Position
Category
 Set
Icon
 Position
Description
 Return the index of the current item within its containing sequence
Inputs
Item Item to retrieve index of
Outputs
Index Index of the item within its sequence (zero-based)
Properties
None -

Usage

The Data Mapper Set Position function allows you to retrieve the index of an item within its sequence. As with many of the mapping functions, the Position component is often most useful in conjunction with other functions. To apply the Set Position function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using clubs_source.xsd:

Source XML Copy Code
<sport_clubs>
 <club>
  <name>New Town Football Club</name>
  <member>
   <active>Yes</active>
   <member_name>Chris Black</member_name>
   <member_since>2005</member_since>
   <won>League 2009</won>
   <won>Cup 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Jim Thomson</member_name>
   <member_since>2003</member_since>
   <won>League 2010</won>
  </member>
  <member>
   <active>No</active>
   <member_name>Barry Jones</member_name>
   <member_since>1996</member_since>
   <won>League 1999</won>
   <won>Cup 1999</won>
   <won>League 2000</won>
  </member>
 </club>
 <club>
  <name>City Netball Team</name>
  <member>
   <active>No</active>
   <member_name>Jacqueline Johnson</member_name>
   <member_since>1999</member_since>
   <won>National Championship 2001</won>
   <won>Regional Championship 2002</won>
   <won>National Championship 2002</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Joanne Smith</member_name>
   <member_since>2005</member_since>
   <won>Regional Championship 2007</won>
   <won>National championship 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Mary Owens</member_name>
   <member_since>2007</member_since>
   <won>National Championship 2008</won>
  </member>
 </club>
</sport_clubs>

For our target schema we will be using clubs_alt_target.xsd:

The data models sporting clubs and their members. Some of the elements can appear multiple times. Notice that the target XML has an item that is not present in the source: the "memb_num" attribute of the "player" element. Let's assume that this is a unique member number within each club. We will need to generate this number for each member while mapping the data. To assign the numbers in a sensible fashion, we will give integer values to each "member", starting at 1 and assigning the numbers in order of the member's join date, so that the oldest member has the smallest number and so on. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Set Position function from the Component Palette into the mapping area:

Set Position Component

Position Function Added

The Position function takes one input 'Nodes', when this is set the output values are created, but before we do that let add a Sort function and connect it so it sorts the members on there joining date.

Reader to Sort

We can now connect the sorted members to the position 'Nodes' input. When this connection is made the Position function outputs are created, note that an additional index value is added to the members data.

Position to Add

Now we have access to the position of each "member" within its parent element, so we can use this to assign member numbers in join date order. However, the position uses a zero-based index, and we want our member numbers to start at 1 rather than zero. Let's add one to each position number to arrive at the member number in each case. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Choose an integer from the Data Type drop-down list and enter the number 1 as the Value.

Now drag an Add function from the Maths section onto the Mapper. Connect its first input to the Position function output and its second input to the Constant output.

Connect the output of the Add function to the "memb_num" input in the XML Writer. The members in each club will now have their own unique numbers starting at one.

Add to Writer

Finally let's connect the remaining input and output connections. Remember to map "member_since" to "joined" - although we have used the item as a reference, we have not yet mapped it from Reader to Writer.

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<clubs>
 <team t_name="New Town Football Club">
  <player p_name="Barry Jones" is_active="No" memb_num="1">
   <joined>1996</joined>
   <title>League 1999</title>
   <title>Cup 1999</title>
   <title>League 2000</title>
  </player>
  <player p_name="Jim Thomson" is_active="Yes" memb_num="2">
   <joined>2003</joined>
   <title>League 2010</title>
  </player>
  <player p_name="Chris Black" is_active="Yes" memb_num="3">
   <joined>2005</joined>
   <title>Cup 2007</title>
   <title>League 2009</title>
  </player>
 </team>
 <team t_name="City Netball Team">
   <player p_name="Jacqueline Johnson" is_active="No" memb_num="1">
    <joined>1999</joined>
    <title>National Championship 2001</title>
    <title>Regional Championship 2002</title>
    <title>National Championship 2002</title>
   </player>
   <player p_name="Joanne Smith" is_active="Yes" memb_num="2">
    <joined>2005</joined>
    <title>Regional Championship 2007</title>
    <title>National championship 2007</title>
   </player>
   <player p_name="Mary Owens" is_active="Yes" memb_num="3">
    <joined>2007</joined>
    <title>National Championship 2008</title>
   </player>
  </team>
</clubs>

Each "player" has a "memb_num" attribute, with the number a member has reflecting their order of joining. The oldest players for each team have the number 1, with more recent players assigned ascending numbers.

Here we are using the Position value as a reference for assigning another value within the data. However, in many cases you may find the Position function useful as input to other functions, rather than just as a value in itself.

See Also

GetAt
Sort

Data Mapping
Using Set Functions


Sort
Data Mapping > Data Mapper Functions > By Category > Set > Sort

Glossary Item Box

Function Name
 Sort
Category
 Set
Icon
 Sort
Description
 Sort input values
Inputs

Nodes | Nodes to sort
Sort Key | Value to sort nodes on
Outputs
Sort Values

Nodes in sorted order.
The output takes its type from the input Nodes, see Dynamic Output Values.
Properties
None -

Usage

The Data Mapper Set Sort function allows you to sort input items on a value of your choice. You can sort items within a specified context, whether the sort key is numerical or textual. To apply the Set Sort function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using clubs_source.xsd, and the following XML source:

Source XML Copy Code
<sport_clubs>
 <club>
  <name>New Town Football Club</name>
  <member>
   <active>Yes</active>
   <member_name>Chris Black</member_name>
   <member_since>2005</member_since>
   <won>League 2009</won>
   <won>Cup 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Jim Thomson</member_name>
   <member_since>2003</member_since>
   <won>League 2010</won>
  </member>
  <member>
   <active>No</active>
   <member_name>Barry Jones</member_name>
   <member_since>1996</member_since>
   <won>League 1999</won>
   <won>Cup 1999</won>
   <won>League 2000</won>
  </member>
 </club>
 <club>
  <name>City Netball Team</name>
  <member>
   <active>No</active>
   <member_name>Jacqueline Johnson</member_name>
   <member_since>1999</member_since>
   <won>National Championship 2001</won>
   <won>Regional Championship 2002</won>
   <won>National Championship 2002</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Joanne Smith</member_name>
   <member_since>2005</member_since>
   <won>Regional Championship 2007</won>
   <won>National championship 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Mary Owens</member_name>
   <member_since>2007</member_since>
   <won>National Championship 2008</won>
  </member>
 </club>
</sport_clubs>

For our target schema we will be using clubs_target.xsd.

The data models sporting clubs and their members. Some of the elements can appear multiple times. Let's assume that we want to sort the members in order of when they joined their club. This will involve applying the Sort function to "member" elements using the "member_since" item as Sort Key. To demonstrate the different ways in which you can use the function, we will also sort the "won" elements into alphabetical order within each "member" parent element. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Set Sort function from the Component Palette into the mapping area:

Set Sort Component

Sort Transform Added

The Set Sort function takes two inputs, representing the item to sort and the key to sort on. The Nodes input should be connected to the source item you want to map in sorted order when output. The Sort Key input should be connected to the value you want the items to be sorted on, which will often be a child element or attribute of the item being sorted. The output connection point will be created when the "Nodes" input connection point is connected.

Let's start by sorting the members in chronological order of when they joined their clubs. Connect the "Nodes" input of the Sort function to the "member" output in the XML Reader and the "Sort Key" input to the "member_since" output.

When the Sort components "Nodes" connection point was connected its output connection point "member" will have been created dynamically, we can connect this to the "player" input in the XML Writer. The members will map in order of the year the person joined.

Reader and Writer to Sort

Now let's add an additional Sort function to the Mapper to see it used in a slightly different way. Drag another Sort component over and connect both its Nodes and Sort Key inputs to the "won" output in the XML Reader. This will simply sort the "title" elements in the output into alphabetical order within their parent "player" elements.

Second Sort Function Added

By connecting both Sort inputs to the same item, we sort the elements using their content values, within their immediate context, i.e. the parent element. With the first Sort function, we used numerical values, so the results will be in ascending numerical order. This time the values are Strings, so the results will be sorted alphabetically.

Finally, connect the remaining inputs and outputs between Reader and Writer. Remember to map "member_since" in the XML Reader to "joined" in the XML Writer. Although we have used the item as a reference for a Sort function, we have not yet mapped it.

Inputs and Outputs Connected

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<clubs>
 <team t_name="New Town Football Club">
  <player p_name="Barry Jones" is_active="No">
   <joined>1996</joined>
   <title>Cup 1999</title>
   <title>League 1999</title>
   <title>League 2000</title>
  </player>
  <player p_name="Jim Thomson" is_active="Yes">
   <joined>2003</joined>
   <title>League 2010</title>
  </player>
  <player p_name="Chris Black" is_active="Yes">
   <joined>2005</joined>
   <title>Cup 2007</title>
   <title>League 2009</title>
  </player>
 </team>
 <team t_name="City Netball Team">
  <player p_name="Jacqueline Johnson" is_active="No">
   <joined>1999</joined>
   <title>National Championship 2001</title>
   <title>National Championship 2002</title>
   <title>Regional Championship 2002</title>
  </player>
  <player p_name="Joanne Smith" is_active="Yes">
   <joined>2005</joined>
   <title>National championship 2007</title>
   <title>Regional Championship 2007</title>
  </player>
  <player p_name="Mary Owens" is_active="Yes">
   <joined>2007</joined>
   <title>National Championship 2008</title>
  </player>
 </team>
</clubs>

The "player" items appear within their "team" parent elements in order of "joined" dates. The "title" elements also appear in alphabetical order within their parent "player" elements.

As with many of the Mapping functions, Sort can prove extremely useful when used in conjunction with other functions from the Set, Comparator and Aggregate sections.

See Also

Data Mapping
Using Set Functions
Dynamic Output Values


Top
Data Mapping > Data Mapper Functions > By Category > Set > Top

Glossary Item Box

Function Name
 Top
Category
 Set
Icon
 Top
Description
 Retrieve the top n items in a sequence
Inputs

Nodes | Sequence to retrieve first n values from
Count | Number of values to retrieve (up to)
Outputs
Result First n items in sequence
Properties
None -

Usage

The Data Mapper Set Top function allows you to retrieve the first n items in a sequence. If the sequence contains less than the count number specified, all items will be mapped - the count value is the maximum number to map. The Top function is particularly useful in conjunction with other functions such as Sort. To apply the Set Top function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using clubs_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<sport_clubs>
 <club>
  <name>New Town Football Club</name>
  <member>
   <active>Yes</active>
   <member_name>Chris Black</member_name>
   <member_since>2005</member_since>
   <won>League 2009</won>
   <won>Cup 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Jim Thomson</member_name>
   <member_since>2003</member_since>
   <won>League 2010</won>
  </member>
  <member>
   <active>No</active>
   <member_name>Barry Jones</member_name>
   <member_since>1996</member_since>
   <won>League 1999</won>
   <won>Cup 1999</won>
   <won>League 2000</won>
  </member>
 </club>
 <club>
  <name>City Netball Team</name>
  <member>
   <active>No</active>
   <member_name>Jacqueline Johnson</member_name>
   <member_since>1999</member_since>
   <won>National Championship 2001</won>
   <won>Regional Championship 2002</won>
   <won>National Championship 2002</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Joanne Smith</member_name>
   <member_since>2005</member_since>
   <won>Regional Championship 2007</won>
   <won>National championship 2007</won>
  </member>
  <member>
   <active>Yes</active>
   <member_name>Mary Owens</member_name>
   <member_since>2007</member_since>
   <won>National Championship 2008</won>
  </member>
 </club>
</sport_clubs>

For our target schema we will be using clubs_target.xsd, inferred from the following XML:

Target XML Copy Code
<clubs>
 <team t_name="City Baseball Team">
  <player p_name="Mark Peterson" is_active="yes">
   <joined>1998</joined>
   <title>UK Championship 2000</title>
  </player>
  <player p_name="John Paterson" is_active="yes">
   <joined>2001</joined>
   <title>English Championship 2003</title>
   <title>European Finalists 2004</title>
  </player>
  <player p_name="Barry Thomson" is_active="no">
   <joined>1995</joined>
   <title>English Championship 1997</title>
  </player>
 </team>
 <team t_name="New Town Hockey Team">
  <player p_name="Jill Chapman" is_active="yes">
   <joined>2004</joined>
   <title>National League Championships 2004</title>
  </player>
  <player p_name="Samantha Jackson" is_active="no">
   <joined>1997</joined>
   <title>British Cup 1999</title>
   <title>British Cup 2000</title>
  </player>
  <player p_name="Jane Maxwell" is_active="yes">
   <joined>2003</joined>
   <title>National League Championship 2004</title>
   <title>British Cup 2004</title>
   <title>National League Championship 2005</title>
  </player>
 </team>
</clubs>

The data models sporting clubs and their members. Some of the elements can appear multiple times. Let's assume that, for each "club" element, we want to map the two oldest members, i.e. the two "member" elements with the earliest "member_since" values. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Set Top function from the Component Palette into the mapping area:

Set Top Component

Top Transform Added

The Set Top function takes two inputs, representing the nodes to retrieve the items from and the number of items to retrieve. The Nodes input should be connected to the item you are looking to map n instances of within its parent element, while the Count input should be connected to a numerical indicator of the number you want to apply as the maximum. The Mapper will iterate through the nodes, applying the count in the order in which it receives the nodes, retrieving the first n items only. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper.

The output of the Top function naturally depends on the order in which the Mapper receives the nodes. Before we apply the Top function, let's sort the "member" items on their "member_since" values, since we want the two oldest members. Drag a Sort function onto the Mapper, connecting its Nodes input to the "member" output in the XML Reader and its Sort Key input to the "member_since" output. Now the Sort Values output will contain the "member" elements for a club, listed in order of the dates the members joined.

Reader to Sort

Connect the Sort output to the Nodes input of the Top function, since this is the sequence we want to retrieve the top n values from.

Sort to Top

Now we have to define the number of items we want to retrieve. Drag a Constant Value from the Data Type section onto the Mapper. Right-click it and choose Show Properties. Select an integer Data Type from the drop-down list and enter the number 2 as the Value, so that we retrieve the first two items in the sequence.

Connect the Constant output to the Count input in the Top function. The Top function will now output the top 2 items in the sorted sequence of "member" elements for each "club" element.

Constant to Top

Now we can map the Top function to the output, connecting it to the "player" input in the XML Writer.

Top to Writer

Finally let's connect the remaining input and output connections. Remember to map "member_since" to "joined" - although we have used the item as a reference, we have not yet mapped it from Reader to Writer.

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<clubs>
 <team t_name="New Town Football Club">
  <player p_name="Barry Jones" is_active="No">
   <joined>1996</joined>
   <title>League 1999</title>
   <title>Cup 1999</title>
   <title>League 2000</title>
  </player>
  <player p_name="Jim Thomson" is_active="Yes">
   <joined>2003</joined>
   <title>League 2010</title>
  </player>
 </team>
 <team t_name="City Netball Team">
  <player p_name="Jacqueline Johnson" is_active="No">
   <joined>1999</joined>
   <title>National Championship 2001</title>
   <title>Regional Championship 2002</title>
   <title>National Championship 2002</title>
  </player>
  <player p_name="Joanne Smith" is_active="Yes">
   <joined>2005</joined>
   <title>Regional Championship 2007</title>
   <title>National championship 2007</title>
  </player>
 </team>
</clubs>

Each "team" element contains two "player" elements - the two with the earliest "joined" values from the source. In many cases, the Top function proves most useful in conjunction with other functions as in the example above. The Maths, Comparator and Aggregate functions can also be used in combination to achieve detailed results.

If you only need to retrieve the first item in a sequence, you can alternatively use the First function. The Last function retrieves the final item, and the Get At function retrieves the item at a specific index.

If your count value exceeds the number of items in a sequence, the values will all be mapped.

See Also

Sort
First
Last
GetAt

Data Mapping
Using Set Functions


Cast
Data Mapping > Data Mapper Functions > By Category > Type > Cast

Glossary Item Box

Function Name
 Cast
Category
 Type
Icon
 Cast
Description
 Cast input data to a specified type
Inputs
Input Input value to cast
Outputs
Result Input value cast to specified type
Properties

Name | Set a name for the function
Cast Type | Choose a data type to cast the input value to

Usage

The Data Mapper Type Cast function returns the input value cast as a particular type. When mapping data, you naturally have to accommodate differing data storage models in the source and target applications. Converting from one type to another is therefore a common task. The Cast function can cast to various numerical types, booleans, Strings, binary/ bytes and date/ time types. To apply the Type Cast function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using client_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<clients>
 <customer business="false">
  <name>Mary Smith</name>
 </customer>
 <customer business="true">
  <name>Steve Jackson</name>
 </customer>
</clients>

For our target schema we will be using client_target.xsd, inferred from the following XML:

Target XML Copy Code
<current_customers>
 <client>
  <is_business>0</is_business>
  <contact_name>Jim Brown</contact_name>
 </client>
 <client>
  <is_business>1</is_business>
  <contact_name>Jack Taylor</contact_name>
 </client>
</current_customers>

The data models clients for an organisation, with a boolean indicator of whether a client is in the "business" category or not. We are going to convert the boolean input values to integers, so that true is represented as 1, with false represented as zero. Here is the Data Mapper with source and target imported:

Data Mapper Source and Target

Drag the Type Cast function from the Component Palette into the mapping area:

Type Cast Component

Type Cast Transform Added

The Type Cast function takes a single input and gives an output of the type chosen. The input should be connected to the source item you want to cast to a specific type during mapping. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper.

We need to let the Cast component know what type we want to cast to, so right-click it and choose Show Properties. In this case we choose the smallest integer type from the Cast Type drop-down list, since we only need to store values of 1 or 0. You can also alter the Name value to make your Cast function clearer as it appears in the Mapper, particularly useful if your Cast forms part of a large, complex mapping process.

Notice that the drop-down list contains many different data types you can cast your input values to. Click OK to confirm your settings. Connect the "business" output in the XML Reader to the Cast input, and the Cast output to the "is_business" item in the XML Writer.

Cast to Reader and Writer

Finally, connect the remaining inputs and outputs:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<current_customers>
 <client>
  <is_business>0</is_business>
  <contact_name>Mary Smith</contact_name>
 </client>
 <client>
  <is_business>1</is_business>
  <contact_name>Steve Jackson</contact_name>
 </client>
</current_customers>

The boolean items in the source have been cast to integers as part of the mapping process. The result is that the "business" status of a client is now represented numerically, using either zero or 1.

If you pass an input value to the Cast function that cannot be cast to your specified type, the Mapper will encounter an error. The function can handle the following data types: Binary, Boolean, Byte, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int16, Int32, Int64, SByte, String, Time and Node.

This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

See Also

NodeType


DefaultIfNull
Data Mapping > Data Mapper Functions > By Category > Type > DefaultIfNull

Glossary Item Box

Function Name
 Default If Null
Category
 Type
Icon
 Cast
Description
 If the Value input contains items then they are passed to the Output.
However if the Value input is empty, then the items from Fallback are passed to the Output.
Inputs

Value | 0-n items (values or nodes) If the Value input contains any items then they are passed to the Output. If the Value input is empty then the values in the Fallback input passed to the Output.
Fallback | 0-n items (values or nodes) The items are only passed to the Output if the input Value contains no items. The type must match (or be castable to) the type of the input Value.
Outputs
Output 0-n items (reflects the type of the input Value)
The items read from the Value or Fallback Inputs.
Properties
Name Set a name for the function

Usage

Allows a default value or sequence of values to be used in the event that the value read is null or an empty sequence.

Typically used when dealing with data sources that contain a value that is optional (i.e. a database value that is nullable). The component allows a default value to be used, so instead of the source value returning null (an empty sequence) it could be made to return a default value.

i.e. If the HomePhone field in the database is null the string value '[UNKNOWN]' will be used instead.

If the input Value is a primitive value then provided to Fallback must be the same type or castable to the type used in Value.

If the input Value is a complex node then the Fallback input must be of the same type, i.e. if Value is an Address node, then Fallback must also be an Address node.

The type of the Output mirrors the type of the input Value.

See Also

Data Mapping
Dynamic Output Values


IsNull
Data Mapping > Data Mapper Functions > By Category > Type > IsNull

Glossary Item Box

Function Name
 Is Null
Category
 Type
Icon
 Cast
Description
 If the input Node is null (an empty sequence) then the Result is true, if it contains a sequence of one or more values then the Result is false.
Inputs
Node

The input value to check (0-n items, values or nodes).
Outputs
Result True if the input Node is an empty sequence.
False if the input Node is a sequence or one or more items.

Usage

Determines if an input contains an empty sequence (i.e. database value that is null).

See Also

DefaultIfNull


NodeName
Data Mapping > Data Mapper Functions > By Category > Type > NodeName

Glossary Item Box

Function Name
 Node Name
Category
 Type
Icon
 Type
Description
 Retrieve the name of the input connection point
Inputs
Value The Input connection point get the name of
Outputs
Name The name of the input connection point as String
Properties
None -

Usage

The Data Mapper Type function returns the name of a particular input value as a String.

In the above example the output Name value from "NodeName 1" would be "anyUriElm".

See Also

NodeType


NodeType
Data Mapping > Data Mapper Functions > By Category > Type > NodeType

Glossary Item Box

Function Name
 Type
Category
 Type
Icon
 Type
Description
 Retrieve the type of an input value
Inputs
Value Input value to determine type of
Outputs
Type Type of input value represented as String
Properties
None -

Usage

The Data Mapper Type function returns the type of a particular input value as a String. When mapping data, it is of course possible that your target application will not have awareness of the details of input data values, in which case you may need to determine data types before making use of your mapped values. The Type function can recognise various numerical types, booleans, Strings, binary/ bytes and date/ time types, as indicated in XSDs. To apply the Type function, use the following process:

Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using value_types_source.xsd, an XML Schema Definition inferred from the following source:

Source XML Copy Code
<values>
 <section name="Objects">
  <item>Mat</item>
  <item>Hat</item>
  <item>Cat</item>
 </section>
 <section name="Colors">
  <item>Blue</item>
  <item>Green</item>
  <item>Yellow</item>
 </section>
</values>

For our target schema we will be using value_types_target.xsd, inferred from the following XML:

Target XML Copy Code
<data>
 <data_type>String</data_type>
 <category>
  <cat_name>People</cat_name>
  <value_item>Mary</value_item>
  <value_item>John</value_item>
 </category>
 <category>
  <cat_name>Places</cat_name>
  <value_item>London</value_item>
  <value_item>Paris</value_item>
 </category>
</data>

The data models values within sections, with the target including an element indicating the data types contained within the file. We are going to determine the type of the "item" element content, which in this case is String. The "data_type" element in the target will include an indicator of this data type. Here is the Data Mapper with Source and Target imported:

Data Mapper Source and Target

Drag the Type function from the Component Palette into the mapping area:

Type Transform Added

The Type function takes a single input and gives an output indicating the type in question. The input should be connected to the source item you want to determine type from. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper.

Connect the Type function output to the "data_type" input in the XML Writer.

Type to Writer

We have input data with multiple elements of the type we are interested in, so we only need one to determine the type from. To achieve this, let's drag a First function from the Set section of the Component Palette - this will return the first instance of the specified item within the source data. Connect the Nodes input of the First function to the "item" element in the XML Reader, since this is the element we are interested in.

XML Reader to First

This function will retrieve the first "item" element in the input data, so let's connect its output to the Value input of the Type function.

First to Type

Finally, connect the remaining inputs and outputs, remembering to map "item" to "value_item", meaning that the "item" output is connecting to two different inputs:

Input and Output Connections Mapped

We can now execute the transform by pressing Shift-F5 or the Execute button ( Execute). The transform is applied and the file we selected as output opens in the editor:

Output XML Copy Code
<data>
 <data_type>String</data_type>
 <category>
  <cat_name>Objects</cat_name>
  <value_item>Mat</value_item>
  <value_item>Hat</value_item>
  <value_item>Cat</value_item>
 </category>
 <category>
  <cat_name>Colors</cat_name>
  <value_item>Blue</value_item>
  <value_item>Green</value_item>
  <value_item>Yellow</value_item>
 </category>
</data>

The type of the first "item" element has been mapped to the "data_type" element in the target as part of the mapping process. The result is that the output data now includes an indicator of the types of data item being handled.

Possible output values of the Type function include: Binary, Boolean, Byte, DateTime, DateTimeOffset, Decimal, Double, Float, Guid, Int16, Int32, Int64, SByte, String, Time and Node.

See Also

Cast
NodeName


Excel Source
Send Feedback
Data Mapping > Data Mapper Functions > Excel Source

Glossary Item Box


Excel Target
Send Feedback
Data Mapping > Data Mapper Functions > Excel Target

Glossary Item Box


OutputParameter
Data Mapping > Data Mapper Functions > OutputParameter

Glossary Item Box

Function Name
 Output Parameter
Category
 Data Type
Icon
 Constant
Description
 Defines an output parameter for the transform.
Inputs
Value The value to write to the output parameter
Properties
Parameter Name The name of the parameter name used when setting the it in code or via a command line argument

Usage

The Output Parameter component allows a value to be returned from a transform. In the case when a command line executable is generated this data is written out to the console, if .Net source code has been generated then the value can be retrieved and then used by the calling application.

A sequence of values can be written to the Output Parameter, which cause multiple Value elements to be created.

If a transform contains multiple Output Parameters then they are executed in the order defined by the Execution Order property, and the values are combined, resulting in multiple Value elements.

Example

The following simple transform returns the value "My Result" via the output parameter.

When this is executed within the Liquid Studio Environment the following is printed to the output window.

Output Copy Code
<TransformResults>
   <Value type="String">My Result</Value>
</TransformResults>

If it compiled to an executable then running it returns the following

You can use the transform within your own .Net project as follows

Sample Code Copy Code
    ParameterCollection parameters = new ParameterCollection();
    using (DataTransformation.GeneratedTransform transform = new DataTransformation.GeneratedTransform(parameters))
    {
        IEnumerable<DataNode> transformResults = transform.Execute();
        foreach (DataNode result in transformResults)
        {
            Debug.WriteLine($"Result({result.DataType}) = {result.AsString}");
        }
    }

The DataNode contains a typed value, which depends on the value passed to the output parameter in the transform.

If multiple values are passed to the output parameter then the transformResults with contain multiple DataNodes.

See Also

Constant
InputParameter


CSS Editor Overview
Send Feedback

Glossary Item Box

The CSS Editor allows CSS documents to be written and validated. The editor provides syntax highlighting and the means to validate the CSS using the Validate Button ( Validate Button). Validation errors are underlined and reported in the error window.


DTD Editor Overview
Send Feedback

Glossary Item Box

The DTD Editor allows DTD documents to be written and validated. The editor provides syntax highlighting and the means to validate the DTD using the Validate Button ( Validate Button). Validation errors are underlined and reported in the error window.


JSON Editor
Send Feedback

Glossary Item Box

The JSON Editor allows JSON documents to be written and validated. The editor provides syntax highlighting and the means to validate the JSON using the Validate Button ( [image]). Validation errors are underlined and reported in the error window.


JSON Schema Editor
Send Feedback

Glossary Item Box

The JSON Schema editor abstracts much of the complexity of the Json schema standard, presenting structure of the schema without showing the unnecessary complexity. This provides a view that makes it simple to understand and edit the your schema. Access to the full range of related facets is available via the properties window and the JSON Source can be edited directly within the Source View.

Some knowledge of the JSON Schema standard is still required.


Graphical Notation Overview
JSON Schema Editor > Graphical Notation Overview

Glossary Item Box

Graphical representation | Description
 | Root Schema
 | Array Item Container
 | Array Item
 | Additional Array Items
 | Properties Container
 | Property
 | Pattern Property
 | Required Property
 | Additional Properties
 | Inline Property
 | Definition Container
 | Schema
 | Dependency Container
 | Property Dependency
 | Schema Dependency
 | AllOf AnyOf OneOf
 | Not

See Also

Array Item Container
Array Item
Additional Items
Properties Container
Property
Required Property
Pattern Property
Additional Properties
Definition Container
Referenced Schema
AllOf, AnyOf, OneOf
Not
Dependency Container
Property Dependency
Schema Dependency
Schema
Schema File
Inline Property


Schema
Send Feedback
JSON Schema Editor > Graphical Notation Overview > Schema

Glossary Item Box

A Json Schema is built up from schema objects, each schema containing its own sub schemas.

In order to depict this graphically schemas are rendered in number of different ways, but still have the same properties and children.

Common Properties

All schema items have the following Inline Properties.

Properties

Default
Description
Enum
ID
Title
Type

Array Constraints
MaxItems
MinItems
UniqueItems

Numeric Constraints
ExclusiveMaximum
ExclusiveMinimum
Maximum
Minimum
MultipleOf

Object Constraints
MaxProperties
MinProperties
Required

String Constraints
MaxLength
MinLength
Pattern

Many of these properties are dependent on the schemas type

Common Child Items

All schemas can also have the following child nodes

Array Item Container

Properties Container

Dependency Container

AllOf, AnyOf, OneOf & Not

These child nodes are dependent on the schemas type

The File/Root Schema

This has all the standard schema properties, but can also have a Definition Container and $schema property.

Property

The property node is a schema with a name, the name is used to match it against members in the instance object.

Pattern Property

The Pattern Property node is a schema with a name, the name is used as a regular expression to match it against members in the instance object.

Required Property

The Pattern Property node is a place holder for a schema, it has none of the properties of child items of a schema, but can be converted into a schema using the 'Convert to Property' setting in the property window.

Additional Properties

The Additional Properties node initially behaves as a placeholder for a schema, but once a child item is added or the "Convert to schema" property is set it behave like a regular schema.

Array Item

The Array Item node is a schema, it has no is shown with the name gives it an index which indicates the item in the instance array that it will be used to validate.

Additional Array Items

The Additional Array Items node can behave as a schema or as a placeholder for a schema.

When its behaving as a placeholder adding a child or setting the "Convert to schema" property will convert it to a schema and it will then operate as a regular schema.

Definition

A Definition Node is just a named schema node within the Definition Container node. It behaves the same as any other schema.

Child Schema

The nodes AllOf, AnyOf, OneOf can contain 1 or more child schemas, these schemas shown in grey behave like any other schema, but are explicitly shown within the diagram.

The Not is similar in that it is an explicitly defined schema, but it behaves as all other schemas do.

The child schema node of a Schema Dependency behaves as a normal schema. Note : This is drawn within a container, which makes it visually different from other schemas, but it behaves the same.


Array Item Container
JSON Schema Editor > Graphical Notation Overview > Array Item Container

Glossary Item Box

The Array Item Container determines the validation rules applied to an instance array.

The visual representation shows the schema that will be applied to the items at a given index in the instance array.

Array Items

An 'Array Item' node shows the index it applies too in the instance array.

Additional Array Items

An 'Additional Items' node is one which covers a range of indexes i.e. [0-n], in this case the schema is used to validate items in the instance array with corresponding indexes.

Example 1

Array Items 'List' Validation Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",    "additionalProperties": false,
    "properties": {
        "Users": {
            "additionalItems": false,
            "items": {
                "type": "string"
            },
            "type": "array"
        }
    }
}

So the following is valid

Valid Json Document Copy Code
{ "Users": [ "Alice", "Bob", "Eve" ] }
Invalid Json Document (as 5 is not a string) Copy Code
{ "Users": [ "Alice", 5, "Eve" ] }

Example 2

Array Items 'List' Validation Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",    "additionalProperties": false,
    "properties": {
        "Values": {
            "additionalItems": false,
            "items": [
                { "type": "integer" },
                { "type": "string"  },
                { "type": "boolean" }
            ],
            "type": "array"
        }
    }
}

The array item shows the index items it applies too in the instance value;

The value at index 0 must be an integer.

The value at index 1 must be a string.

The value at index 2 must be a boolean.

So the following are valid

Valid Json Document Copy Code
{ "Values": [ 5, "Bob", true ] }

{ "Values": [ 5, "Bob" ] }

{ "Values": [ ] }
Invalid Json Document Copy Code
{ "Users": [ "5", "Bob", true ] } // Note "5" is not an integer its a string

{ "Users": [ 5, "Bob", true, "Extra Value" ] }

Example 3

Array Items 'List' Validation Copy Code
{    "$schema": "http://json-schema.org/draft-04/schema#",    "type": "object",    "additionalProperties": false,    "properties": {        "Values": {            "type": "array",            "additionalItems": {                "type": "string"            },            "items": [
                { "type": "integer" },
                { "type": "string"  },
                { "type": "boolean" }
            ]        }    }}

The array item shows the index items it applies too in the instance value;

The value at index 0 must be an integer.

The value at index 1 must be a string.

The value at index 2 must be a boolean.

The value at index 3 or above must be a string.

So the following are valid

Valid Json Document Copy Code
{ "Values": [ ] }

{ "Values": [ 5, "Bob" ] }

{ "Values": [ 5, "Bob", true ] }

{ "Values": [ 5, "Bob", true, "another string", "and another" ] }
Invalid Json Document Copy Code
{ "Users": [ "5", "Bob", true ] } // Note "5" is not an integer its a string

{ "Users": [ 5, "Bob, "another string" ] } // Note item at index 2 must be a boolean ("another string" is a string).

See Also

Array Constraints
AdditionalItems
Items
MaxItems
MinItems
UniqueItems


Array Item
Send Feedback
JSON Schema Editor > Graphical Notation Overview > Array Item Container > Array Item

Glossary Item Box

The array container shows the schemas that will be used to validate the instance array.

The index values on the 'Array Item' nodes (shown in square brackets []) indicate the index in the instance array that the schema apply's to.

If the index value covers a range (e.g. [3-n]) then this schema will be used to validate all array items in the instance array from index 3 and above, and is referred to as the 'Additional Items' node.

To add a schema to validate the an item in the instance array, use the context menu 'Add Array Items -> Add Item ...' from the Parent Schema or the context menu on the Array Item Container itself.

The order of the items can be changed by dragging them to the desired position (if an 'Additional Items' node exists other nodes can not be dragged past this, and the 'Additional Items' node itself can not be dragged).

The 'Array Item Container' is a representation of the 'items' and 'additionalItems' keyword, the rules surrounding this are complex, and for more information see the documentation for 'additionalItems'.

Array Item Validation.

The items and additionalItems keywords control what kind of objects can appear in an instance array. They are closely interrelated and subtlety effect the validation applied. Broadly speaking there are 2 types of validation we will call them List and Tuple validation.

Json Schema validators make assumptions about the values of the items and additionalItems keywords

  • If the items keyword is not present it is considered to contain an empty schema (which validates against everything).
  • If the additionalItems keyword is not present or true then it is considered to contain an empty schema (which validates against everything).

List Validation

When List validation is used, a schema is defined and all the objects in the array must validate against this schema. This is the simplest and mostly widely used form of array validation.

List validation is used when the items keyword contains a single schema object.

When this is the case the property additionalItems is ignored.

Json Schema Source Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Users": {
            "additionalItems": false,
            "items": {
                "type": "string"
            },
            "type": "array"
        }
    }
}
Valid Instance Json Document Copy Code
{
    "Users": ["Alice","Bob", "Eve"]
}

Tuple Validation

Tuple validation allows you to provide a schema to validate each item in the instance array.

Tuple validation is used when the items property contains an array of schema objects.

Each item in the items array validates an object in the instance array at the corresponding index.

  • It is acceptable for the instance array to contain less items than are specified in the items array.
  • If the instance array contains more items than their are entries in the items array then the additionalItems keyword affects how these additional items are validated.
    • If the additionalItems keyword is 'true', then any additional array items in the instance array are allowed (regardless of there type or value).
    • If the additionalItems keyword is 'false', then additional array items in the instance array are NOT allowed.
    • If the additionalItems keyword contains a schema, then additional array items in the instance array must validate against this schema.

Tuple Example 1

In this example the schema specifies the schemas for first 3 items in the array, if more than 3 items appear in the instance array then it is an error, however it is acceptable for the array to contain less than 3 items as long as the ones that are present validate against the appropriate schema.

Json Schema Source Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Values": {
            "additionalItems": false,
            "items": [
                { "type": "integer" },
                { "type": "string"  },
                { "type": "boolean" }
            ],
            "type": "array"
        }
    }
}
Valid Instance Json Document Copy Code
{
    "Users": [34, "Bob", true]
}
Valid Instance Json Document (note: it is allowable to miss values off of the end) Copy Code
{
    "Users": [34, "Bob"]
}

Tuple Example 2

In this example the schema is specified for the first 3 items in the array, additionally a schema is provided for any additional array items (note the [3-n] indicator).

The first 3 objects in the instance array must validate against the corresponding schema, but any additional items must validate against the [3-n] schema.

Json Schema Source Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Values": {
            "type": "array",
            "additionalItems": {
                "type": "string"
            },
            "items": [
                { "type": "integer" },
                { "type": "string"  },
                { "type": "boolean" }
            ]
        }
    }
}
Valid Instance Json Document Copy Code
{
    "Users": [34, "Bob", true]
}
Valid Instance Json Document (note: it is allowable to miss values off of the end) Copy Code
{
    "Users": [34, "Bob"]
}
Valid Instance Json Document Copy Code
{
    "Users": [34, "Bob", true, "Other1", "Other2"]
}


Additional Items
JSON Schema Editor > Graphical Notation Overview > Array Item Container > Additional Items

Glossary Item Box

The array container shows the schemas that will be used to validate the instance array.

The index values on the 'Array Item' nodes (shown in square brackets []) indicate the index in the instance array that the schema apply's to.

If the index value covers a range (e.g. [3-n]) then this schema will be used to validate all array items in the instance array from index 3 and above, and is referred to as the 'Additional Items' node.

To add a schema to validate the additional array items, use the context menu 'Add Array Items -> Additional Items' from the Parent Schema or the Array Item Container.

The 'Array Item Container' is a representation of the 'items' and 'additionalItems' keyword, the rules surrounding this are complex, and for more information see the documentation for 'additionalItems'.

Advanced Properties

Due to the way in which the Json schema is structured, sometimes an Additional Items node will be represented in the Json source code via the additionalItems keyword.

Is Explicit

True if additionalItems is set to true.

False if additionalItems is not present (and has just defaulted to true).

Convert to Schema

False if additionalItems is set to true.

Setting this to true will cause additionalItems to contain an actual schema object. This schema object can then be manipulated as any other schema can.

Array Item Validation.

The items and additionalItems keywords control what kind of objects can appear in an instance array. They are closely interrelated and subtlety effect the validation applied. Broadly speaking there are 2 types of validation we will call them List and Tuple validation.

Json Schema validators make assumptions about the values of the items and additionalItems keywords

  • If the items keyword is not present it is considered to contain an empty schema (which validates against everything).
  • If the additionalItems keyword is not present or true then it is considered to contain an empty schema (which validates against everything).

List Validation

When List validation is used, a schema is defined and all the objects in the array must validate against this schema. This is the simplest and mostly widely used form of array validation.

List validation is used when the items keyword contains a single schema object.

When this is the case the property additionalItems is ignored.

Json Schema Source Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Users": {
            "additionalItems": false,
            "items": {
                "type": "string"
            },
            "type": "array"
        }
    }
}
Valid Instance Json Document Copy Code
{
    "Users": ["Alice","Bob", "Eve"]
}

Tuple Validation

Tuple validation allows you to provide a schema to validate each item in the instance array.

Tuple validation is used when the items property contains an array of schema objects.

Each item in the items array validates an object in the instance array at the corresponding index.

  • It is acceptable for the instance array to contain less items than are specified in the items array.
  • If the instance array contains more items than their are entries in the items array then the additionalItems keyword affects how these additional items are validated.
    • If the additionalItems keyword is 'true', then any additional array items in the instance array are allowed (regardless of there type or value).
    • If the additionalItems keyword is 'false', then additional array items in the instance array are NOT allowed.
    • If the additionalItems keyword contains a schema, then additional array items in the instance array must validate against this schema.

Tuple Example 1

In this example the schema specifies the schemas for first 3 items in the array, if more than 3 items appear in the instance array then it is an error, however it is acceptable for the array to contain less than 3 items as long as the ones that are present validate against the appropriate schema.

Json Schema Source Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Values": {
            "additionalItems": false,
            "items": [
                { "type": "integer" },
                { "type": "string"  },
                { "type": "boolean" }
            ],
            "type": "array"
        }
    }
}
Valid Instance Json Document Copy Code
{
    "Users": [34, "Bob", true]
}
Valid Instance Json Document (note: it is allowable to miss values off of the end) Copy Code
{
    "Users": [34, "Bob"]
}

Tuple Example 2

In this example the schema is specified for the first 3 items in the array, additionally a schema is provided for any additional array items (note the [3-n] indicator).

The first 3 objects in the instance array must validate against the corresponding schema, but any additional items must validate against the [3-n] schema.

Json Schema Source Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Values": {
            "type": "array",
            "additionalItems": {
                "type": "string"
            },
            "items": [
                { "type": "integer" },
                { "type": "string"  },
                { "type": "boolean" }
            ]
        }
    }
}
Valid Instance Json Document Copy Code
{
    "Users": [34, "Bob", true]
}
Valid Instance Json Document (note: it is allowable to miss values off of the end) Copy Code
{
    "Users": [34, "Bob"]
}
Valid Instance Json Document Copy Code
{
    "Users": [34, "Bob", true, "Other1", "Other2"]
}

See Also

Json Schema Standard
Array Item Container
Array Item


Definition Container
JSON Schema Editor > Graphical Notation Overview > Definition Container

Glossary Item Box

The root schema may contain a definition container, this holds the definitions for named schemas that can then be referenced within the schema.

This provides a mechanism for re-use and extensibility within the Json Schema.

It is good practice to define any commonly used data types here and then reference them.

It is allowable for a definition to contain references to other definitions (and even itself).

See Also

Referenced Schema

JSON Schema Editor
Reference Resolution


Referenced Schema
JSON Schema Editor > Graphical Notation Overview > Definition Container > Referenced Schema

Glossary Item Box

References and Definitions are the main mechanism within the JSON Schema standard to support re-use. Essentially a schema can be declared within the root schemas Definitions Container, these definition schemas can then be referenced and re-used elsewhere within the schema.

Schemas that reference a definition have a [image] over the normal icon, and the type field shows the definition they are referencing.

Code Snippet Copy Code
"ISBN": {
    "$ref": "#/definitions/isbnType"
}

The UI will provide a list of existing definitions when the type field is dropped down and automatically build a reference is one is selected.

Changes made to a referenced schema are made to the definition.

See Also

Definition Container


Dependency Container
Send Feedback
JSON Schema Editor > Graphical Notation Overview > Dependency Container

Glossary Item Box

Dependences allow relationships between properties to be defined.

There are 2 types of dependency supported by the Json Schema standard.

Property Dependencies

A property dependency has a name and a list of other property names. If the named property exists, then the list of named properties must also exist.

In this example if the property 'ISBN' is present then the 'Publisher' property must also be present.

There is no requirement that any of the property names match a property definition (as they could match against Pattern Property or Additional Property nodes.

Schema Dependencies

A schema dependency has a named property and a sub schema. If the named property exists, then the schema is applied to the containing object, and must validate.

In this way it is possible to create dependencies that provide more details validation or even exclude other properties when the named property is present (see not).

In this example if the property 'Price' is present then the contained schema must validate, in this case the property 'Currency' must exist and it must be a string.

As dependencies only apply to properties (which are only used in instance object validation) if the target schema is not allowed to contain an object, then they are not valid for the schema.


Property Dependency
Send Feedback
JSON Schema Editor > Graphical Notation Overview > Dependency Container > Property Dependency

Glossary Item Box

A property dependency has a name and a list of 1 or more property names.

If the named property exists, then the list of named properties must also exist.

Example Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "title": "My schema",
    "additionalProperties": false,
    "properties": {
        "Price": {
            "type": "number"
        },
        "Currency": {
            "type": "string"
        }
    },
    "dependencies": {
        "Currency": [
            "Price"
        ]
    }
}

In this example if the property 'Currency' is present then the 'Price' property must also be present.

The converse is NOT true, 'Price' can be present without 'Currency', in order to ensure they both exist or neither exists, a second property dependency would have to be added saying id 'Price' exists 'Currency' must exist.

There is no requirement that any of the property names match a property definition (as they could match against Pattern Property or Additional Property nodes.


Schema Dependency
Send Feedback
JSON Schema Editor > Graphical Notation Overview > Dependency Container > Schema Dependency

Glossary Item Box

A schema dependency has a named property and a sub schema. If the named property exists, then the schema is applied to the containing object, and must validate.

There is no requirement that any of the property names match a property definition (as they could match against Pattern Property or Additional Property nodes).

Example 1

Example Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "title": "My schema",
    "additionalProperties": true,
    "properties": {
        "a": { "type": "string" },
        "b": { "type": "string" }
    },
    "dependencies": {
        "a": {
            "type": "object",
            "properties": {
                "x": { "type": "number" }
            },
            "required": [ "x" ]
        }
    }
}

In this example if the property 'a' is present then the contained schema must also validate the containing instance object.

Valid Copy Code
{
    "a":"String",
    "x":4
}
Invalid Copy Code
{
    "a":"String"
}

As this validation effectively uses 2 schemas to validate the same instance object the 2 schemas must 'overlap'.

In other words the properties defined by the core schema must also be allowable by the dependency schema and visa versa.

This is easiest to do by ensuring both schemas contain an Additional Properties node (but can be done with property or PatternProperty nodes.

Example 2 - Restricting Existing Types

Schema dependencies can also be used to further constrain existing property definitions.

Example Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "title": "My schema",
    "additionalProperties": false,
    "properties": {
        "a": { "type": "string" },
        "b": {
            "type": "string",
            "minLength": 3
        }
    },
    "dependencies": {
        "a": {
            "type": "object",
            "properties": {
                "b": {
                    "type": "string",
                    "maxLength": 4
                }
            }
        }
    }
}

In this example property 'a' is optional and can contain a string of any length, and property 'b' is optional, but if present must contain a string of 3 or more chars.

However, because of the dependency rule, if the property 'a' is present then additional rules are applied to property 'b' (if present).

The additional rule in the dependency ensure that 'b' can contain any string with a max length of 4.

The constraints of the core and dependency schema are both applied ensuring if b is present it is s string of 3-4 chars.

Valid Copy Code
{    "a":"String with no restrictions"    }

{    "b":"Long String - Which is Valid as 'a' is not present"    }

{
     "a":"String with no restrictions",
     "b":"ABC"
}
Invalid Copy Code
{    "b":"A"    }   // To Short

{
     "a":"String with no restrictions",
     "b":"ABCDE"    // To Long as dependency rules are applied as 'a' is present.
}

Example 3 - Excluding Existing Properties

Schema dependencies can also be used to remove existing properties.

The logic and implementation for this are not intuitive, so its best avoided if possible!
But you do see it in a number of production schemas.

Example Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "title": "My schema",
    "additionalProperties": false,
    "properties": {
        "a": { "type": "string" },
        "b": { "type": "string" }
    },
    "dependencies": {
        "a": {
            "type": "object",
            "not": { "required": [ "b" ] }
        }
    }
}
If your not familiar with the 'not' node, then its probably a good idea to read through that topic first.

In this example property 'a' is optional and can contain a string of any length, and property 'b' is optional and contain a string of any length.

However, because of the dependency rule, if the property 'a' is present the following additional rules apply :

The object must validate against the schema in the dependency, which contains:

A Properties Collection which contains an additional properties node (this allows any properties so has no effect on the validation).

A Not schema (which is not allowed to validate against the containing instance object), this contains:

A required property 'b' and an additional properties node (so this will validate if the property 'b' is present).

The negative logic here makes this somewhat unintuitive, but basically reading backwards.

  • The bit inside the 'not' is valid if the property 'b' is present.
  • Negating this through the 'not', its valid when the property 'b' is not present.
  • Taking this back through the dependency you get; if property 'a' is present, then property 'b' must not be present.
Valid Copy Code
{                    }

{    "a":"String"    }

{    "b":"String"    }
Invalid Copy Code
{
    "a":"String",
    "b":"String"
}


Properties Container
JSON Schema Editor > Graphical Notation Overview > Properties Container

Glossary Item Box

The Property Container(0) determines the validation rules applied to the child members within an instance object.

The property container can contain a number of different nodes types.

Property (1)

A property node validates an instance object with a matching name. If it s drawn with a solid border then it is required in the instance object, if it has a dotted line then it is optional.

The Property Container can hold 0-n Property nodes.

Required Properties (2)

A required property is one that must exist within the instance object, but is not explicitly defined by a property, meaning it must fit into a rule defined by a pattern property or the additional properties node must be present.

The Property Container can hold 0-n Required Properties nodes.

Pattern Property (3)

A pattern Property node validates an instance object with a matching name. If it s drawn with a solid border then it is required in the instance object, if it has a dotted line then it is optional.

The Property Container can hold 0-n Pattern Property nodes.

Additional Properties (4)

The Additional Properties node contains validation rules for any instance objects that do not match a property or pattern property.

The Property Container can hold 0-1 Additional Properties node.

Ordering

The Property Container always draw the property nodes in groups, in the following order

  • Property
  • Required Properties
  • Pattern Property
  • Additional Properties

Attempting to drag items outside of the group they are contained is not possible.

For more in depth information regarding see the keywords properties, patternProperties and additionalProperties.

See Also

Properties Container
Property
Required Property
Pattern Property
Additional Properties

Object Constraints
AdditionalProperties
MaxProperties
MinProperties
Pattern Properties
Properties
Required


Property
JSON Schema Editor > Graphical Notation Overview > Properties Container > Property

Glossary Item Box

A property provides the validation for a member within the instance object.

Each property in the container must have a unique name, and this name is used to match it against the member in the instance object.

Matching instance objects are validated using the properties schema.

If the property is drawn with a dotted line (as above) then it is optional in the instance object. If it is drawn with a solid line then it is required, and a member with the corresponding name must exist in the instance object.

Properties can be added to the parent schema or containing Properties container using the right click context menu.

For more in depth information regarding see the keywords properties, patternProperties and additionalProperties.

Its recommended that you use strongly typed properties wherever possible.

See Also

Schema
Properties Container
Required Property
Pattern Property
Additional Properties

JSON Schema Editor
Schema Design Guidelines

Object Constraints
AdditionalProperties
MaxProperties
MinProperties
Pattern Properties
Properties
Required


Pattern Property
JSON Schema Editor > Graphical Notation Overview > Properties Container > Pattern Property

Glossary Item Box

A pattern property provides the validation for a members within the instance object.

Each pattern property in the container must have a unique name. This name is interpreted as a regular expression and used to match against members in the instance object.

Matching instance objects are validated using the pattern properties schema.

Properties can be added to the parent schema or containing Properties container using the right click context menu.

For more in depth information regarding see the keywords properties, patternProperties and additionalProperties.

See Also

Properties Container
Property
Required Property
Additional Properties

Object Constraints
AdditionalProperties
MaxProperties
MinProperties
Pattern Properties
Properties
Required


Required Property
JSON Schema Editor > Graphical Notation Overview > Properties Container > Required Property

Glossary Item Box

A required property can exist within even when it is not explicitly defined within the schemas Properties Container.

This means it is required in the instance object either because it matches a patternProperty or because the schema allows additional properties.

Source Code Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "title": "My schema",
    "additionalProperties": false,
    "patternProperties": {
        "MyProperty[0-1]*": {
            "type": "string"
        }
    },
    "required": [ "MyProperty1" ]
}

In this example the patternProperty "MyProperty[0-1]*" allows properties to exist which start with "MyProperty" and have a number on the end.

Lets assume we want as many "MyProperty" entries as we like, but we to ensure one exists called "MyProperty1".

By adding "MyProperty1" as a required property we ensure it must exist and validate against the rules in the patternProperty (i.e. its a string).

All required properties are drawn with a solid line around them, optional properties are drawn with a dotted line.

Required properties can be added via the properties right click menu

For more detail see the 'required' keyword.

For more in depth information regarding see the keywords properties, patternProperties and additionalProperties.

See Also

Properties Container
Property
Pattern Property
Additional Properties

Object Constraints
AdditionalProperties
MaxProperties
MinProperties
Pattern Properties
Properties
Required


Additional Properties
JSON Schema Editor > Graphical Notation Overview > Properties Container > Additional Properties

Glossary Item Box

The additional properties node provides the validation for members within the instance object which do not match a property or pattern property.

An Additional Properties node can be added to the parent schema or containing Properties Container using the right click context menu.

Its recommended that you use strongly typed properties wherever possible.

For more in depth information regarding see the keywords Properties, Pattern Properties and AdditionalProperties.

See Also

Properties Container
Property
Required Property
Pattern Property

Object Constraints
AdditionalProperties
MaxProperties
MinProperties
Pattern Properties
Properties
Required


AllOf, AnyOf, OneOf
Send Feedback
JSON Schema Editor > Graphical Notation Overview > AllOf, AnyOf, OneOf

Glossary Item Box

The 3 keywords AnyOf, AllOf and OneOf work in the same way, but have slightly different logic for each.

Essentially each can contain a number of schemas, each schema is validated against the instance value.

  • AllOf : All of the contained schemas must validate against the instance value.
  • AnyOf : One or more of the contained schemas must validate against the instance value.
  • OneOf : One (and only one) of the contained schemas must validate against the instance value.

The AllOf, AnyOf, OneOf nodes are all optional, and a schema can contain any combination of them.

Example - Multiple Versions of a type

This example shows how its possible to create 2 versions of an address, in this case a US and UK style.

The AddressLine1, AddressLine2 & City properties are common to both.

The OneOf node means that the instance object must also validate against just one of the 2 contained schemas.

The first schema stipulates that the instance object must contain a ZipCode and may also have a State.

The second schema stipulates that the instance object must contain a PostCode and may also have a County.

Notice in the OneOf schemas the ZipCode & PostCode are required.

If these were left as optional fields then the schemas would validate against any instance object (due to the Additional Properties not), and if both of them validated the OneOf clause would fail.
Example Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "title": "My schema",
    "additionalProperties": true,
    "properties": {
        "AddressLine1": { "type": "string" },
        "AddressLine2": { "type": "string" },
        "City":         { "type": "string" }
    },
    "required": [ "AddressLine1" ],
    "oneOf": [
        {
            "type": "object",
            "properties": {
                "State":   { "type": "string" },
                "ZipCode": { "type": "string" }
            },
            "required": [ "ZipCode" ]
        },
        {
            "type": "object",
            "properties": {
                "County":   { "type": "string" },
                "PostCode": { "type": "string" }
            },
            "required": [ "PostCode" ]
        }
    ]
}

The following data is valid as it validates against the core schema and the first 'OneOf' schema (the second 'OneOf' schema requires that a PostCode be present, so this one does not validate).

Valid Json Data Copy Code
{
    "AddressLine1" : "Microsoft Corporation",
    "AddressLine2" : "One Microsoft Way",
    "City" : "Redmond",
    "State" : "WA",
    "ZipCode" : "98052-7329"
}


Not
Send Feedback
JSON Schema Editor > Graphical Notation Overview > Not

Glossary Item Box

The 'Not' node contains a single schema, if this schema validates against the instance value then the validation fails.

Put another way, it's a negative operator, it says this instance value MUST NOT validate against the schema contained within the 'not' node.

Although the 'not' operator can be very useful, its unintuitive and easy to miss-interpreted, so should be used only when absolutely necessary.

Lets say we want to have a schema the has values that are Index1, Index2, ... index3484 etc.

Our simple schema may look something like this

Json Schema Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "title": "My schema",
    "additionalProperties": false,
    "patternProperties": {
        "Index[0-9]*": {
            "type": "string"
        }
    }
}

That's fine, but lets say you really don't want a value of Index0 to be allowed (which it currently is).

One way to solve this is to explicitly exclude it, we can do this with a Not node.

Json Schema Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "title": "My schema",
    "additionalProperties": false,
    "patternProperties": {
        "Index[0-9]*": {
            "type": "string"
        }
    },
    "not": {
        "type": "object",
        "required": [
            "Index0"
        ]
    }
}

These things are sometimes easier to read in reverse order, so looking at the properties collection in the 'Not' node, its saying that it will validate any instance object as long as it contains a member called 'Index0'.

Moving down, the Not node negates this schema, so is satisfied by an instance document as long as it DOES NOT contain a member called 'Index0'.

The properties collection at the root level must also validate. It validates as long as all the instance object member names conform to the regex 'Index[0-9]*'

Put it altogether and you get, the instance object must contain members with names that conform to the regex 'Index[0-9]*', but are not named 'Index0'.

This is an artificial example, and in this case the problem is much more effectively solved with a better regular expression.


Keywords
JSON Schema Editor > Keywords

Glossary Item Box

If you are already familiar with the Json Schema standard then you may want to know how the Json Schema keywords relate to the graphical representation.

This table gives you a list of the keywords and the linked topic provides information about how they relate the diagram.

Keyword
additionalItems
additionalProperties

default
description
enum
exclusiveMaximum
exclusiveMinimum
id
items
maximum
maximum

maxItems
maxLength
maxProperties
minimum
minItems
minLength
minProperties
multipleOf
pattern
patternProperties
properties
required
title
type
uniqueItems

See Also

Default
Description
Enum
ID
Title
Type

Array Constraints
AdditionalItems
Items
MaxItems
MinItems
UniqueItems

Numeric Constraints
ExclusiveMaximum
ExclusiveMinimum
Maximum
Minimum
MultipleOf

Object Constraints
AdditionalProperties
MaxProperties
MinProperties
Pattern Properties
Properties
Required

String Constraints
MaxLength
MinLength
Pattern


AdditionalItems
JSON Schema Editor > Keywords > AdditionalItems

Glossary Item Box

Validation

5.3.1.1. Valid values

The value of "additionalItems" MUST be either a boolean or an object. If it is an object, this object MUST be a valid JSON Schema.

The value of "items" MUST be either an object or an array. If it is an object, this object MUST be a valid JSON Schema. If it is an array, items of this array MUST be objects, and each of these objects MUST be a valid JSON Schema.

5.3.1.2. Conditions for successful validation

Successful validation of an array instance with regards to these two keywords is determined as follows:

if "items" is not present, or its value is an object, validation of the instance always succeeds, regardless of the value of "additionalItems";

if the value of "additionalItems" is boolean value true or an object, validation of the instance always succeeds;

if the value of "additionalItems" is boolean value false and the value of "items" is an array, the instance is valid if its size is less than, or equal to, the size of "items".

5.3.1.4. Default values

If either keyword is absent, it may be considered present with an empty schema.

8.2.3.1. If "items" is a schema

If items is a schema, then the child instance must be valid against this schema, regardless of its index, and regardless of the value of "additionalItems".

8.2.3.2. If "items" is an array

In this situation, the schema depends on the index:

if the index is less than, or equal to, the size of "items", the child instance must be valid against the corresponding schema in the "items" array;

otherwise, it must be valid against the schema defined by "additionalItems".

Graphical Representation

As you can see from the Json Schema spec (above), the rules resulting from the combination of 'additionalItems' and 'items' keywords are quite complex and not at all intuitive.

In order to make the user interface intuitive and simple to use these values are encapsulated into "Array Items Container".

As you can see you get some unexpected results, which would be difficult to spot without a UI representation, for example the first item sets additionItems to false and has no value for items, intuitively you would expect this to disallow array items, but reading through the rules above you see that it allows anything.

Schema Source Code Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "title": "My schema",
    "additionalProperties": false,
    "properties": {
        "ItemsNullAdditionalItemsFalse": {
            "type": "array",
            "additionalItems": false
        },
        "ItemsNullAdditionalItemsTrue": {
            "type": "array",
            "additionalItems": true
        },
        "ItemsNullAdditionalItemsNull": {
            "type": "array"
        },
        "ItemsNullAdditionalItemsSchema": {
            "type": "array",
            "additionalItems": {
                "type": "string",
                "maxLength": 5
            }
        },
        "ItemsSchemaAdditionalItemsFalse": {
            "type": "array",
            "additionalItems": false,
            "items": {}
        },
        "ItemsSchemaAdditionalItemsTrue": {
            "type": "array",
            "additionalItems": true,
            "items": {}
        },
        "ItemsSchemaAdditionalItemsNull": {
            "type": "array",
            "items": {}
        },
        "ItemsSchemaAdditionalItemsSchema": {
            "type": "array",
            "additionalItems": {
                "type": "string",
                "maxLength": 5
            },
            "items": {}
        },
        "ItemsEmptyArrayAdditionalItemsFalse": {
            "type": "array",
            "additionalItems": false,
            "items": []
        },
        "ItemsEmptyArrayAdditionalItemsTrue": {
            "type": "array",
            "additionalItems": true,
            "items": []
        },
        "ItemsEmptyArrayAdditionalItemsNull": {
            "type": "array",
            "items": []
        },
        "ItemsEmptyArrayAdditionalItemsSchema": {
            "type": "array",
            "additionalItems": {
                "type": "string",
                "maxLength": 5
            },
            "items": []
        },
        "ItemsArrayWithSchemaAdditionalItemsFalse": {
            "type": "array",
            "additionalItems": false,
            "items": [
                {}
            ]
        },
        "ItemsArrayWithSchemaAdditionalItemsTrue": {
            "type": "array",
            "additionalItems": true,
            "items": [
                {}
            ]
        },
        "ItemsArrayWithSchemaAdditionalItemsNull": {
            "type": "array",
            "items": [
                {}
            ]
        },
        "ItemsArrayWithSchemaAdditionalItemsSchema": {
            "type": "array",
            "additionalItems": {
                "type": "string",
                "maxLength": 5
            },
            "items": [
                {}
            ]
        }
    }
}

Array Item Validation.

The items and additionalItems keywords control what kind of objects can appear in an instance array. They are closely interrelated and subtlety effect the validation applied. Broadly speaking there are 2 types of validation we will call them List and Tuple validation.

Json Schema validators make assumptions about the values of the items and additionalItems keywords

  • If the items keyword is not present it is considered to contain an empty schema (which validates against everything).
  • If the additionalItems keyword is not present or true then it is considered to contain an empty schema (which validates against everything).

List Validation

When List validation is used, a schema is defined and all the objects in the array must validate against this schema. This is the simplest and mostly widely used form of array validation.

List validation is used when the items keyword contains a single schema object.

When this is the case the property additionalItems is ignored.

Json Schema Source Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Users": {
            "additionalItems": false,
            "items": {
                "type": "string"
            },
            "type": "array"
        }
    }
}
Valid Instance Json Document Copy Code
{
    "Users": ["Alice","Bob", "Eve"]
}

Tuple Validation

Tuple validation allows you to provide a schema to validate each item in the instance array.

Tuple validation is used when the items property contains an array of schema objects.

Each item in the items array validates an object in the instance array at the corresponding index.

  • It is acceptable for the instance array to contain less items than are specified in the items array.
  • If the instance array contains more items than their are entries in the items array then the additionalItems keyword affects how these additional items are validated.
    • If the additionalItems keyword is 'true', then any additional array items in the instance array are allowed (regardless of there type or value).
    • If the additionalItems keyword is 'false', then additional array items in the instance array are NOT allowed.
    • If the additionalItems keyword contains a schema, then additional array items in the instance array must validate against this schema.

Tuple Example 1

In this example the schema specifies the schemas for first 3 items in the array, if more than 3 items appear in the instance array then it is an error, however it is acceptable for the array to contain less than 3 items as long as the ones that are present validate against the appropriate schema.

Json Schema Source Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Values": {
            "additionalItems": false,
            "items": [
                { "type": "integer" },
                { "type": "string"  },
                { "type": "boolean" }
            ],
            "type": "array"
        }
    }
}
Valid Instance Json Document Copy Code
{
    "Users": [34, "Bob", true]
}
Valid Instance Json Document (note: it is allowable to miss values off of the end) Copy Code
{
    "Users": [34, "Bob"]
}

Tuple Example 2

In this example the schema is specified for the first 3 items in the array, additionally a schema is provided for any additional array items (note the [3-n] indicator).

The first 3 objects in the instance array must validate against the corresponding schema, but any additional items must validate against the [3-n] schema.

Json Schema Source Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Values": {
            "type": "array",
            "additionalItems": {
                "type": "string"
            },
            "items": [
                { "type": "integer" },
                { "type": "string"  },
                { "type": "boolean" }
            ]
        }
    }
}
Valid Instance Json Document Copy Code
{
    "Users": [34, "Bob", true]
}
Valid Instance Json Document (note: it is allowable to miss values off of the end) Copy Code
{
    "Users": [34, "Bob"]
}
Valid Instance Json Document Copy Code
{
    "Users": [34, "Bob", true, "Other1", "Other2"]
}

See Also

Items
MaxItems
MinItems
UniqueItems

Notation
Additional Items
Array Item Container
Array Item


AdditionalProperties
JSON Schema Editor > Keywords > AdditionalProperties

Glossary Item Box

Validation

The 'additionalProperties' keyword may be a boolean (true, false) value or a schema object.

From the Json Schema Standard Version 4 draft.

5.4.4.1. Valid values

The value of "additionalProperties" MUST be a boolean or an object. If it is an object, it MUST also be a valid JSON Schema.

The value of "properties" MUST be an object. Each value of this object MUST be an object, and each object MUST be a valid JSON Schema.

The value of "patternProperties" MUST be an object. Each property name of this object SHOULD be a valid regular expression, according to the ECMA 262 regular expression dialect. Each property value of this object MUST be an object, and each object MUST be a valid JSON Schema.

5.4.4.3. Default values

Successful validation of an object instance against these three keywords depends on the value of "additionalProperties":

if its value is boolean true or a schema, validation succeeds;

if its value is boolean false, the algorithm to determine validation success is described below.

5.4.4.4. If "additionalProperties" has boolean value false

In this case, validation of the instance depends on the property set of "properties" and "patternProperties". In this section, the property names of "patternProperties" will be called regexes for convenience.

The first step is to collect the following sets:

s
The property set of the instance to validate.
p
The property set from "properties".
pp
The property set from "patternProperties".

Having collected these three sets, the process is as follows:

remove from "s" all elements of "p", if any;

for each regex in "pp", remove all elements of "s" which this regex matches.

Validation of the instance succeeds if, after these two steps, set "s" is empty.

8.3.2. Implied keywords

The three keywords implied in this calculation are "properties", "patternProperties" and "additionalProperties".

If "properties" or "patternProperties" are absent, they are considered present with an empty object as a value.

If "additionalProperties" is absent, it is considered present with an empty schema as a value. In addition, boolean value true is considered equivalent to an empty schema.

8.3.3. Calculation

8.3.3.1. Names used in this calculation

The calculation below uses the following names:

m
The property name of the child.
p
The property set from "properties".
pp
The property set from "patternProperties". Elements of this set will be called regexes for convenience.
s
The set of schemas for the child instance.

8.3.3.2. First step: schemas in "properties"

If set "p" contains value "m", then the corresponding schema in "properties" is added to "s".

8.3.3.3. Second step: schemas in "patternProperties"

For each regex in "pp", if it matches "m" successfully, the corresponding schema in "patternProperties" is added to "s".

8.3.3.4. Third step: "additionalProperties"

The schema defined by "additionalProperties" is added to "s" if and only if, at this stage, "s" is empty.

Trying to simplify this;

When 'additionalProperties' is false.

The name of every member in the instance object must for full at least on of the following;

  • Match a name in 'properties' keyword
  • Match against a regular expression given by the name of a member in 'patternProperties'.

Furthermore:

If the instance object's member matches by name against a member in 'properties' then the instance value must validate against the corresponding schema.

If the instance object's member matches the regular expression given by the name of a member in 'patternProperties' then the instance value must validate against the corresponding schema.

When 'additionalProperties' is true or absent.

The instance object places no restriction on the names of the members it contains.

But:

If the instance object's member matches by name against a member in 'properties' then the instance value must validate against the corresponding schema.

If the instance object's member matches the regular expression given by the name of a member in 'patternProperties' then the instance value must validate against the corresponding schema.

When 'additionalProperties' is a schema.

The instance object places no restriction on the names of the members it contains.

But:

If the instance object's member matches by name a member in 'properties' then the instance value must validate against the corresponding schema.

If the instance object's member matches the regular expression given by the name of a member in 'patternProperties' then the instance value must validate against the corresponding schema.

The value of any instance object members whose name did not match against 'properties' or 'patternProperties' must validate against the schema contained in 'additionalProperties'.

Graphical Representation

The UI simplifies the properties and displays them in a logical way, but if you are already familiar with the JSON standard this section describes how the UI is mapped from the source.

Additional Properties is false

Sample Json Schema Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "My schema",
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "MyBooleanProperty": {
            "type": "boolean"
        },
        "MyArrayProperty": {
            "type": "array"
        }
    },
    "patternProperties": {
        "MyStringProperty[0-9]*": {
            "type": "string"
        }
    }
}

Shown graphically this looks like this

When 'additionalProperties' is set to false it does not appear in the properties container.

To add the 'additionalProperties' keyword back into the schema you can use the 'Add Properties -> Additional Properties' command from the context menu in the parent schema or the properties container (this will give the schema below).

Additional Properties is true

Sample Json Schema Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "My schema",
    "type": "object",
    "additionalProperties": true,
    "properties": {
        "MyBooleanProperty": {
            "type": "boolean"
        },
        "MyArrayProperty": {
            "type": "array"
        }
    },
    "patternProperties": {
        "MyStringProperty[0-9]*": {
            "type": "string"
        }
    }
}

Shown graphically this looks like this

The <Additional Properties> node would also be displayed the same way if the 'additionalProperties' keyword was missing (as it defaults to true).

Converting 'additionaProperties' back to 'false' can be done by deleting it from the diagram.

To remove the 'additionaProperties' from the schema you can set the "IsExplicit" property to false. The schema will be still rendered the same, but the property will be omitted from the schema (as it defaults to true the meaning does not change)

To make the 'additionalProperties' into a schema, you can either add child properties or array items to it, change its type or set "Convert to schema" to true in the properties grid (if we set its type to Number, we get the schema below).

Additional Properties contains a schema

Sample Json Schema Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "My schema",
    "type": "object",
    "additionalProperties": {
        "type": "number"
    },
    "properties": {
        "MyBooleanProperty": {
            "type": "boolean"
        },
        "MyArrayProperty": {
            "type": "array"
        }
    },
    "patternProperties": {
        "MyStringProperty[0-9]*": {
            "type": "string"
        }
    }
}

Shown graphically this looks like this

The <Additional Properties> entry now holds a schema and can be edited as any other schema.

To make the 'additionalItems' to false, you can just delete it.

To make the 'additionalItems' to true, you can must delete it and re-add Additional Properties'

See Also

MaxProperties
MinProperties
Pattern Properties
Properties
Required


Default
JSON Schema Editor > Keywords > Default

Glossary Item Box

Validation

There are no restrictions placed on the value of this keyword. It may contain any valid JSON item (array, number string etc).

This keyword can be used to supply a default JSON value associated with a particular schema.

See Also

Keywords
Description
Enum
ID
Title
Type


Description
JSON Schema Editor > Keywords > Description

Glossary Item Box

Validation

The 'description' provides an explanation about the purpose of the instance described by this schema.

The property is optional and does not affect the validation, it exists to a human readable explanation of the schema.

Graphical Representation

The property is represented in line within the diagram, properties with the icon [image].

The properties are also shown in the property grid when the containing schema is selected.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

The Description field can also be edited via the Documentation window when a documentable object is selected in the diagram.

See Also

Keywords
Default
Enum
ID
Title
Type


Enum
JSON Schema Editor > Keywords > Enum

Glossary Item Box

Validation

An array of unique Json elements. If the 'enum' property is specified then it must contain at lease one element. Elements in the array MAY be of any type, including null.

An instance validates successfully against this property if its value is equal to one of the elements in this array.

Put simply the instance value for this schema must be one of the values in the 'enum' property.

See Also

Keywords
Default
Description
ID
Title
Type


ExclusiveMaximum
JSON Schema Editor > Keywords > ExclusiveMaximum

Glossary Item Box

Validation

The 'exclusiveMaximum' keyword must is a boolean.

If "exclusiveMaximum" is not present, or has boolean value false, then the instance is valid if it is lower than, or equal to, the value of "maximum";

If "exclusiveMaximum" has boolean value true, the instance is valid if it is strictly lower than the value of "maximum".

If "exclusiveMaximum" is present, "maximum" MUST also be present.

Its default is false.

Graphical Representation

The constraint is represented in line within the diagram, properties with the icon [image] apply to instance array values.

Constraints are also shown in the property grid when the containing schema is selected.

If the schema is not allowed to contain an array value, then the constraint is ignored and not shown in the property grid.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

ExclusiveMinimum
Maximum
Minimum
MultipleOf


ExclusiveMinimum
JSON Schema Editor > Keywords > ExclusiveMinimum

Glossary Item Box

Validation

The 'exclusiveMinimum' keyword must is a boolean.

If "exclusiveMinimum" is not present, or has boolean value false, then the instance is valid if it is greater than, or equal to, the value of "minimum";

If "exclusiveMinimum" has boolean value true, the instance is valid if it is strictly greater than the value of "minimum".

If "exclusiveMinimum" is present, "minimum" MUST also be present.

Its default is false.

Graphical Representation

The constraint is represented in line within the diagram, properties with the icon [image] apply to instance array values.

Constraints are also shown in the property grid when the containing schema is selected.

If the schema is not allowed to contain an array value, then the constraint is ignored and not shown in the property grid.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

ExclusiveMaximum
Maximum
Minimum
MultipleOf


ID
JSON Schema Editor > Keywords > ID

Glossary Item Box

Validation

The value for this keyword MUST be a string, and MUST be a valid URI. This URI MUST be normalized, and SHOULD NOT be an empty fragment (#) or the empty URI.

The 'id' property changes the current resolution scope.

Typically it is only used on the root schema in order to place everything within that schema within a specified scope.

The subtleties of this attribute are beyond the scope of this documentation and only hinted at within the Json schema standard.

It is not recommended that it is used outside of the root schema.

If its is used outside the root schema, then it is recommended that you do a lot more reading on its implications and effects, as it can be a source of errors and inconsistent behavior in validating JSON parsers.

See The id conundrum, Understanding Json Schema

Graphical Representation

The property is represented in line within the diagram, properties with the icon [image].

The properties are also shown in the property grid when the containing schema is selected.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

Keywords
Default
Description
Enum
Title
Type

JSON Schema Editor
Reference Resolution


Items
JSON Schema Editor > Keywords > Items

Glossary Item Box

Validation

5.3.1.1. Valid values

The value of "additionalItems" MUST be either a boolean or an object. If it is an object, this object MUST be a valid JSON Schema.

The value of "items" MUST be either an object or an array. If it is an object, this object MUST be a valid JSON Schema. If it is an array, items of this array MUST be objects, and each of these objects MUST be a valid JSON Schema.

5.3.1.2. Conditions for successful validation

Successful validation of an array instance with regards to these two keywords is determined as follows:

if "items" is not present, or its value is an object, validation of the instance always succeeds, regardless of the value of "additionalItems";

if the value of "additionalItems" is boolean value true or an object, validation of the instance always succeeds;

if the value of "additionalItems" is boolean value false and the value of "items" is an array, the instance is valid if its size is less than, or equal to, the size of "items".

5.3.1.4. Default values

If either keyword is absent, it may be considered present with an empty schema.

8.2.3.1. If "items" is a schema

If items is a schema, then the child instance must be valid against this schema, regardless of its index, and regardless of the value of "additionalItems".

8.2.3.2. If "items" is an array

In this situation, the schema depends on the index:

if the index is less than, or equal to, the size of "items", the child instance must be valid against the corresponding schema in the "items" array;

otherwise, it must be valid against the schema defined by "additionalItems".

Graphical Representation

As you can see from the Json Schema spec (above), the rules resulting from the combination of 'additionalItems' and 'items' keywords are quite complex and not at all intuitive.

In order to make the user interface intuitive and simple to use these values are encapsulated into "Array Items Container".

As you can see you get some unexpected results, which would be difficult to spot without a UI representation, for example the first item sets additionItems to false and has no value for items, intuitively you would expect this to disallow array items, but reading through the rules above you see that it allows anything.

Schema Source Code Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "title": "My schema",
    "additionalProperties": false,
    "properties": {
        "ItemsNullAdditionalItemsFalse": {
            "type": "array",
            "additionalItems": false
        },
        "ItemsNullAdditionalItemsTrue": {
            "type": "array",
            "additionalItems": true
        },
        "ItemsNullAdditionalItemsNull": {
            "type": "array"
        },
        "ItemsNullAdditionalItemsSchema": {
            "type": "array",
            "additionalItems": {
                "type": "string",
                "maxLength": 5
            }
        },
        "ItemsSchemaAdditionalItemsFalse": {
            "type": "array",
            "additionalItems": false,
            "items": {}
        },
        "ItemsSchemaAdditionalItemsTrue": {
            "type": "array",
            "additionalItems": true,
            "items": {}
        },
        "ItemsSchemaAdditionalItemsNull": {
            "type": "array",
            "items": {}
        },
        "ItemsSchemaAdditionalItemsSchema": {
            "type": "array",
            "additionalItems": {
                "type": "string",
                "maxLength": 5
            },
            "items": {}
        },
        "ItemsEmptyArrayAdditionalItemsFalse": {
            "type": "array",
            "additionalItems": false,
            "items": []
        },
        "ItemsEmptyArrayAdditionalItemsTrue": {
            "type": "array",
            "additionalItems": true,
            "items": []
        },
        "ItemsEmptyArrayAdditionalItemsNull": {
            "type": "array",
            "items": []
        },
        "ItemsEmptyArrayAdditionalItemsSchema": {
            "type": "array",
            "additionalItems": {
                "type": "string",
                "maxLength": 5
            },
            "items": []
        },
        "ItemsArrayWithSchemaAdditionalItemsFalse": {
            "type": "array",
            "additionalItems": false,
            "items": [
                {}
            ]
        },
        "ItemsArrayWithSchemaAdditionalItemsTrue": {
            "type": "array",
            "additionalItems": true,
            "items": [
                {}
            ]
        },
        "ItemsArrayWithSchemaAdditionalItemsNull": {
            "type": "array",
            "items": [
                {}
            ]
        },
        "ItemsArrayWithSchemaAdditionalItemsSchema": {
            "type": "array",
            "additionalItems": {
                "type": "string",
                "maxLength": 5
            },
            "items": [
                {}
            ]
        }
    }
}

Array Item Validation.

The items and additionalItems keywords control what kind of objects can appear in an instance array. They are closely interrelated and subtlety effect the validation applied. Broadly speaking there are 2 types of validation we will call them List and Tuple validation.

Json Schema validators make assumptions about the values of the items and additionalItems keywords

  • If the items keyword is not present it is considered to contain an empty schema (which validates against everything).
  • If the additionalItems keyword is not present or true then it is considered to contain an empty schema (which validates against everything).

List Validation

When List validation is used, a schema is defined and all the objects in the array must validate against this schema. This is the simplest and mostly widely used form of array validation.

List validation is used when the items keyword contains a single schema object.

When this is the case the property additionalItems is ignored.

Json Schema Source Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Users": {
            "additionalItems": false,
            "items": {
                "type": "string"
            },
            "type": "array"
        }
    }
}
Valid Instance Json Document Copy Code
{
    "Users": ["Alice","Bob", "Eve"]
}

Tuple Validation

Tuple validation allows you to provide a schema to validate each item in the instance array.

Tuple validation is used when the items property contains an array of schema objects.

Each item in the items array validates an object in the instance array at the corresponding index.

  • It is acceptable for the instance array to contain less items than are specified in the items array.
  • If the instance array contains more items than their are entries in the items array then the additionalItems keyword affects how these additional items are validated.
    • If the additionalItems keyword is 'true', then any additional array items in the instance array are allowed (regardless of there type or value).
    • If the additionalItems keyword is 'false', then additional array items in the instance array are NOT allowed.
    • If the additionalItems keyword contains a schema, then additional array items in the instance array must validate against this schema.

Tuple Example 1

In this example the schema specifies the schemas for first 3 items in the array, if more than 3 items appear in the instance array then it is an error, however it is acceptable for the array to contain less than 3 items as long as the ones that are present validate against the appropriate schema.

Json Schema Source Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Values": {
            "additionalItems": false,
            "items": [
                { "type": "integer" },
                { "type": "string"  },
                { "type": "boolean" }
            ],
            "type": "array"
        }
    }
}
Valid Instance Json Document Copy Code
{
    "Users": [34, "Bob", true]
}
Valid Instance Json Document (note: it is allowable to miss values off of the end) Copy Code
{
    "Users": [34, "Bob"]
}

Tuple Example 2

In this example the schema is specified for the first 3 items in the array, additionally a schema is provided for any additional array items (note the [3-n] indicator).

The first 3 objects in the instance array must validate against the corresponding schema, but any additional items must validate against the [3-n] schema.

Json Schema Source Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "additionalProperties": false,
    "properties": {
        "Values": {
            "type": "array",
            "additionalItems": {
                "type": "string"
            },
            "items": [
                { "type": "integer" },
                { "type": "string"  },
                { "type": "boolean" }
            ]
        }
    }
}
Valid Instance Json Document Copy Code
{
    "Users": [34, "Bob", true]
}
Valid Instance Json Document (note: it is allowable to miss values off of the end) Copy Code
{
    "Users": [34, "Bob"]
}
Valid Instance Json Document Copy Code
{
    "Users": [34, "Bob", true, "Other1", "Other2"]
}

See Also

AdditionalItems
MaxItems
MinItems
UniqueItems

Notation
Array Item Container
Additional Items
Array Item


Minimum
JSON Schema Editor > Keywords > Minimum

Glossary Item Box

Validation

The 'minimum' keyword must is a Number. Its meaning is modified by the optional 'exclusiveMinimum' keyword.

If "exclusiveMinimum" is not present, or has boolean value false, then the instance is valid if it is greater than, or equal to, the value of "minimum";

If "exclusiveMinimum" has boolean value true, the instance is valid if it is strictly greater than the value of "minimum".

Graphical Representation

The constraint is represented in line within the diagram, properties with the icon [image] apply to instance array values.

Constraints are also shown in the property grid when the containing schema is selected.

If the schema is not allowed to contain an array value, then the constraint is ignored and not shown in the property grid.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

ExclusiveMaximum
ExclusiveMinimum
Maximum
MultipleOf


MinItems
JSON Schema Editor > Keywords > MinItems

Glossary Item Box

Validation

The 'minItems' keyword must be a integer with a value greater than or equal to 0. The constraint ensures the instance array to contains a minimum of 'minItems' items.

Graphical Representation

The constraint is represented in line within the diagram, properties with the icon [image] apply to instance array values.

Constraints are also shown in the property grid when the containing schema is selected.

If the schema is not allowed to contain an array value, then the constraint is ignored and not shown in the property grid.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

AdditionalItems
Items
MaxItems
UniqueItems


MinLength
JSON Schema Editor > Keywords > MinLength

Glossary Item Box

Validation

The value of this keyword MUST be an integer. This integer MUST be greater than, or equal to, 0.

A string instance is valid against this keyword if its length is greater than, or equal to, the value of this keyword.

The length of a string instance is defined as the number of its characters as defined by RFC 4627 [RFC4627].

Graphical Representation

The constraint is represented in line within the diagram, properties with the icon [image] apply to instance string values.

Constraints are also shown in the property grid when the containing schema is selected.

If the schema is not allowed to contain a string value then constraint is ignored, and not shown in the property grid.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

MaxLength
Pattern


MinProperties
JSON Schema Editor > Keywords > MinProperties

Glossary Item Box

Validation

The value of this keyword MUST be an integer. This integer MUST be greater than, or equal to, 0.

An object instance is valid against "minProperties" if its number of properties is greater than, or equal to, the value of this keyword.

Graphical Representation

The constraint is represented in line within the diagram, properties with the icon [image] apply to instance Object values.

Constraints are also shown in the property grid when the containing schema is selected.

If the schema is not allowed to contain an object the constraint is ignored, and not shown in the property grid.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

AdditionalProperties
MaxProperties
Pattern Properties
Properties
Required


Maximum
JSON Schema Editor > Keywords > Maximum

Glossary Item Box

Validation

The 'maximum' keyword must is a Number. Its meaning is modified by the optional 'exclusiveMaximum' keyword.

If "exclusiveMaximum" is not present, or has boolean value false, then the instance is valid if it is lower than, or equal to, the value of "maximum";

If "exclusiveMaximum" has boolean value true, the instance is valid if it is strictly lower than the value of "maximum".

Graphical Representation

The constraint is represented in line within the diagram, properties with the icon [image] apply to instance array values.

Constraints are also shown in the property grid when the containing schema is selected.

If the schema is not allowed to contain an array value, then the constraint is ignored and not shown in the property grid.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

ExclusiveMaximum
ExclusiveMinimum
Minimum
MultipleOf


MaxItems
Send Feedback
JSON Schema Editor > Keywords > MaxItems

Glossary Item Box

Validation

The 'maxItems' keyword must be a integer with a value greater than or equal to 0. The constraint restricts the instance array to containing a maximum of 'maxItems' items.

Graphical Representation

The constraint is represented in line within the diagram, properties with the icon [image] apply to instance array values.

Constraints are also shown in the property grid when the containing schema is selected.

If the schema is not allowed to contain an array value, then the constraint is ignored and not shown in the property grid.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.


MaxLength
JSON Schema Editor > Keywords > MaxLength

Glossary Item Box

The value of this keyword MUST be an integer. This integer MUST be greater than, or equal to, 0.

A string instance is valid against this keyword if its length is less than, or equal to, the value of this keyword.

The length of a string instance is defined as the number of its characters as defined by RFC 4627 [RFC4627].

Graphical Representation

The constraint is represented in line within the diagram, properties with the icon [image] apply to instance string values.

Constraints are also shown in the property grid when the containing schema is selected.

If the schema is not allowed to contain a string value then constraint is ignored, and not shown in the property grid.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

MinLength
Pattern


MaxProperties
JSON Schema Editor > Keywords > MaxProperties

Glossary Item Box

Validation

The value of this keyword MUST be an integer. This integer MUST be greater than, or equal to, 0.

An object instance is valid against "maxProperties" if its number of properties is less than, or equal to, the value of this keyword.

Graphical Representation

The constraint is represented in line within the diagram, properties with the icon [image] apply to instance Object values.

Constraints are also shown in the property grid when the containing schema is selected.

If the schema is not allowed to contain an object the constraint is ignored, and not shown in the property grid.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

AdditionalProperties
MinProperties
Pattern Properties
Properties
Required


MultipleOf
JSON Schema Editor > Keywords > MultipleOf

Glossary Item Box

Validation

The value of "multipleOf" MUST be a JSON number. This number MUST be strictly greater than 0.

A numeric instance is valid against "multipleOf" if the result of the division of the instance by this keyword's value is an integer.

Graphical Representation

The constraint is represented in line within the diagram, properties with the icon [image] apply to instance array values.

Constraints are also shown in the property grid when the containing schema is selected.

If the schema is not allowed to contain an array value, then the constraint is ignored and not shown in the property grid.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

ExclusiveMaximum
ExclusiveMinimum
Maximum
Minimum


Pattern
JSON Schema Editor > Keywords > Pattern

Glossary Item Box

Validation

The value of this keyword MUST be a string. This string SHOULD be a valid regular expression, according to the ECMA 262 regular expression dialect.

A string instance is considered valid if the regular expression matches the instance successfully. Recall: regular expressions are not implicitly anchored.

Graphical Representation

The constraint is represented in line within the diagram, properties with the icon [image] apply to instance string values.

Constraints are also shown in the property grid when the containing schema is selected.

If the schema is not allowed to contain a string value then constraint is ignored, and not shown in the property grid.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

MaxLength
MinLength


Pattern Properties
JSON Schema Editor > Keywords > Pattern Properties

Glossary Item Box

Validation

The 'patternProperties' keyword contains 1 or more named schemas, the name of the schema represents a regular expression. The associated schema is used to validate instance members whose names match against the regular expressions.

The names (regular expressions) of the members within the 'patternProperties' collection must be unique.

From the Json Schema Standard Version 4 draft.

5.4.4.1. Valid values

The value of "additionalProperties" MUST be a boolean or an object. If it is an object, it MUST also be a valid JSON Schema.

The value of "properties" MUST be an object. Each value of this object MUST be an object, and each object MUST be a valid JSON Schema.

The value of "patternProperties" MUST be an object. Each property name of this object SHOULD be a valid regular expression, according to the ECMA 262 regular expression dialect. Each property value of this object MUST be an object, and each object MUST be a valid JSON Schema.

5.4.4.3. Default values

Successful validation of an object instance against these three keywords depends on the value of "additionalProperties":

if its value is boolean true or a schema, validation succeeds;

if its value is boolean false, the algorithm to determine validation success is described below.

5.4.4.4. If "additionalProperties" has boolean value false

In this case, validation of the instance depends on the property set of "properties" and "patternProperties". In this section, the property names of "patternProperties" will be called regexes for convenience.

The first step is to collect the following sets:

s
The property set of the instance to validate.
p
The property set from "properties".
pp
The property set from "patternProperties".

Having collected these three sets, the process is as follows:

remove from "s" all elements of "p", if any;

for each regex in "pp", remove all elements of "s" which this regex matches.

Validation of the instance succeeds if, after these two steps, set "s" is empty.

8.3.2. Implied keywords

The three keywords implied in this calculation are "properties", "patternProperties" and "additionalProperties".

If "properties" or "patternProperties" are absent, they are considered present with an empty object as a value.

If "additionalProperties" is absent, it is considered present with an empty schema as a value. In addition, boolean value true is considered equivalent to an empty schema.

8.3.3. Calculation

8.3.3.1. Names used in this calculation

The calculation below uses the following names:

m
The property name of the child.
p
The property set from "properties".
pp
The property set from "patternProperties". Elements of this set will be called regexes for convenience.
s
The set of schemas for the child instance.

8.3.3.2. First step: schemas in "properties"

If set "p" contains value "m", then the corresponding schema in "properties" is added to "s".

8.3.3.3. Second step: schemas in "patternProperties"

For each regex in "pp", if it matches "m" successfully, the corresponding schema in "patternProperties" is added to "s".

8.3.3.4. Third step: "additionalProperties"

The schema defined by "additionalProperties" is added to "s" if and only if, at this stage, "s" is empty.

Trying to simplify this;

When 'additionalProperties' is false.

The name of every member in the instance object must for full at least on of the following;

  • Match a name in 'properties' keyword
  • Match against a regular expression given by the name of a member in 'patternProperties'.

Furthermore:

If the instance object's member matches by name against a member in 'properties' then the instance value must validate against the corresponding schema.

If the instance object's member matches the regular expression given by the name of a member in 'patternProperties' then the instance value must validate against the corresponding schema.

When 'additionalProperties' is true or absent.

The instance object places no restriction on the names of the members it contains.

But:

If the instance object's member matches by name against a member in 'properties' then the instance value must validate against the corresponding schema.

If the instance object's member matches the regular expression given by the name of a member in 'patternProperties' then the instance value must validate against the corresponding schema.

When 'additionalProperties' is a schema.

The instance object places no restriction on the names of the members it contains.

But:

If the instance object's member matches by name a member in 'properties' then the instance value must validate against the corresponding schema.

If the instance object's member matches the regular expression given by the name of a member in 'patternProperties' then the instance value must validate against the corresponding schema.

The value of any instance object members whose name did not match against 'properties' or 'patternProperties' must validate against the schema contained in 'additionalProperties'.

See Also

AdditionalProperties
MaxProperties
MinProperties
Properties
Required


Properties
JSON Schema Editor > Keywords > Properties

Glossary Item Box

Validation

The 'properties' keyword contains 1 or more named schemas, the name of the schema represents the name of a member in the instance object. The associated schema is used to validate instance members whose names match.

The names of the members within the 'properties' collection must be unique.

From the Json Schema Standard Version 4 draft.

5.4.4.1. Valid values

The value of "additionalProperties" MUST be a boolean or an object. If it is an object, it MUST also be a valid JSON Schema.

The value of "properties" MUST be an object. Each value of this object MUST be an object, and each object MUST be a valid JSON Schema.

The value of "patternProperties" MUST be an object. Each property name of this object SHOULD be a valid regular expression, according to the ECMA 262 regular expression dialect. Each property value of this object MUST be an object, and each object MUST be a valid JSON Schema.

5.4.4.3. Default values

Successful validation of an object instance against these three keywords depends on the value of "additionalProperties":

if its value is boolean true or a schema, validation succeeds;

if its value is boolean false, the algorithm to determine validation success is described below.

5.4.4.4. If "additionalProperties" has boolean value false

In this case, validation of the instance depends on the property set of "properties" and "patternProperties". In this section, the property names of "patternProperties" will be called regexes for convenience.

The first step is to collect the following sets:

s
The property set of the instance to validate.
p
The property set from "properties".
pp
The property set from "patternProperties".

Having collected these three sets, the process is as follows:

remove from "s" all elements of "p", if any;

for each regex in "pp", remove all elements of "s" which this regex matches.

Validation of the instance succeeds if, after these two steps, set "s" is empty.

8.3.2. Implied keywords

The three keywords implied in this calculation are "properties", "patternProperties" and "additionalProperties".

If "properties" or "patternProperties" are absent, they are considered present with an empty object as a value.

If "additionalProperties" is absent, it is considered present with an empty schema as a value. In addition, boolean value true is considered equivalent to an empty schema.

8.3.3. Calculation

8.3.3.1. Names used in this calculation

The calculation below uses the following names:

m
The property name of the child.
p
The property set from "properties".
pp
The property set from "patternProperties". Elements of this set will be called regexes for convenience.
s
The set of schemas for the child instance.

8.3.3.2. First step: schemas in "properties"

If set "p" contains value "m", then the corresponding schema in "properties" is added to "s".

8.3.3.3. Second step: schemas in "patternProperties"

For each regex in "pp", if it matches "m" successfully, the corresponding schema in "patternProperties" is added to "s".

8.3.3.4. Third step: "additionalProperties"

The schema defined by "additionalProperties" is added to "s" if and only if, at this stage, "s" is empty.

Trying to simplify this;

When 'additionalProperties' is false.

The name of every member in the instance object must for full at least on of the following;

  • Match a name in 'properties' keyword
  • Match against a regular expression given by the name of a member in 'patternProperties'.

Furthermore:

If the instance object's member matches by name against a member in 'properties' then the instance value must validate against the corresponding schema.

If the instance object's member matches the regular expression given by the name of a member in 'patternProperties' then the instance value must validate against the corresponding schema.

When 'additionalProperties' is true or absent.

The instance object places no restriction on the names of the members it contains.

But:

If the instance object's member matches by name against a member in 'properties' then the instance value must validate against the corresponding schema.

If the instance object's member matches the regular expression given by the name of a member in 'patternProperties' then the instance value must validate against the corresponding schema.

When 'additionalProperties' is a schema.

The instance object places no restriction on the names of the members it contains.

But:

If the instance object's member matches by name a member in 'properties' then the instance value must validate against the corresponding schema.

If the instance object's member matches the regular expression given by the name of a member in 'patternProperties' then the instance value must validate against the corresponding schema.

The value of any instance object members whose name did not match against 'properties' or 'patternProperties' must validate against the schema contained in 'additionalProperties'.

See Also

AdditionalProperties
MaxProperties
MinProperties
Pattern Properties
Required


Required
JSON Schema Editor > Keywords > Required

Glossary Item Box

Validation

An array of strings, each string names a property that must exit within the instance object.

An object instance is valid against this keyword if its property set contains all elements in this array.

The property names within this array do not have to be listed in the 'properties' keyword, they could be valid because they are allowable due to a value in the patternProperties or addittionalProperties.

The list of required properties is not directly exposed via the UI, but can still be manipulated.

Required properties that exist within the 'properties' collection are shown with a solid line around them.

Required property is defined in 'properties' Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalProperties": false,
    "properties": {
        "OptionalProperty": {
            "type": "integer"
        },
        "RequiredProperty": {
            "type": "string"
        }
    },
    "required": [
        "RequiredProperty"
    ]
}

They can be made optional or required using the cardinality right click menu

The property must still exist within the instance object, but must validate against a 'patternProperty' or the 'additionalProperties' keywords.

When a property name exists within 'required' properties list, but does not exist in the properties, then it is shown in the user interface as an required property.

Required property is NOT defined in 'properties' Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalItems": false,
    "required": [
        "UndefinedProperty"
    ]
}

Required properties can be added via the properties right click menu

A required property can be converted into an actual property using the Property Window 'Convert to Property' setting.

See Also

AdditionalProperties
MaxProperties
MinProperties
Pattern Properties
Properties


Title
JSON Schema Editor > Keywords > Title

Glossary Item Box

Validation

The 'title' provides a short explanation about the purpose of the instance described by this schema.

The property is optional and does not affect the validation, it exists to provide a human readable explanation of the schemas purpose.

Graphical Representation

The property is represented in line within the diagram, properties with the icon [image].

The properties are also shown in the property grid when the containing schema is selected.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

Keywords
Default
Description
Enum
ID
Type


Type
JSON Schema Editor > Keywords > Type

Glossary Item Box

Validation

The value of this keyword MUST be either a string or an array. If it is an array, elements of the array MUST be strings and MUST be unique.

String values MUST be one of the seven primitive types defined by the core specification ("array", "boolean", "integer", "number", "null", "object", "string").

An instance matches successfully if its primitive type is one of the types defined by keyword. Recall: "number" includes "integer".

Graphical Representation

You can easily tell the type of a schema object as its displayed within the node as an icon, and as text (unless it is a reference to another type).

Icon | Description
 | The data type is any, i.e. any one of the primitive types "array", "boolean", "integer", "number", "null", "object", "string".
 | The data type is an array.
 | The data type is a boolean (true/false).
 | The data type is an integer.
 | The data type is a null (the text null in the instance document).
 | The data type is a number (integer or real number).
 | The data type is an object.
 | The data type is a string.
 | The data type is union of 2 or more types.
 | The data type is unknown, it either contains an invalid value or can not be determined as the referenced type can not be resolved.

When the schema contains a reference, the reference id is shown not the type, but the icon still reflects the type. In this case a string.

When the type is changed any keywords that no longer apply are removed.

For example if a schema object is of type any and contains 'properties'. If the type is changed to string, then the 'properties' are automatically removed as the are not used for validating a string.

See Also

Keywords
Default
Description
Enum
ID
Title


UniqueItems
JSON Schema Editor > Keywords > UniqueItems

Glossary Item Box

Validation

The 'uniqueItems' keyword is a boolean. If the constraint is true, then all items in the instance array must be unique.

Its default is false.

Graphical Representation

The constraint is represented in line within the diagram, properties with the icon [image] apply to instance array values.

Constraints are also shown in the property grid when the containing schema is selected.

If the schema is not allowed to contain an array value, then the constraint is ignored and not shown in the property grid.

The constraint values are also shown on the tooltips (select and hover over an item in the diagram).

Editing

Its value can be edited in the following ways

  • In place on the schema object by expanding the properties and clicking on it once it is already selected.
  • Edited via the properties window when the containing schema is selected
  • Edited directly in the Json Source view.

It can be deleted by selecting it and pressing delete, or right clicking it an pressing delete.

See Also

AdditionalItems
Items
MaxItems
MinItems


Schema Design Guidelines
Send Feedback
JSON Schema Editor > Schema Design Guidelines

Glossary Item Box

The following topic lays out some basic design advice, as with all things not all of it should be applied rigidly, but an understanding of some of the pitfalls behind some approaches is always useful.

Show Keep it simple, this ones important so again, keep is simple

If you can achieve your goals using basic constructs, then do so. Do not feel just because some aspect of the schema standard exists it should be used.

The further you venture from the basic constructs the more likely you are to find bugs and ambiguity in the parser and validator implementations.

The core constructs will cover the majority of cases, using more advanced features like the Schema Dependencies, id's, AnyOf, AllOf, OneOf, Not, Implied Properties should be undertaken with clear understanding of how they work and what you are trying to achieve. They complicate schemas and make them much more difficult for a user to understand. That's not to say they can't be used, but make sure the additional complexity is worth it.

And keep in mind you are unlikely to be able to capture 100% of the rules relating to your data within your schema regardless of how complex you make it, so its often better to keep it simple and add more documentation of explain any quirks.

Show A schema should have a single data type

If the 'type' keyword is not specified it defaults to 'any' allowing it to contain any data type, ("array", "boolean", "integer", "number", "null", "object", "string").

This is rarely desirable, and means that the value in the instance document can be very different from the value that was envisaged.

For example you may create a schema, give the schema some child properties, but leave its type empty (so it defaults to any), the instance object could contain all the values you specified, alternatively it could contain a string (which is unlikely to be what you intended).

You also get readability issues, the 'Any' property in the diagram although obvious only hints at the implications. Furthermore if an object us given both properties and array items, the implication to a user unfamiliar with the Json Schema standard is that the instance object will contain both the items and properties (not one or the other in the instance document).

Finally, the consumer of your schema must eventually produce code that will deal with the data it describes. If they have to be continually checking the type of the data then the code becomes more verbose less readable and more error prone. Much of this kind of validation can be pushed of to a validating Json parser if the schema is better typed.

So to summarize, there are legitimate reasons to produce a schema based on the union of two or more types, but on the whole it adds complexity and is error prone.

Show Keep references simple

Reusable schema definitions should be placed in the root schemas definitions section and nowhere else.

References should only reference schemas within the definitions section.

The Json schema is pretty lax when it comes to structuring references ($ref), as a result it allows schemas to be referenced from pretty much anywhere. This is not a good thing! It makes reading the schemas complex is also error prone.

Show Rules regarding the 'id' keyword.

The 'id' keyword opens up a whole can of worms, its recommended that if it is used it should only be used on the root schema and contain an absolute URI.

If it is used elsewhere then the following recommendations should be followed.

id in root schemas

  • In root schemas, id MUST be absolute. It MUST have no, or an empty, fragment part.
  • Implementations SHOULD ignore the value of id if the rules above are not met.
  • If the schema has been loaded from another URI than the one mentioned in id, implementations SHOULD consider that the schema URI is the loading URI, not the one in id.

id in subschemas

  • In subschemas, id MUST be a fragment only URI. The fragment MUST NOT be empty, and MUST NOT start with a solidus (/) [this is to avoid conflicts with JSON Pointer].
  • The same id MUST NOT be used twice in a same schema.
  • Implementations MUST raise an exception if the rules above are not met.

For a full discussion of this have a look at Francis Galiegue's article The "id" conundrum

Show Names should (no MUST) be unique

The Json & Json Schema are very vague about what to do with duplicate names within an object. This ambiguity this leads to is potential bugs and security issues, so we have taken the approach of preventing duplicate names and treating them as errors if they are encountered.

You should carry this through into your Json documents.

Their is a lot of discussion threads dedicated to this issue, form more information of this a simple Google search will provide more information.


Text Editor
Send Feedback

Glossary Item Box

The Text Editor allows unformatted documents to be viewed and edited.


WSDL Editor Overview

Glossary Item Box

The WSDL editor abstracts much of the complexity of the WSDL standard, presenting structure of the WSDL without showing the unnecessary complexity. This provides a view that makes understanding and editing the your WSDL document simple. Access to the full range of related facets is available via the properties window and the WSDL can be edited directly within the Source view.

See Also

WSDL Graphical Notation Guide
Graphical Notation Overview


Graphical Notation Overview
Send Feedback
WSDL Editor > Graphical Notation Overview

Glossary Item Box

Liquid XML Studio provides a graphical visualization of your WSDL document using the following graphical notations:

Binding
Fault Binding
Input Binding
Message
Message Part
Operation
Operation Binding
Operation Fault
Operation Input
Operation Output
Output Binding
Port
Port Type
Service
WSDL Definitions


Binding
Send Feedback
WSDL Editor > Graphical Notation Overview > Binding

Glossary Item Box

Graphical Representation

Summary

The Binding element contains binding definitions for binding a protocol such as SOAP or HTTP to a Port Type via the 'type' attribute in the WSDL.

Creating

A Binding can be added as a root level item. This can be done using the right click context menu.

Properties

Name - The name of the Binding, used in the 'binding' attribute of Port.
Port Type - The Port Type to bind against.
Protocol - The protocol extension to bind. Supported extensions are: HTTP GET, HTTP POST, SOAP and SOAP 1.2.
Required - Indicates whether the Extension is necessary for the action to which it refers.

SOAP Extension Properties

Style - Specifies the type of SOAP binding to use, can be either 'document' (default value) or 'rpc'.

Transport - The URI with the specification for HTTP transmission of SOAP data.

HTTP Extension Properties

Verb - Indicates whether the HTTP request will be made using the 'GET' or 'POST' method.

Sample

The WSDL code for a simple SOAP Binding to a Port Type named NewPortType:

<binding name="NewBinding" type="tns:NewPortType">

    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" />

    <operation name="NewOperation">

        <soap:operation soapAction="" />

        <input>

            <soap:body />

        </input>

        <output>

            <soap:body />

        </output>

        <fault />

    </operation>

</binding>


Fault Binding
Send Feedback
WSDL Editor > Graphical Notation Overview > Fault Binding

Glossary Item Box

Graphical Representation

Summary

The Fault Binding element contains binding definitions for binding a protocol such as SOAP or HTTP to an Operation Fault.

Creating

A Fault Binding is automatically added when the containing Binding is bound to a Port Type that contains an Operation Fault.

Properties

Required - Indicates whether the Extension is necessary for the action to which it refers.

SOAP Extension Properties

HTTP Extension Properties

Sample

WSDL code showing an Fault Binding in a simple SOAP Binding to a Port Type named NewPortType:

<binding name="NewBinding" type="tns:NewPortType">

    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" />

    <operation name="NewOperation">

        <soap:operation soapAction="" />

        <input>

            <soap:body />

        </input>

        <output>

            <soap:body />

        </output>

        <fault />

    </operation>

</binding>


Input Binding
Send Feedback
WSDL Editor > Graphical Notation Overview > Input Binding

Glossary Item Box

Graphical Representation

Summary

The Input Binding element contains binding definitions for binding a protocol such as SOAP or HTTP to an Operation Input.

Creating

A Input Binding is automatically added when the containing Binding is bound to a Port Type that contains an Operation Input.

Properties

Required - Indicates whether the Extension is necessary for the action to which it refers.

SOAP Extension Properties

Encoding - A string containing a list of space-delimited URIs. The URIs represent the encoding style (or styles) to be used to encode messages within the SOAP body.
Namespace - The URI representing the location of the specifications for encoding of content not specifically defined by the Encoding property.
Parts - Indicates which parts of the transmitted message appear within the SOAP body portion of the transmission.
Parts String- Indicates which parts of the transmitted message appear within the SOAP body portion of the transmission.
Use - Indicates whether the message parts are encoded using specified encoding rules, or define the concrete schema of the message. Value can be 'literal' (default value) or 'encoded'.

HTTP Extension Properties

Sample

WSDL code showing an Input Binding in a simple SOAP Binding to a Port Type named NewPortType:

<binding name="NewBinding" type="tns:NewPortType">

    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" />

    <operation name="NewOperation">

        <soap:operation soapAction="" />

        <input>

            <soap:body />

        </input>

        <output>

            <soap:body />

        </output>

        <fault />

    </operation>

</binding>


Message
Send Feedback
WSDL Editor > Graphical Notation Overview > Message

Glossary Item Box

Graphical Representation

Summary

The Message element provides a common abstraction for messages using XML schema elements and types. Each Message can contain many Message Part child items.

Creating

A Message can be added as a root level item. This can be done using the right click context menu.

Properties

Name - the name of the Message, used in the Operation elements Input, Output and Fault.

Sample

The WSDL code for a Message containing a Message Part:

<message name="NewOutputMessage">

    <part name="OutputMessagePart" element="tns:OutputType" />

</message>


Message Part
Send Feedback
WSDL Editor > Graphical Notation Overview > Message Part

Glossary Item Box

Graphical Representation

Summary

The Message Part element contains attributes that associate a Message with XML schema elements and types.

Creating

A Message Part can be added to a Message using the right click context menu.

Properties

Name - the name of the Message Part.
Type - the XML schema data type.

Sample

The WSDL code for a Message containing a Message Part:

<message name="NewOutputMessage">

    <part name="OutputMessagePart" element="tns:OutputType" />

</message>


Operation
Send Feedback
WSDL Editor > Graphical Notation Overview > Operation

Glossary Item Box

Graphical Representation

Summary

The Operation element represents an abstract function that can used between client and server. It contains Operation Input, Operation Output and Operation Fault elements that define the abstract functions usage.

Creating

An Operation can be added to a Port Type using the right click context menu.

Properties

Name -The name of the Operation.
Operation Type - The type of transmission supported. This is automatically set depending on the parameters specified. Values can be 'Request-response' (input message and output message), 'One-way' (input message only), 'Solicit-response' (output message and input message), or 'Notification' (output message only).

Sample

The WSDL code for a Port Type containing an Operation with an Operation Input, Operation Output and Operation Fault:

<portType name="NewPortType">

    <operation name="NewOperation">

        <input message="tns:NewInputMessage" />

        <output message="tns:NewOutputMessage" />

        <fault message="tns:ErrorMessage" />

    </operation>

</portType>


Operation Binding
Send Feedback
WSDL Editor > Graphical Notation Overview > Operation Binding

Glossary Item Box

Graphical Representation

Summary

The Operation Binding element contains binding definitions for binding a protocol such as SOAP or HTTP to an Operation.

Creating

A Operation Binding is automatically added when the containing Binding is bound to a Port Type that contains an Operation.

Properties

Required - Indicates whether the Extension is necessary for the action to which it refers.

SOAP Extension Properties

Soap Action - The URI for the SOAP Header.
Style - Specifies the type of SOAP binding used. Values can be 'Document' or 'Rpc'.

HTTP Extension Properties

Location - The URL relative to the location specified by the Port.

Sample

WSDL code showing an Operation Binding in a simple SOAP Binding to a Port Type named NewPortType:

<binding name="NewBinding" type="tns:NewPortType">

    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" />

    <operation name="NewOperation">

        <soap:operation soapAction="" />

        <input>

            <soap:body />

        </input>

        <output>

            <soap:body />

        </output>

        <fault />

    </operation>

</binding>


Operation Fault
Send Feedback
WSDL Editor > Graphical Notation Overview > Operation Fault

Glossary Item Box

Graphical Representation

Summary

The Operation Fault element represents an abstract function's usage for an Operation.

Creating

An Operation Fault can be added to a Operation using the right click context menu.

Properties

Message - The Operation Fault's Message.
Name - The name of the Operation Fault.

Sample

The WSDL code for a Port Type containing an Operation with an Operation Input, Operation Output and Operation Fault:

<portType name="NewPortType">

    <operation name="NewOperation">

        <input message="tns:NewInputMessage" />

        <output message="tns:NewOutputMessage" />

        <fault message="tns:ErrorMessage" />

    </operation>

</portType>


Operation Input
Send Feedback
WSDL Editor > Graphical Notation Overview > Operation Input

Glossary Item Box

Graphical Representation

Summary

The Operation Input element represents an abstract function's usage for an Operation.

Creating

An Operation Input can be added to a Operation using the right click context menu.

Properties

Message - The Operation Input's Message.
Name - The name of the Operation Input.

Sample

The WSDL code for a Port Type containing an Operation with an Operation Input, Operation Output and Operation Fault:

<portType name="NewPortType">

    <operation name="NewOperation">

        <input message="tns:NewInputMessage" />

        <output message="tns:NewOutputMessage" />

        <fault message="tns:ErrorMessage" />

    </operation>

</portType>


Operation Output
Send Feedback
WSDL Editor > Graphical Notation Overview > Operation Output

Glossary Item Box

Graphical Representation

Summary

The Operation Output element represents an abstract function's usage for an Operation.

Creating

An Operation Output can be added to a Operation using the right click context menu.

Properties

Message - The Operation Ouput's Message.
Name - The name of the Operation Output.

Sample

The WSDL code for a Port Type containing an Operation with an Operation Input, Operation Output and Operation Fault:

<portType name="NewPortType">

    <operation name="NewOperation">

        <input message="tns:NewInputMessage" />

        <output message="tns:NewOutputMessage" />

        <fault message="tns:ErrorMessage" />

    </operation>

</portType>


Output Binding
Send Feedback
WSDL Editor > Graphical Notation Overview > Output Binding

Glossary Item Box

Graphical Representation

Summary

The Output Binding element contains binding definitions for binding a protocol such as SOAP or HTTP to an Operation Output.

Creating

A Output Binding is automatically added when the containing Binding is bound to a Port Type that contains an Operation Output.

Properties

Required - Indicates whether the Extension is necessary for the action to which it refers.

SOAP Extension Properties

Encoding - A string containing a list of space-delimited URIs. The URIs represent the encoding style (or styles) to be used to encode messages within the SOAP body.
Namespace - The URI representing the location of the specifications for encoding of content not specifically defined by the Encoding property.
Parts - Indicates which parts of the transmitted message appear within the SOAP body portion of the transmission.
Parts String- Indicates which parts of the transmitted message appear within the SOAP body portion of the transmission.
Use - Indicates whether the message parts are encoded using specified encoding rules, or define the concrete schema of the message. Value can be 'literal' (default value) or 'encoded'.

HTTP Extension Properties

Part - The name of the MessagePart to which the MimeContentBinding applies.
Type - Indicates the format of the body of the HTTP transmission.

Sample

WSDL code showing an Output Binding in a simple SOAP Binding to a Port Type named NewPortType:

<binding name="NewBinding" type="tns:NewPortType">

    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" />

    <operation name="NewOperation">

        <soap:operation soapAction="" />

        <input>

            <soap:body />

        </input>

        <output>

            <soap:body />

        </output>

        <fault />

    </operation>

</binding>


Port
Send Feedback
WSDL Editor > Graphical Notation Overview > Port

Glossary Item Box

Graphical Representation

Summary

The Port element is an endpoint for the Web Service and is referenced by an address.

Creating

A Port can be added to a Service using the right click context menu.

Properties

Binding - The Port's Binding.
Name - The name of the Port.
Protocol - The Port's protocol set by the Port's Binding extension.
Required - Indicates whether the Extension is necessary for the action to which it refers.

SOAP Extension Properties

Location - The URI for the Port.

HTTP Extension Properties

Location - The URI for the Port.

Sample

The WSDL code for a simple Service containing a Port bound to a SOAP Binding named NewBinding:

<service name="NewService">

    <port name="NewPort" binding="tns:NewBinding">

        <soap:address location="" />

    </port>

</service>


Port Type
Send Feedback
WSDL Editor > Graphical Notation Overview > Port Type

Glossary Item Box

Graphical Representation

Summary

The Port Type element contains a set of abstract Operations that represent the abstract functions that can used between client and server.

Creating

A Port Type can be added as a root level item. This can be done using the right click context menu.

Properties

Name - The name of the Port Type, used in the type attribute of Binding.

Sample

The WSDL code for a Port Type containing an Operation with an Operation Input, Operation Output and Operation Fault:

<portType name="NewPortType">

    <operation name="NewOperation">

        <input message="tns:NewInputMessage" />

        <output message="tns:NewOutputMessage" />

        <fault message="tns:ErrorMessage" />

    </operation>

</portType>


Service
Send Feedback
WSDL Editor > Graphical Notation Overview > Service

Glossary Item Box

Graphical Representation

Summary

The Service element contains a group of related Ports.

Creating

A Service can be added as a root level item. This can be done using the right click context menu.

Properties

Name - The name of the Service.

Sample

The WSDL code for a simple Service containing a Port bound to a SOAP Binding named NewBinding:

<service name="NewService">

    <port name="NewPort" binding="tns:NewBinding">

        <soap:address location="" />

    </port>

</service>


WSDL Definitions
Send Feedback
WSDL Editor > Graphical Notation Overview > WSDL Definitions

Glossary Item Box

Graphical Representation

Summary

The WSDL Definitions element contains the definition for the whole WSDL. It is the root element in the document, and as such there can be only one instance of it.

The WSDL Definitions can contain global definitions for Service, Binding, Port Type, and Message, along with Types.

Creating

A WSDL Definitions entity is automatically created when you create a new WSDL document.

Properties

Name - The name of the WSDL.
Target Namespace - The XML target namespace attribute of the descriptions tag (cannot be a relative URI).

Sample

The WSDL code for an empty document:

<definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:tns="http://example.com/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" name="WebServiceName" targetNamespace="http://example.com/" xmlns="http://schemas.xmlsoap.org/wsdl/">

    <types>

        <xs:schema elementFormDefault="qualified" targetNamespace="http://example.com/" />

    </types>

</definitions>


WSDL 2 Editor

Glossary Item Box

The WSDL editor abstracts much of the complexity of the WSDL standard, presenting structure of the WSDL without showing the unnecessary complexity. This provides a view that makes understanding and editing the your WSDL document simple. Access to the full range of related facets is available via the properties window and the WSDL can be edited directly within the Source view.

See Also

WSDL Graphical Notation Guide
Graphical Notation Overview


XHTML Editor Overview
Send Feedback

Glossary Item Box

The XHTML Editor allows XHTML documents to be written and validated. The editor provides syntax highlighting and the means to validate the XHTML using the Validate Button ( Validate Button). Validation errors are underlined and reported in the error window.


XML Editor Overview

Glossary Item Box

The XML Editor is a convenient way to edit your XML documents. If your XML Document has a corresponding XML schema that describes it, then you can make use of intellisense and more complete validation.

If your document does not reference a schema explicitly, then you can associate one with it see Associating a schema with your XML Document.

If you don't have a schema, then you can infer one from your sample document and use that, see Inferring and XML Schema (XSD).

If you are using the Visual Studio Plug-in, then the standard XML Editor is used. See Microsoft documentation for this.
Also see Associating a schema with an XML Document in Visual Studio

See Also

Associating a schema with an XML Document
XML Validation
Inferring an XML Schema (XSD)
XML Schema Library
XML Document Graphical View
XML Document Split View
XML Document Text View

Editor
XML Editor Intellisense Options


Associating a schema with an XML Document
Send Feedback
XML Editor > Associating a schema with an XML Document

Glossary Item Box

Validation and Intellisense

For Validation and intellisense to operate correctly XML Studio needs to know the XML Schema that describes your XML Document.

The rules for finding the schema are as follows.

1. Check Schema Location Attributes

If the XML Document contains a schema location attributes (xsi:noNamespaceSchemaLocation or xsi:schemaLocation attributes), then the schemas pointed to are loaded and used for validation and intellisense.

2. Namespace

The namespaces declared in the XML file are used to lookup schemas from the Schema Library. If a namespace in your XML file matches an entry in the schema library then all the schemas for that entry are loaded. You can also add your own entries to the Schema Library.

3. Manually associating schemas

You can manually associate schemas with your XML File. The schemas must been within the Schema Library, these settings are then remembered then next time the XML file is opened. This is particularly useful if your XML file does not contain a target namespace, as automatic matching is therefore not possible.

It is also possible to explicitly exclude schemas from being used. This is useful when dealing with multiple versions of a schema or if intellisense becomes to slow (which can happen when using very large complex schemas).

Manually associating a schema with an XML File

You can control the schemas that are associated with your XML File using the "Xml Document to Schema Mappings" form.

Liquid XML Studio - associating an XML Schema with an XML File

The form show all the schemas that have been added to the Schema Library. At the top of the list are the schemas that have been found in your XML document (i.e. via xsi:noNamespaceSchemaLocation or xsi:schemaLocation attributes). You can add your own entries to the schema library using the Add Button.

Automatic schema selection | Automatic schema selection. If the namespace in the schema entry match the ones in your XML file then this entry will be used. This is the default state for all entries.
Explicitly included schema | Explicitly use schema. The schema is used regardless of whether the namespaces appear in the XML document. This can be useful when associating schemas XML documents that do not contain any namespace information.
Explicitly exluded schema | Don't use Schema. The schema will not be used regardless of whether its namespaces match the XML Document. This is useful when you have several versions of the same schema, and they all have the same namespace, or where the schema is so large intellisense slows down the XML Editor to an unacceptable degree.

Add

Adds a new entry to the Schema Library (global setting)

Remove

Removes an entry Schema Library (global setting)

Reset

Discards all changes you have made to the schema library and resets it to the installation default state (global setting).

Adding a new Schema Entry

New schemas and schema sets can be added to the schema library using the Add button.

Add Schema Library Entry

The new entry must have a unique name and contain at least one schema. The namespace's shown in the list are used to map the XML schema to an XML document. If your schema includes other schemas, then they will automatically be included.

The other entries are for your own use and are optional

Only add in entries for the root schemas. As the matching is done based on namespace, if you explicitly add in common schemas (xlink etc) then this entry will be matched for any XML File containing an xlink namespace, this will slow things down and lead to validation errors.


XML Validation
XML Editor > XML Validation

Glossary Item Box

There are 2 levels of XML validation, well formed, and schema level validation.

Well Formed

This is a basic level of checking and ensures that the document obeys the XML standard (i.e. all the tags are matched and closed etc).

This level of validation is always possible to perform, and certain operations can not be performed until the document is well formed (i.e. Formatting XML, and Inferring an XSD).

Schema Level Validation

This ensures that the structure of the XML document matches that described in an external XML Schema (XSD). In order for this level of validation to be performed, XML Studio must be able to associate an XSD file with the XML document. This can be done in 2 ways via the schemaLocation, or noNamespaceSchemaLocation attributes or via the schema to XML mapping rules See Associating an XML Schema with an XML Document.

You can see the level of validation performed on your XML document by examining the validation confirmation dialog.

Confirmation Dialog when validation is complete

This well tell you the state of the document, and also they schemas used to validate it. Any errors will be shown in the error window.

You can see the XML Schemas that are associated with your XML Document by looking at the properties window.

The xml schema associatied with the XML Document

See Also

XML Editor
Associating a schema with an XML Document
XML Schema Library


Inferring an XML Schema (XSD)
Send Feedback
XML Editor > Inferring an XML Schema (XSD)

Glossary Item Box

If your new to XML schema's or have just been given XML documents which have no underlying XSD, then it is possible to create an XML Schema that describes your data using the XSD Inferrer.

This uses one or more XML documents, and uses them to construct an XML Schema (XSD). Typically the XSD will need a little tweaking before it is exactly what you want, but it is a good starting point.

There are a number of advantages to using an XML Schema.

  • It provides intellisense when editing your XML documents
  • It allows stricter validation when editing your XML documents
  • Validation can be performed prior to an XML document being consumed, which lowers the amount of error handling required in the consuming application (its more acceptable to make assumptions that element will exist etc, as the schema validation has already guaranteed they do).
  • Provides a formal description of your data, this is especially useful when more than one developer/analyst is working on the project.

You can infer an XML Schema by opening up an XML file and selecting the "Infer XML Schema" option ( [image])

Specify the sample XML files that will be used to infer the XSD schema.

The more sample files you have the more accurate the resulting XML Schema.

The second page contains options relating to the inferring process.

Schema Name

The name of the schema that will be produced (there is no need to add the .xsd extension).
If more than 1 schema file needs to be created, then the schema files will be named <Schema Name>1.xsd, <Schema Name>2.xsd etc

Output Directory

The location where your schema file/files will be written.

Encoding

The encoding that will be applied to your XML Schema (UTF-8 or UTF-16 are the most commonly used, only change this if you understand encoding).

Occurrence Options

If the Occurrence property is set to Restricted, the first time elements are encountered in the XML document, the schema declaration is inferred as minOccurs="1".
When attributes are encountered, the schema declaration is inferred as use="required". If the Occurrence property is set to Relaxed, element schema declarations are inferred as minOccurs="0", and attribute schema declarations are inferred as use="optional".

Type Inference Option

If the TypeInference property is set to Relaxed, the inferred type of elements and attributes in the XML document with simple content is always xs:string.
If the TypeInference property is set to Restricted, more specific types are inferred, such as xs:date, xs:decimal, xs:unsignedByte, and so on.


XML Schema Library
XML Editor > XML Schema Library

Glossary Item Box

The XML Schema Library is a global of schemas that the system knows about. Liquid XML Studio comes with a number of installed schemas for all the main standards, you can also add your own entries into the list.

The schemas in the library allow Liquid XML Studio to associate Schemas with XML documents, based on there namespace. Having a schema associated with an XML document enables validation and intellisense for the XML Document.

If you would like us to consider adding your standard to the Schema Library installed with Liquid XML Studio, then please contact us at sales@liquid-technologies.com.

See Also

XML Editor
Associating a schema with an XML Document
XML Validation


Working with large files
Send Feedback
XML Editor > Working with large files

Glossary Item Box

Liquid XML Studio works by loading the documents it is working with into memory. These files are then manipulated within the application, and if necessary written back to the disk. Because of this if you attempt to load very large files into the application you can run into problem with memory and performance. Furthermore some of the features that the editors use mean that the whole document has to be processed before they can be used, this can significantly slow down the user experience when working with large files.

XML Editor

When dealing with XML files some of these issues can me mitigated by turning off some of the XML Editor features.

Their are 3 editor features that can be disabled to improve performance.

When an XML file is loaded some of these features are automatically turned off if the document exceeds certain thresholds. It is possible to turn them back on using the tool bar, but this may detract from the usability of the application.

These can be found on the XML Editor tool bar

Outlining

In order to provide outlining (code folding), the whole document must be parsed at a grammatical level, all changes to the document potentially invalidate this state, so cause the whole document to need re-parsing.

Turning this off provides the biggest performance benefits

Syntax Highlighting

In order to provide syntax highlighting the lexical parser must have reached the point in the document you are viewing. Changes to the top of the document, affect everything below, and so invalidate the state of everything below.

Turning this off can make a large improvements to editing performance

Intellisense

In order to provide intellisense, the XML must be parsed to the point where you are making your changes. If this point is near the top of the file, this can be quite quick, but if you are working at the bottom of the file, then this can take some time to do, making it make your changes.

Turning this off can improve performance when working at the bottom of large files.


XPath Builder
XML Editor > XPath Builder

Glossary Item Box

The XPath builder allows makes it possible to quickly get the XPath expressions that describes a given element within the XML document.

The builder allows filtering rules to be applied at each XML element level, up to the selected element.

Step 1

Select the element in the XML document, using the context (right click) menu select "Build XPath Expression".

XPath Builder - Select Node

Step 2

Change the filters in the query to suite your requirements.

In the example shown below we will only match book elements for a specific ISBN number.

Step 3

Once the expression is accepted, the results of the query are displayed in the XML Editor, using the XPath Query Builder Window.

XPath Builder - Results

It is now possible to change the expression further, and visualize the results.

See Also

XPath Query Builder
XPath Query Builder Window


XML Editor Context Menu
XML Editor > XML Editor Context Menu

Glossary Item Box

This is the context menu used within the XML Editor, it is accessed by right clicking on the XML Editor.

Cut

Cuts the selected text into the clipboard. The text is copied as plain text, and marked up HTML (so it looks good in HTML aware applications like word etc).

Copy

Copies the selected text into the clipboard. The text is copied as plain text, and marked up HTML (so it looks good in HTML aware applications like word etc).

Paste

Pastes the content of clipboard into the XML Editor.

Delete

Deletes the selected text within the XML Editor

Build XPath Expression

Pops up the "XPath Builder" form which makes it simple to get the XPath for the selected XML Element.

Goto Definition

If the XML document is based on an XML Schema (XSD), then this option will take you to the node in the XSD Editor that describes the XML Element.

See Also

XML Editor
XPath Builder
XML Document Text View

XSD Editor
XSD Editor Overview


XML Document Graphical View
XML Editor > XML Document Graphical View

Glossary Item Box

See Also

XML Document Split View
XML Document Text View


XML Document Split View
XML Editor > XML Document Split View

Glossary Item Box

See Also

XML Document Graphical View
XML Document Text View


XML Document Text View
XML Editor > XML Document Text View

Glossary Item Box

See Also

XML Document Graphical View
XML Document Split View


XML Grid - Cut and Paste from Excel
Send Feedback
XML Editor > XML Grid - Cut and Paste from Excel

Glossary Item Box

Its possible to cut and paste data from excel and other grid based applications i.e. SQL Server.Tabular data can only be pasted into the XML Grid, and only into cells which are being viewed in the table layout. The pasted cells overwrite existing cells (as with Excel) so its better to add new data to the end of an existing table.

If the clipboard data contains more columns than are to the right of the target paste point then they are discarded.

If the clipboard data contains more rows than are bellow the target paste point then new rows are inserted.

Step By Step Walk through

Step 1

Open and XML Document

Step 2

Ensure the Design or Split View layout is selected (bottom left of the window)

Step 3

Create a row at the end of the existing data, we will paste our new data over this.

Step 4

Select the data within Excel and copy it to the clipboard (excluding any title rows)

Step 5

Select the first columns in the row we inserted in step 3 and paste the Excel data. New rows will be created for each Excel row.


XQuery Debugger Overview

Glossary Item Box

The XQuery Editor and integrated debugger allows XQuery 1.0 documents to be written validated, and debugged.

The debugger supports step by step debugging, breakpoints, and shows local variables, watch expressions and current call stack.

The debugger toolbar and keyboard shortcuts make it quick and easy to step through your XSLT stylesheet.

Liquid XML Studio XQuery Debugger

Liquid XML Studio currently supports 1 XQuery Engine.

Saxon XQuery 1.0 Engine

Source | Saxonica
Version | Saxon HE 9.2.1.1
Supported Version | XSLT 1.0 & 2.0
Execute Transform | Yes
Debug Transform | Yes

The XQuery expression can be executed or debugged using the Saxon XQuery 1.0 engine.

When debugging the current line of execution is highlighted, break points can be set within the project, watch windows show user defined variables, the call stack can be viewed and variables local to the stack frame can be examined.

See Also

XQuery Debugger
XQuery Debugger Options
XQuery Debugger Walk through
XQuery Debugger Overview
XQuery Debugger Options
XQuery Debugger Walk through

Debugger
Local Variables Window
Watch Window
Breakpoints ToolWindow
Call Stack Window
Options Window
Debugger Toolbar


XQuery Debugger Variable Icons
XQuery Editor/Debugger > XQuery Debugger Variable Icons

Glossary Item Box

The following icons appear within the Debugger Watch and Local Variable windows when the XQuery Debugger is being used.

An Atomic value (i.e an integer, string, date etc)
An Empty Element
An Item (node/element/atomic value etc)
A sequence of items
An XML Attribute
XML CDATA
XML Comment
XML Declaration
XML DocType
XML Document
XML Element
XML Namespace
XML Processing Instruction
XML Text
XML Whitespace
An Argument
Error
Unknown

See Also

XQuery Debugger
XQuery Debugger Options
XQuery Debugger Walk through
XQuery Debugger Overview


XQuery Debugger Options
XQuery Editor/Debugger > XQuery Debugger Options

Glossary Item Box

The debugger options shown are dependant upon the XQuery engine selected.

Currently the only XQuery engine is supported is

  • Saxon HE XQuery 1.0 Engine

Saxon HE XQuery Engine options

Input

Main Module Filename - The XQuery file that will be executed or debugged (read only).

Context Item - The initial context for the XQuery expression, this must be an XML file. XQuery expressions do not have to have an initial context object, but they normally do.

Output

Filename - The filename that the default output file to be written to.

Format - The format of the output file. This affects the validation rules and formatting of the output.

Input Values

Sets parameters within the XQuery expression. The value of the parameter can be a string or XML loaded from a file.
The parameter values can be picked up in the xquery using the directive.

define variable $id  as xs:string external

Parameter Name - The name of the parameter (must match the name attribute in the param directive).

Data Type - The type of data either text or XML data read from a file.

Value - The value either the text literal or the filename, depending on the value of data type

Modules

Allows other XQuery scripts to be imported into the parent script. To do this the filenames must be aliases with a module Url, and then imported like this

module "http://example.com/xquery/library/book"

Module Uri - The alias the XQuery module is known by. This value is used in the module <alias> directive in the XQuery script.

Filename - The filename of the XQuery module to load

Properties

Base Uri - The base URI property is used when resolving relative URIs within a module. For example, the fn:doc function resolves a relative URI using the base URI of the calling module.

Boundary Space - Boundary-space policy controls whether boundary whitespace is preserved by element constructors during processing of the query.] If boundary-space policy is preserve, boundary whitespace is preserved. If boundary-space policy is strip, boundary whitespace is stripped (deleted). A further discussion of whitespace in constructed elements can be found in 3.7.1.4 Boundary Whitespace

Default Collation - The default collation is the collation that is used by functions and operators that require a collation if no other collation is specified. For example, the gt operator on strings is defined by a call to the fn:compare function, which takes an optional collation parameter. Since the gt operator does not specify a collation, the fn:compare function implements gt by using the default collation.

Enabled Optimizations - Turns on/off Saxon performance optimizations. For debugging it is recommended that this be turned off, as the execution path with it turned on can make debugging difficult to understand.

Show whitespace in watch windows - default unchecked, shows/hides whitespace nodes within the Watch and Variable windows. Whitespace nodes are typically not processed within an stylesheet, and thus just clutter up the watch windows.

See Also

XQuery Debugger
XQuery Debugger Walk through
XQuery Debugger Overview

Debugger
Local Variables Window
Watch Window
Breakpoints ToolWindow
Call Stack Window
Options Window
Debugger Toolbar


XQuery Debugger Walk through
XQuery Editor/Debugger > XQuery Debugger Walk through

Glossary Item Box

See Also

XQuery Debugger
XQuery Debugger Options
XQuery Debugger Overview

Debugger
Local Variables Window
Watch Window
Breakpoints ToolWindow
Call Stack Window
Options Window
Debugger Toolbar


XSD Editor Overview

Glossary Item Box

The XSD editor abstracts much of the complexity of the XSD standard, presenting structure of the schema without showing the unnecessary complexity. This provides a view that makes understanding and editing the your schema simple. Access to the full range of related facets is available via the properties window and the XSD can be edited directly within the Source View.

See Also

XML Schema Graphical Notation Guide
Graphical Notation Overview


Graphical Notation Overview
Send Feedback
XSD Editor > Graphical Notation Overview

Glossary Item Box

Liquid XML Studio provides a graphical visualization of your XML Schema using the following graphical notations:

All |
Alternative |
Any |
Any Attribute |
Assert |
Attribute | (Required) (Optional)
Attribute Group Definition |
Attribute Group Reference |
Choice |
ComplexType Definition |
ComplexType Reference |
Element Definition (Child Elements) |
Element Definition (Data) | (required 1-n) (Optional 0-n)
Element Definition (Complex Content) |
Element Reference |
Group Definition |
Group Reference |
Import |
Include |
Key | Key
KeyRef | KeyRef
Notation |
Open Content |
Override |
Redefine |
Schema |
Sequence |
Simple Type |
Unique | Unique


All
XSD Editor > Graphical Notation Overview > All

Glossary Item Box

Show Graphical Representation

Show Summary

The xs:all element is a container for other elements, groups and any's.
An Element for all the child items must appear within the XML document, but they can appear in any order.
In essence this is an unordered container.

Show Creating

An <all> can be added to an element, group or schema object. This can be done using the right click context menu on any of these entities.

Show Properties

Min Occurs | the minimum number of times the elements described in the <all> must appear in the XML Document (default 1).
Max Occurs | The maximum number of times the elements described in the <all> can appear in the XML Document (default 1).
Id | A user defined ID to uniquely identify the entity within the schema

Show Sample

The following XSD code

<xs:element name="MyAllElm">

<xs:complexType>

<xs:all>

<xs:element name="AddressLine1" type="xs:string" />

<xs:element name="ZipCode" type="xs:string" />

</xs:all>

</xs:complexType>

</xs:element>

Will be represented like this

Sample XML would look like this

<?xml version="1.0" encoding="utf-16"?>

<AllElm>

<ZipCode>765755</ZipCode>

<AddressLine1>12 SomePlace St</AddressLine1>

</AllElm>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.

See Also

Element
Element Definition Simple Content

Group
{Group}

Schema
Schema


XsdEditorNotation Alternative
Send Feedback
XSD Editor > Graphical Notation Overview > XsdEditorNotation Alternative

Glossary Item Box

Show Graphical Representation

Show Summary

An xs:element can have a number of xs:alternative's associated with it. When the xml is loaded the 'test' property on each <alternative> is evaluated. If its true then that alternative is used in place of the parent element.

The definition of an xs:alternative is very similar that of an xs:element, however its base type must be a base type of the contained element.

Show Creating

An <alternative> can only be applied to an <element>, this can be done using the right click context menu on any of these entities.

Show Properties

Derived By |
Facets | The facets available depend on the 'type' attribute see Facets for more information.
Id | A user defined ID to uniquely identify the entity within the schema
Test | The test carried out to see if this alternative definition will be applied. An XPath expression.
XPath Default Namespace | The default namespace applied to the 'Test' property

Show Sample

The following XSD code

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
        elementFormDefault="qualified">
    <xs:element name="Example">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="Beverage" type="BeverageType" maxOccurs="unbounded">
                    <xs:alternative test="@current-time &lt;= '12:00:00'" type="MorningBeverage" />
                    <xs:alternative test="@current-time &gt; '12:00:00'" type="AfternoonBeverage" />
                </xs:element>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:complexType name="BeverageType">
        <xs:simpleContent>
            <xs:extension base="xs:string">
                <xs:attribute name="current-time" type="xs:time" use="required" />
            </xs:extension>
        </xs:simpleContent>
    </xs:complexType>
    <xs:complexType name="MorningBeverage">
        <xs:simpleContent>
            <xs:restriction base="BeverageType">
                <xs:simpleType>
                    <xs:restriction base="xs:string">
                        <xs:enumeration value="tea" />
                    </xs:restriction>
                </xs:simpleType>
            </xs:restriction>
        </xs:simpleContent>
    </xs:complexType>
    <xs:complexType name="AfternoonBeverage">
        <xs:simpleContent>
            <xs:restriction base="BeverageType">
                <xs:simpleType>
                    <xs:restriction base="xs:string">
                        <xs:enumeration value="juice" />
                    </xs:restriction>
                </xs:simpleType>
            </xs:restriction>
        </xs:simpleContent>
    </xs:complexType>
</xs:schema>

Will be represented like this

Sample XML would look like this

<?xml version="1.0" encoding="utf-8"?>
<Example>
        <Beverage current-time="08:00:00">tea</Beverage>
        <Beverage current-time="13:00:00">juice</Beverage>

</Example>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Any
Send Feedback
XSD Editor > Graphical Notation Overview > Any

Glossary Item Box

Show Graphical Representation

Show Summary

The xs:any element indicates that the resulting XML document can contain any elements.
There are further restrictions that can be placed on the elements that can appear in the XML document (See properties).
In essence this is a wild card, allowing any elements to appear in the XML document.

Show Creating

An <any> can be added to a compositor or group object. This can be done using the right click context menu on any of these entities.

Show Properties

Min Occurs | The minimum number of times the elements described in the <all> must appear in the XML Document (default 1).
Max Occurs | The maximum number of times the elements described in the <all> can appear in the XML Document (default 1).
Id | A user defined ID to uniquely identify the entity within the schema
Namespace | allows you to specify that the undefined element must belong to the a given namespace. This may be a list of namespace's (space separated). There are also 3 built in values ##any, ##other, ##targetnamespace, ##local. Consult the XSD standard for more information on this.
Process Contents Options are
  • Lax - if there is a schema to validate the element, then it must be valid against it, if there is no schema, then that's OK
  • Strict - There must be a definition for the element available to the parser, and it must be valid against it
  • Skip - no validation is performed - but it must be well formed XML

Show Sample

The following XSD code

<xs:element name="MessageBody">

<xs:complexType>

<xs:sequence>

<xs:any />

</xs:sequence>

</xs:complexType>

</xs:element>

Will be represented like this

Sample XML would look like this

<MessageBody>

<AccountCreationRequest>

<AccountName>Fred</AccountName>

</AccountCreationRequest>

</MessageBody>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Any Attribute
Send Feedback
XSD Editor > Graphical Notation Overview > Any Attribute

Glossary Item Box

Show Graphical Representation

Show Summary

The xs:anyAttribute element indicates that the resulting XML document can contain any attributes.
There are further restrictions that can be placed on the attributes that can appear in the XML document (See properties).
In essence this is a wild card, allowing any element to contain any undefined attributes.

Show Creating

An <anyAttribute> can be added to an element or complexType. This can be done using the right click context menu on any of these entities.

Show Properties

Id | A user defined ID to uniquely identify the entity within the schema
Namespace | Allows you to specify that the undefined attributes must belong to the a given namespace. This may be a list of namespace's (space separated). There are also 3 built in values ##any, ##other, ##targetnamespace, ##local. Consult the XSD standard for more information on this.
Process Contents Options are
  • Lax - if there is a schema to validate the attribute, then it must be valid against it, if there is no schema, then that's OK
  • Strict - There must be a definition for the attribute available to the parser, and it must be valid against it
  • Skip - no validation is performed - but it must be well formed XML

Show Sample

The following XSD code

<xs:element name="AdditionalInfo">

<xs:complexType>

<xs:anyAttribute />

</xs:complexType>

</xs:element>

Will be represented like this

Sample XML would look like this

<AdditionalInfo Height="174" Weight="76" />

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


XsdEditorNotation Assert
Send Feedback
XSD Editor > Graphical Notation Overview > XsdEditorNotation Assert

Glossary Item Box

Show Graphical Representation

Show Summary

When the XML document is loaded the XPath expression in the xs:assert element is evaluated, if it does not evaluate to true, a validation error is raised.

This mechanism provides the ability to provide cross field validation, something that has been lacking in the XSD 1.0 standard.

Show Creating

An xs:assert can be added to the following XSD entities

  • xs:alternative
  • xs:complexType
  • xs:element

This can be done using the right click context menu on any of these entities.

A new facet type called Assertion has also been added to the XSD 1.1 standard. This is functionally the same as <xs:assert> but can also be applied to attributes and simpleTypes.

Show Properties

Id | A user defined ID to uniquely identify the entity within the schema
Test | The XPath expression that must be true for the XML document to be considered valid
XPath Default Namespace | The default namespace used in the XPath expression 'Test'.

Show Sample

The following XSD code

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
        elementFormDefault="qualified">
    <xs:element name="Example">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="paragraph" type="paragraphType" maxOccurs="unbounded" />
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:complexType name="paragraphType" mixed="true">
        <xs:sequence>
            <xs:element name="table" type="xs:string" minOccurs="0" />
            <xs:element name="paragraph" type="paragraphType" minOccurs="0" />
        </xs:sequence>
        <xs:assert test="if (paragraph) then paragraph/preceding-sibling::table else true()" />
    </xs:complexType>
</xs:schema>

Will be represented like this

Sample XML would look like this

<?xml version="1.0" encoding="utf-8"?>
<Example>
    <paragraph>
        <table>Table 1</table>
        <paragraph>Paragraph 1</paragraph>
    </paragraph>

</Example>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Attribute
XSD Editor > Graphical Notation Overview > Attribute

Glossary Item Box

Show Graphical Representation

Show Summary

The xs:attribute element indicates that the parent can/must contain an attribute within the XML document.

Show Creating

An xs:attribute can be added to an xs:element, xs:complexType or xs:attributeGroup. This can be done using the right click context menu on any of these entities and using the menu item Add Child -> Attribute.

Show Properties

Name | The name of the attribute (this is used within the XML document i.e. <Order OrderID="87">).
Type | Describes the type of data contained within the attribute. There are a number of built in types, but you can define your own by defining a <simpleType>.
Facets | The facets available depend on the 'type' attribute see Facets for more information.
Default | The default value given to the attribute. If the attribute is not specified then a parser should use this value in its place (Default and Fixed are mutually exclusive).
Fixed | The value that the attribute has to take (Default and Fixed are mutually exclusive).
Form |
Id | A user defined ID to uniquely identify the entity within the schema
Simple Type Content | Determines the content type of the attribute. If it is Restriction, then the type specified in the Type property can be further restricted by using facets (i.e. you can set value ranges or lengths etc). If its List, then the attribute can contain a space separated list of values (of the type defined in the Type property), the number of items can then be constrained with the MinOccurs and MaxOccurs. If its Union, then the property Union Types, allows you to specify all the types that the attribute may contain (i.e. it could contain a date or a number).
Union Types | Only valid when the Simple Type Content is set to Union. Allows you to provide a list of the types that the attribute can contain.
Use | If the value is Required, then the attribute must appear in the XML document. If its Optional then it may appear, if its Prohibited then it must not appear, this is only applicable when the parent element has been restricted (see <element> and <complexType>)

Show Sample

The following XSD code

<xs:attribute name="OrderID">

<xs:simpleType>

<xs:restriction base="xs:int">

<xs:maxInclusive value="999" />

<xs:minInclusive value="0" />

</xs:restriction>

</xs:simpleType>

</xs:attribute>

Will be represented like this

Sample XML would look like this

<?xml version="1.0" encoding="utf-16"?>

<Order OrderID="87">

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.

See Also

Facets


Attribute Group Definition
Send Feedback
XSD Editor > Graphical Notation Overview > Attribute Group Definition

Glossary Item Box

Show Graphical Representation

Show Summary

The xs:attributeGroup allows you to create groups of attributes that can be used as components inside other elements.
A group can only be defined at the root level (i.e. as a parent of the xs:schema).

Show Creating

A xs:attributeGroup can be added to a xs:schema by right click context menu on the xs:schema item and selecting Add Child -> Attribute Group.

Show Properties

Name | The name the group will be referred to as. This must be unique, and its a good standard to postfix it with 'Group').
Id | A user defined ID to uniquely identify the entity within the schema.

Show Sample

Will be represented like this

XSD Sample Code Copy Code
<xs:attributeGroup name="FullNameGroup">
 <xs:attribute name="Forename" type="xs:string" />
 <xs:attribute name="Middlename" type="xs:string" use="optional" />
 <xs:attribute name="Surname" type="xs:string" />
</xs:attributeGroup>

Will be represented like this

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Attribute Group Reference
Send Feedback
XSD Editor > Graphical Notation Overview > Attribute Group Reference

Glossary Item Box

Show Graphical Representation

Show Summary

The xs:attributeGroup allows you to create groups of attributes that can be used as components inside other elements.
Before you can reference an attribute group, you must define a one at root level (i.e. as a parent of the <xs:schema>.

Show Creating

A reference to a xs:attributeGroup can be created by right clicking on an xs:element or xs:complexType item and selecting Add Child -> Attribute Group . You must then set the type to reference the root level group you have already defined (properties type) or via the drop down in the group box.

Show Properties

Type The name the attribute group that is being referenced. Must correspond to a globally defined attribute group.

Show Sample

The following XSD code

XSD Sample Code Copy Code
<xs:element name="AdditionalInfo">
 <xs:complexType>
  <xs:attributeGroup ref="FullNameGroup" />
 </xs:complexType>
</xs:element>

Will be represented like this

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Choice
Send Feedback
XSD Editor > Graphical Notation Overview > Choice

Glossary Item Box

Graphical Representation

Summary

The <choice> element is a container for other elements, groups and any's.
Only one of the contained entities can appear within the XML document.

Creating

An <choice> can be added to an element, group or schema object. This can be done using the right click context menu on any of these entities.

Properties

Min Occurs - the minimum number of times the elements described in the <choice> must appear in the XML Document (default 1).
Max Occurs - The maximum number of times the elements described in the <choice> can appear in the XML Document (default 1).
Id - A user defined ID to uniquely identify the entity within the schema

Sample

The following XSD code

<xs:element name="ChoiceElm">

<xs:complexType>

<xs:choice>

<xs:element name="FlightNumber" type="xs:string" />

<xs:element name="BusNumber" type="xs:string" />

</xs:choice>

</xs:complexType>

</xs:element>

Will be represented like this

Sample XML would look like this

<?xml version="1.0" encoding="utf-16"?>

<ChoiceElm>

<FlightNumber>3453453453</FlightNumber>

</ChoiceElm>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Complex Type Definition
Send Feedback
XSD Editor > Graphical Notation Overview > Complex Type > Complex Type Definition

Glossary Item Box

Graphical Representation

Summary

The <complexType> allows you to build up re-usable or extendable objects. The Complex Type may contain compositors (<all>, <choice>, <sequence>) as well as <attribute>'s and <attributeGroup>'s.
ComplexTypes can only be defined at global level (as a child of the <schema>). They can then be used as the type for other <element>'s.

Creating

A <complexType> can only be added to the <schema> object. This can be done using the right click context menu Add Child->Complex Type.

Properties

Name - The name the complex type will be referred to as. This must be unique, and its a good standard to postfix it with 'Type').
Type - (optional) It is possible to create a new complex type based on an existing simple or complex type. If you specify an existing type then there are 2 ways that the 'base' type can be interpreted determined by the 'Derived By' property.

Derived By - Only available when the base type is specified. If this is Extension , then the complexType takes all the properties of the 'Type' (elements/attributes etc), and allows a new compositor (<all>, <choice>, <sequence>) and <attribute>'s to be added to it. If the value is Restriction, then the complexType can ONLY contain the elements and attributes defined in the 'Type'. You can not add in elements and attributes that are not defined in the base type.
Abstract - If this is true then it means that the complexType can not be used on its own, it must be extended or restricted before it can be used (See 'Derived By' and 'Type' properties).
Block - Indicates that the type can not be substituted, extended or restricted - see 'Derived By' Property and Substitution Groups on <element>.
Final - .
Id - A user defined ID to uniquely identify the entity within the schema.
Mixed - Indicates if the XML element described by this complexType may contain text interspersed between its child elements (like HTML). It is recommended that is is false, as it makes processing the resulting XML documents more difficult, but it is sometimes necessary to use this.

Sample

The following XSD code

Example Title Copy Code
    <xs:complexType name="AddressType">
        <xs:sequence>
            <xs:element name="Recipient" type="xs:string" />
            <xs:element name="StreetAddress" type="xs:string" />
            <xs:element name="Town" type="xs:string" />
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="USAddressType">
        <xs:complexContent>
            <xs:extension base="AddressType">
                <xs:sequence>
                    <xs:element name="State" type="USStateType" />
                    <xs:element name="ZipCode" type="ZipCodeType" />
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
    <xs:complexType name="InternalOfficeAddress">
        <xs:complexContent>
            <xs:restriction base="AddressType">
                <xs:sequence>
                    <xs:element name="Recipient" type="xs:string" />
                </xs:sequence>
            </xs:restriction>
        </xs:complexContent>
    </xs:complexType>
    <xs:simpleType name="PostcodeType">
        <xs:restriction base="xs:string">
            <xs:pattern value="(GIR 0AA)|((([A-Z-[QVX]][0-9][0-9]?)|(([A-Z-[QVX]][A-Z-[IJZ]][0-9][0-9]?)|(([A-Z-[QVX]][0-9][A-HJKSTUW])|([A-Z-[QVX]][A-Z-[IJZ]][0-9][ABEHMNPRVWXY])))) [0-9][A-Z-[CIKMOV]]{2})" />
        </xs:restriction>
    </xs:simpleType>

Shows the definition of a complex Type.

The complex type UKAddressType Extends the complexType AddressType, note the icon [image].

The complex type UKAddressType Restricts the complexType AddressType, note the icon [image].

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


XsdEditorNotation ComplexType Extension
XSD Editor > Graphical Notation Overview > Complex Type > XsdEditorNotation ComplexType Extension

Glossary Item Box

Graphical Representation

Summary

A new <complexType> can be defined by extending an existing <complexType> and adding additional items <all>, <choice>, <sequence>, <element>, <group>, <attribute>, <attributeGroup>.
ComplexTypes can only be defined at global level (as a child of the <schema>).

The complex type that extends another complexType is given the icon [image].

Creating

A <complexType> can only be added to the <schema> object. This can be done using the right click context menu Add Child->Complex Type.

The ComplexType is automatically turned into an extension when its type is set to another complexTye (in our example AddressType).

Properties

Name - The name the complex type will be referred to as. This must be unique, and its a good standard to postfix it with 'Type').
Type - (optional) It is possible to create a new complex type based on an existing simple or complex type. If you specify an existing type then there are 2 ways that the 'base' type can be interpreted determined by the 'Derived By' property.

Derived By - Only available when the base type is specified. If this is Extension , then the complexType takes all the properties of the 'Type' (elements/attributes etc), and allows a new compositor (<all>, <choice>, <sequence>) and <attribute>'s to be added to it. If the value is Restriction, then the complexType can ONLY contain the elements and attributes defined in the 'Type'. You can not add in elements and attributes that are not defined in the base type.
Abstract - If this is true then it means that the complexType can not be used on its own, it must be extended or restricted before it can be used (See 'Derived By' and 'Type' properties).
Block - Indicates that the type can not be substituted, extended or restricted - see 'Derived By' Property and Substitution Groups on <element>.
Final - .
Id - A user defined ID to uniquely identify the entity within the schema.
Mixed - Indicates if the XML element described by this complexType may contain text interspersed between its child elements (like HTML). It is recommended that is is false, as it makes processing the resulting XML documents more difficult, but it is sometimes necessary to use this.

Sample

The following XSD code

ComplexType Example Copy Code
    <xs:complexType name="AddressType">
        <xs:sequence>
            <xs:element name="House" type="xs:string" />
            <xs:element name="Town" type="xs:string" />
            <xs:element name="Country" type="CountryCodeType" />
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="USAddressType">
        <xs:complexContent mixed="false">
            <xs:extension base="AddressType">
                <xs:sequence>
                    <xs:element name="ZipCode" type="xs:string" />
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
    <xs:complexType name="UKAddressType">
        <xs:complexContent mixed="false">
            <xs:extension base="AddressType">
                <xs:sequence>
                    <xs:element name="PostCode" type="xs:string" />
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
    <xs:simpleType name="CountryCodeType">
        <xs:restriction base="xs:string">
            <xs:enumeration value="FR" />
            <xs:enumeration value="DE" />
            <xs:enumeration value="ES" />
            <xs:enumeration value="UK" />
            <xs:enumeration value="US" />
        </xs:restriction>
    </xs:simpleType>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.

See Also

Complex Type Definition
Complex Type Reference
XsdEditorNotation ComplexType Extension
XsdEditorNotation ComplexType Restriction


XsdEditorNotation ComplexType Restriction
XSD Editor > Graphical Notation Overview > Complex Type > XsdEditorNotation ComplexType Restriction

Glossary Item Box

Graphical Representation

Summary

A new <complexType> can be defined by restricting an existing <complexType>. A restricted complexType must re-declare all of the contained elements that it wants to make available, no new elements can be added. Child elements that are declared may be further restricted in by changing the cardinality, type, facets or fixed values. Conversely any attributes in the base complexType are deemed to be available in the derived type by default, if an attribute needs removing from the restricted type then it must be declared and marked as use=prohibited.

ComplexTypes can only be defined at global level (as a child of the <schema>).

The complex type that restricts another complexType is given the icon [image].

Creating

A <complexType> can only be added to the <schema> object. This can be done using the right click context menu Add Child->Complex Type.

The ComplexType is automatically turned into an extension when its type is set to another complexTye (in our example Employee), to make it a restriction set the property 'Derived By = Restriction'.

Properties

Name - The name the complex type will be referred to as. This must be unique, and its a good standard to postfix it with 'Type').
Type - (optional) It is possible to create a new complex type based on an existing simple or complex type. If you specify an existing type then there are 2 ways that the 'base' type can be interpreted determined by the 'Derived By' property.

Derived By - Only available when the base type is specified. If this is Extension , then the complexType takes all the properties of the 'Type' (elements/attributes etc), and allows a new compositor (<all>, <choice>, <sequence>) and <attribute>'s to be added to it. If the value is Restriction, then the complexType can ONLY contain the elements and attributes defined in the 'Type'. You can not add in elements and attributes that are not defined in the base type.
Abstract - If this is true then it means that the complexType can not be used on its own, it must be extended or restricted before it can be used (See 'Derived By' and 'Type' properties).
Block - Indicates that the type can not be substituted, extended or restricted - see 'Derived By' Property and Substitution Groups on <element>.
Final - .
Id - A user defined ID to uniquely identify the entity within the schema.
Mixed - Indicates if the XML element described by this complexType may contain text interspersed between its child elements (like HTML). It is recommended that is is false, as it makes processing the resulting XML documents more difficult, but it is sometimes necessary to use this.

Sample

The following XSD code

ComplexType Example Copy Code
    <xs:complexType name="Employee">
        <xs:sequence>
            <xs:element name="Name" type="xs:string" />
            <xs:element name="DateOfBirth" type="xs:date" />
            <xs:element name="Salary" type="xs:int" minOccurs="0" />
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="Intern">
        <xs:complexContent>
            <xs:restriction base="Employee">
                <xs:sequence>
                    <xs:element name="Name" type="xs:string" />
                    <xs:element name="DateOfBirth" type="xs:date" />
                </xs:sequence>
            </xs:restriction>
        </xs:complexContent>
    </xs:complexType>

Show Restricted Node Notation

When an item is restricted a template is produced showing all the items (elements, attributes, etc) that have been taken from the base type. Items that have a line through them are not allowed within the resulting type.

Grayed out items are empty placeholders taken from items defined within the base types, clicking the ( [image] icon) will cause its definition to be included into the type, this can then be further restricted using facets, changing the type etc.

Clicking the ( [image] icon) on a restricted child item will cause its definition to be removed from the restricted type.

A line through an item means that it is not available within the restricted type.

By default attributes from the base type are available in the restricted type, to remove them, define them in the restricted type and set 'use=prohibited'.

By default elements from the base type are not part of the restricted type, to include them, then must be defined within the restricted type.

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.

See Also

Complex Type Definition
Complex Type Reference
XsdEditorNotation ComplexType Extension


Complex Type Reference
Send Feedback
XSD Editor > Graphical Notation Overview > Complex Type > Complex Type Reference

Glossary Item Box

Graphical Representation

Summary

The <complexType> allows you to build up re-usable or extendable objects. Before you can reference a Complex Type you must first define one (See Complex Type Definition). A complex Type can be referenced as a 'Type' within an element or another ComplexType definition. Once referenced a complex Type can either be used as is, extended or restricted.

Creating

A <complexType> can be referenced by setting an <element> or a complexTypes'a 'Type' property to the existing complex Type. This can be done via the properties panel or the type drop down in the graphical view.

Sample

The following XSD code

<xs:complexType name="AddressType">

<xs:sequence>

<xs:element name="Line1" type="xs:string" />

<xs:element name="Line2" type="xs:string" />

<xs:element name="Line3" type="xs:string" />

<xs:element name="Country" type="xs:string" />

</xs:sequence>

</xs:complexType>

...

<xs:sequence>

<xs:element name="BillingAddress" type="AddressType" />

<xs:element name="DeliveryAddress" type="AddressType" />

</xs:sequence>

Will be represented like this

Sample XML would look like this

<?xml version="1.0" encoding="utf-16"?>

<Customer>

<BillingAddress>

<Line1>12 SomePlace St</Line1>

<Line2>Some Town</Line2>

<Line3>Some City</Line3>

<Country>UK</Country>

</BillingAddress>

<DeliveryAddress>

<Line1>12 SomePlace St</Line1>

<Line2>Some Town</Line2>

<Line3>Some City</Line3>

<Country>UK</Country>

</DeliveryAddress>

</Customer>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Element Definition Data
Send Feedback
XSD Editor > Graphical Notation Overview > Element > Element Definition Data

Glossary Item Box

Graphical Representation

Summary

The <xs:element> allows you to define an element within the XML document. An element can either be defined globally i.e. as a child of the <xs:schema>, or locally within a compositor (<xs:all>, <xs:choice>, <xs:sequence>). A globally defined <xs:element> can be used as the root element within an XML document, and can also be re-used within the schema. Locally defined elements can only appear within there containing element.

There are a number of forms that an element can take.

  • Data - The element has the type set to an existing simpleType (int, datetime, base64 etc). The resulting XML element then just contains data conforming to the rules given by the data type.
  • Child Elements - The element contains a compositor (<xs:all>, <xs:choice>, <xs:sequence>), and this compositor contains definitions for other child elements.
  • Simple Content - The element extends or restricts an existing type. This can either be a built in type or one defined using the <xs:simpleType>.
  • Complex Content - The element extends or restricts an existing <xs:complexType>.

Depending on the form a given element takes, the properties applicable to it can be greatly changed.

This topic covers the 'Data' form. Typically you can change the form that an element takes by changing the Type property.

Creating

An <xs:element> that extends or restricts an existing <xs:complexType> can be created by selecting a compositor (<xs:all>, <xs:choice>, <xs:sequence>) or <schema> object. Then right clicking and selecting Add Child->Element , the type property can then be set to an existing ComplexType.

Properties

Min Occurs - the minimum number of times the element must appear in the XML Document (default 1).
Max Occurs - The maximum number of times the element can appear in the XML Document (default 1).
Name - The name of the element as it will appear in the XML Document, if the elements parent is <xs:schema> then this name should be unique.
Simple Content Type - Effects the value of the element. In this form the value is None, if the value is anything else then the element is in the SimpleContent form. Other possible values include, Restriction, the type selected is being restricted. The restrictions come in the form of facets. Union, the value can take any valid value from the list of types defined in the Union Types property. List, the value can be a number of valid values for the Type selected. These values are white space separated in the XML document.
Type - The simple type that is being used as the base for this element (only available when the Simple Content Type, is NOT set to union).
Facets - See Facets Information
Abstract - Indicates that the element can not actually appear in the XML document. But can be used as a building block or substitution for other elements.
Block - Indicates that the element can not be substituted, extended or restricted - see 'Derived By' Property and Substitution Groups on <xs:element>.
Default - The default value given to the element. If the element is not specified then a parser should use this value in its place (Default and Fixed are mutually exclusive).
Final - .
Fixed - The value that the element has to take (Default and Fixed are mutually exclusive).
Form -
Id - A user defined ID to uniquely identify the entity within the schema.
Nillable - Indicates that the element in the XML document can be omitted (there are compatibility issues when using this flag and XML Data Binding, for this reason it is best avoided if possible).

Sample

The following XSD code

<xs:element name="Line1" type="xs:string" />

Will be represented like this

Sample XML would look like this

<?xml version="1.0" encoding="utf-16"?>

<Line1>12 SomePlace St</Line1>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Element Definition Child Elements
Send Feedback
XSD Editor > Graphical Notation Overview > Element > Element Definition Child Elements

Glossary Item Box

Graphical Representation

Summary

The <xs:element> allows you to define an element within the XML document. An element can either be defined globally i.e. as a child of the <xs:schema>, or locally within a compositor (<xs:all>, <xs:choice>, <xs:sequence>). A globally defined <xs:element> can be used as the root element within an XML document, and can also be re-used within the schema. Locally defined elements can only appear within there containing element.

There are a number of forms that an element can take.

  • Data - The element has the type set to an existing simpleType (int, datetime, base64 etc). The resulting XML element then just contains data conforming to the rules given by the data type.
  • Child Elements - The element contains a compositor (<xs:all>, <xs:choice>, <xs:sequence>), and this compositor contains definitions for other child elements.
  • Simple Content - The element extends or restricts an existing type. This can either be a built in type of one defined using the <xs:simpleType> construct.
  • Complex Content - The element extends or restricts an existing <xs:complexType>.

Depending on the form a given element takes, the properties applicable to it can be greatly changed.

This topic covers the 'Data' form. Typically you can change the form that an element takes by changing the Type property.

Creating

An <xs:element> can be created by selecting a compositor (<xs:all>, <xs:choice>, <xs:sequence>) or <schema> object. Then right clicking and selecting Add Child->Element , a compositor can then be added to the new element.

Properties

Name - The name the complex type will be referred to as. This must be unique, and its a good standard to postfix it with 'Type').
Type - The type that this element will extend or restrict - in this form this would be empty. If the type was a simple type then the form would be simpleContent, if it were a complex type then the form would be complexContent.
Abstract - Indicates that the element can not actually appear in the XML document. But can be used as a building block or substitution for other elements.
Block - Indicates that the element can not be substituted, extended or restricted - see 'Derived By' Property and Substitution Groups on <xs:element>.
Default - The default value given to the element. If the element is not specified then a parser should use this value in its place (Default and Fixed are mutually exclusive).
Final - .
Fixed - The value that the element has to take (Default and Fixed are mutually exclusive).
Form -
Id - A user defined ID to uniquely identify the entity within the schema.
Nillable - Indicates that the element in the XML document can be omitted (there are compatibility issues when using this flag and XML Data Binding, for this reason it is best avoided if possible).

Sample

The following XSD code

<xs:element name="Address">

<xs:complexType>

<xs:sequence>

<xs:element name="Line1" type="xs:string" />

<xs:element name="Line2" type="xs:string" />

<xs:element name="Postcode" type="xs:string" />

</xs:sequence>

</xs:complexType>

</xs:element>

Will be represented like this

Sample XML would look like this

<?xml version="1.0" encoding="utf-16"?>

<Address>

<Line1>12 SomePlace St</Line1>

<Line2>Some Town</Line2>

<Postcode>HG27JU</Postcode>

</Address>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Element Definition Simple Content
Send Feedback
XSD Editor > Graphical Notation Overview > Element > Element Definition Simple Content

Glossary Item Box

Graphical Representation

Summary

The <xs:element> allows you to define an element within the XML document. An element can either be defined globally i.e. as a child of the <xs:schema>, or locally within a compositor (<xs:all>, <xs:choice>, <xs:sequence>). A globally defined <xs:element> can be used as the root element within an XML document, and can also be re-used within the schema. Locally defined elements can only appear within there containing element.

There are a number of forms that an element can take.

  • Data - The element has the type set to an existing simpleType (int, datetime, base64 etc). The resulting XML element then just contains data conforming to the rules given by the data type.
  • Child Elements - The element contains a compositor (<xs:all>, <xs:choice>, <xs:sequence>), and this compositor contains definitions for other child elements.
  • Simple Content - The element extends or restricts an existing type. This can either be a built in type of one defined using the <xs:simpleType> construct.
  • Complex Content - The element extends or restricts an existing <xs:complexType>.

Depending on the form a given element takes, the properties applicable to it can be greatly changed.

This topic covers the 'Simple Content form. Typically you can change the form that an element takes by changing the Type property.

In this form an element extends or restricts an existing primitive type, this can be one of the built in types (int, datetime, base64 etc), or one you have defined yourself using the <xs:simpleType>.

Note: An element based on a simple type can only contain data and have attributes, it can not have child compositor or elements.

Creating

An <xs:element> that extends or restricts an existing simple type can be created by selecting a compositor (<xs:all>, <xs:choice>, <xs:sequence>) or <schema> object. Then right clicking and selecting Add Child->Element , the type property can then be set to an existing simpleType.

Properties

Min Occurs - the minimum number of times the element must appear in the XML Document (default 1).
Max Occurs - The maximum number of times the element can appear in the XML Document (default 1).
Name - The name of the element as it will appear in the XML Document, if the elements parent is <xs:schema> then this name should be unique.
Simple Content Type - Effects the value of the element. Restriction, the type selected is being restricted. The restrictions come in the form of facets. Union, the value can take any valid value from the list of types defined in the Union Types property. List, the value can be a number of valid values for the Type selected. These values are white space separated in the XML document.
Type - The simple type that is being used as the base for this element (only available when the Simple Content Type, is NOT set to union).
Union Type - The list of types that are valid as values for the element (only available when the Simple Content Type, is set to union).
Facets - See Facets Information
Abstract - Indicates that the element can not actually appear in the XML document. But can be used as a building block or substitution for other elements.
Block - Indicates that the element can not be substituted, extended or restricted - see 'Derived By' Property and Substitution Groups on <xs:element>.
Default - The default value given to the element. If the element is not specified then a parser should use this value in its place (Default and Fixed are mutually exclusive).
Final - .
Fixed - The value that the element has to take (Default and Fixed are mutually exclusive).
Form -
Id - A user defined ID to uniquely identify the entity within the schema.
Nillable - Indicates that the element in the XML document can be omitted (there are compatibility issues when using this flag and XML Data Binding, for this reason it is best avoided if possible).

Sample 1

The following XSD code

<xs:element name="SuitableDates">

<xs:simpleType>

<xs:list itemType="xs:date" />

</xs:simpleType>

</xs:element>

Will be represented like this

Sample XML would look like this (space separated list)

<?xml version="1.0" encoding="utf-16"?>

<SuitableDates>2000-01-12 2000-01-15 2000-01-18</SuitableDates>

Sample 2

The following XSD code

<xs:element name="Line1">

<xs:simpleType>

<xs:restriction base="xs:string">

<xs:maxlength value="40" />

</xs:restriction>

</xs:simpleType>

</xs:element>

Will be represented like this

Sample XML would look like this, where the contents '12 SomePlace St' is not more than 40 chars long.

<?xml version="1.0" encoding="utf-16"?>

<Line1>12 SomePlace St</Line1>

Sample 3

The following XSD code

<xs:element name="Line1">

<xs:simpleType>

<xs:union memberTypes="xs:dateTime xs:int" />

</xs:simpleType>

</xs:element>

Will be represented like this

Sample XML would look like this, where the contents are either a valid int or a valid datetime.

<?xml version="1.0" encoding="utf-16"?>

<Line1>46</Line1>

or

<?xml version="1.0" encoding="utf-16"?>

<Line1>2000-01-12T12:13:14Z</Line1>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Element Definition Complex Content
Send Feedback
XSD Editor > Graphical Notation Overview > Element > Element Definition Complex Content

Glossary Item Box

Graphical Representation

Summary

The <xs:element> allows you to define an element within the XML document. An element can either be defined globally i.e. as a child of the <xs:schema>, or locally within a compositor (<xs:all>, <xs:choice>, <xs:sequence>). A globally defined <xs:element> can be used as the root element within an XML document, and can also be re-used within the schema. Locally defined elements can only appear within there containing element.

There are a number of forms that an element can take.

  • Data - The element has the type set to an existing simpleType (int, datetime, base64 etc). The resulting XML element then just contains data conforming to the rules given by the data type.
  • Child Elements - The element contains a compositor (<xs:all>, <xs:choice>, <xs:sequence>), and this compositor contains definitions for other child elements.
  • Simple Content - The element extends or restricts an existing type. This can either be a built in type or one defined using the <xs:simpleType> construct.
  • Complex Content - The element extends or restricts an existing <xs:complexType>.

Depending on the form a given element takes, the properties applicable to it can be greatly changed.

This topic covers the 'Complex Content' form. Typically you can change the form that an element takes by changing the Type property.

In this form an element extends or restricts an existing <xs:complexType>, in this way the new element can be constructed reusing some common definition.

Creating

An <xs:element> that extends or restricts an existing <xs:complexType> can be created by selecting a compositor (<xs:all>, <xs:choice>, <xs:sequence>) or <schema> object. Then right clicking and selecting Add Child->Element , the type property can then be set to an existing ComplexType.

Properties

Name - The name the complex type will be referred to as. This must be unique, and its a good standard to postfix it with 'Type').
Type - The <xs:complexType> that this element will extend or restrict.
Abstract - Indicates that the element can not actually appear in the XML document. But can be used as a building block or substitution for other elements.
Block - Indicates that the element can not be substituted, extended or restricted - see 'Derived By' Property and Substitution Groups on <xs:element>.
Default - The default value given to the element. If the element is not specified then a parser should use this value in its place (Default and Fixed are mutually exclusive).
Final - .
Fixed - The value that the element has to take (Default and Fixed are mutually exclusive).
Form -
Id - A user defined ID to uniquely identify the entity within the schema.
Nillable - Indicates that the element in the XML document can be omitted (there are compatibility issues when using this flag and XML Data Binding, for this reason it is best avoided if possible).

Sample

The following XSD code

<xs:complexType name="CustomerType">

<xs:sequence>

<xs:element name="Name" type="xs:string" />

<xs:element name="DeliveryAddress" type="cmn:AddressType" />

<xs:element name="BillingAddress" type="cmn:AddressType" />

</xs:sequence>

</xs:complexType>

...

<xs:element name="VipCustomer">

<xs:complexType>

<xs:complexContent mixed="false">

<xs:extension base="cust:CustomerType">

<xs:sequence>

<xs:element name="VipNumber" type="xs:int" />

</xs:sequence>

</xs:extension>

</xs:complexContent>

</xs:complexType>

</xs:element>

Will be represented like this

Sample XML would look like this

<?xml version="1.0" encoding="utf-16"?>

<VipCustomer>

<Name>Joe Bloggs</Name>

<DeliveryAddress>

...

</DeliveryAddress>

<BillingAddress>

...

</BillingAddress>

<VipNumber>656</VipNumber>

</VipCustomer>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Element Reference
Send Feedback
XSD Editor > Graphical Notation Overview > Element > Element Reference

Glossary Item Box

Graphical Representation

Summary

An <xs:element> that is defined in a global scope (i.e. its parent is <xs:schema>) can be referenced through out the schema. This provides a mechanism for reuse.

Note: <xs:complexType> is typically am much better mechanism to provide re-use. Globally defined elements indicate that the element can be the root element in an XML Document, so over use of them can be confusing.

Creating

An <xs:element> can be referenced by setting a the type of the <xs:element> to the name of an existing global element. This can be done via the properties panel or the type drop down in the graphical view.

Sample

The following XSD code

<xs:element name="Address">

<xs:complexType>

<xs:sequence>

<xs:element name="Line1" type="xs:string" />

<xs:element name="Line2" type="xs:string" />

<xs:element name="Postcode" type="xs:string" />

</xs:sequence>

</xs:complexType>

</xs:element>

...

<xs:element name="Customer">

<xs:complexType>

<xs:sequence>

<xs:element ref="Address" />

</xs:sequence>

</xs:complexType>

</xs:element>

Will be represented like this

Sample XML would look like this

<?xml version="1.0" encoding="utf-16"?>

<Customer>

<Address>

<Line1>12 SomePlace St</Line1>

<Line2>Some Town</Line2>

<Postcode>HG27JU</Postcode>

</Address>

</Customer>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Group Definition
Send Feedback
XSD Editor > Graphical Notation Overview > Group Definition

Glossary Item Box

Graphical Representation

The Group Definition

Summary

The <group> allows you to create groups of elements that can be used as components inside other schema elements.
The group element must contain is a all/choice/sequence.
A group can only be defined at the root level (i.e. as a parent of the <schema>).

Creating

A <group> can be added to a <schema> by right click context menu on the <schema> item and selecting Add Child -> Group.

Group Definition Properties

Id - A user defined ID to uniquely identify the entity within the schema
Name - The name the group is referred to within the schema. You can only have one group with a given name.

Sample Group Definition

The following XSD code

<xs:group name="ProductInformation">

<xs:sequence>

<xs:element name="ProductID" type="xs:int" />

<xs:element name="ProductSerialNumber" type="xs:string" />

</xs:sequence>

</xs:group>

Will be represented like this

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Group Reference
Send Feedback
XSD Editor > Graphical Notation Overview > Group Reference

Glossary Item Box

Graphical Representation

A reference to an existing Group

Summary

The <group> allows you to create groups of elements that can be used as components inside other schema elements.
The group element must contain is a all/choice/sequence.
Before you can reference a group, you must define a one at root level (i.e. as a parent of the <xs:schema>), but once defined it can be referred to within any <all>, <choice> or <sequence>.

Creating

A reference to a <group> can be created by right clicking on an <all>, <choice> or <sequence> item and selecting Add Child -> Group You must then set the type to reference the root level group you have already defined (properties type) or via the drop down in the group box.

Group Reference Properties

Id - A user defined ID to uniquely identify the entity within the schema
Type - The name the group that is being referenced. Must correspond to a globally defined group.
Min Occurs - the minimum number of times the elements described in the <sequence> must appear in the XML Document (default 1).
Max Occurs - The maximum number of times the elements described in the <sequence> can appear in the XML Document (default 1).

Sample Group Reference

The following XSD code

<xs:group ref="ProductInformation" />

Will be represented like this

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Import
Send Feedback
XSD Editor > Graphical Notation Overview > Import

Glossary Item Box

Graphical Representation

Summary

The <xs:import> element causes the definitions from an external schema to be imported into the current schema. Once imported these definitions can be used within the containing schema.

Note: the Target Namespace in the external schema must match the namespace property defined in the <xs:import> element.

Creating

An <xs:import> can be added to a <xs:schema> by selecting schema object in the diagram and using the menu Edit->Import/Include Wizard.

Properties

Id - A user defined ID to uniquely identify the entity within the schema.
Namespace - The target namespace used in the imported schema.
Schema Location - The location of the schema to import, can be a url or relative path from this schema file.

Sample

The following XSD code

<?xml version="1.0" encoding="utf-16"?>

<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:import schemaLocation="CommonTypes.xsd" namespace="http://NamespaceTest.com/CommonTypes" />

...

</xs:schema>

Will be represented like this

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Include
Send Feedback
XSD Editor > Graphical Notation Overview > Include

Glossary Item Box

Graphical Representation

Summary

The <xs:include> element causes the definitions from an external schema to be included into the current schema. Once included these definitions can be used within the containing schema.

Creating

An <xs:import> can be added to a <xs:schema> by selecting schema object in the diagram and using the menu Edit->Import/Include Wizard

Properties

Id - A user defined ID to uniquely identify the entity within the schema
Schema Location - The location of the schema to include, can be a url or relative path from this schema file.

Sample

The following XSD code

<?xml version="1.0" encoding="utf-16"?>

<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:include schemaLocation="CommonTypes.xsd" />

   ...

</xs:schema>

Will be represented like this

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Key
Send Feedback
XSD Editor > Graphical Notation Overview > Key

Glossary Item Box

Graphical Representation

Summary

The <key> element defines a key that unambiguously identifies an element within the XML Document.

Creating

A <key> can only be added to an element object. This can be done using the right click context menu on any of these entities.

Properties

Name - the name of the key.
XPath Fields - 1 or more XPath expressions that uniquely identify selected element.
XPath Selector - The XPath expression that identifies the element to which this key applies.
Id - A user defined ID to uniquely identify the entity within the schema

Sample

The following XSD code

<?xml version="1.0" encoding="utf-8" ?>

<xs:schema elementFormDefault="qualified" xmlns:xs=http://www.w3.org/2001/XMLSchema>

  <xs:element name="Library">

    <xs:complexType>

      <xs:sequence>

        <xs:element name="Book">

          <xs:complexType>

            <xs:sequence>

              <xs:element name="Title" type="xs:string" />

            </xs:sequence>

            <xs:attribute name="ISBN" type="xs:string" />

          </xs:complexType>

        </xs:element>

      </xs:sequence>

    </xs:complexType>

    <xs:key name="BookReference">

      <xs:selector xpath="Book" />

      <xs:field xpath="@ISBN" />

    </xs:key>

  </xs:element>

</xs:schema>

Will be represented like this

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


KeyRef
Send Feedback
XSD Editor > Graphical Notation Overview > KeyRef

Glossary Item Box

Graphical Representation

Summary

The <keyRef> element defines a reference to a key or unique constraint.

Creating

A <keyRef> can only be added to an element object. This can be done using the right click context menu on any of these entities.

Properties

Id - A user defined ID to uniquely identify the entity within the schema
Name - the name of the key.
Refer - the key or unique constraint to which this constraint refers.
XPath Fields - 1 or more XPath expressions that uniquely identify selected element.
XPath Selector - The XPath expression that identifies the element to which this key applies.

Sample

The following XSD code

<?xml version="1.0" encoding="utf-8" ?>

<!--Created with Liquid XML Studio (https://www.liquid-technologies.com)-->

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="library">

    <xs:complexType>

      <xs:sequence>

        <xs:element name="Book">

        ...

        </xs:element>

      </xs:sequence>

    </xs:complexType>

    <xs:key name="ID">

      <xs:selector xpath="Book|Author|Character" />

      <xs:field xpath="@id" />

    </xs:key>

    <xs:keyref name="IDREF" refer="ID">

      <xs:selector xpath="Book/Author-Ref|Book/Character-Ref" />

      <xs:field xpath="@ref" />

    </xs:keyref>

  </xs:element>

</xs:schema>

Will be represented like this

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Notation
Send Feedback
XSD Editor > Graphical Notation Overview > Notation

Glossary Item Box

Graphical Representation

Summary

The <xs:notation> element allows machine readable markup to be added to the schema. This does not effect the meaning of the schema, but can be interpreted by an external application.

Creating

A <xs:notation> can be added to a <xs:schema> by using the right click context menu on the schema object Notation

Properties

Id - A user defined ID to uniquely identify the entity within the schema
Name - .
Public - .
System - .

Sample

The following XSD code

<?xml version="1.0" encoding="utf-16"?>

<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:notation name="DiagramData" />

   ...

</xs:schema>

Will be represented like this

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


XsdEditorNotation OpenContent
XSD Editor > Graphical Notation Overview > XsdEditorNotation OpenContent

Glossary Item Box

Show Graphical Representation

Show Summary

The xs:openContent provides an mechanism for making XSD's extensible.

The xs:openContent node tells the validator the containing element (in the instance document) can contain additional XML elements that are not defined within this schema. Prior to XSD 1.1 the only way to do with was via the xs:any node, however xs:openContent allows a greater level of control and freedom.

Show Creating

The xs:openContent node can be added to an xs:element or xs:complexType by right clicking on it and selecting the Open Content menu item, or selecting the ( [image]) item from the toolbar.

The xs:schema element can also have a xs:defaultOpenContent node which works the same as the xs:openContent node, but is applied to all elements defined within the schema.

If an xs:defaultOpenContent node is defined for a schema then it can be turned off for a given element by declaring an xs:openContent node and setting the mode=none

Show Properties

Id user defined ID to uniquely identify the entity within the schema
Mode

Valid values

  • none - no additional elements may be contained within the instance element
  • suffix - additional elements must appear after all the ones defined explicitly in the schema
  • interleave - additional elements can appear between elements defined within the schema.

The xs:openContent node can have a child xs:any which defines the rules that additional elements must comply with.

Show Sample

The following XSD code

XSD Sample Code Copy Code
    <element name="Book">
        <complexType>
            <openContent mode="interleave">
                <any namespace="http://www.book.org"
                     processContents="strict" />
            </openContent>
            <sequence>
                <element name="Title"
                         type="string" />
                <element name="Author"
                         type="string" />
                <element name="Date"
                         type="gYear" />
                <element name="ISBN"
                         type="string" />
                <element name="Publisher"
                         type="string" />
            </sequence>
        </complexType>
    </element>

Will be represented like this

Resulting XML Document Copy Code
        <Book xmlns:bk="http://www.book.org">
                <bk:Binding>Hardcover</bk:Binding>
                <Title>My Life and Times</Title>
                <bk:Size>5 x 7</bk:Size>
                <Author>Paul McCartney</Author>
                <bk:InStock>true</bk:InStock>
                <Date>1998</Date>
                <bk:Category>Non-fiction</bk:Category>
                <ISBN>1-56592-235-2</ISBN>
                <bk:NumPages>299</bk:NumPages>
                <Publisher>McMillin Publishing</Publisher>
                <bk:AvailableOnTape>false</bk:AvailableOnTape>
        </Book>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.

See Also

W3C xs:openContent


XsdEditorNotation Override
Send Feedback
XSD Editor > Graphical Notation Overview > XsdEditorNotation Override

Glossary Item Box

Show Graphical Representation

Show Summary

The <xs:override> element is functionally the same as the <xs:refine> element which causes the definitions from an external schema to be included and modified.

The <xs:override> construct allows attributeGroups, complexTypes, group & simpleTypes to be modified.

Added in XSD 1.1 (replaces redefine).

Show Creating

Can only be added using the source view.

Show Properties

Id | A user defined ID to uniquely identify the entity within the schema
Schema Location | The location of the schema to include, can be a url or relative path from this schema file

Show Sample

The following XSD code

BaseDef.xsd Copy Code
<?xml version="1.0" encoding="utf-8" ?>
<!--Created with Liquid XML Studio (https://www.liquid-technologies.com)-->
<xs:schema elementFormDefault="qualified"
           xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:complexType name="personName">
        <xs:sequence>
            <xs:element name="title"
                        minOccurs="0" />
            <xs:element name="forename"
                        minOccurs="0"
                        maxOccurs="unbounded" />
        </xs:sequence>
    </xs:complexType>
    <xs:element name="addressee"
                type="personName" />
    <xs:simpleType name="genderType">
        <xs:restriction base="xs:string" />
    </xs:simpleType>
    <xs:group name="elementGroup">
        <xs:sequence>
            <xs:element name="a"
                        minOccurs="0"
                        maxOccurs="unbounded" />
        </xs:sequence>
    </xs:group>
    <xs:attributeGroup name="attributeGroup">
        <xs:attribute name="a"
                      type="xs:string" />
    </xs:attributeGroup>
</xs:schema>

RedefineExample.xsd Copy Code
<?xml version="1.0" encoding="utf-8" ?>
<xs:schema elementFormDefault="qualified"
           xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:override schemaLocation="BaseDef.xsd">
        <xs:complexType name="personName">
            <xs:complexContent>
                <xs:extension base="personName">
                    <xs:sequence>
                        <xs:element name="generation"
                                    minOccurs="0" />
                    </xs:sequence>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
        <xs:simpleType name="genderType">
            <xs:restriction base="genderType">
                <xs:enumeration value="Male" />
                <xs:enumeration value="Female" />
            </xs:restriction>
        </xs:simpleType>
        <xs:group name="elementGroup">
            <xs:sequence>
                <xs:element name="a"
                            minOccurs="0" />
            </xs:sequence>
        </xs:group>
        <xs:attributeGroup name="attributeGroup">
            <xs:attribute name="a"
                          type="xs:token"
                          use="required" />
        </xs:attributeGroup>
    </xs:override>
    <xs:element name="author"
                type="personName" />
    <xs:element name="Use">
        <xs:complexType>
            <xs:sequence>
                <xs:group ref="elementGroup" />
                <xs:element name="Gender"
                            type="genderType" />
            </xs:sequence>
            <xs:attributeGroup ref="attributeGroup" />
        </xs:complexType>
    </xs:element>
</xs:schema>

Will be represented like this

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Redefine
Send Feedback
XSD Editor > Graphical Notation Overview > Redefine

Glossary Item Box

Show Graphical Representation

Show Summary

The <xs:redefine> element causes the definitions from an external schema to be included and modified.

The <xs:redefine> construct allows attributeGroups, complexTypes, group & simpleTypes to be modified.

Deprecated in XSD 1.1.

Show Creating

Can only be added using the source view.

Show Properties

Id | A user defined ID to uniquely identify the entity within the schema
Schema Location | The location of the schema to include, can be a url or relative path from this schema file

Show Sample

The following XSD code

BaseDef.xsd Copy Code
<?xml version="1.0" encoding="utf-8" ?>
<xs:schema elementFormDefault="qualified"
           xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:complexType name="personName">
        <xs:sequence>
            <xs:element name="title"
                        minOccurs="0" />
            <xs:element name="forename"
                        minOccurs="0"
                        maxOccurs="unbounded" />
        </xs:sequence>
    </xs:complexType>
    <xs:element name="addressee"
                type="personName" />
</xs:schema>
RedefineExample.xsd Copy Code
<?xml version="1.0" encoding="utf-8"?>
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:redefine schemaLocation="BaseDef.xsd">
        <xs:complexType name="personName">
            <xs:complexContent>
                <xs:extension base="personName">
                    <xs:sequence>
                        <xs:element name="generation" minOccurs="0" />
                    </xs:sequence>
                </xs:extension>
            </xs:complexContent>
        </xs:complexType>
    </xs:redefine>
    <xs:element name="author" type="personName" />
</xs:schema>

Will be represented like this

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Schema
Send Feedback
XSD Editor > Graphical Notation Overview > Schema

Glossary Item Box

Graphical Representation

Summary

The <schema> element contains the definition for the whole schema. It is the root element in the document, and as such there can be only one instance of it.
The schema can contain global definitions for <element>, <complexType>, <attribute>, <group> and <attributeGroup> as well as other constructs such as <include>, <redefine>, <import> and <notation>.

Creating

A schema entity is automatically created when you create a new schema.

Properties

Attribute Form Default - .
Block Default - .
Element Form Default - .
Final Default - .
Id - A user defined ID to uniquely identify the entity within the schema
Target Namespace - .
Version - .

Sample

The following XSD code

<?xml version="1.0" encoding="utf-16"?>

<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

   ...

</xs:schema>

Will be represented like this

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Sequence
Send Feedback
XSD Editor > Graphical Notation Overview > Sequence

Glossary Item Box

Graphical Representation

Summary

The <sequence> element is a container for other elements, groups and any's.
The contained items must appear within the XML document, but they MUST appear in the order they are defined.
In essence this is an order container.

Creating

An <sequence> can be added to an element, group or schema object. This can be done using the right click context menu on any of these entities.

Properties

Min Occurs - the minimum number of times the elements described in the <sequence> must appear in the XML Document (default 1).
Max Occurs - The maximum number of times the elements described in the <sequence> can appear in the XML Document (default 1).
Id - A user defined ID to uniquely identify the entity within the schema

Sample

The following XSD code

<xs:element name="SequenceElm">

<xs:complexType>

<xs:sequence>

<xs:element name="AddressLine1" type="xs:string" />

<xs:element name="ZipCode" type="xs:string" />

</xs:sequence>

</xs:complexType>

</xs:element>

Will be represented like this

Sample XML would look like this

<?xml version="1.0" encoding="utf-16"?>

<SequenceElm>

<AddressLine1>12 SomePlace St</AddressLine1>

<ZipCode>765755</ZipCode>

</SequenceElm>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Simple Type
Send Feedback
XSD Editor > Graphical Notation Overview > Simple Type

Glossary Item Box

Graphical Representation

Summary

The <xs:simpleType> element allows you to define new types. These new types can then be used though out your schema.

There are 3 main forms for a simple type, these are determined by the 'Simple Type Content' property. Restriction allows an existing type to be further restricted. List allows an number of valid values to be contained within the type. Union allows a number of different types to be valid for the value.

Creating

A <xs:simpleType> can be created by selecting the <xs:schema> object and using the right click context menu, Add Child -> Simple Type.

Properties

(When 'Simple Type Content' is Restriction, None or List)

Name - The name of the attribute (this is used within the XML document i.e. <Order OrderID="87">).
Simple Content Type - Effects the value of the type. Restriction, the type selected is being restricted. The restrictions come in the form of facets. Union, the value can take any valid value from the list of types defined in the Union Types property. List, the value can be a number of valid values for the Type selected. These values are white space separated in the XML document.
Type - The simple type that is being used as the base for this element (only available when the Simple Content Type, is NOT set to union).
Facets - The facets available depend on the 'Type' attribute see Facets for more information.
Final -
Id - A user defined ID to uniquely identify the entity within the schema

(When 'Simple Type Content' is Union)

Union Type - The list of types that are valid as values for the element (only available when the Simple Content Type, is set to union).

Sample Restriction

The following XSD code

<xsd:simpleType name="LowerCaseLetterType">

<xsd:restriction base="xsd:string">

<xsd:pattern value="[a-z]" />

</xsd:restriction>

</xsd:simpleType>

...

<xsd:element name="MiddleInitial" type="LowerCaseLetterType" />

Will be represented like this

Sample XML would look like this

<?xml version="1.0" encoding="utf-16"?>

<MiddleInitial>j</MiddleInitial>

Sample List

The following XSD code

<xs:simpleType name="SuitableDatesType">

<xs:list itemType="xs:date" />

</xs:simpleType>

...

<xs:element name="SuitableDates" type="SuitableDatesType" />

Will be represented like this

Sample XML would look like this (space separated list)

<?xml version="1.0" encoding="utf-16"?>

<SuitableDates>2000-01-12 2000-01-15 2000-01-18</SuitableDates>

Sample Union

The following XSD code

<xs:simpleType name="DateOrNumberType" >

<xs:union memberTypes="xs:date xs:int" />

</xs:simpleType>

...

<xs:element name="BookingLengthOrCheckoutDate" type="DateOrNumberType" />

Will be represented like this

Sample XML would look like this, where the contents are either a valid int or a valid date.

<?xml version="1.0" encoding="utf-16"?>

<BookingLengthOrCheckoutDate>3</BookingLengthOrCheckoutDate>

or

<?xml version="1.0" encoding="utf-16"?>

<BookingLengthOrCheckoutDate>2000-01-12</BookingLengthOrCheckoutDate>

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Unique
Send Feedback
XSD Editor > Graphical Notation Overview > Unique

Glossary Item Box

Graphical Representation

Summary

The <unique> element defines a key that unambiguously identifies an element within the XML Document.

Creating

A <unique> can only be added to an element object. This can be done using the right click context menu on any of these entities.

Properties

Name - the name of the key.
XPath Fields - 1 or more XPath expressions that uniquely identify selected element.
XPath Selector - The XPath expression that identifies the element to which this key applies.
Id - A user defined ID to uniquely identify the entity within the schema

Sample

The following XSD code

<?xml version="1.0" encoding="utf-8" ?>

<xs:schema elementFormDefault="qualified" xmlns:xs=http://www.w3.org/2001/XMLSchema>

  <xs:element name="Library">

    <xs:complexType>

      <xs:sequence>

        <xs:element name="Book">

          <xs:complexType>

            <xs:sequence>

              <xs:element name="Title" type="xs:string" />

            </xs:sequence>

            <xs:attribute name="ISBN" type="xs:string" />

          </xs:complexType>

        </xs:element>

      </xs:sequence>

    </xs:complexType>

    <xs:unique name="BookReference">

      <xs:selector xpath="Book" />

      <xs:field xpath="@ISBN" />

    </xs:unique>

  </xs:element>

</xs:schema>

Will be represented like this

Show Inline Properties

Properties that apply to a type are shown inline at the bottom of the items container.

Values that are inherited from the base types are shown in brackets, values specifically set against the item are shown without brackets.

If a facet is not valid for a given type (typically because of its data type), then its value is shown in red.

Inline properties can be disabled in the Options.


Facets
Send Feedback
XSD Editor > Graphical Notation Overview > Facets

Glossary Item Box

Summary

There are a number of facets that can be applied to data types. These facets allow data types to be restricted. For a given build in data type, only a sub set of the possible facets are valid. The properties window will only show the facets valid for the given data type.

Facets

Facet | Description
length | The value must contain this number of chars
minLength | The value must contain a minimum of this number of chars
maxLength | The value must contain a maximum of this number of chars
pattern | The value must comply with the regular expression provided. See W3C standard for the details of the regular expressions
enumeration | One of the possible values that can be used. Multiple enumeration elements can be present.
whiteSpace | Defines how whitespace is to be treated within the value. See W3C standard for details.
maxInclusive | The value must be below or equal to this value.
maxExclusive | The value must be bellow this value.
minExclusive | The value must be above this value.
minInclusive | The value must be above or equal to this value.
totalDigits | The value must have less than or equal to this number of digits after the decimal place.
fractionDigits | The value must have less than or equal to this number of decimal places.

Validity Map

Types | Facets
length minLength maxLength pattern enumeration whiteSpace
max
Inclusive
max
Exclusive
min
Inclusive
min
Exclusive
total
Digits
fraction
Digits
string | y | y | y | y | y | y
normalizedString | y | y | y | y | y | y
token | y | y | y | y | y | see (1)
base64Binary | y | y | y | y | y | see (1)
hexBinary | y | y | y | y | y | see (1)
integer | y | y | see (1) | y | y | y | y | y | see (2)
positiveInteger | y | y | see (1) | y | y | y | y | y | see (2)
negativeInteger | y | y | see (1) | y | y | y | y | y | see (2)
nonNegativeInteger | y | y | see (1) | y | y | y | y | y | see (2)
nonPositiveInteger | y | y | see (1) | y | y | y | y | y | see (2)
long | y | y | see (1) | y | y | y | y | y | see (2)
unsignedLong | y | y | see (1) | y | y | y | y | y | see (2)
int | y | y | see (1) | y | y | y | y | y | see (2)
unsignedInt | y | y | see (1) | y | y | y | y | y | see (2)
short | y | y | see (1) | y | y | y | y | y | see (2)
unsignedShort | y | y | see (1) | y | y | y | y | y | see (2)
byte | y | y | see (1) | y | y | y | y | y | see (2)
unsignedByte | y | y | see (1) | y | y | y | y | y | see (2)
decimal | y | y | see (1) | y | y | y | y | y | y
float | y | y | see (1) | y | y | y | y
double | y | y | see (1) | y | y | y | y
boolean | y | see (1)
duration | y | y | see (1) | y | y | y | y
dateTime | y | y | see (1) | y | y | y | y
date | y | y | see (1) | y | y | y | y
time | y | y | see (1) | y | y | y | y
gYear | y | y | see (1) | y | y | y | y
gYearMonth | y | y | see (1) | y | y | y | y
gMonth | y | y | see (1) | y | y | y | y
gMonthDay | y | y | see (1) | y | y | y | y
gDay | y | y | see (1) | y | y | y | y
Name | y | y | y | y | y | see (1)
QName | y | y | y | y | y | see (1)
NCName | y | y | y | y | y | see (1)
anyURI | y | y | y | y | y | see (1)
language | y | y | y | y | y | see (1)
ID | y | y | y | y | y | see (1)
IDREF | y | y | y | y | y | see (1)
IDREFS | y | y | y | y | y | see (1)
ENTITY | y | y | y | y | y | see (1)
ENTITIES | y | y | y | y | y | see (1)
NOTATION | y | y | y | y | y | see (1)
NMTOKEN | y | y | y | y | y | see (1)
NMTOKENS | y | y | y | y | y | see (1)

Note:

  1. Although the whiteSpace facet is applicable to this type, the only value that can be specified is collapse
  2. Although the fractionDigits facet is applicable to this type, the only value that can be specified is zero.


Built in XSD Types
Send Feedback
XSD Editor > Graphical Notation Overview > Built in XSD Types

Glossary Item Box

Built in Data Types

There are a number of built in data types defined within the W3C standard. The following table (taken from the standard) shows them, and provides an example value. Form more information see the standards documentation.

Simple Type | Examples (delimited by commas) | Notes
anyURI | http://www.example.com/ |
anyAtomicType |  | New in XSD 1.1, a generic type that encompasses all atomic types, both primitive and derived
anySimpleType |  | New in XSD 1.1 , a base type from which all other built-in types are derived. Any value (including an empty value) is allowed for xsd:anySimpleType.
base64Binary | GpM7 |
boolean | true, false, 1, 0 |
byte | -128, ...-1, 0, 1, ... 127 | see (2)
date | 31/05/1999 | see (2)
dateTime | 1999-05-31T13:20:00.000-05:00 | May 31st 1999 at 1.20pm Eastern Standard Time which is 5 hours behind Coordinated Universal Time, see (2)
dateTimeStamp | 2004-04-12T13:20:00-05:00 | New in XSD 1.1
dayTimeDuration | P3DT10H30M12.3S | New in XSD 1.1
decimal | -1.23, 0, 123.4, 1000.00 | see (2)
double | -INF, -1E4, -0, 0, 12.78E-2, 12, INF, NaN | equivalent to double-precision 64-bit floating point, see (2)
duration | P1Y2M3DT10H30M12.3S | 1 year, 2 months, 3 days, 10 hours, 30 minutes, and 12.3 seconds
ENTITIES |  | XML 1.0 ENTITIES attribute type, see (1)
ENTITY |  | XML 1.0 ENTITY attribute type, see (1)
float | -INF, -1E4, -0, 0, 12.78E-2, 12, INF, NaN | equivalent to single-precision 32-bit floating point, NaN is "not a number", see (2)
gDay | -31 | the 31st day, see (2) (5)
gMonth | 5 | May, see (2) (5)
gMonthDay | -26 | every May 31st, see (2) (5)
gYear | 1999 | 1999, see (2) (5)
gYearMonth | 1999-02 | the month of February 1999, regardless of the number of days, see (2) (5)
hexBinary | 0FB7 |
ID |  | XML 1.0 ID attribute type, see (1)
IDREF |  | XML 1.0 IDREF attribute type, see (1)
IDREFS |  | XML 1.0 IDREFS attribute type, see (1)
int | -2147483648, ... -1, 0, 1, ... 2147483647 | see (2)
integer | ...-1, 0, 1, ... | see (2)
language | en-GB, en-US, fr | valid values for xml:lang as defined in XML 1.0
long | -9223372036854775808, ... -1, 0, 1, ... 9223372036854775807 | see (2)
Name | shipTo | XML 1.0 Name type
NCName | USAddress | XML Namespace NCName, i.e. a QName without the prefix and colon
negativeInteger | ... -2, -1 | see (2)
NMTOKEN | US, | XML 1.0 NMTOKEN attribute type, see (1)
NMTOKENS | US UK, | XML 1.0 NMTOKENS attribute type, i.e. a whitespace separated list of NMTOKEN's, see (1)
nonNegativeInteger | 0, 1, 2, ... | see (2)
nonPositiveInteger | ... -2, -1, 0 | see (2)
normalizedString | Confirm this is electric | see (3)
NOTATION |  | XML 1.0 NOTATION attribute type, see (1)
positiveInteger | 1, 2, ... | see (2)
precisionDecimal |  | New in XSD 1.1, the precisionDecimal data type represents decimal numbers which retain precision
QName | po:USAddress | XML Namespace QName
short | -32768, ... -1, 0, 1, ... 32767 | see (2)
string | Confirm this is electric |
time | 13:20:00.000, 13:20:00.000-05:00 | see (2)
token | Confirm this is electric | see (4)
unsignedByte | 0, 1, ... 255 | see (2)
unsignedInt | 0, 1, ...4294967295 | see (2)
unsignedLong | 0, 1, ... 18446744073709551615 | see (2)
unsignedShort | 0, 1, ... 65535 | see (2)
yearMonthDuration | P0Y20M | New in XSD 1.1

Notes:

  1. To retain compatibility between XML Schema and XML 1.0 DTDs, the simple types ID, IDREF, IDREFS, ENTITY, ENTITIES, NOTATION, NMTOKEN, NMTOKENS should only be used in attributes.
  2. A value of this type can be represented by more than one lexical format, e.g. 100 and 1.0E2 are both valid float formats representing "one hundred". However, rules have been established for this type that define a canonical lexical format, see XML Schema Part 2.
  3. Newline, tab and carriage-return characters in a normalizedString type are converted to space characters before schema processing.
  4. As normalizedString, and adjacent space characters are collapsed to a single space character, and leading and trailing spaces are removed.
  5. The "g" prefix signals time periods in the Gregorian calendar.


XSD Editor Edit Menu
XSD Editor > Menus and Toolbars > XSD Editor Edit Menu

Glossary Item Box

XSD Editor

Menu in Liquid XML Studio | Menu In Visual Studio Extension

XSD Editor Specific Menus (also see Edit Menu)

Add Schema Item

Adds a root level directive to the schema. This allows other schemas to be included or imported into the currently selected one.
See Add Schema Item Context Menu.

Add Child Item

Adds the selected Item to the currently selected entity.
See Add Child Item Context Menu.

Insert Above

Adds the selected Item to the parent of the currently selected entity, above the selected item.
See Add Child Item Context Menu.

Append Below

Adds the selected Item to the parent of the currently selected entity, below the selected item.
See Add Child Item Context Menu.

Cardinality

Allows the cardinality of the selected compositor to be changed.
See Cardinality Content Menu

Compositor Type

Allows the type selected compositor to be changed.
See Compositor Type Context Menu

Edit Annotation

Edits the annotation associated with the selected entity.
Annotations allow human or machine readable information to be added to an entity, but are ignored by the parser (such as comments).

Expand All

Expands all the nodes in the active XSD Editor diagram.

This can take quite a long time on large schemas, and consume a lot of resources.

Import/Include Wizard

Allows a <import> or <include> to be added to the current schema. This allows you to use the definitions from an external file within the current XSD document.

The schema object must be selected in order to use this menu item.

See Import/Include Wizard

Generate Code

Launches the XML Data Binding wizard, which allows code to be generated from your XML Schema. The generated code provides strongly typed properties for all the elements and attributes in your schema. This makes it quick and easy to write code to create or consume compliant XML.

The code generation can be performed for cross platform C++, C#, Java, VB.Net & VB6.

Create Sample XML

Creates an Sample XML document from the selected element in the schema.

See Also

XSD Editor
Create Sample XML Document


XSD Editor Context Menu
XSD Editor > Menus and Toolbars > XSD Editor Context Menu

Glossary Item Box

This is the context menu show when you right click on an item within the XSD Graphical Development Environment.

Add Child Item

Adds the selected Item to the currently selected entity.
See Add Child Item Context Menu.

Insert Above

Adds the selected Item to the parent of the currently selected entity, above the selected item.
See Add Child Item Context Menu.

Append Below

Adds the selected Item to the parent of the currently selected entity, below the selected item.
See Add Child Item Context Menu.

Refactor

Allows elements of the schema to be altered globally across the whole schema set.
i.e. you can rename a schema element, and the changes will be propagated to all the references to the object.
See Refactor Menu

Cardinality

Allows the cardinality of the selected compositor to be changed.
See Cardinality Content Menu

Compositor Type

Allows the type selected compositor to be changed.
See Compositor Type Context Menu

Edit Annotation

Edits the annotation associated with the selected entity.
Annotations allow human or machine readable information to be added to an entity, but are ignored by the parser (such as comments).

Expand All

Expands all the nodes in the active XSD Editor diagram.

This can take quite a long time on large schemas, and consume a lot of resources.

Import/Include Wizard

Allows Import or Include files to be added to the current schema.
See Import Wizard

Generate Code

Launches the XML Data Binding wizard, which allows code to be generated from your XML Schema. The generated code provides strongly typed properties for all the elements and attributes in your schema. This makes it quick and easy to write code to create or consume compliant XML.

The code generation can be performed for cross platform C++, C#, Java, VB.Net, & VB6.

Create Sample XML

Creates an Sample XML document from the selected element in the schema.

Cut

Cuts the currently selected graphical element into the clipboard.

Copy

Copies the currently selected graphical element into the clipboard.

Paste

Pastes the contents of the clipboard, into the currently selected graphical element.

Delete

Deletes the selected graphical element.

See Also

XSD Editor
Create Sample XML Document
Import/Include Wizard

©2001-2019 Liquid Technologies Limited. All Rights Reserved.
Liquid XML Studio | XML Data Binder | XML Editor | XML Schema Editor | WSDL Editor | XPath Viewer | Web Service Tools


Add Child Menu
Send Feedback
XSD Editor > Menus and Toolbars > XSD Editor Context Menu > Add Child Menu

Glossary Item Box

Allows the type of entity to be added to be selected. The position that the entity is added is dependant on the parent menu item.
Only options that are valid given the state of the selected object will be enabled.

All

Selects an <xs:all> element to be added to the schema.

Choice

Selects an <xs:choice> element to be added to the schema.

Sequence

Selects an <xs:sequence> element to be added to the schema.

Any

Selects an <xs:any> element to be added to the schema.

Element

Selects an <xs:element> element to be added to the schema.

Group

Selects an <xs:group> element to be added to the schema.
If the item is to be added as a child of <xs:schema>, then the group must have a name, and is the declaration.
If the item is NOT to be added as a child of <xs:schema>, then the group is a reference to an existing named group, defined as a child of <xs:schema>.

Any Attribute

Selects an <xs:anyAttribute> element to be added to the schema.

Attribute

Selects an <xs:attribute> element to be added to the schema.

Attribute Group

Selects an <xs:attributeGroup> element to be added to the schema.
If the item is to be added as a child of <xs:schema>, then the group must have a name, and is the declaration.
If the item is NOT to be added as a child of <xs:schema>, then the group is a reference to an existing named group, defined as a child of <xs:schema>.

Complex Type

Selects a named <xs:complexType> element to be added to the schema, this can only be done if is to be added as a child of <xs:schema>.

Simple Type

Selects a named <xs:simpleType> element to be added to the schema, this can only be done if is to be added as a child of <xs:schema>.

Notation

Selects a named <xs:notation> element to be added to the schema, this can only be done if is to be added as a child of <xs:schema>.

Key

Adds a <xs:key> element to an <xs:element>.

KeyRef

Adds a <xs:keyref> element to an <xs:element>.

Unique

Adds a <xs:unique> element to an <xs:element>.


Cardinality Menu
Send Feedback
XSD Editor > Menus and Toolbars > XSD Editor Context Menu > Cardinality Menu

Glossary Item Box

Allows the cardinality of a given entity to be changed.
The options provided show only the commonly used values, if you have more specific requirements, then you will have to set them in the properties window.

0..1

The entity can appear in the XML document 0 or 1 times, it is in effect optional.

0..unbounded

The entity can appear in the XML document 0 or more times, it is in effect an unbounded collection.

1..1

The entity must appear in the XML document once, it is in effect mandatory.

1..unbounded

The entity can appear in the XML document 1 or more times, it is in effect an unbounded collection, which can not be empty.


Compositor Type Menu
Send Feedback
XSD Editor > Menus and Toolbars > XSD Editor Context Menu > Compositor Type Menu

Glossary Item Box

Allows the type of a compositor to be changed.

All

Make the compositor into an <xs:all> element. This means that the contained entities have to be present into the resulting XML document, but the order that they appear in not important.
Note: An all can not be the child of a <xs:choice> or <xs:sequence>, so this option is sometimes disabled.

Choice

Make the compositor into an <xs:choice> element. This means that only one of the contained entities can be present into the resulting XML document.

Sequence

Make the compositor into an <xs:sequence> element. This means that the contained entities have to be present into the resulting XML document, and they must appear in the order they are defined in the XSD schema.


Refactor Menu
XSD Editor > Menus and Toolbars > XSD Editor Context Menu > Refactor Menu

Glossary Item Box

XSD Editor - Refactoring Menu

Rename

Renames the item, and updates all references to the item.

Can only be performed on root elements, attributes, groups, attributeGroups, complexTypes and simpleTypes.

The side effects of the action are displayed before any action is taken.

This action can be difficult to undo as it updates the references in all the loaded schema files, so in order to undo the action you must perform the undo in each changed schema.

Convert To Global Type

Causes a root simpleType or complexType to be created from the selected item. The selected item is then changed to become a reference to the new type.

Can only be performed on Attributes with restricted simpleTypes, Elements with restricted simpleTypes, Elements with restricted extended or restricted complexTypes.

Convert To Global Element

Causes the selected element to be moved to the root (i.e. a child of the schema), and replaced with a reference to the new root element.

Convert To Global Attribute

Causes the selected attribute to be moved to the root (i.e. a child of the schema), and replaced with a reference to the new root attribute.

See Also

XSD Editor Side Effects


XSD Editor Side Effects
Send Feedback
XSD Editor > Menus and Toolbars > XSD Editor Context Menu > Refactor Menu > XSD Editor Side Effects

Glossary Item Box

When refactoring a schema, a change may have knock on effects in other parts of the schema, this dialog shows these changes.

Examples

If the name of a global type (i.e. a complex type) is changed, then the change is also made in all the places it is referenced, in order to maintain the integrity of the schema.

If the a global type (i.e. a complex type) is deleted, then all references to it are also deleted.


XSD Editor Toolbar
Send Feedback
XSD Editor > Menus and Toolbars > XSD Editor Toolbar

Glossary Item Box

XSD Editor Toolstrip

Add <xsd:all>

Add <xsd:choice>

Add <xsd:sequence>

Add <xsd:any>

Add <xsd:element>

Add <xsd:group>

Add <xsd:anyAttribute>

Add <xsd:attribute>

Add <xsd:attributeGroup>

Add <xsd:complexType>

Add <xsd:simpleType>

Add <xsd:notation>

Format XML

Validate XML Schema (F7)

Create XML Sample from the XML Schema

Generate Source Code from the XML Schema

Generate HTML Documentation for the XML Schema

View Schema Dependencies


Create Sample XML Document
Send Feedback
XSD Editor > Tools > Create Sample XML Document

Glossary Item Box

It is possible to create a sample XML document from an XML Schema. This can be done by using the "Tools->Create Sample XML Document" Menu ( [image]).

The sample XML Document is created by stepping though the possible options in the schema and creating the appropriate elements and attributes as it goes. The path that the sample builder takes through the schema is random, so each time you generate a sample file it make contain different items.

The builder attempts to create values for each element/attribute that reflect its type and restrictions, however this is not always possible (especially for regular expression restrictions).

Step 1

The first step in creating a sample is to deicide what the root element will be. The wizard presents a list of all the possible options.

Step 2

Step 3

There are a number of generation options that effect the way the your sample file is constructed.

Include a 'schemaLocation' attribute

If you select this option, then the schemaLocation or noNamespaceSchemaLocation attribute is added to the root element in the sample. This allows parsers to determine the XSD file that can be used to validate the XML file. This also allows you to use intellisense.

You can also change the way the schema is referenced in this attribute - i.e. you could make the path relative, or reference a schema on a remote web server etc.

Force the creation of optional entities to a depth of

Whenever an optional entity appears in the schema (an element with minoccurs 0, an attribute with use=optional), then it is 50/50 whether the entity will appear in the resulting XML. This option forces these entities to appear in the schema until the element nesting depth hits this value (then is 50/50 as to whether they appear).

In this sample a has a nesting depth of 1, b of 2, c of 3.

<a>
<b>
<c/>
</b>
</a>

This option can force more child elements into your sample XML, but set it to high and your sample may become very large!

Stop Creating optional items after a depth of

Whenever an optional entity appears in the schema (an element with minoccurs 0, an attribute with use=optional), then it is 50/50 whether the entity will appear in the resulting XML. This option prevents these entities from appearing in the schema after the element nesting depth hits this value.

This can prevent your sample XML file from becoming to large.

Step 4

You can also control the default namespace and the namespace aliases that will be used in the XML document.


Import/Include Wizard
Send Feedback
XSD Editor > Tools > Import/Include Wizard

Glossary Item Box

Imports and Includes allow types defined in external XSD files to be used/re-used within another XSD.

The Import/Include wizard allows you to set these links up.

Include

Allows access to all the globally defined entities in another schema with the same target namespace (or no specified target namespace) as the containing schema.

Import

Allows access to all the globally defined entities in another schema with a different target namespace as the containing schema.

Import Wizard

Creates an Import or Include entry in the selected (parent) schema depending on the type of schema being included.

Create New Schema

Creates a new XSD schema file, and adds an include or import statement into the selected schema.

Include an existing schema

Includes or imports an existing schema into the selected schema

Create New Schema Options

This wizard page is only shown if you selected "Create a new schema" in the previous page.

Schema Filename

The filename used to save the new schema file. The filename should end with .xsd.

A relative or absolute path can be provided for the filename.

If a relative path is supplied then it is relative to the selected (parent) schema.

Don't use a target namespace

The new schema will contain no target namespace declaration.

Use the current schema target namespace

The new schema will copy the target namespace declaration from the selected (parent) schema. If the parent has no target namespace then neither will the new schema.

Use this target namespace

The new schema will use the target namespace specified in the text box.

Include Existing Schema

This wizard page is only shown if you selected "include an existing schema" in the previous page.

Full Schema Filename

The full path of the XSD to be included/imported. This can be a url.

Use relative path

If this is checked and it is possible to form a relative path from the selected (parent) schema to the specified schema. Then the schema will be referenced using a relative path in the selected (parent) schema.

Target Namespace

(Readonly) shows the target namespace used in the included schema (will be blank if it contains no target namespace).


Generate Documentation
Send Feedback
XSD Editor > Tools > Generate Documentation

Glossary Item Box

You can generate HTML documentation for your XML Schema (XSD) using the Liquid XML Schema Documentation Generator. It is only accessible when an XSD file is the selected document, and can be invoked using the tool bar icon ( [image]), via the menu (Tools->Generate Documentation) or via the command line.

The generator can output your documentation in the following formats

  • Vanilla HTML suitable for placing on a network drive or web site
  • Asp.Net documentation suitable for an IIS web site (.net 2.0 or higher)
  • Custom XSLT 2.0 Templates (not available in the starter edition).

If you select custom templates then it is possible to provide a set of XSLT stylesheets that will be used to generate your documentation, the HTML and ASP.Net templates are provided as a starting point for this. See Custom XSD Documentation Templates for more information.

Sample output can be seen at http://schemas.liquid-technologies.com

When you select the Schema Documentation Generator tool, a wizard is provided to guide you through the process.

XSD Documentation Generator Wizard Page 1

You must select the type of documentation to generate, choose asp.net if you are planning to host the documentation on an IIS server, choose html if you want to use the documentation on a disk or another type of web server. The custom templates allow you to select your own XSLT transform to use. See Custom Templates.

XSD Documentation Generator Wizard Page 2

The Documentation title is shown at the top of each output page, and as the html page title, the documentation you provide is added to the home page for your mini site.

XSD Documentation Generator Wizard Page 3

Output Directory

The directory where the documentation files will be placed. This process can create a lot of files so it is recommended that you select an empty folder.

Include DISQUS commenting

Commenting allows users to place comments against each documentation page, this can be useful when a schema is being designed, or can show usage notes etc. To use the commenting system you will need to create a free DISQUS account (visit http://disqus.com/). The Thread ID qualifies each page within your mini-site making the comments unique to it.

XSD Documentation Generator Wizard Page 4

Additional Schemas

Some schemas have a number of root level schema files, i.e. you may have one schema with common elements, then a top level schema describing an Invoice and another top level schema describing a Customer. This page allows you to add in any additional schemas you want documenting, and linking into your documentation. For most schemas this is not necessary.

Pressing Finish will start the documentation generation, this can take a little time if your schema is very large. The output folder should be opened when the process completes.


XSD Editor Generate Documentation Cmd Line Interface
XSD Editor > Tools > Generate Documentation > XSD Editor Generate Documentation Cmd Line Interface

Glossary Item Box

The documentation Generation can be run from the command line. In order to do this the /XsdDoc argument must be specified.

/XsdDoc | Generates HTML documentation for an XSD.
/XsdDocType=Html|Aspx|Custom | The type of documents to generate.
/XsdDocTemplate=<xslt file> | If XsdDocType=Custom then this is the XSLT file used to perform the documentation generation.
/XsdDocOut=<outputDir> | The full path where the HTML files will be written.
/XsdDocTitle=<title> | The title of the documentation.
[/XsdDocDesc=<desc>] | The description of the documentation.
[/XsdDocSchemas=<url>] | Additional schemas, separated by ; or a XsdDocSchemas parameter for each schema.
[/XsdDocParam=param:value] | Parameter values passed to transform. Built in values: DisqusShortName:<Disqus username> DisqusThreadID:<Disqus thread UID> Note : Multiple parameters can be added on the command line.

Example - Generate HTML Documentation: Copy Code
XmlStudio.exe C:\Schemas\MySchema.xsd /XsdDoc
/XsdDocType=Html /XsdDocOut="C:\My Output" /XsdDocTitle="My Schema" /Close

See Also

User Interface
Command Line Interface


XSD Editor Generate Documentation Using Custom Templates
Send Feedback
XSD Editor > Tools > Generate Documentation > XSD Editor Generate Documentation Using Custom Templates

Glossary Item Box

It is possible to provide your own templates to the XSD Schema Documentation Generator. The generator uses XSLT 2.0 to perform the code generation, so you must supply one or more XSLT stylesheets.

The XSLT stylesheet operates on an XML document that is generated from the XSD schemas.
The schema for this can be found at <Installation Folder>/DocTemplates/SchemaInfo.xsd.

The HTML and ASP.Net templates are provided for reference and can be found in

  • <Installation Folder>/DocTemplates/XsdToAspx
  • <Installation Folder>/DocTemplates/XsdToHtml

The following Folders and files have special meaning. There location is relative to the initial XSLT style sheet provided to the generator.

  • StaticFiles - The contents of this folder will be copied directly into the output folder (this includes all sub folders and files). This folder is optional, if its not found no error is raised.
  • PreTransform.bat - This is executed after the SchemaInfo.XML, and image files are generated, but before the XSLT transform is run. It allows the Image files or SchemaInfo.XML file to be moved or pre-processed. This file is optional, if its not found no error is raised.

Example

If your setup is as follows

  • Template file c:\Templates\MyTemplate.xslt
  • Output folder c:\MyDocs

When the code generation is run the following steps are performed.

  • The images are written to <Output Folder>\Images
    In this example c:\MyDocs\Images
  • The contents of the <Template Folder>\StaticFiles is copied to <Output Folder>
    In this example the contents of c:\Templates\StaticFiles is copied to c:\MyDocs
  • The Batch file <Template Folder>\PreTransform.bat is executed.
    In this example c:\Templates\PreTransform.bat is executed.
  • The XSLT Transform is executed.
    In this example c:\Templates\MyTemplate.xslt, with the output folder set to c:\MyDocs.


XSD Dependency Viewer
XSD Editor > Tools > XSD Dependency Viewer

Glossary Item Box

The XSD Dependency viewer makes it easy to see how complex schema are constructed.

The tool can be accessed from the XSD Editor context menu, using the Dependency Viewer icon ( Schema Depency Viewer Icon)

XSD Dependency Viewer

The diagram shows how all the schemas in the FpML standard relate to each other. Double clicking on one of the schema nodes will open that XSD Schema in a new XSD Editor window.

See Also

XSD Editor
XSD Editor Toolbar
XSD Editor Overview


XSD Editor Flatten Schema
XSD Editor > Tools > XSD Editor Flatten Schema

Glossary Item Box

XSD Schemas can be split across multiple files using the xs:include, xs:import, xs:redefine and xs:override nodes. Breaking a large schema down into multiple files can increase re-use and make maintenance simpler.

However, it can sometime cause problems for some less compliant applications, which can not properly interpret these additional files. For this reason we provide a tool which will collapse a hierarchy of XML Schema files down into a single XSD file.

The tool is available on the tools menu when an XSD is open ( [image]), when selected it will flatten the current schema into a new file which you can then save in a suitable location.

You can view the structure of the XSD Hierarchy using the XSD Dependency Viewer. This will show a tree of all the XSD files that the current schema uses.

Limitations

The W3C XSD standard allows schemas elements to be defined within multiple namespaces. This is achieved by setting the targetNamespace attribute within the xs:schema element. This has the effect of making everything defined within the schema part of this targetNamespace. If schema set uses multiple targetNamespaces then their is no way to correctly collapse this into a single file. The behavior of xs:redefine and xs:override are also impossible to correctly replicate within a single file. As a result of this xs:import, xs:redefine and xs:override nodes are not collapsed, and are added into the file unchanged.

See Also

XSD Dependency Viewer
Import/Include Wizard


XSLT Debugger Overview

Glossary Item Box

The Liquid XSLT editor and integrated debugger allows XSLT 1.0 & 2.0 documents to be written, validated, and debugged.

The debugger supports step by step debugging, breakpoints, and shows local variables, watch expressions and current call stack.

The debugger toolbar and keyboard shortcuts make it quick and easy to step through your XSLT stylesheet.

Liquid XML Studio currently supports 2 XSLT Engines.

Microsoft XSLT 1.0 Engine

Source | Microsoft .Net Framework
Version | .Net 4.0 Framework
Supported Version | XSLT 1.0
Execute Transform | Yes
Debug Transform | No

Saxon XSLT 2.0 Engine

Source | Saxonica
Version | Saxon HE 9.2.1.1
Supported Version | XSLT 1.0 & 2.0
Execute Transform | Yes
Debug Transform | Yes

The editor provides syntax highlighting and the means to validate the XSLT using the Validate Button ( Validate Button).
Validation errors are underlined and reported in the error window.

The XSLT can be executed using either the Saxon XSLT 2.0 engine or the Microsoft XSLT 1.0 engine.

Step by step debugging can be performed against the Saxon 1.0 & 2.0 XSLT Engine. The debugger highlights the current line of execution, break points can be set within the project, watch windows show user defined variables, the call stack can be viewed and variables local to the stack frame can be examined.

See Also

Debugger
Local Variables Window
Watch Window
Breakpoints ToolWindow
Call Stack Window
Options Window
Debugger Toolbar

XSLT Debugger
XSLT Debugger Options
XSLT Debugger Walk through


XSLT Debugger Variable Icons
XSLT Editor/Debugger > XSLT Debugger Variable Icons

Glossary Item Box

The following icons appear within the Debugger Watch and Local Variable windows when the XSLT Debugger is being used.

An Atomic value (i.e an integer, string, date etc)
An Empty Element
An Item (node/element/atomic value etc)
A sequence of items
An XML Attribute
XML CDATA
XML Comment
XML Declaration
XML DocType
XML Document
XML Element
XML Namespace
XML Processing Instruction
XML Text
XML Whitespace
An Argument
Error
Unknown

See Also

Debugger
Local Variables Window
Watch Window
Breakpoints ToolWindow
Call Stack Window
Options Window
Debugger Toolbar

XSLT Debugger
XSLT Debugger Options
XSLT Debugger Walk through


XSLT Debugger Options
XSLT Editor/Debugger > XSLT Debugger Options

Glossary Item Box

The debugger options shown are dependant upon the XSLT engine selected.

The 2 XSLT engines currently supported are

  • Saxon HE XSLT 1.0 & 2.0 Engine
  • .Net XSLT 1.0 Engine

Saxon HE XSLT Engine options

Input

Main Module Filename - The XSLT file that will be executed or debugged (read only). Other XSLT files can be included using the <xsl:import href="common.xslt"/> directive.

Context Item - The initial context for the XSLT Transform, this must be an XML file. Transforms do not have to have an initial context object, but they normally do.

Output

Filename - The filename that the default output if written to (you can us <xsl:result-document> to write to other files within the same transform).

Format - The format of the output file. This affects the validation rules and formatting of the output. For more information see the W3C XSLT Standard.

Input Values

Sets parameters within the XSLT transform. The value of the parameter can be a string or XML loaded from a file.
The parameter values can be picked up in the transform using the <xsl:param name="CssTheme" select="None"/> directive.

Parameter Name - The name of the parameter (must match the name attribute in the param directive).

Data Type - The type of data either text or XML data read from a file.

Value - The value either the text literal or the filename, depending on the value of data type

XSLT Debugger Options

Properties

Base Uri - This is used for resolving any relative URIs appearing within the stylesheet, for example in xsl:include and xsl:import declarations, in schema locations defined to xsl:import-schema, or as an argument to the document() or doc() function

Whitespace Rule - Ignorable stops ignorable whitespace to be output. All causes all whitespace to the stripped.

DTD Validation Mode - Set whether or not DTD validation of this source documents is performed.

Schema Validation Mode - Set whether or not XSD validation of this source documents is performed.

Support XInclude - allows XInclude instructions in the source files to be processed.

Enabled Optimizations - Turns on/off Saxon performance optimizations. For debugging it is recommended that this be turned off, as the execution path with it turned on can make debugging difficult to understand.

Show whitespace in watch windows - default unchecked, shows/hides whitespace nodes within the Watch and Variable windows. Whitespace nodes are typically not processed within an stylesheet, and thus just clutter up the watch windows.

Saxon Debugger Options - Custom Startup

Startup Options

It is possible to configure the saxon environment programmatically before the XSLT is executed or debugged. This allows custom functions and variables to be registered with the saxon environment, it also allows subtle tweaks to the environment to be performed.

To programmatically configure the saxon environment you must create an assembly that implements the LiquidTechnologies.Debugger.SaxonPlugin.IExternalSaxonAdapter interface, the interface is defined within the assembly LiquidTechnologies.Debugger.SaxonPlugin.dll, so you must reference this dll in your class library.

IExternalSaxonAdapter Copy Code
public interface IExternalSaxonAdapter
{
    void PreCompile(Processor saxonProccessor);
    void PreExecute(XsltTransformer saxonXsltEvaluator);
}

The PreCompile method is called before the transform is compiled, and allows functions to be registered into the environment.

The PreExecute method is called before the transform is executed and allows parameters to be set into the environment.

The class implementing the interface must be public and have a public default constructor (i.e. one which takes no parameters).

See the Example in the folder Examples\Xslt Custom Functions

Once you have built your class library you can use it by clicking the "Select Initialization Class", and select your assembly.

The first class found supporting the IExternalSaxonAdapter interface will be selected.
You should also be able to debug the code within your assembly by attaching a debugger to the Liquid XML Studio application when its running.

.Net XSLT 1.0 Engine

The XSLT engine is the one shipped within .Net 4.0.

The .Net XSLT engine does not support XSLT 2.0 and can not be debugged

Input

Main Module Filename - The XSLT file that will be executed or debugged (read only).

Context Item - The initial context for the XSLT Transform, this must be an XML file. Transforms do not have to have an initial context object, but they normally do.

Output

Filename - The filename that the output if written to.

Input Values

Sets parameters within the XSLT transform. The value of the parameter can be a string or XML loaded from a file.
The parameter values can be picked up in the transform using the <xsl:param name="CssTheme" select="None"/> directive.

Parameter Name - The name of the parameter (must match the name attribute in the param directive).

Data Type - The type of data either text or XML data read from a file.

Value - The value either the text literal or the filename, depending on the value of data type

See Also

Debugger
Local Variables Window
Watch Window
Breakpoints ToolWindow
Call Stack Window
Options Window
Debugger Toolbar

XSLT Debugger
XSLT Debugger Walk through


XSLT Debugger Walk through
XSLT Editor/Debugger > XSLT Debugger Walk through

Glossary Item Box

Introduction

The Liquid XSLT Debugger makes it possible to step through an XSLT stylesheet, examining the internal state of variables and contexts as you go.

This brief walk through will show you how to get started.

Source Files

  • XSLT Html Transform Sample (PersonToHtml.xslt)
  • XML Source Data (PersonData.xml)

1. Open Liquid XML Studio.

You need the Trial, Designer or Developer Edition to debug XSLT stylesheets.
The starter edition will not work.

2. Open the stylesheet

File->Open

Select the file PersonToHtml.xslt

3. Select the XSLT Debugger Engine

Select the Debugger engine (only Saxon HE supports debugging at this time)

4. Configure the XSLT Debugger

Select the Debugger Options ( [image]). We need to configure the input/output files before we can run/debug the stylesheet.

XSLT Debugger Options

Set the Input->Context Input to be the source XML file PersonData.xml.

Provide a filename for the stylesheet output to be written to Output->Filename.

Set the output type. Ensure its set to HTML. Other values have an impact on the validation and formatting of the output file.

Parameters can be passed to the stylesheet using the Input Values Tab. We will pass the parameter "Title" to the stylesheet, this will be come the HTML page title. It is also possible to use an XML file as the source for a parameter.

5. Add a break point

Breakpoints can be added to the stylesheet by pressing F9 or clicking in the editor margin.
Add a breakpoint at line 26

6. Start the Debugger

Start the debugger using the Step Into button ( [image]), which will pause on the first instruction within the XSLT.

Once the debugger is in the paused state, the current instruction is highlighted in yellow, and the local variables are displayed in the Variables window. Watch expressions are also re-evaluated.

7. Continue to the next break point

Pressing the Run button ( [image]) causes the debugger to resume execution until the program completes or a break point is encountered.

The execution should pause on the break point we created in step 5.

The output file is opened in a separate pane when the stylesheet writes to it. The content of the output file are updated in real time as the stylesheet runs.

The Local Variables window shows all the variables within the current context. We can see the input parameter Title, and the variable [Context] which contains the XML context node. This is used as the root for all XPath expressions.

8. Create a Watch Expression

Watch expressions can be added by right clicking in the watch window. Watch expressions allow dynamic expressions to be evaluated, ideal for proto typing or digging into data.

Add a watch expression "lower-case(./name/text())", and see the result in the value column.

Every time the debugger enters the paused state watch expression are re-evaluated.

9. Run to the end.

The run command (F5 or [image]) will cause the execution to resume. There are 2 Person entries in our sample file, and these have been sorted (see line 17) so the execution will stop again on line 26 within the context being the Person element John Smith. Notice the watch expression reflects the new context.

Pressing Run again will cause the transform to complete.

10. Notes About Debugger Settings.

The settings for the debugger are stored in the current project. If no projects are open then the settings are stored in the default project. It is recommended that when working with XSLT's you create a project and include your stylesheet, input and output files. In this way you have quick and easy access to all the elements of your work.

See Also

Debugger
Local Variables Window
Watch Window
Breakpoints ToolWindow
Call Stack Window
Options Window
Debugger Toolbar

XSLT Debugger
XSLT Debugger Options


Web Service Test Client Overview
Send Feedback

Glossary Item Box

Web Services are typically called from applications, but sometimes it is useful to be able to call the yourself, either when developing or testing.

The Web Service Browser, allows you to bind to a web service, select a given web method and call it.

When you select a web method, the wizard automatically creates a sample request based on the WSDL. You will typically want to modify this before making the call to the web service.

Once you have selected your Web Method, you can manually modify the request and send it to the web service using the "Execute" button.

Once the call has completed, the response XML is displayed in the response tab.

In order to re-run the query you must go back to the Request tab (using either the tab or the "Back To Request" button), before pressing "Execute" again.

Because the sample builder steps randomly through the allowable elements described in the WSDL's embedded schema, your sample may not always reflect the request you would like. So you can create a new sample request by pressing the "Rebuild Request" button.

Custom Headers

Your Web Service may require custom headers to be passed to it as Name Value pairs. You can add these by clicking the 'Custom Headers...' button. The values you add will be sent to the Web Service as part of the web method call.

Viewing the WSDL

To see a detailed view of the WSDL for the specified Web Service you can click 'View WSDL' which will pull the WSDL down from the server and display it within the WSDL Editor.


Selecting a Web Service Method
Send Feedback
Web Service Test Client > Selecting a Web Service Method

Glossary Item Box

Before you can call a Web Service you must first bind to it. This can be accomplished using the "Tools->Web Service Test Client" Menu.

Select a WSDL or WADL File

First you must select the web service type you want to look at (WSDL, WADL or User Defined Web Service - see below) using the radio buttons at the top of the page.

You then need to specify the URL that returns the WSDL or WADL for the web service.

For .Net web services, this of the form http://ServerName/Service.asmx?WSDL

You can also select a local file e.g C:\temp\Service.wsdl

You can test the web service your have specified is valid using the "Test" button.

For those just curious about the tool, we have supplied a simple web service which allows you to explore the functionality of the Web Service Test Client. To use this web service, click the "Use Liquid Technologies Sample Web Service" link button.

If the service requires authentication, then you can add a user name and password.

If you save the web service call then the password is not encrypted in the file.

The Wizard will not allow you to move on until the web service URL is pointing at a valid WSDL file.

Selecting a Web Method

You can now select the Web method you wish to call. Web services typically offer the ability call there methods using a number of protocols. The browser shows all the supported protocols and all the methods exposed for each of them (Note Not all methods can be called via HTTP POST & GET).

The Web Service Test Client supports 4 protocols, Soap 1.1, Soap 1.2, HTTP GET & HTTP POST. Any other protocols are ignored.

Once you select your method, and press Finish, and request is constructed for you.
You can then modify the request and call the web method. See Web Service Test Client.

Select option to create a User Defined Web Service

If your Web Service does not have a WSDL or WADL file, you can choose the option to create a User Defined Web Service on the first page of the Wizard.

When you click 'Next >' you are then presented with the following screen which allows you to specify a service, URI, method (GET or POST) and method parameters.

Clicking 'Finish' then allows you to save the User Defined Web Service as a WADL file.

The next time you want to access the service, you can then select the WADL file you just created.


My Schema opens as text (there is no graphical view)
Send Feedback
Trouble Shooting > My Schema opens as text (there is no graphical view)

Glossary Item Box

I try to load my schema but I get an error and the graphical view is grayed out, what's wrong?

The most likely cause of this is that your schema is invalid. If the schema contains errors it is loaded into the code view, and the errors reported in the error window. Once you have fixed the errors in the code view, you can click back into the graphical view, and the schema will be loaded there as well.


Code Generation (C#, C++, Java, VB.Net & Visual Basic 6)
Send Feedback
Related Products > Code Generation (C#, C++, Java, VB.Net & Visual Basic 6)

Glossary Item Box

Overview

XML Data Binding is the process of creating a class library from an XML schema). Liquid XML Data Binder generates class libraries specific to your needs allowing your XML documents to be manipulated programmatically, in a simple, intuitive way. This reduces the amount of coding needed, increasing reliability and productivity.

Liquid XML Data Binder is the most comprehensive XML Data Binding tool on the market. With Support for all major development languages, hardware environments, and schema standards.

Liquid XML Data Binder benefits include:

  • Reduces Development Time
  • Increased reliability
  • Generates an easy to use Class Library for C#, VB.Net, Java, Visual Basic 6, cross platform C++ (Windows, Linux, Solaris, HP)
  • Supports XSD, XDR & DTD's
  • Supports the Fast Infoset binary XML standard
  • Support for the most complex XML standards including; ACORD, Dimensional Markup Language (DML), Financial products Markup Language (FpML 4), Health Level Seven (HL7), Moving Picture Experts Group (MPEG-7), Project Management XML (PMXML), QuickBooks (qbXML)

Using Liquid XML within your software development project will radically simplify your interaction with XML documents, increasing reliability, reducing development time, and testing effort. Simply put it bridges the gap between your development language (C++, C#, Java, VB6, Vb.Net) and XML. Once you try it you'll never go back to a basic parser.

If you are new to XML Data Binding, then please read our Introduction to XML Data Binding, or look at our examples.

Features

Saves you time and money

90% reduction in the amount of code you have to write! It simplifies the development cycle, cutting development and maintenance effort, saving you time and money.

Simplifies Development

XML Data Binding objects provide XML serialization and validation, leaving you to concentrate on implementing business logic.

Language support for C++, C#, Java, VB .Net and Visual Basic 6

We have clients on a wide range of platforms, using a number of languages. The structure of the generated code is the same in each language, meaning you don't need to re-learn the libraries if you are working with more than one language.
Our cross platform C++ libraries come with runtimes for Win32, Linux and Mac OS X and generate project files for Visual Studio 6, 2003, 2005, 2008 and 2010. The full C++ runtime source code is also available (see the Pro Edition) and is easily compiled onto other platforms (e.g. Sun Solaris, HP-UX, Mac OS).

C++ | The C++ library is platform neutral. The product ships with Windows and Linux runtime files. It is successfully being used on Solaris, Forte, HP, embedded systems and other more obscure platforms.
Java | Compiles to a single jar using a provided ANT build script. The resulting code can be used on java.
C# & VB.Net | 100% native .Net package, the generated library can be used by .Net languages
Visual Basic 6 | Allows COM Objects to be created, which can then be used from any COM compliant environment (Delphi, Business Objects, ASP etc.)

Unrivaled support for the W3C XSD standard

The Liquid XML supports an unprecedented amount of the XSD standard, meaning it will process complex XML schema that lesser products will not. Industry standard schema that are used as Liquid XML test cases include:

More readable and reliable code

More readable code means lower maintenance and development costs. If you are using MSXML or another XML DOM parser, the code you create is bloated and difficult to follow. With the XML classes the code is smaller and simple to read.

Ease of Use

The XML classes are simple to use. This reduces time spent developing and maintaining code. Because the classes are specific to your schemas, and strongly typed, your developers can also make use of intellisense - further speeding development!

Simple Intuitive Code

We have worked hard to ensure the interface you will use is as simple and intuitive as possible, as well as being extremely fast and easy to work with. See our Performance Statistics and Sample Project.

Fast Infoset Support in C++ , C# and VB .Net

Support for the binary XML Fast Infoset specification (X.891) implementation of the W3C XML Information Set.

Documentation

A full set of HTML documentation is created along with your code making getting to grips with the structure of your new library simple. This means your team will no longer have to spend hours referencing the XSD schema documents (some of which are huge for example, xCBL is almost 2Mb of schema). They can simply use the hyper linked help generated specifically for your schema.

Mature Product

Liquid XML has had continual product enhancement since 2001, and is used on business critical systems by many leading companies world wide - see our client list.

Unparalleled support

We provide a first rate support service with excellent response times and you will always be answered by a real person, no automated systems.

Reliable and Future Proofed

The generated classes ensure compliance to the specified schema, so you and your team do not need to spend unnecessary time learning the complexities of XSD, XDR or DTD.

Even if your schemas are simple now, its unlikely that they will stay that way. If you incorporate a lesser product into your development, what happens when it can't cope with the latest change to your schema? This is especially critical when you don't have control over a schema (i.e.. its a standard).

Strongly Typed with flexibility to change the code

The generated classes are strongly typed, meaning they are easier to work with, and have the added benefit of highlighting problems in your code at compile time NOT runtime.

Even though the classes are strongly typed you have the ability to add custom code in HAND_CODED_BLOCKS. Then when you regenerate the code from the schema your changes are still in place, many of our users find this invaluable.

Available Source Code

If you buy the Pro Edition, you get the source code for the C++ libraries allowing you to re-compile it on many platforms.

No Royalties

You pay for the development licenses only. The compiled code and associated redistributable library are royalty free (see License Guide for full details).

XML Data Binding is sometimes referred to as XML Code Generation, or XSD Code Generation.

Liquid XML Data Binding Wizard (LXDB) is an extension on the DOM parser (Document object Model) but instead of presenting a tree of untyped nodes, the representation is a strongly typed set of objects modeled directly from the XML Schema. Liquid XML produces a set of classes from an XML schema (XSD, XDR, DTD).


Empty Index Entry
Send Feedback

Glossary Item Box

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Topic Not Found
Send Feedback

Glossary Item Box

Topic Not Found

The link you just clicked was not able to connect to the target page.

Some possible reasons and remedies are as follows:

Reason | Remedy
Destination topic is not part of the area you specified in the Filtered by field. | Either select another filter or select (no filter).
The URL of the destination topic is incorrect or has changed. | Use the index or the search function instead.
Problems with the help installation. | Rerun Setup for the product this help is related to and select the 'Repair' option.

Additional help is available for filters, search, and the index.

Click Back to return to the page you were on.

The target parameters are:

Keyword:
Index Moniker:
URL:


Check In Files
Send Feedback

Glossary Item Box


Check Out Files
Send Feedback

Glossary Item Box


Advanced Functions

Glossary Item Box

This is a brief overview of some of more advanced functions that allow you to solve more complex problems.

EmptyToNull ( )

If your data source contains empty string values, but you don't want to end up generating empty records in the output. This function allows you to ignore empty records.
Typically used when reading CSV data where there is no concept of a missing field.

DefaultIfNull ( )

Replaces a missing input value with a default value. For example if an XML has an optional attribute then you can set a default value that will be used when it is not present in the source data.

Combine ( )

Takes 2 or more values or sequences and turns them into a single sequence. This is handy for building lists or combing data values from different sources.

Lookup ( )

This is a dictionary style lookup, the input value is looked up and the corresponding value returned.
This is invaluable for mapping values (i.e. ISO country codes 2 digit to 3 digit 'US' become 'USA').

InputParameter ( )

Allows a value to be provided to the transform (either via the command line or programmatically).

Output Formatting

The formatting applied to a value being written to a data target can be customized. This allow strings to be padded, decimal places to be fixed, and date/time data to be formatted.
This is especially useful when the output data is EDI or CSV and requires specific formatting rules to be applied.

Inline Casting

The default conversion rules used when casting a string to more complex data type will not be applicable for all input data. For example a data source may contain a string '010203' which describes a date in the format YYMMDD, the default conversion rules would misinterpret this, so we can apply our own casting rules.

Recursive Copy Connectors

A normal connector made to a data target will just create an entry for the specific node it is connected to. In contrast recursive copy connector will copy the node and all its children. This is especially useful when duplicating large sections of a document from the source to the destination (Copy and modify use case).

See Also

Output Formatting

Values
InputParameter

File
List Files

Misc
Lookup

String
EmptyToNull

Set
Combine

Type
DefaultIfNull


Aggregate Functions

Glossary Item Box

Aggregate functions perform a calculation on a set of values and return a single value.

See Also

Average
Count
Max
Min
Sum


In place casting
Send Feedback

Glossary Item Box

Casting rules can be applied to an input connection point, allowing the input data to be converted before its is processed by the component.

This is typically used to convert string data into one of the following types binary, date, datetime, time or timespan. It can also be used to refine the input type for a component, i.e. some components accept generic types, any, atomic or numeric. The type can be changed before it reaches the component providing more control, so you could ensure that a component that accepted a numeric type always dealt with it as an Int64.

Example

In this example this source data is a string and the target data type is 'Date'.

Source Data Copy Code
<?xml version="1.0" encoding="utf-8"?>
<!-- Created with Liquid XML Studio (https://www.liquid-technologies.com) -->
<Strings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="..\..\Common\Numbers.xsd">
    <String>2014/01/02</String>
    <String>2014/05/05</String>
    <String>2014/14/07</String>
</Strings>

The input data contains dates in US format (YYYY/DD/MM), without the cast the default string to date rules are applied which assume its in XSD xs:date format. The result would be a runtime error as the value '2014/01/02' is not a valid XSD xs:date.

So we need to apply a cast to the input data to allow it to be converted to a Date.

We do this on the properties window, first select the input connection point 'Date'.

Then select the "Cast Type" in the properties window.

As the target type is explicitly a Date, we have only one option.

Once a 'Cast Type' has been selected a new option appears 'Cast Conversion Rule', select this and click the '...' button.

This presents a 'Casting Rules' dialog with a number of options for converting to a string to a Date.

We will select the 'Customizable DateTime' option.

The dialog presents some common specifiers, have a look at Standard Date and Time Format Strings & Custom Date and Time Format Strings for more information about them.

The parser will match the first 'Format Specifier' to match the expression, so we can replace them all with yyyy'/'dd'/'MM.

We could also use the Format Specifier 'd' which matches a date, but it works very differently in with different local settings so if you use the general format specifiers be careful to consider the local settings.

When an inline cast has been setup against a connection point input it is noticeable on the diagram as the name is post fixed with the type in brackets.

Now when we run the transform we get the output we expect.

Transform Output Copy Code
<Dates>
  <Date>2014-02-01</Date>
  <Date>2014-05-05</Date>
  <Date>2014-07-14</Date>
</Dates>
The output type is an xs:date, so the output is formatted according to the W3C xs:date rules (YYYY-MM-DD).

Casting Rules

xs:date format

Parses the string treating it as an XSD xs:date format.

Customizable DateTime

This is a simple but powerful set of rules that allow a date to be parsed.

The rules are based on the .Net DateTime parser. The parser matches 'Format Specifiers' which can be general rules or specific masks.

Several Format Specifiers can be provided and the first one to match is used.

Many of the general format specifies are local specific so ensure the appropriate local is used or use a specific mask to avoid problems on machines in other locals.

Additional information regarding the format specifiers can be found at

  • Standard Date and Time Format Strings
  • Custom Date and Time Format Strings

Custom Regex

This is the most powerful conversion rule, it allows complex regular expressions to be constructed and value elements extracted into variables that are then used to build the target data type.

The values required to build the expression are shown under the expression, and a sample expression is initially created.

The regular expression engine used is the one that ships with .Net 4.0, the rules for regular expressions are complex and beyond the scope of this documentation, but are documented fully elsewhere.

  • Online expression builder and evaluator Regex Hero
  • .Net Framework Regular Expressions


SetTimezone

Glossary Item Box

Function Name
 SetTimezone
Category
 DateTime
Icon
Description
 Return the DateTime in a given time zone
Inputs
DateTime A value of type Date, DateTime, or Time
Outputs
Local The input value converted to the given time zone
Properties
time zone The time zone to apply to the input values

Usage

Applies the specified time zone to the input Date, DateTime, or Time.

If the current Time Zone is +03:00, and we are applying the time zone +02:00 then SetTimezone yields the following results

Input | Output
11:27:42+00:00 | 13:27:42+02:00
11:27:42+01:00 | 12:27:42+02:00
11:27:42Z | 13:27:42+02:00
11:27:42 | 10:27:42+02:00
Times with no time zone information are considered to be local, so the local time zone is applied to them.

See Also

CreateDate
CreateDateTime
CreateTime
Day
Hour
Millisecond
Minute
Month
Now
Second
Today
Year
ToLocal
ToUTC
DateAdd


ToLocal

Glossary Item Box

Function Name
 ToLocal
Category
 DateTime
Icon
Description
 Return the DateTime as a local time
Inputs
DateTime A value of type Date, DateTime, or Time
Outputs
Local The input value converted to the local time zone
Properties
None -

Usage

Converts the input Date, DateTime, or Time to a representation in local time.

If the current Time Zone is +03:00, then ToLocal yields the following results

Input | Output
11:27:42+00:00 | 14:27:42
11:27:42+01:00 | 13:27:42
11:27:42Z | 14:27:42
11:27:42 | 11:27:42

See Also

CreateDate
CreateDateTime
CreateTime
Day
Hour
Millisecond
Minute
Month
Now
Second
Today
Year
ToUTC
SetTimezone
DateAdd


ToUTC

Glossary Item Box

Function Name
 ToUTC
Category
 DateTime
Icon
Description
 Return the DateTime as a UTC time
Inputs
DateTime A value of type Date, DateTime, or Time
Outputs
Local The input value converted to UTC
Properties
None -

Usage

Converts the input Date, DateTime, or Time to a representation in UTC time.

If the current Time Zone is +03:00, then ToUTC yields the following results

Input | Output
11:27:42+00:00 | 11:27:42Z
11:27:42+01:00 | 10:27:42Z
11:27:42Z | 11:27:42Z
11:27:42 | 08:27:42Z

See Also

CreateDate
CreateDateTime
CreateTime
Day
Hour
Millisecond
Minute
Month
Now
Second
Today
Year
ToLocal
SetTimezone
DateAdd


Component Palette Window
Send Feedback

Glossary Item Box

The Component Palette provides a list of all the components that are available for use. The components can be added to the canvas by dragging them on. Many of the more complex components launch a wizard to guide you through the configuration process once they have been dropped on the transform canvas.

If user functions are created then these are automatically added to the Component Palette, and are also available to drag onto the current transform.

Data Mapper Component Palette


Where Clause (Database Source Wizard)
See Also Send Feedback

Glossary Item Box

By default the DataSource will read all the data from the source data table and any linked tables. In a large database this can be huge amounts of data. In order to reduce the data read an SQL WHERE clause can be used which will reduce the quantity of data read.

The 'WHERE SQL' must start with keyword 'WHERE' and MUST use the name 'TableAlias' when referencing columns within the source table.
Failure to use the TableAlias will result in errors (i.e. "WHERE Country = 'USA'" could fail you should use "WHERE TableAlias.Country = 'USA'")

The WHERE clause can also be parameterized to allow values to be taken from within the transform.

Once you have completed your WHERE Clause it can be tested with the Test button, the results are shown in dialog.

It is advisable to test the query before exiting the wizard.
If you want to test the query then you need to provide default values for all of the parameters as you define them.

For complex queries it is recommended that you build and test them in your standard database tools, and then cut and paste the SQL into this dialog.

See Also

Connection Selector (Database Wizard)
Source Selector (Database Wizard)

Database
Database Source


Connection Selector (Database Wizard)
See Also Send Feedback

Glossary Item Box

In order to bind to a database it must be configure as a global Database Connection. Database connections can be created via the Database Explorer Window or via the 'New Connection' button on the wizard.

The database creation screens are standard windows functionality, refer to online sources for configuring them.

Once a data base connection is selected, we can move onto the next wizard page with the next button.

See Also

Connection Selector (Database Wizard)
Source Selector (Database Wizard)
Where Clause (Database Source Wizard)

Database
Database Source


Source Selector (Database Wizard)
See Also Send Feedback

Glossary Item Box

The next page shows all the user tables within the database. This is a starting point for the data you will be loading.

Pick a table that is at the root of the output data you are trying to extract, so if you want to extract all the orders for each customer then select the Customer table.

See Also

Connection Selector (Database Wizard)
Where Clause (Database Source Wizard)

Database
Database Source


Standard Selector (EDI Wizard)
See Also Send Feedback

Glossary Item Box

This wizard page makes it possible to select the required EDI standard.

Once a standard has been selected the next button is enabled and we can move onto the next wizard page.

See Also

Standard Selector (EDI Wizard)
Syntax (EDI Wizard)

EDI
EDI Source
EDI Target


Syntax (EDI Wizard)
See Also Send Feedback

Glossary Item Box

The default terminators and separators will be selected based on the standard selected on the previous page (i.e. EDIFACT or X12).

These are common default values, however the files you need to process may use different values. If you receive errors when reading the EDI documents you may wish to investigate changing these values as appropriate.

These values are set when you first run the Wizard, however you can change them inside the Data Mapper by selecting the Component and selecting Properties from the right click menu.

Ignore File Declared Markers

When checked, the parser exclusively uses the values set in this dialog and ignores any terminator and separator characters declared in the EDI document.

If it is not checked, the parser will use any terminator and separator characters declared in the EDI document and fall back to use the values set in this dialog if the markers are not found in the EDI document.

See Also

Standard Selector (EDI Wizard)
Syntax (EDI Wizard)

EDI
EDI Source
EDI Target


Syntax (EDI Wizard)
See Also Send Feedback

Glossary Item Box

The default terminators and separators will be selected based on the standard selected on the previous page.

These are common default values, however the files you need to write may use different values and so you should change these values as appropriate.

These values are set when you first run the Wizard, however you can change them inside the Data Mapper by selecting the Component and selecting Properties from the right click menu.

Write End of Line

When checked, each segment is written to a new line.

If it is not checked, the entire EDI document is written onto a single line.

Write Missing Trailing Components

When checked, separators are added for all empty components within an element.

If it is not checked, then trailing empty components are omitted.

Write Missing Trailing Elements

When checked, empty fields and separators are added for all empty Elements within a segment.

If it is not checked, then trailing empty elements are omitted.

Pad Fields to Minimum Length (0s and spaces)

When checked, all fields (Elements and Components) are padded to the Minimum Length specified in the standard. Text fields are right padded with spaces, and numeric fields are left padded with zeros.

If it is not checked, then the fields are written using the specified values and any padding should be done using components within the Data Mapper transform before connecting to the EDI Target Component.

Pad Empty Fields to Minimum Length

When checked, all empty fields (Elements and Components) are padded to the Minimum Length specified in the standard using spaces.

If it is not checked, then the fields are written with empty values and any padding should be done using components within the Data Mapper transform before connecting to the EDI Target Component.

Truncate Fields to Minimum Length (0s and spaces)

When checked, all fields (Elements and Components) are truncated by removing zeros and spaces to the Minimum Length specified in the standard. Text fields have trailing spaces truncated from the right, and numeric fields have leading zeros truncated from the left.

If it is not checked, then the fields are written using the specified values and any truncating should be done using components within the Data Mapper transform before connecting to the EDI Target Component.

Truncate Fields to Maximum Length

When checked, all fields (Elements and Components) are truncated to the Maximum Length specified in the standard. Text fields are truncated from the right, and numeric fields are truncated from the left.

If it is not checked, then the fields are written using the specified values and any truncating should be done using components within the Data Mapper transform before connecting to the EDI Target Component.

Caution, truncating values may lead to loss of data.

See Also

Standard Selector (EDI Wizard)

EDI
EDI Source
EDI Target


How a JSON Schema is translated into a Data Mapper Component
Send Feedback

Glossary Item Box

When you create a JSON data source or target the component that is created can contain connectors that seem like duplicates. This topic will walkthrough how a JSON schema is translated into a data mapper component and show how the schema design can be improved the quality of the schema and as result simplify the model.

Example 1

This schema has a number of properties, the first 6 properties are strongly typed, by that I mean that they have an explicit type set on them.

Strongly typed schemas convert well into the data mapper an produce a single connection point in the resulting transform.

The next property 'UntypedProperty' does not contain any type information in the schema, this means it can contain data of any type (array, bool, integer, null, number, object, string).

Untyped values do not translate as well into the data mapper as every possible type has to be represented in the model. The result is duplicate connection points, one for each possible type.

The next property 'UnionProperty' allows integer types and string types. As you can see in the data mapper this is created as 2 connection points, one for string and one for integer.

Finally lets look at <Additional Properties> this means the object can contain any additional properties with any name or type. As you can see this translates to a connection point called 'Additional Properties' in the data mapper. An 'Additional Properties' value will exist for each property read from the data source, it has a child called 'Name' which will have a single value holding then name of the property read from the data source, and one or more 'Value' nodes, one for each type that the <Additional Properties> permits, only the 'Value' connection point corresponding to the type of the current property will contain a value for a given property.

Schema Source Code Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "title": "My schema",
    "additionalProperties": true,
    "properties": {
        "ArrayProperty": {
            "type": "array"
        },
        "BooleanProperty": {
            "type": "boolean"
        },
        "IntegetProperty": {
            "type": "integer"
        },
        "NullProperty": {
            "type": "null"
        },
        "ObjectProperty": {
            "type": "object"
        },
        "StringProperty": {
            "type": "string"
        },
        "UntypedProperty": {},
        "UnionProperty": {
            "type": [
                "integer",
                "string"
            ]
        }
    }
}

If the following JSON data was loaded the values in the reader would look like this

Sample Data Copy Code
{
    "ArrayProperty": [],
    "BooleanProperty": true,
    "IntegetProperty": 744,
    "NullProperty": null,
    "ObjectProperty": {},
    "StringProperty": "ABCDEFG",
    "UntypedProperty": false,
    "UnionProperty": 468,
    "OtherString" : "Value1",
    "OtherBool" : true
}
Data Source Representation Copy Code
Root                                                : Node
    ArrayProperty (ArrayList)                       : Node
    BooleanProperty (Boolean)                       : true,
    IntegetProperty (integer)                       : 744,
    NullProperty (Null)                             :
    ObjectProperty (Object)                         : Node
    StringProperty (String)                         : "ABCDEFG",
    UntypedProperty (Boolean)                       : false,
    UnionProperty (Integer)                         : 468,
    Additional Properties (Additional Properties)   : Node
        Name (PropertyName)                         : "OtherString",
        Value (String)                              : "Value1"
    Additional Properties (Additional Properties)   : Node
        Name (PropertyName)                         : "OtherBool"
        Value (Boolean)                             : true

Example 2 Arrays

In the previous example we glossed over how the values in an array are translated into a Data Mapper component. This example digs a little deeper.

The JSON Schema standard defines 2 mechanisms for array validation tuple and list based. List based means that every item in the array must comply with a given schema. Tuple based validation means that each item of data must comply with the schema at the corresponding index.

The property 'ListArrayProperty' specifies that all items in the array must be strings. This translates into a hierarchy of connection points within the data mapper. The connection point 'ListArrayProperty (ArrayList)' contains a value if the property is present in the source data (even if its an empty array). This contains a child 'Item[0-n] (Any)' this contains a value for every element within the source data array (this may seem like an unnecessary child relation, but in more complex cases it is required). Within this is a child connection point 'Value (String)', this contains a string value representing the array item in the source data.

The property 'TupleArrayProperty' specifies that the array can have 0-3 items the first item must be a string, the second an Integer and the third a Boolean. The translation into the data mapper is more straight forward. The connection point 'TupleArrayProperty (ArrayTuple)' contains a value if the property is present in the source data (even if its an empty array). The child 'Item; connection points represent the items at a given index within the array.

If the array allows untyped items then as with the previous example a connection point is created for each type that is allowed.

If the following JSON data was loaded the values in the reader would look like this

Sample Data Copy Code
{
    "ListArrayProperty": ["ItemA", "ItemB", "ItemC", "ItemD"],
    "TupleArrayProperty": ["ItemA", 34, false],
    "UntypedArrayProperty": ["ItemA", "ItemB", 32.2, true]
}
Data Source Representation Copy Code
Root                                                : Node
    ListArrayProperty (ArrayList)                   : Node
        Item[0-n] (Any)                             : Node
            Value (String)                          : "ItemA"
        Item[0-n] (Any)                             : Node
            Value (String)                          : "ItemB"
        Item[0-n] (Any)                             : Node
            Value (String)                          : "ItemC"
        Item[0-n] (Any)                             : Node
            Value (String)                          : "ItemD"
    UpleArrayProperty (ArrayList)                   : Node
        Item[0] (String)                            : "ItemA"
        Item[1] (Integer)                           : 34
        Item[2] (Boolean)                           : false
    UntypedArrayProperty (ArrayList)                : Node
        Item[0-n] (Any)                             : Node
            Value (String)                          : "ItemA"
        Item[0-n] (Any)                             : Node
            Value (String)                          : "ItemB"
        Item[0-n] (Any)                             : Node
            Value (Number)                          : 32.2
        Item[0-n] (Any)                             : Node
            Value (Boolean)                         : true


Data Source (JSON Reader Wizard)
See Also Send Feedback

Glossary Item Box

Allows you to select the JSON data that this components represents.

No default JSON Data

No data is associated with the JSON Reader, it is expected that either the 'Filename' or 'JSON String' input values will be connected within the transform.

Read the default JSON data from a file

JSON Data is read from the filename provided (the filename can be an absolute path or can be a relative path which will be evaluated relative to the transform file)

Generate a default JSON file

A sample JSON document is generated from the JSON Schema.

Complex rules within the schema may mean this will not be 100% compliant with the schema

See Also

JSON Schema Selector (JSON Wizard)


JSON Schema Selector (JSON Wizard)
See Also Send Feedback

Glossary Item Box

In order to read data from a JSON document, the Data Mapper needs to be aware of its structure.

Json Schema (IEFT drat 4)

Loads the JSON Schema from the file specified.

Infer a JSON Schema from a sample JSON document.

If you don't have a JSON Schema then you can infer one from a sample JSON document, select this option and press next.

See Also

JSON Schema Selector (JSON Wizard)
Options (JSON Reader Wizard)
Data Source (JSON Reader Wizard)

JSON
JSON Source


Options (JSON Reader Wizard)
See Also Send Feedback

Glossary Item Box

This wizard page allows you to infer a JSON Schema from a sample JSON document.

Sample JSON filename

A JSON file containing data that is representative of the data you intend to load. The better the sample data the better the results.

As far as possible ensure that the file contains all the possible combinations of data you expect to see, and try to show objects with and without optional fields.

If your data is very complex you may need to refine the results afterwards using the JSON Schema Editor.

JSON Schema filename

The generated JSON Schema fill be written here.

JSON Schema Encoding

The encoding used to write the JSON Schema.

Force Required

Makes objects definitions required/mandatory if it that has not been identified as optional. If this is not set then all objects are declared as optional.

Infer Enums

When checked the values within objects and arrays are generated as Enumerated values using the unique values in the sample document.

so if an array contained ["true", "false", "false", "false", "true" ] this would be inferred as an enumeration with the values "true", "false".

This option works well on large sample documents, but on small sample sets it can cause the creation of values as enumerations, when in fact they should contain free text.

Infer Enum Tolerance

A tolerance factor for determining if a set of values can be considered an enumeration or free text.

They will be considered an enumeration if (NoOfSamples/UniqueValues) > InferEnumTolorence.

Array Rules

  • AllowAnything - Any kind of item is allowed into the array (not recommended as untyped values are difficult to work with in the Data Mapper)
  • ListValidation - All items comply to the same schema. Each item in the array is considered to be of the same type, and the definition of that type is derived from all the items in the array.
  • TupleTyping - Each item in the array is described using its own schema based on its index in the array (this is rarely how data is formatted in real world documents).

Default Additional Items

Indicates if additional items are allowed within the schemas definitions produced. This is a 3 state field.

  • If checked additional items are allowed
  • If unchecked additional items are NOT allowed
  • Else the 'additionalItems' property is omitted (in which case it defaults to true)

Default Additional Properties

Indicates if additional properties are allowed within the schemas definitions produced. This is a 3 state field.

  • If checked additional properties are allowed
  • If unchecked additional properties are NOT allowed
  • Else the 'additionalProperties' property is omitted (in which case it defaults to true)

See Also

JSON Schema Selector (JSON Wizard)
Data Source (JSON Reader Wizard)

JSON
JSON Source


Options (JSON Writer Wizard)
See Also Send Feedback

Glossary Item Box

This wizard page allows you to infer a JSON Schema from a sample JSON document.

Sample JSON filename

A JSON file containing data that is representative of the data you intend to load. The better the sample data the better the results.

As far as possible ensure that the file contains all the possible combinations of data you expect to see, and try to show objects with and without optional fields.

If your data is very complex you may need to refine the results afterwards using the JSON Schema Editor.

JSON Schema filename

The generated JSON Schema fill be written here.

JSON Schema Encoding

The encoding used to write the JSON Schema.

Force Required

Makes objects definitions required/mandatory if it that has not been identified as optional. If this is not set then all objects are declared as optional.

Infer Enums

When checked the values within objects and arrays are generated as Enumerated values using the unique values in the sample document.

so if an array contained ["true", "false", "false", "false", "true" ] this would be inferred as an enumeration with the values "true", "false".

This option works well on large sample documents, but on small sample sets it can cause the creation of values as enumerations, when in fact they should contain free text.

Infer Enum Tolerance

A tolerance factor for determining if a set of values can be considered an enumeration or free text.

They will be considered an enumeration if (NoOfSamples/UniqueValues) > InferEnumTolorence.

Array Rules

  • AllowAnything - Any kind of item is allowed into the array (not recommended as untyped values are difficult to work with in the Data Mapper)
  • ListValidation - All items comply to the same schema. Each item in the array is considered to be of the same type, and the definition of that type is derived from all the items in the array.
  • TupleTyping - Each item in the array is described using its own schema based on its index in the array (this is rarely how data is formatted in real world documents).

Default Additional Items

Indicates if additional items are allowed within the schemas definitions produced. This is a 3 state field.

  • If checked additional items are allowed
  • If unchecked additional items are NOT allowed
  • Else the 'additionalItems' property is omitted (in which case it defaults to true)

Default Additional Properties

Indicates if additional properties are allowed within the schemas definitions produced. This is a 3 state field.

  • If checked additional properties are allowed
  • If unchecked additional properties are NOT allowed
  • Else the 'additionalProperties' property is omitted (in which case it defaults to true)

See Also

JSON Schema Selector (JSON Wizard)
Data Target (JSON Writer )

JSON
JSON Target


Data Target (JSON Writer )
See Also Send Feedback

Glossary Item Box

Allows you to select the output location for the JSON data that this components represents.

No default JSON Data

No output filename has been provided so one must be provided within the transform using the 'Filename' input, the resulting JSON data will be written to the filename taken from the value of this input.

Write JSON data to this file

JSON Data is written to the filename provided (the filename can be an absolute path or can be a relative path which will be evaluated relative to the transform file)

See Also

JSON Schema Selector (JSON Wizard)
Options (JSON Writer Wizard)

JSON
JSON Target


JSON Schema Selector (JSON Wizard)
See Also Send Feedback

Glossary Item Box

In order to write data to a JSON document, the Data Mapper needs to be aware of its structure.

JSON Schema (IEFT drat 4)

Loads the JSON Schema from the file specified.

Infer a JSON Schema from a sample JSON document.

If you don't have a JSON Schema then you can infer one from a sample JSON document, select this option and press next.

See Also

JSON Schema Selector (JSON Wizard)
Options (JSON Writer Wizard)
Data Target (JSON Writer )

JSON
JSON Target


DataMapper Terminology
Send Feedback

Glossary Item Box

Terminology

Primitive Value

A value holding a single piece of information (string, number, date etc).

Complex Value

A container for other values both complex or primitive. Only a complex value can contain child values.

Sequence

A sequence of 0 or more values (complex or primitive), all items in a sequence will be of the same type.

Connection Point

A connection point is either a source of data (output connection point) or the destination (input connection point).

Connector

Connectors can join connection point outputs to connection point inputs, the connector draws the value from the input when the output connection point is evaluated.

Notation

Component - The component highlighted is called "Equal 1", but the transform contains others, "Xml Reader 1", "Genre Filter" and "Xml Writer 1" the constant value 'Reference' is also a Component, but to save space does not display its name. Components can be created by dragging them from the Component Palette Window.

Primitive Output Value - The price output is of type 'double' (see the type system for more information). A primitive value contains a single piece of information (string, number, date etc).

Complex Output Value - The author output is a complex node, it contains structured data, in this case first-name and last-name. The bookstore and book outputs are other examples of complex nodes.

Input Value - Inputs can be primitive or complex in the same way that outputs can be, this can be seen in the 'Xml Writer 1'. The highlighted input Nodes is a special case, it belongs to a component that has Dynamic Output Values, so the output of the component takes on the type that is passed to the input.

Simple Connector - Takes all the values read from the output (the connection point on the left, also referred to as the source) and passes them to the input (the connection point on the right, also referred to as the destination), if the input is complex (as is the case for bookstore) then a bookstore node will be created for each input value (regardless of its type), but its child items (book) will not be created or populated.

Recursive Connector - Takes all the values read from the source (input) and passes them to the destination (output), if the input is complex (as is the case for book) then a book node will be created for each input value, all child nodes will also be copies recursively. Note in order to create a recursive connector the input and output types must be the same.

Output Properties

Each output has a number of properties, which can be viewed and edited (if applicable) using the Properties Window

The image above shows the properties for the selected output genre.
The 2 of particular interest are the Type and Cardinality.

Type

This shows the data type of the output. When an output is connected to an input if the data types differ, casting will be done to convert one type to another, some casts are not possible (i.e. an integer can never be cast to a date), and some may fail at runtime (i.e. a string converted to an int), when data conversion errors may take place at runtime warnings are generated.

Cardinality

This indicates the number of values that this output is capable of returning (within the context of its parent node).

Values are

  • 0-1 - Optional
  • 0-n - Zero to many items
  • 1-1 (abbreviated to 1) - Mandatory
  • 1-n - One to many

Internally the transform treats all outputs as sequences, but the cardinality determines how many values a sequence may contain.

Input Properties

Inputs are a little more complex

Type

Shows the type of the input and the type that is being provided via the input connector, this is displayed as [INPUT TYPE] ([CONNECTOR TYPE]).

So in this case publicationDate input is a Date, but the value being provided via the connector is a String.

When the value of publicationDate is evaluated it will read a String value from the connector and cast it to a Date (this may fail if the formatting is not as expected).

When casts are performed that require more formatting information the 'Cast Type' property is also available, this allows casting rules to provided inline.

Cast Type

If the value taken from the connector is different from input type then the value needs to be cast. If the casting rules for the conversion are complex or ambiguous (typically converting strings to other types like dates), then an extra 'Cast Type' property is also shown. This allows specific Inline Casting rules to be applied.

If a property has an inline cast associated with it then this is shown on the diagram with the cast in brackets
i.e. publicationDate (Date)

Format Value

This property is only presented on data targets (i.e. XML Writer, JSON Writer etc), this property allows the incoming value to be formatted as it is written to the target file.

Inputs with formatting rules are shown with a *
i.e. publicationDate*


Properties - General (Text Reader Component)
Send Feedback

Glossary Item Box

Name

The name of the component, must be unique within the transform


Properties - Source Data (Text Reader Component)
Send Feedback

Glossary Item Box

Default input filename

If the reader component does not have a connector to the 'Filename' or ' Text Source' then the filename is read from this property.

If the connection point 'Filename' or ' Text Source' is connected, then this is ignored (and can be blank)

Store as relative path

Indicates that the filename is to be resolved relative to the data mapping file (.dm). If the transform is compiled the filename will be resolved relative to the compiled exe.


Properties - Structure (Text Reader Component)
Send Feedback

Glossary Item Box

Default Encoding

The encoding used to decode the data read from the file into text if the encoding is not specifically identified within the file (see BOM).

First line contains field headings

If checked then the first line in the data file is ignored as it is assumed to contain the names of the columns

Ignore invalid rows

The transform does not stop when an invalid row is encounters, it just ignores it and moves onto the next line.

Remove leading and trailing whitespace from each field

If checked leading and trailing whitespace is removed from the field value i.e.

Col1 , Col2 , Col3

if checked the values are "Col1", "Col2", "Col3"

if unchecked the values are "Col1 ", " Col2 ", " Col3"

Fields are enclosed in quotes

When checked quotes are considered to be enclosing characters, i.e.

"col 1 has a coma, would normally be seen as a separator", col 2

By enclosing column 1 in quotes the ',' is treated as data not a separator.

Delimiters

All the delimiters selected are treated as column separators unless they are enclosed in quotes (see Fields are enclosed in quotes).

Edit Columns

Allows the column definitions to be manually edited.


Properties - General (Text Writer Component)
Send Feedback

Glossary Item Box

Name

The name of the component, must be unique within the transform


Properties - Output (Text Writer Component)
Send Feedback

Glossary Item Box

Default output filename

If the writer component does not have a connector to the 'Filename' input then the filename the data is written to is taken from this property.

If the connection point 'Filename' is connected, then this property is ignored (and can be blank)

Store as relative path

Indicates that the filename is to be resolved relative to the data mapping file (.dm). If the transform is compiled the filename will be resolved relative to the compiled exe.

Default Encoding

The encoding used to write the text data to a file.

Write column heading on first line

If checked then all the column headings are written onto the first line of the file.


Properties - Structure (Text Writer Component)
Send Feedback

Glossary Item Box

Edit Columns

Allows the column definitions to be manually edited.


Select Data Source (Xml Source Wizard)
Send Feedback

Glossary Item Box

The next section allows you to specify where you want your source data to come from. This is the data that will be mapped when your transform executes. If you inferred a Schema from source XML, you may wish to use this here. If you specified an XSD you already had before starting your mapping project, you can use it to generate default XML data to use in the Mapper.


Select Data Target (Xml Target Wizard)
Send Feedback

Glossary Item Box

Allows you to select the output location for the XML data that this components represents.

No default XML Data

No output filename has been provided so one must be provided within the transform using the 'Filename' input, the resulting XML data will be written to the filename taken from the value of this input.

Write XML data to this file

XML Data is written to the filename provided (the filename can be an absolute path or can be a relative path which will be evaluated relative to the transform file)


Infer Schema (Xml Wizard)
Send Feedback

Glossary Item Box

The second page contains options relating to the inferring process.

Schema Name

The name of the schema that will be produced (there is no need to add the .xsd extension).
If more than 1 schema file needs to be created, then the schema files will be named <Schema Name>1.xsd, <Schema Name>2.xsd etc

Output Directory

The location where your schema file/files will be written.

Encoding

The encoding that will be applied to your XML Schema (UTF-8 or UTF-16 are the most commonly used, only change this if you understand encoding).

Occurrence Options

If the Occurrence property is set to Restricted, the first time elements are encountered in the XML document, the schema declaration is inferred as minOccurs="1".
When attributes are encountered, the schema declaration is inferred as use="required". If the Occurrence property is set to Relaxed, element schema declarations are inferred as minOccurs="0", and attribute schema declarations are inferred as use="optional".

Type Inference Option

If the TypeInference property is set to Relaxed, the inferred type of elements and attributes in the XML document with simple content is always xs:string.
If the TypeInference property is set to Restricted, more specific types are inferred, such as xs:date, xs:decimal, xs:unsignedByte, and so on.


Schema Selector (Xml Wizard)
Send Feedback

Glossary Item Box

You need to provide a schema to describe the data that you will be mapping, you can do this using by providing an XSD, DTD or XDR.

If you don't have a schema (i.e. you just have an xml data file) then you can infer a schema from the XML data file (see Inferring an XML Schema (XSD)).

If you infer an XSD from an XML document, then you may have to finesse the XSD manually in the XSD Editor.


Select Root Element (Xml Wizard)
Send Feedback

Glossary Item Box

When you have selected a Schema, the next part of the Wizard will allow you to select the root element or complex type.

Types that are abstract are disabled and grayed out.


XHTML Editor Options

Glossary Item Box

Indent Size

The number of columns used for a tab. This is also the number of columns XML data will be indented by.

Use

Tabs - a tab is used to for each indent.

Spaces - a number of spaces characters is used for each indent.

Show Line Numbers

Indicates if line numbers should be shown in the left hand margin

Show Whitespace

Non-visible characters like spaces and tabs are shown in the editor (default is off).

Word Wrap

Line lines are wrapped when displayed in the editor (default is off).

Can cause performance problems when line lengths are very long (typically if a large xml file is unformatted and exists as a single line of text).

Enable Macros

Enabled keyboard macros to be recorded and played back (default is enabled).

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

Ignore Significant Whitespace Formatting XML

Causes leading and trailing whitespace to be ignored (default is false). Whitespace before and after data contained within an XML Element is considered to be significant to most parsers. It will therefore be preserved when formatting your XML documents, which can cause them to look verbose. Consider the XML sample.

The following XML is formatted as follows

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
<book id="b0836217462" available="yes">
<isbn>
   08362   17462
</isbn>
</book>
</library>

Formatting and respecting the Significant whitespace (i.e. unchecked) will result in the following (note the data within the isbn element is the same, but its not cleanly formatted).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>
   08362   17462
</isbn>
    </book>
</library>

Formatting and ignoring the Significant whitespace (i.e. checked) will result in the following (note the data within the isbn element has changed, the leading and trailing whitespace has been removed).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>08362   17462</isbn>
    </book>
</library>

See Also

Options
Text Editor Options


XML Code Editor Options

Glossary Item Box

Indent Size

The number of columns used for a tab. This is also the number of columns XML data will be indented by.

Use

Tabs - a tab is used to for each indent.

Spaces - a number of spaces characters is used for each indent.

Show Line Numbers

Indicates if line numbers should be shown in the left hand margin

Show Whitespace

Non-visible characters like spaces and tabs are shown in the editor (default is off).

Word Wrap

Line lines are wrapped when displayed in the editor (default is off).

Can cause performance problems when line lengths are very long (typically if a large xml file is unformatted and exists as a single line of text).

Enable Macros

Enabled keyboard macros to be recorded and played back (default is enabled).

Show XML Tooltips

If this is true the tooltips are shown within the XML Code Editor when a element/attribute is hovered over.

Indent Attributes

If this is checked then when attributes are auto formatted then they are placed one per line. If its not checked then they are all placed on the same line as the opening element.

Ignore Significant Whitespace Formatting XML

Causes leading and trailing whitespace to be ignored (default is false). Whitespace before and after data contained within an XML Element is considered to be significant to most parsers. It will therefore be preserved when formatting your XML documents, which can cause them to look verbose. Consider the XML sample.

The following XML is formatted as follows

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
<book id="b0836217462" available="yes">
<isbn>
   08362   17462
</isbn>
</book>
</library>

Formatting and respecting the Significant whitespace (i.e. unchecked) will result in the following (note the data within the isbn element is the same, but its not cleanly formatted).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>
   08362   17462
</isbn>
    </book>
</library>

Formatting and ignoring the Significant whitespace (i.e. checked) will result in the following (note the data within the isbn element has changed, the leading and trailing whitespace has been removed).

Copy Code
<?xml version="1.0" encoding="utf-8"?>
<library>
    <book id="b0836217462" available="yes">
        <isbn>08362   17462</isbn>
    </book>
</library>

See Also

Options
Text Editor Options


Column Details (Excel Reader Wizard)
Send Feedback

Glossary Item Box

After you have specified the spreadsheet range to read data from, the Wizard will display the Columns contained within the range along with a calculated Data Type for each column based on the existing data within each column.

This page allows you to change the Data Type, e.g. the current data may look like integer values, but you may want to change this to be String.


Select Range (Excel Reader Wizard)
Send Feedback

Glossary Item Box

The Wizard will analyse the spreadsheet and dispay all the Sheets which contain data along with globally and locally defined regions and tables.

You then have the choice to either select one of these predefined areas (which populates the Refers To field) or specify a data range yourself in the 'Refers To' field.

Additionally, you can specify if the First Line contains column names and optionally Ignore Last Line which, for example, may contain totals.


Source File (Excel Reader Wizard)
Send Feedback

Glossary Item Box

Excel Data

The first screen allows you to select your Excel file containing the structure of the data you want to read.


Data Structure (Excel Writer Wizard)
See Also Send Feedback

Glossary Item Box

When writing to an Excel spreadsheet you must first determine the structure of the data area to write into. We recommend that you use an existing spreadsheet to simplify this process.

Clicking on 'Read structure from an existing sample document' button will run the Excel Reader Wizard to allow you to select the data range.

See Also

Source File (Excel Reader Wizard)


Output Filename (Excel Writer Wizard)
Send Feedback

Glossary Item Box

The final screen allows you to specify the output filename to use.


Select Range (Excel Writer Wizard)
Send Feedback

Glossary Item Box

If you chose to select the data range from an existing spreadsheet, this page will be pre-populated with the range information you specified.

If not, you can manually specify the required range information.

You can also specify the option to 'Write Column Names' into the output.


File Associations

Glossary Item Box

The Liquid XML Studio is asked to open a file with an extension it does not know about, the user is prompted to select the editor that will be used to open the document. This choice is remembered and used in the future when a file of the same type is opened.

These file associations can be changed in the Options dialog.

Editor Selection Dialog

See Also

Options
File Associations Options


File New
Send Feedback

Glossary Item Box

Visual Studio Extension

From the File->New->File... Menu you are prompted to select a file type. A New XSD Schema can be created using the Liquid XML Schema Editor->XML Schema (XSD) item.

Liquid XML Studio

Liquid XML Studio New File Dialog


Columns (Flat File Reader Wizard)
See Also Send Feedback

Glossary Item Box

Column Details Page

If your source data contained column headings then you may well be finished at this stage, however if the data contains no column information, or you don't like the names in the file then you can change them on this page.

Simply select the column to edit and set the name (if you are working on a fixed width file then you also get the option to set the column width).

If you did not provide a source document to infer the structure from then you must define it here by hand.

See Also

Source File (Flat File Reader Wizard)
Structure (Flat File Reader Wizard)
Delimiters (Flat File Reader Wizard)
Fixed Length Delimiters (Flat File Reader Wizard)

Text
Text File Source


Delimiters (Flat File Reader Wizard)
See Also Send Feedback

Glossary Item Box

Delimited File Configuration

If your file was delimitated, then the next screen allows you to define the rules used to read each field.

The delimiters break the fields, its possible to select a number of delimiters, but in practice the file normally only uses a tab or a comma.

The "Fields are enclosed in quotes" property means that if the first char within a field is a quote then the value is considered to be everything up to the next quote. This makes it possible for a field to contain the delimiter character. If the field also needs to contain a quote char then 2 quote chars in a row are interpreted as a single quote.

Data | Field 1 Value | Field 3 Value | Field 3 Value | Field 4 Value
abc,123,xyz | abc | 123 | xyz |
abc,"123",xyz | abc | 123 | xyz |
abc,"1,23",xyz | abc | 1,23 | xyz |
abc,1,23,xyz | abc | 1 | 2 | xyz
abc,"1""23",xyz | abc | 1"23 | xyz |
abc,"1"23",xyz | ERROR |  |  |
abc,1"23,xyz | abc | 1"23 | xyz |
abc,"1""2,3",xyz | abc | 1"2,3 | xyz |

See Also

Source File (Flat File Reader Wizard)
Structure (Flat File Reader Wizard)
Fixed Length Delimiters (Flat File Reader Wizard)
Columns (Flat File Reader Wizard)

Text
Text File Source


Fixed Length Delimiters (Flat File Reader Wizard)
See Also Send Feedback

Glossary Item Box

Fixed Field Width Delimiter

If you selected "Fixed Width" on the delimiter page then the delimiter setup page is next, this allows you to graphically determine where the breaks in the fields are, just click on the display area where the delimiters should be, if you make a mistake just click it again to remove it.

Here you can see the delimiters have been added at the appropriate positions.

See Also

Source File (Flat File Reader Wizard)
Structure (Flat File Reader Wizard)
Delimiters (Flat File Reader Wizard)
Columns (Flat File Reader Wizard)

Text
Text File Source


Source File (Flat File Reader Wizard)
See Also Send Feedback

Glossary Item Box

Flat File Data

The first wizard page give you the option of basing the reader on an existing data file, or defining the data source from scratch.

While it possible to describe a data source from scratch, its much easier to infer it from an existing data file.

If you selected a to infer the structure from an existing file then the next page allows you to define the field delimiters.

See Also

Source File (Flat File Reader Wizard)
Structure (Flat File Reader Wizard)
Delimiters (Flat File Reader Wizard)
Fixed Length Delimiters (Flat File Reader Wizard)
Columns (Flat File Reader Wizard)

Text
Text File Source


Structure (Flat File Reader Wizard)
See Also Send Feedback

Glossary Item Box

Delimiter Type

There are 2 forms of file delimited and fixed width, delimited files use a special character to separate fields, fixed width pad all the fields so they take up the same amount of space.

Some files also contain the column names on the first row.

Select the options that are applicable and press Next.

See Also

Source File (Flat File Reader Wizard)
Delimiters (Flat File Reader Wizard)
Fixed Length Delimiters (Flat File Reader Wizard)
Columns (Flat File Reader Wizard)

Text
Text File Source


Columns (Flat File Writer Wizard)
See Also Send Feedback

Glossary Item Box

Column Details Page

If your source data contained column headings then you may well be finished at this stage, however if the data contains no column information, or you don't like the names in the file then you can change them on this page.

Simply select the column to edit and set the name (if you are working on a fixed width file then you also get the option to set the column width).

If you did not provide a source document to infer the structure from then you must define it here by hand.

See Also

Load Structure (Flat File Writer Wizard)
Structure (Flat File Writer Wizard)
Delimiters (Flat File Writer Wizard)
Output Filename (Flat File Writer Wizard)


Delimiters (Flat File Writer Wizard)
See Also Send Feedback

Glossary Item Box

Delimited File Configuration

If your file was delimitated, then the next screen allows you to define the rules used to read each field.

The delimiters break the fields, its possible to select a number of delimiters, but in practice the file normally only uses a tab or a comma.

The "Fields are enclosed in quotes" property means that if the first char within a field is a quote then the value is considered to be everything up to the next quote. This makes it possible for a field to contain the delimiter character. If the field also needs to contain a quote char then 2 quote chars in a row are interpreted as a single quote.

Data | Field 1 Value | Field 3 Value | Field 3 Value | Field 4 Value
abc,123,xyz | abc | 123 | xyz |
abc,"123",xyz | abc | 123 | xyz |
abc,"1,23",xyz | abc | 1,23 | xyz |
abc,1,23,xyz | abc | 1 | 2 | xyz
abc,"1""23",xyz | abc | 1"23 | xyz |
abc,"1"23",xyz | ERROR |  |  |
abc,1"23,xyz | abc | 1"23 | xyz |
abc,"1""2,3",xyz | abc | 1"2,3 | xyz |

See Also

Load Structure (Flat File Writer Wizard)
Structure (Flat File Writer Wizard)
Columns (Flat File Writer Wizard)
Output Filename (Flat File Writer Wizard)


Load Structure (Flat File Writer Wizard)
See Also Send Feedback

Glossary Item Box

If you already have an example of an output file then you can use this to define the structure that will be used for your writer.

The "Read structure from existing sample document" runs another wizard that allows you to define the structure of your document based on an existing file format.

See Also

Load Structure (Flat File Writer Wizard)
Structure (Flat File Writer Wizard)
Delimiters (Flat File Writer Wizard)
Columns (Flat File Writer Wizard)
Output Filename (Flat File Writer Wizard)


Output Filename (Flat File Writer Wizard)
See Also Send Feedback

Glossary Item Box

The default filename that will be used to write out the new text file. If this is not specified then the input connection point 'Filename' must be connected.

This provides a simple way to write to a single file, if you need to create multiple files or construct the filename dynamically, then leave this blank.

See Also

Load Structure (Flat File Writer Wizard)
Structure (Flat File Writer Wizard)
Delimiters (Flat File Writer Wizard)
Columns (Flat File Writer Wizard)


Structure (Flat File Writer Wizard)
See Also Send Feedback

Glossary Item Box

Delimiter Type

There are 2 forms of file delimited and fixed width, delimited files use a special character to separate fields, fixed width pad all the fields so they take up the same amount of space.

Some files also contain the column names on the first row.

Select the options that are applicable and press Next.

See Also

Load Structure (Flat File Writer Wizard)
Delimiters (Flat File Writer Wizard)
Columns (Flat File Writer Wizard)
Output Filename (Flat File Writer Wizard)


%%Phrase%%

Glossary
Send Feedback

Glossary Item Box

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

A

additionalItems
Applied to array values, it determines the validation applied AFTER the values defined in 'items' have been validated. If its true, any values after the ones specified in items are accepted, if its false values after the ones defined in 'items' are invalid, if its a JsonSchema object, then any items after the ones defined in 'items' must conform the 'AdditionalItem' schema.

Any

Represent any data type.

Binary, Byte, Char, Date, DateTime, Decimal, Double, Float, Guid, Int16, Int32, Int64, Node, SByte, String, Time, TimeSpan, UInt16, UInt32, UInt64

Atomic

Represent any primitive data type.

Binary, Byte, Char, Date, DateTime, Decimal, Double, Float, Guid, Int16, Int32, Int64, SByte, String, Time, TimeSpan, UInt16, UInt32, UInt64

B

Binary
Binary data, an array of bytes.

Boolean
A boolean value (true, false)

Byte
Unsigned 8-bit integer in the range 0 to 255

C

Char
A Unicode character, represented as an unsigned 16-bit integer

Component

A transform component within a Data Mapper Transform.

Transforms can contain many Components.

Connection Point

A connectable point on a component, component can have 2 types of connection point, input and output.

Connector

Connects an output connection point to an input connection point.

D

Date
Represents a date in the range January 1, 0001 to December 31, 9999

DateTime
Represents an instant in time, typically expressed as a date and time of day. With a millisecond precision.
In the range 00:00:00.0000000, January 1, 0001 to 23:59:59.9999999, December 31, 9999

Decimal

The decimal keyword indicates a 128-bit data type. Compared to floating-point types, the decimal type has more precision and a smaller range, which makes it appropriate for financial and monetary calculations.

In the range -79228162514264337593543950335 to 79228162514264337593543950335 (28-29 significant digits)

Double

Stores a 64-bit floating-point value.
±5.0 × 10−324 to ±1.7 × 10308 (15-16 significant digits)

F

Float
Stores a 32-bit floating-point values.
In the range -3.4 × 1038 to +3.4 × 1038 (15-16 significant digits)

G

Guid
Represents a 16 byte globally unique identifier (GUID).

I

Input Connection Point

This is a connectable input on a component.

Input connection points can be connected to a single output connection point on another component.

Int16
Signed 8-bit integer in the range -32,768 to 32,767

Int32
Signed 32-bit integer in the range -2,147,483,648 to 2,147,483,647

Int64
Signed 64-bit integer in the range -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807

N

Numeric

Represent any numeric primitive data type.

Byte, Decimal, Double, Float, Int16, Int32, Int64, SByte, UInt16, UInt32, UInt64

O

Output Component

A component that writes to a data out (to XML, DB, text file etc).

A transform can have one output transform.

Output Connection Point

This is a connectable output on a component.

Output connection points can be connected to one or more input connection points on other components.

P

Properties Window

Displays the properties for the currently selected object. If the window is not visible then F4 will show it (or View->Properties Window).

The Properties window is key to editing most graphical views.

S

SByte
Signed 8-bit integer in the range -128 to 127

String
The string type represents a sequence of zero or more Unicode characters

T

Time
Represents a time, with a millisecond precision.

TimeSpan

TimeSpan represents a duration of time, it can be negative or positive and has a millisecond precision.

In the range -10,675,199 days to +10,675,199 days.

U

UInt16
Unsigned 16-bit integer in the range 0 to 65,535

UInt32
Unsigned 32-bit integer in the range 0 to 4,294,967,295

UInt64
Unsigned 64-bit integer in the range 0 to 18,446,744,073,709,551,615


Inline Property
Send Feedback

Glossary Item Box

Schema nodes may have a number of properties and constraints set against them, valid properties are shown in the Properties Window with the node is selected.

The Keywords list provides a list of all of these along with a detailed explanation.

The properties are also displayed inline within the schema.

They can also be seen in the properties window

and tooltips

Inline properties can be added by setting them in the property window.

They can be edited inline within the schema or via the property window.

They can be deleted by selecting them in the diagram an pressing delete or by clearing their value in the property window.


Schema File

Glossary Item Box

The file (or root) schema is the outer most schema in the file.

On the whole it behaves like any other schema, but is also allowed to contain definitions, it also contains a $schema tag which indicates that this Json document is a schema and the version of the Json Schema standard it uses.

See Also

Schema


Generating Documentation
Send Feedback

Glossary Item Box


Reference Resolution
Send Feedback

Glossary Item Box

The Json Schema allows schemas to be defined inline or retrieved from a reference.

To indicate a reference the $ref keyword is used with the value being the reference to the schema using the JSON Pointer convention.

Json Schema Source Copy Code
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "ProductCode": {
            "$ref": "#/definitions/ProductCodeType"
        }
    },
    "definitions": {
        "ProductCodeType": {
            "type": "string",
            "pattern": "[A-Z][0-9]*"
        }
    }
}

The resolution of a reference is carried out as follows.

  • The base context for of the schema containing the $ref keyword is determined.
  • This $ref value is combined with this base context to produce a qualified reference.
  • The qualified traversed to find the schema that is referred to.

So working through our example, lets assume our schema is at http://example/test.json.

  • We need to calculate the base context for the schema containing $ref ("ProductCode"). This is easies to do working back towards the root. In simple terms we do this by looking at the source and getting all the quoted names in the path, so working "ProductCode, "properties", the root schema takes its context from the url "http://example/test.json". These are all combined to produce our base context which is http://example/test.json#/properties/ProductCode.
  • We combine this base context (http://example/test.json#/properties/ProductCode) and our reference value (#/definitions/ProductCodeType) which gives us http://example/test.json#/definitions/ProductCodeType
  • We then traverse the schema source to find the schema that is referenced.

The referenced schema may be in another schema file.

This is an over simplification of the resolution process as the id keyword comes into play while calculating the contexts.

Put simply if a schema has an id keyword then its context is taken from it and not the name of the schema name.

The use of id's significantly complicates schemas and is beyond the scope of this documentation.

The complexity that belies it is only hinted at within the Json schema standard.

See The id conundrum, Understanding Json Schema for a better description of the issues.


Large File Editor
Send Feedback

Glossary Item Box

The Large File Editor is capable of opening huge document, 1000s GigaBytes, larger in fact there is no practical limit to the size of file it can open. When a document is opened in Liquid XML Studio that is to large load into memory, the Large File Editor is used instead.

The Large File Editor differs from standard editors in that it does not need to load the entire document into memory. In order to accomplish this the editor loads only the sections of the document that are visible on screen, and when edits are made, only the changes to the document are held in memory, meaning that working with ridiculously large documents can be done on a low spec PC while maintaining a responsive user interface.

In order to accomplish this internal the editor is quite different to conventional editors, much of this is implementation detail and nothing the end user needs to be aware of, but it does lead to a few quirks.

Some standard editor features

Cut & Paste

Clipboard operations within the same document are unlimited in size and take place at a very low (memory) cost, allowing GB cut and paste operations instantly. Limits are placed on the amount to text data that can be placed on the clipboard for use in other applications (you can't copy a 10 TB of text onto the clipboard, windows wont like it!).

Undo/Redo

The Large File Editor supports unlimited multi-step undo and redo. Again these actions are at a very low cost, making them fast and efficient.

Find/Replace

Standard Find/Replace functionality is supported within the editor, but given the size of the documents may take a while, scanning though huge files takes time!

Text Encodings

The standard text encodings are all supported including Unicode and UTF-8.

Some Quirks

Save

Because the description of the edited document is a combination of the current document on disk and the in memory change list, when the document is saved a copy is made, the original deleted and the copy renamed to be the original. As a result you need enough free space to create a copy of the file plus your changes, it also means that even a trivial change may be slow to save (at least as long as it takes to copy the file using Windows commands or Windows explorer).

As a result of saving the document the undo/redo buffer is lost (the undo actions were recorded against the changes to the original file, when the document is saved the original document has been changed and our undo list is no longer of any use).

The undo/redo buffer is not effected when SaveAs is used.

Scrolling

In a standard text editor the position in the document (and therefore the vertical scroll position) is worked out based on the line number the caret is on. However the only way to know the current line number is to count all the lines from the start, this would make the user interface too slow to use. So instead the vertical scroll position is calculated from the byte offset of the caret, this may not accurately reflect the position in the file (most notably in small files, or files with a long run of short lines followed by a run of long lines), but works well enough in practical examples.


Web Service Browser Wizard - Select a WSDL or WADL File

Glossary Item Box

Select a WSDL or WADL File

First you must select the web service type you want to look at (WSDL, WADL or User Defined Web Service - see below) using the radio buttons at the top of the page.

You then need to specify the URL that returns the WSDL or WADL for the web service.

For .Net web services, this of the form http://ServerName/Service.asmx?WSDL

You can also select a local file e.g C:\temp\Service.wsdl

You can test the web service your have specified is valid using the "Test" button.

For those just curious about the tool, we have supplied a simple web service which allows you to explore the functionality of the Web Service Test Client. To use this web service, click the "Use Liquid Technologies Sample Web Service" link button.

If the service requires authentication, then you can add a user name and password.

If you save the web service call then the password is not encrypted in the file.

The Wizard will not allow you to move on until the web service URL is pointing at a valid WSDL file.

See Also

Web Service Browser Wizard - Selecting a Web Method
Web Service Browser Wizard - Select option to create a User Defined Web Service


Web Service Browser Wizard - Selecting a Web Method

Glossary Item Box

Selecting a Web Method

You can now select the Web method you wish to call. Web services typically offer the ability call there methods using a number of protocols. The browser shows all the supported protocols and all the methods exposed for each of them (Note Not all methods can be called via HTTP POST & GET).

The Web Service Test Client supports 4 protocols, Soap 1.1, Soap 1.2, HTTP GET & HTTP POST. Any other protocols are ignored.

Once you select your method, and press Finish, and request is constructed for you.
You can then modify the request and call the web method. See Web Service Test Client.

See Also

Web Service Browser Wizard - Select a WSDL or WADL File
Web Service Browser Wizard - Select option to create a User Defined Web Service


Web Service Browser Wizard - Select option to create a User Defined Web Service
See Also Send Feedback

Glossary Item Box

Select option to create a User Defined Web Service

If your Web Service does not have a WSDL or WADL file, you can choose the option to create a User Defined Web Service on the first page of the Wizard.

When you click 'Next >' you are then presented with the following screen which allows you to specify a service, URI, method (GET or POST) and method parameters.

Clicking 'Finish' then allows you to save the User Defined Web Service as a WADL file.

The next time you want to access the service, you can then select the WADL file you just created.

See Also

Web Service Browser Wizard - Select a WSDL or WADL File
Web Service Browser Wizard - Selecting a Web Method


Xml InferXsd Wizard 1
Send Feedback

Glossary Item Box

Specify the sample XML files that will be used to infer the XSD schema.

The more sample files you have the more accurate the resulting XML Schema.


Xml InferXsd Wizard 2
Send Feedback

Glossary Item Box

The second page contains options relating to the inferring process.

Schema Name

The name of the schema that will be produced (there is no need to add the .xsd extension).
If more than 1 schema file needs to be created, then the schema files will be named <Schema Name>1.xsd, <Schema Name>2.xsd etc

Output Directory

The location where your schema file/files will be written.

Encoding

The encoding that will be applied to your XML Schema (UTF-8 or UTF-16 are the most commonly used, only change this if you understand encoding).

Occurrence Options

If the Occurrence property is set to Restricted, the first time elements are encountered in the XML document, the schema declaration is inferred as minOccurs="1".
When attributes are encountered, the schema declaration is inferred as use="required". If the Occurrence property is set to Relaxed, element schema declarations are inferred as minOccurs="0", and attribute schema declarations are inferred as use="optional".

Type Inference Option

If the TypeInference property is set to Relaxed, the inferred type of elements and attributes in the XML document with simple content is always xs:string.
If the TypeInference property is set to Restricted, more specific types are inferred, such as xs:date, xs:decimal, xs:unsignedByte, and so on.