Re: [dita] Namespace resolution

[Eliot Kimber <ekimber@innodata-isogen.com>]

Erik Hennum wrote:

> As a possible lead-in to discussion of namespaces (slippery little devils),
> I wanted to summarize my understanding of the resolution that Eliot
> discovered.  Please correct as needed:

0. The TC will define a distinct namespace for the dita class attribute 
(and, possibly, other universal DITA-specific attributes, such as ID). 
All DITA documents will use this namespace to qualify all instances of 
the class attribute. No other namespaces need be used for DITA documents 
(but may be if desired).

> 1.  The TC will define a distinct namespace for each specialization package
> and document type shell in OASIS DITA (see the candidate list below).

I don't see a need to have a namespace for the document type shells (the 
declaration sets or schema documents). That is, there is no real 
distinction between a specialization package and the DTD declarations 
that define the syntax rules for the types in that package. We may want 
to have normative URIs for the declaration set files, but those URIs 
would *not* be namespace URIs, they would just be persistent resource URIs.

Or said another way: what's important is the abstraction that is the 
*idea* of the specialization package, which is what the namespace 
identifies. The specific declaration set or sets that are an 
implementation projection of the package are more or less arbitrary and 
there may be any number of them for different practical purposes.

> 2.  In the first release, the DITA DTD and Schema document types will _not_
> be distributed with namespace attributes that declare these namespaces
> directly.

Except for the "dita base" namespace defined in item zero above, which 
qualifies the class attribute--that must be declared in all DTDs, 
schemas, and schema-less document instances.

> 3.  Specializers are encouraged to define a distinct namespace for each
> specialization package and document type shell that they create.

I think this needs to be a hard requirement: c/are encouraged/must/

> 4.  Processors are encouraged to treat specialization package identifiers
> and specialization package namespaces as interchangeable identifiers.

I would state this more strongly: package identifiers *are* namespace 
identifiers. That is, for every package identifier this is/must be 
exactly one corresponding namespace URI declared within the scope of the 
use of the package identifier (that is, on the element or one of its 
ancestors).

> 5.  DITA adopters may use the namespace for the shell document type to
> identify a document during authoring or processing but must recognize that
> the shell namespace does not identify the type of the document element.

I'm not sure I understand this statement. In particular, I'm not sure 
what you mean by "document type":

   - The name of the root element of an instance?

   - The system identifier of the applicable declaration set?

   - The governing abstract schema?

The namespace of the specialization package should be sufficient to 
identify the *abstract* document type, which is sufficient to condition 
type-based processing.

Remember that syntactic validation by DTD declarations or schemas is 
largely orthogonal to the task of mapping element types to processing, 
so how one finds the appropriate declarations is essentially up to the 
user.

When DTDs are used there's no standards-defined relationship between 
namespaces and DTDs in the way there is for schemas, so for DTDs as long 
as the element types defined in the DTD are consistent with the rules 
defined by the abstract name space then everything's ok. If people feel 
a need for definitive URIs or public IDs for the DTD declarations, I 
wouldn't object, but those URIs would *not* be namespace URIs, they 
would be URIs to concrete resources.

For schemas, where there is both a standards-defined relationship 
between namespaces and schemas (targetNamespace/schemaLocation) I assert 
that good practice is to have exactly one top-level schema document for 
a given namespace. Therefore, my expectation would be that for each 
package namespace there would be exactly one corresponding top-level 
schema document, which I think is what Erik is referring to as the shell 
document types.

That is, you don't need a separate namespace just to refer to the 
schemas--the targetNamespace and schemaLocation attributes would serve 
to bind the package namespaces to the shell schema documents.

> Because a topic type can be used in multiple shells (for instance, shells
> assembling different combinations of domains), the same DITA topic element
> could be the document element in several different document types. If the
> shell namespaces are declared in these documents, a topic element could
> belong to several different namespaces.  The best solution for this problem
> would be to attach the namespace for the shell document type to something
> other than a specialization package element.  Until we have that solution,
> people need to be aware of the ambiguity.

I'm not sure I understand this comment. A given element instance can 
only be in one namespace and the namespace it is in is entirely a 
function of its namespace declaration, not the declaration set that 
describes it.

That is, as long as all element type names are fully qualified there can 
be no ambiguity regardless of how element types are combined in a single 
document instance.

Or maybe you're thinking of the implication of using default namespaces? 
I think the answer has to be: namespaces have to either be explicit or 
the default namespace has to be reset on any element that is the root of 
a subtree from a package different from its parent's package. Of course, 
this is only required if you are choosing to qualify element type names 
at all, which isn't ever necessary except to disambiguate name clashes 
between non-DITA-defined specialization packages. So if you rely 
entirely on class mappings and don't worry about namespace qualification 
of element type names, there's no worries at all.

That is, if all processing is based on class mappings, the namespace 
qualification of element type names is either arbitrary or irrelevant, 
depending on the task at hand.

> 6.  A future release of DITA may integrate namespaces more directly into
> the DITA type classification system.  This change alone should not result
> in any changes to element structures or local element names but could
> change the way namespaces are used on the document element.

Exactly.

> Here follows a list of candidate namespaces in the following formats
> proposed by Eric Sirois:
> 
>     http://dita.oasis-open.org/{version}/shell/{documentTypeBasename}
> 
> http://dita.oasis-open.org/{version}/package/{specializationPackageIdentifier}
> 
> The shell document type namespaces (equivalent to *.dtd and *.xsd) might be
> as follows:
> 
>     http://dita.oasis-open.org/1.0/shell/topic
>     http://dita.oasis-open.org/1.0/shell/concept
>     http://dita.oasis-open.org/1.0/shell/reference
>     http://dita.oasis-open.org/1.0/shell/task
> 
>     http://dita.oasis-open.org/1.0/shell/ditabase
> 
>     http://dita.oasis-open.org/1.0/shell/map

To re-iterate, I don't see the need for separate namespaces for the 
declaration sets themselves (see discussion above).

> The specialization package namespaces (equivalent to *.mod and the
> qualifiers on the class attribute) might be as follows:
> 
>     http://dita.oasis-open.org/1.0/package/topic
>     http://dita.oasis-open.org/1.0/package/concept
>     http://dita.oasis-open.org/1.0/package/reference
>     http://dita.oasis-open.org/1.0/package/task
> 
>     http://dita.oasis-open.org/1.0/package/hi-d
>     http://dita.oasis-open.org/1.0/package/pr-d
>     http://dita.oasis-open.org/1.0/package/sw-d
>     http://dita.oasis-open.org/1.0/package/ui-d
>     http://dita.oasis-open.org/1.0/package/ut-d
> 
>     http://dita.oasis-open.org/1.0/package/map
>     http://dita.oasis-open.org/1.0/package/mapgroup-d

These all seem fine to me.

Cheers,

E.
-- 
W. Eliot Kimber
Professional Services
Innodata Isogen
9390 Research Blvd, #410
Austin, TX 78759
(512) 372-8122

eliot@innodata-isogen.com
www.innodata-isogen.com