|
|
Some of the most common support questions we receive are about namespace declarations. This document will attempt to provide a simplified explanation of namespace declarations, their significance for the xml documents and for the modeling of the documents in TransacXML.
The possibilities for declaring namespaces are rather complex. The following description will not try to describe all the special cases - it is only an attempt to describe the most common situations you will find in XML documents.
If you want a more exhaustive description of namespaces in XML, the following documents are highly recommended:
Namespace declarations looks exactly like attributes, but they can be recognized by the fact that the name always starts with xmlns.
Namespace declarations are used to specify which namespace a given name belongs to.
Namespace declarations can either declare a default namespace or associate a prefix with a namespace:
Default namespace declarations has the format:
xmlns="http://www.websydian.com/XMLExample"
When a default namespace is declared, it means that all elements where the names does not have a prefix belongs to the specified namespace.
In this case, the format will be like this:
xmlns:xx="http://www.websydian.com/XMLExample"
In this case all elements and attributes with names starting with xx: will belong to the specified namespace.
Please note that a default namespace declaration only applies to elements - attributes must have a prefix if they are to belong to a namespace.
This example document declares the use of two namespaces: http://www.websydian.com/DefaultNamespace and http://www.websydian.com/AnotherNamespace
http://www.websydian.com/DefaultNamespace is the default namespace for the document, while http://www.websydian.com/AnotherNamespace is bound to the prefix we.
This means that the elements A and B belong to http://www.websydian.com/DefaultNamespace.
While the elements C and D and the attribute att2 belong to http://www.websydian.com/AnotherNamespace.
As the attribute att1 has no prefix, it does not belong to any namespace.
To find out which namespace an element or an attribute belongs to - do the following:
If the element has a prefix - find the xmlns declaration that declares the same prefix as the one the element name has - the namespace declared by this declaration is the one the element belongs to.
If the element has not got a prefix, check if a default namespace is declared (xmlns="..."). If there is such a declaration, the element belongs to the namespace specified by the declaration. If no default namespace declaration exists, the element does not belong to a namespace.
For attributes
If the attribute has a prefix - find the xmlns declaration that declares the same prefix as the one the attribute name has - the namespace declared by this declaration is the one the attribute belongs to.
If the attribute has no prefix, the attribute does not belong to a namespace.
The above description will be enough for most documents. But to provide a more complete description, this section will describe a few more advanced topics.
In most cases, the namespace declarations will be placed in the top element of the document - like in the example:
Placing the namespace declarations here means that the namespace declaration is valid for all of the document - in this case, it means that the elements A, B, C, and D all belongs to the specified namespace.
But you can actually place the namespace declarations in any element in the document. The namespace declarations are valid for the element they are placed in and for any scoped elements.
So in the example:
The elements B, C, and D belongs to the specified namespace, while A does not belong to any namespace.
The standard does allow the specification of more than one default namespace declaration - for example:
In this case B, C, and D belongs to http://www.websydian.com/DefaultNamespace, while E and F belongs to http://www.websydian.com/AnotherNamespace.
Even though this is valid, it is clearly not very readable - and it is not a recommended way to create XML documents.
The main reason to mention this here is that you might accidentally create such documents.
This will happen if you in TransacXML specifies a blank prefix for more than one namespace.
If this is the case, it is recommended that you specify a value for the prefix for each of the namespaces - or at least only have one namespace where you do not specify a prefix. You can of course avoid this by always specifying a prefix for all XMLElement entities and ElementFields that inherits from NamespaceAware.
As an example:
In this case all the elements belong to the same namespace - but two different prefixes are used to specify this.
This is obviously more confusing than necessary - and should be avoided.
In TransacXML, you can avoid this situation by ensuring that every time you specify a specific namespace, you specify the same prefix.
A way to ensure this is to create an abstract XMLElement and an abstract ElementField for each namespace you use. Let these objects inherit from NamespaceAware, and specify the namespace and the prefix you want to use in the scoped source codes. Then let the entities and fields that should belong to the namespace inherit form the abstract entity/field.
In general, you do not need to model these declarations.
When creating an XML document, the parser will automatically insert the necessary namespace declarations in the document. This means that for each namespace you have used, at least one namespace declaration will be created.
The only case where you might need to create a namespace declaration is if you want to declare a namespace you does not use for any elements or attributes in the document (for an example - see the section about handling the Schema-instance namespace below).
Again, you do not have to handle these declarations - when creating the document, they are created automatically, when reading the document, the parser uses them to determine the namespace of the elements and attributes - but you have nothing to use this information for.
As a number of support questions have referred to the namespace declarations for the schema instance namespace, this section will describe how you can handle this namespace declaration.
The schema instance namespace is: http://www.w3.org/2001/XMLSchema-instance.
In almost all cases, the prefix used for this namespace will be xsi. This means that the full namespace declaration is:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance
The Schema-Instance namespace is used when you want to specify that an XML document can be validated by using a specific W3C XML schema.
This can be done by specifying a location for the schema for each of the namespaces used using the attribute xsi:schemaLocation or by specifying a location for the schema containing the definitions for the elements that does not belong to any namespace using the attribute xsi:noNamespaceSchemaLocation.
However, many tools indiscriminately insert the namespace declaration whenever a document is created even though neither the schemaLocation nor the noNamespaceSchemaLocation attributes are used.
This means that the following examples can occur:
Only the namespace declaration is inserted in the document:
The namespace declaration and a schemaLocation are inserted in the document.
The schemaLocation attribute specifies that the schema describing the namespace http://www.websydian.com/DefaultNamespace can be found in the file DefaultNamespace.xsd.
The namespace declaration and a noNamespaceSchemaLocation are inserted in the document:
The noNamespaceSchemaLocation specifies that the schema containing the definitions for the elements and attributes that do not belong to any namespace can be found in the file NoNamespace.xsd.
This is the easy situation - you do not have to do anything.
Unless you really want to access the values specified for the schemaLocation or noNamespaceSchemaLocation, there is no reason for you to model these attributes.
If you of some reason want to access these data, specify either an attribute schemaLocation (example 2) or an attribute noNamespaceSchemaLocation (example 3) for the XMLElement A. In both cases let the attribute inherit from NamespaceAware and specify http://www.w3.org/2001/XMLSchema-instance in the Namespace source code scoped by the field.
Doing so means that the value automatically will be returned by the SingleFetch function scoped by the entity A.
In some cases, you are going to create a document according to specifications delivered by another party. In these cases it is quite common that it is demanded that the namespace declaration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" and in some cases either the schemaLocation or the noNamespaceSchemaLocation attributes are included in the document.
In a lot of these cases, this is actually not information that is needed or in fact used for anything by the other party - but normally it is easier to just insert the information in the document instead of discussing it with the other party.
This section will explain how to create handle each of the three examples.
In this case, only the namespace declaration is specified - as described above, this just binds the use of the prefix xsi to the Schema-Instance namespace - and as this prefix is not used in the document, it is actually meaningless. However in some cases the other party will insist that the namespace declaration is inserted - you can do this as follows:
First, create the XML model for the document - this means that an XMLElement entity A will be created.
To insert the namespace declaration, create the following triples:
| A.Fields | field FLD | xmlns:xsi |
| has FLD | A.Fields.xmlns:xsi | |
| A.Fields.xmlns:xsi | is a FLD | AttributeField |
| A.Fields.xmlns:xsi | value VAL | SchemaInstance |
In the literal for the value SchemaInstance - specify: http://www.w3.org/2001/XMLSchema-instance.
Doing this will mean that a field with the name xmlns:xsi will be part of the input to the InsertRow and the InsertRowDangling functions.
When you create the document, you will call the function A.SingleFetch - map the field xmlns:xsi with the value SchemaInstance.
In this case, we use the fact that the XML standard does not prohibit the use of names containing a colon - so we define a name xmlns:xsi for an attribute. When the other party receives this document, there is no information that this was originally created as an attribute - and they will handle it as any other namespace declaration.
First, create the XML model for the document - this means that an XMLElement entity A will be created.
| A.Fields | field FLD | schemaLocation |
| has FLD | A.Fields.schemaLocation | |
| A.Fields.schemaLocation | is a FLD | AttributeField |
| A.Fields.schemaLocation | is a FLD | NamespaceAware |
Specify the following literals for the source codes:
schemaLocation.Namespace: http://www.w3.org/2001/XMLSchema-instance
schemaLocation.prefix: xsi
This means that the field schemaLocation will occur as an input field for the A.InsertRow and A.InsertRowDangling functions.
Specify the value "http://www.websydian.com/DefaultNamespace DefaultNamespace.xsd" for the field schemaLocation when you call the InsertRow function..
The parser will automatically insert the xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" namespace declaration.
First, create the XML model for the document - this means that an XMLElement entity A will be created.
| A.Fields | field FLD | noNamespaceSchemaLocation |
| has FLD | A.Fields.noNamespaceSchemaLocation | |
| A.Fields.noNamespaceSchemaLocation | is a FLD | AttributeField |
| A.Fields.noNamespaceSchemaLocation | is a FLD | NamespaceAware |
Specify the following literals for the source codes:
noNamespaceSchemaLocation.Namespace: http://www.w3.org/2001/XMLSchema-instancenoNamespaceSchemaLocation.prefix: xsi
The field noNamespaceSchemaLocation will occur as an input field for the A.InsertRow and A.InsertRowDangling functions.
Specify the value "http://www.websydian.com/DefaultNamespace DefaultNamespace.xsd" for the field noNamespaceSchemaLocation when you call the InsertRow function.
The parser will automatically insert the xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" namespace declaration.
Online documentation - Websydian v6.5