Skip to end of metadata
Go to start of metadata
This page is work-in-progress. Until finalization, normative language in this page should be considered a proposal. https://github.com/bendlas/data.xml

Runtime data structures

Xml elements are maps with keys #{:tag :attrs :content}. There is a defrecord for tags in data.xml, exposed through the constructors element and element*.

data.xml works with two kinds of xml representations:

  • Representation tier models serialized xml with explicit prefixes.
  • Model tier models the infoset.

Representation Tier (raw)

Names are represented as keywords with the raw prefix, like :prefix/name

This tier maps directly to serialized xml. Xmlns attributes are included by default. It resembles the traditional clojure xml and html format.

This tier maps directly to serialized xml. Xmlns attributes are included by default. It resembles the traditional clojure xml and html format.

Model Tier (resolved)

Names are represented as javax.xml.namespace.QName. If a name has no URI, which frequently happens with attributes, it is canonically represented as a keyword with no namespace.

In this tier, the URI of tags and attribute names is resolved. Xmlns attributes are omitted by default. By default, information about the namespace environment is saved in element metadata.

The defaults are chosen such that Clojure's = function implements deep-equal on model tier data. data.xml functions should preserve metadata on elements.

Auto Keywords

There is a facility to represent names in known xml namespaces, as namespaced keywords. This weakens the = property of resolved xml, but can be very beneficial when dealing with known xmlns and pattern-matching elements.

Known namespaces are introduced via defns, by which the user sets default xmlns and prefixes per clojure-namespace. This allows reusing clojure's namespace-alias facilities to reference xml names:

  • ::name is in the default xmlns of its namespace
  • ::a:name is in the xmlns prefixed by :a, as of its namespace

The emitter transparently emits names names from any defns environment correctly.

Example

XML Name Literals

Representation tier (raw) names

As detailed above, raw names just have a prefix with no canonical translation to a namespace. Thus the emitter will emit the given prefix as is, it won't check the xmlns.

Model tier (resolved) names

These are represented by javax.xml.namespace.QName or a keyword that can be plain or whose namespace must correspond to a defns environment.

There is a builtin coercion to QName, xml-name, which is supposed to be installed as a reader tag. It accepts the following formats:

There is also a print-dup implementation of QName.

Labels: