Qualified Names

In certain cases Jsonix structures have to use qualified names (QNames for short). There are mainly two cases for this:

• On the root or top-level object
• In element reference or references properties

Qualified names are defined in the following form:

{
    localPart : 'element',
    prefix : 'tns',
    namespaceURI : 'urn:test'
}

The prefix and namespaceURI are optional.

You can also use compact naming:

• localPart - lp
• prefix - p
• namespaceURI - ns

The same example:

{
    lp : 'element', p : 'tns', ns : 'urn:test'
}

When marshalling you can provide the qualified name in the string form (i.e. prefix:name).

• If the prefix is known in the context, it will get resolved into the associated URI.
• If the prefix is not known in the context, an empty namespace URI will be assumed.

See also Configuring Namespace Prefixes.

Consider the following example. Assume we want to define a qualified name with the local part GetRecords and namespace URI http://www.opengis.net/cat/csw/2.0.2. In the full object notation this will look as follows:

{
    "namespaceURI": "http://www.opengis.net/cat/csw/2.0.2",
    "localPart": "GetRecords",
    "prefix": "csw"
}

If the csw prefix is often associated with the namespace http://www.opengis.net/cat/csw/2.0.2, it would make sense to configure it on the context level:

var context = new Jsonix.Context([...], {
   namespacePrefixes: {
        'http://www.opengis.net/cat/csw/2.0.2': 'csw'
    }
});

In this case Jsonix will know that namespace URI http://www.opengis.net/cat/csw/2.0.2 usually means the prefix csw and the prefix csw usually means http://www.opengis.net/cat/csw/2.0.2.

In this case instead of the verbose object shown above you could simply write 'csw:GetRecords'. When marshalling, Jsonix will encounter a string where it exected a qualified name and will try to parse that string as a QName, also considering the configured namespace prefixes. This way the prefix csw will be resoved into the namespace URI http://www.opengis.net/cat/csw/2.0.2 and we'll get the correct qualified name.

When unmarshalling, Jsonix will still return qualified names of elements (on the top-level as well as in the reference properties) as object structures by default.