Namespace Handling for Specific X-Machine Requests

This section contains information about the following:

Valid Collection and Doctype Names in TSD3/TSD4

Collection Names

As in TSD3, a collection name is a value of type xs:NMTOKEN. The name of a collection identifies it uniquely within the entire database.

Doctype Names

In TSD4, a doctype name is a QName, with the restriction that both the lexical and the expanded QName must be unique within the collection. The uniqueness of the lexical QName within the collection, effectively being just a plain string, is important especially for plain URL addressing (see X-Machine Programming).

Namespace Context of Doctypes

Each doctype in a Tamino database has a namespace context. From a logical point of view, the namespace context is a table describing a unique mapping of prefixes to URIs. It is extracted from the doctype's schema document(s) from the following locations:

  • namespace declarations in the corresponding tsd:doctype element (used for that doctype only);

  • namespace declarations in the xs:schema root element of the schema document containing the tsd:doctype element (used for all doctypes defined in that schema document);

  • namespace declarations in the tsd:collection document, for the collection in which the doctype is contained. This document allows you to assign properties to a collection, e.g. the namespace context or whether the schemaless storage of documents is permitted in that collection. It can be stored in Tamino using the _DEFINE command. Please see below for an example. The namespace declarations in this document affect all doctypes in the collection.

Any prefix defined at one of these locations goes into the namespace context. The order in which the places are listed reflects their priority; for example, a namespace declaration given in the tsd:doctype element overrides a namespace declaration given in the xs:schema root element. For collections allowing for schemaless storage of documents, there may not be a schema document. Hence, only the third location applies.

Note:
As the namespace context is crucial especially for the behavior of existing applications developed with previous versions of Tamino, namespace declarations contributing to the namespace context of any doctype may not be modified or removed when updating a schema.

Example:

Consider the following schema:

    <xs:schema 
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:tsd="http://namespaces.softwareag.com/tamino/TaminoSchemaDefinition" 
      xmlns:p1="URI1"
      xmlns:p2="URI2"
      targetNamespace="URI1" >
      <xs:annotation>
        <xs:appinfo>
          <tsd:schemaInfo name="mySchema">
            <tsd:collection name="myCollection"/>
            <tsd:doctype name="p1:root"/>
            <tsd:doctype name="p1:other" xmlns:p2="URI2a" xmlns:p3="URI3" xmlns:p5="URI5"/>
          </tsd:schemaInfo>
        </xs:appinfo>
      </xs:annotation>
    ...
    </xs:schema

with the following collection object:

    <tsd:collection name="myCollection"
      xmlns:tsd="http://namespaces.softwareag.com/tamino/TaminoSchemaDefinition" 
      xmlns:p2="URI2b"
      xmlns:p3="URI3a"
      xmlns:p4="URI4"
    />

The namespace context for the doctype with the lexical QName p1:root is:

Prefix URI
p1 URI1
p2 URI2
p3 URI3a
p4 URI4

For doctype p1:other, the namespace context is:

Prefix URI
p1 URI1
p2 URI2a
p3 URI3
p4 URI4
p5 URI5

The namespace context of a doctype is used for different purposes:

  • Provide mapping of prefixes to URIs for X-Query requests (see the _XQL and _DELETE commands).

_XQL, _DELETE

Lexical QNames within _XQL and _DELETE requests are translated to expanded QNames before further processing. This translation is based on the namespace context of the corresponding doctype. If a query, e.g. 

_XQL=/*/p:name

does not uniquely identify the doctype, it is first transformed to a representation where each expression refers to a unique doctype within the current collection.

Assuming the collection contains doctypes dt1, dt2 and dt3, the query above can be transformed to: 

_XQL= /dt1/p:name | /dt2/p:name | /dt3/p:name

Then, the prefix p: can be mapped to a URI for each of the doctypes dt1, dt2, and dt3, based on the corresponding namespace context. Note that the URI to which p: is mapped may differ between the doctypes. If a prefix in the request cannot be mapped based on the namespace context, it is assumed that there is no matching QName in the documents. If a lexical QName does not have a prefix, it is assumed that it does not belong to any namespace at all.

Default Namespace

A special case occurs when a doctype with the schema's targetNamespace attribute is associated with the default namespace in the respective schema document. Consider the following schema: 

    <xs:schema 
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:tsd="http://namespaces.softwareag.com/tamino/TaminoSchemaDefinition" 
      xmlns="URI"
      targetNamespace="URI" >
      <xs:annotation>
        <xs:appinfo>
          <tsd:schemaInfo name="mySchema">
            <tsd:collection name="myCollection"/>
            <tsd:doctype name="root"/>
          </tsd:schemaInfo>
        </xs:appinfo>
      </xs:annotation>
      ...
    </xs:schema

The lexical QName of the doctype defined in the schema is just root without any prefix. Its expanded QName is (URI,root). In order to distinguish the doctype's lexical QName from lexical QNames corresponding to expanded QNames not belonging to any namespace, a prefix mapped to "URI" may be introduced via the tsd:collection document. For example: 

    <tsd:collection name="myCollection"
          xmlns:tsd="http://namespaces.softwareag.com/tamino/TaminoSchemaDefinition" 
          xmlns:p="URI" />

maps the prefix "p:" to "URI". After this document has been stored in Tamino via _DEFINE, a query _XQL=p:root can be used to query all instances.

Plain URL Addressing

Plain URL addressing is based on a doctype's lexical QName, which is required to be unique within the scope of a collection. Instances within the doctype are identified either by their ino:id (a unique number) or by their document name. Neither method depends on namespaces.

XQuery

XQuery requests sent to Tamino (using the _XQUERY command) are based on the W3C's XQuery draft. They must specify a URI for each prefix used in the request. Hence, the namespace context of a doctype is not needed.

Special Handling of the Prefix ino:

ino:id

The ino: namespace prefix can be used in various contexts. If no namespace declaration is in scope, the following is assumed: 

xmlns:ino="http://namespaces.softwareag.com/tamino/response2"

The ino: prefix may not be bound to any other URI.

Note:
This is not correct for XQuery.

When executing a _PROCESS command, Tamino checks for the presence of an ino:id attribute in the root element. If present, the request is interpreted as an attempt to replace the original document identified by that ino:id (if any; otherwise an error occurs). Any prefix other than ino: does not lead to interpretation as a request for replacement of the document — even when mapped to the same URI — and the document is rejected.

_XQL queries and _DELETE requests may use the ino: prefix for the pseudo-attributes ino:id and ino:docname without the need for the ino: prefix to be mapped via the doctype's namespace context.

Security

Instances of doctype ino:acl in collection ino:security are used to configure access to specific collections, doctypes and nodes within doctypes based on simple path expressions given inside the ino:ace element(s). A valid entry for the previous music schema might be: 

<ino:acl 
  xmlns:ino="http://namespaces.softwareag.com/tamino/response2"
  ino:ac lname="myAcl">
  <ino:ace 
    xmlns:e = "http://www.softwareag.com/tamino/doc/examples/models/jazz/encyclopedia"
    xmlns:i = "http://www.softwareag.com/tamino/doc/examples/models/instruments"
    ino:access="change">/e:jazzMusician/e:plays/i:saxophone</ino:ace>
</ino:acl>