Merge branch 'master' into astoecke_parser_stack_new

Conflicts:
	application/CMakeLists.txt
	application/src/core/parser/stack/DocumentHandler.hpp
	application/src/core/parser/stack/DomainHandler.hpp
	application/src/core/parser/stack/ImportIncludeHandler.hpp

6 files changed, 972 insertions, 349 deletions

diff --git a/src/core/model/Document.cpp b/src/core/model/Document.cpp
index bcff41b..a2ba5cf 100644
--- a/src/core/model/Document.cpp
+++ b/src/core/model/Document.cpp
@@ -97,8 +97,7 @@ bool DocumentEntity::doValidate(Logger &logger) const
 	// iterate over every field
 	for (unsigned int f = 0; f < fields.size(); f++) {
 		// we have a special check for primitive fields.
-		if (fieldDescs[f]->getFieldType() ==
-		    FieldDescriptor::FieldType::PRIMITIVE) {
+		if (fieldDescs[f]->isPrimitive()) {
 			switch (fields[f].size()) {
 				case 0:
 					if (!fieldDescs[f]->isOptional()) {
@@ -276,9 +275,9 @@ static int enforceGetFieldDescriptorIndex(Handle<Descriptor> desc,
 {
 	ssize_t idx = desc->getFieldDescriptorIndex(fieldName);
 	if (idx == -1) {
-		throw OusiaException(
-		    std::string("Descriptor \"") + desc->getName() +
-		    "\" has no field with the name \"" + fieldName + "\"");
+		throw OusiaException(std::string("Descriptor \"") + desc->getName() +
+		                     "\" has no field with the name \"" + fieldName +
+		                     "\"");
 	}
 	return idx;
 }
@@ -288,8 +287,7 @@ static int enforceGetFieldDescriptorIndex(
 {
 	ssize_t idx = desc->getFieldDescriptorIndex(fieldDescriptor);
 	if (idx == -1) {
-		throw OusiaException(std::string("Descriptor \"") +
-		                     desc->getName() +
+		throw OusiaException(std::string("Descriptor \"") + desc->getName() +
 		                     "\" does not reference the given field \"" +
 		                     fieldDescriptor->getName() + "\"");
 	}
@@ -308,6 +306,18 @@ const NodeVector<StructureNode> &DocumentEntity::getField(
 	return fields[enforceGetFieldDescriptorIndex(descriptor, fieldDescriptor)];
 }
 
+const NodeVector<StructureNode> &DocumentEntity::getField(
+    const size_t &idx) const
+{
+	if (idx >= fields.size()) {
+		throw OusiaException(std::string("Descriptor \"") +
+		                     descriptor->getName() +
+		                     "\" does not have enough fields for index \"" +
+		                     std::to_string(idx) + "\".");
+	}
+	return fields[idx];
+}
+
 void DocumentEntity::addStructureNode(Handle<StructureNode> s, const int &i)
 {
 	// only add the new node if we don't have it already.
@@ -420,11 +430,10 @@ Rooted<DocumentPrimitive> DocumentEntity::createChildDocumentPrimitive(
 	    subInst->getManager(), subInst, std::move(content), fieldName)};
 }
 
-Rooted<Anchor> DocumentEntity::createChildAnchor(std::string name,
-                                                 const std::string &fieldName)
+Rooted<Anchor> DocumentEntity::createChildAnchor(const std::string &fieldName)
 {
 	return Rooted<Anchor>{
-	    new Anchor(subInst->getManager(), std::move(name), subInst, fieldName)};
+	    new Anchor(subInst->getManager(), subInst, fieldName)};
 }
 
 /* Class StructureNode */
@@ -495,13 +504,61 @@ bool Anchor::doValidate(Logger &logger) const
 {
 	bool valid = true;
 	// check name
-	if (getName().empty()) {
-		logger.error("An Anchor needs a name!", *this);
+	if (!getName().empty()) {
+		logger.error(
+		    "This anchor has a name! Anchors should only be referred to by "
+		    "reference, not by name!",
+		    *this);
 		valid = false;
 	}
+	if (annotation == nullptr) {
+		// this is valid but should throw a warning.
+		logger.warning("This anchor is disconnected.", *this);
+	}
 	return valid & StructureNode::doValidate(logger);
 }
 
+void Anchor::setAnnotation(Handle<AnnotationEntity> anno, bool start)
+{
+	if (annotation == anno) {
+		return;
+	}
+	invalidate();
+	// unset the old reference.
+	if (annotation != nullptr) {
+		if (isStart()) {
+			annotation->setStart(nullptr);
+		} else {
+			annotation->setEnd(nullptr);
+		}
+	}
+	annotation = acquire(anno);
+	// set the new reference.
+	if (anno != nullptr) {
+		if (start) {
+			anno->setStart(this);
+		} else {
+			anno->setEnd(this);
+		}
+	}
+}
+
+bool Anchor::isStart() const
+{
+	if (annotation == nullptr) {
+		return false;
+	}
+	return annotation->getStart() == this;
+}
+
+bool Anchor::isEnd() const
+{
+	if (annotation == nullptr) {
+		return false;
+	}
+	return annotation->getEnd() == this;
+}
+
 /* Class AnnotationEntity */
 
 AnnotationEntity::AnnotationEntity(Manager &mgr, Handle<Document> parent,
@@ -509,13 +566,13 @@ AnnotationEntity::AnnotationEntity(Manager &mgr, Handle<Document> parent,
                                    Handle<Anchor> start, Handle<Anchor> end,
                                    Variant attributes, std::string name)
     : Node(mgr, std::move(name), parent),
-      DocumentEntity(this, descriptor, attributes),
-      start(acquire(start)),
-      end(acquire(end))
+      DocumentEntity(this, descriptor, attributes)
 {
 	if (parent != nullptr) {
 		parent->addAnnotation(this);
 	}
+	setStart(start);
+	setEnd(end);
 }
 
 bool AnnotationEntity::doValidate(Logger &logger) const
@@ -568,10 +625,50 @@ bool AnnotationEntity::doValidate(Logger &logger) const
 			valid = false;
 		}
 	}
+	// check if the Anchors reference this AnnotationEntity correctly.
+	if (start != nullptr) {
+		if (start->getAnnotation() != this) {
+			logger.error(
+			    "This annotations start anchor does not have the correct "
+			    "annotation as parent!",
+			    *this);
+			valid = false;
+		}
+	}
+	if (end != nullptr) {
+		if (end->getAnnotation() != this) {
+			logger.error(
+			    "This annotations end anchor does not have the correct "
+			    "annotation as parent!",
+			    *this);
+			valid = false;
+		}
+	}
+
 	// check the validity as a DocumentEntity.
 	return valid & DocumentEntity::doValidate(logger);
 }
 
+void AnnotationEntity::setStart(Handle<Anchor> s)
+{
+	if (start == s) {
+		return;
+	}
+	invalidate();
+	start = acquire(s);
+	s->setAnnotation(this, true);
+}
+
+void AnnotationEntity::setEnd(Handle<Anchor> e)
+{
+	if (end == e) {
+		return;
+	}
+	invalidate();
+	end = acquire(e);
+	e->setAnnotation(this, false);
+}
+
 /* Class Document */
 
 void Document::doResolve(ResolutionState &state)
@@ -728,5 +825,4 @@ const Rtti AnnotationEntity =
         .parent(&Node)
         .composedOf({&StructuredEntity, &DocumentPrimitive, &Anchor});
 }
-}
-
+}
\ No newline at end of file
diff --git a/src/core/model/Document.hpp b/src/core/model/Document.hpp
index b41393e..5f06eb0 100644
--- a/src/core/model/Document.hpp
+++ b/src/core/model/Document.hpp
@@ -126,6 +126,7 @@ class Document;
 class StructureNode;
 class StructuredEntity;
 class DocumentPrimitive;
+class AnnotationEntity;
 class Anchor;
 
 /**
@@ -236,6 +237,18 @@ public:
 	    Handle<FieldDescriptor> fieldDescriptor) const;
 
 	/**
+	 * This returns the vector of entities containing all members of the field
+	 * with the given index.
+	 *
+	 * If the index is out of bounds an exception is thrown.
+	 *
+	 * @param idx       is the index of a field as specified in the
+	 *                  FieldDescriptor in the Domain description.
+	 * @return          a NodeVector of all StructuredEntities in that field.
+	 */
+	const NodeVector<StructureNode> &getField(const size_t& idx ) const;
+
+	/**
 	 * This adds a StructureNode to the field with the given index.
 	 *
 	 * This method also changes the parent of the newly added StructureNode if
@@ -409,14 +422,13 @@ public:
 	/**
 	 * Creates a new Anchor as child of this DocumentEntity.
 	 *
-	 * @param name      is the Anchor id.
 	 * @param fieldName is the name of the field, where the newly created
 	 *                  Anchor shall be added to this DocumentEntity.
 	 *
 	 * @return          the newly created Anchor.
 	 */
 	Rooted<Anchor> createChildAnchor(
-	    std::string name, const std::string &fieldName = DEFAULT_FIELD_NAME);
+	    const std::string &fieldName = DEFAULT_FIELD_NAME);
 };
 
 /**
@@ -577,6 +589,9 @@ public:
  * Please refer to the AnnotationEntity documentation for more information.
  */
 class Anchor : public StructureNode {
+private:
+	Owned<AnnotationEntity> annotation;
+
 protected:
 	bool doValidate(Logger &logger) const override;
 
@@ -589,15 +604,55 @@ public:
 	 *                  not the AnnotationEntity that references this Anchor.
 	 *                  Note that this Anchor will automatically register itself
 	 *                  as child of the given parent.
-	 * @param name      is the Anchor id.
 	 * @param fieldName is the name of the field in the parent DocumentEntity
 	 *                  where this Anchor shall be added.
 	 */
-	Anchor(Manager &mgr, std::string name, Handle<Node> parent,
+	Anchor(Manager &mgr, Handle<Node> parent,
 	       const std::string &fieldName = DEFAULT_FIELD_NAME)
-	    : StructureNode(mgr, std::move(name), parent, fieldName)
+	    : StructureNode(mgr, "", parent, fieldName)
 	{
 	}
+
+	/**
+	 * Returns the AnnotationEntity this Anchor belongs to.
+	 *
+	 * @return the AnnotationEntity this Anchor belongs to.
+	 */
+	Rooted<AnnotationEntity> getAnnotation() const { return annotation; }
+
+	/**
+	 * Sets the AnnotationEntity this Anchor belongs to. If this Anchor belonged
+	 * to an AnnotationEntity before already, this reference is removed. This
+	 * also sets the start/end reference of the new AnnotationEntity this Anchor
+	 * shall belong to.
+	 *
+	 * @param anno  the new AnnotationEntity this Anchor shall belong to.
+	 * @param start true if this Anchor should be added as start anchor, false
+	 *              if it should be added as end Anchor.
+	 */
+	void setAnnotation(Handle<AnnotationEntity> anno, bool start);
+
+	/**
+	 * Returns true if and only if this Anchor is the start Anchor of the
+	 * AnnotationEntity it belongs to. Note that this will return false also if
+	 * no AnnotationEntity is set yet. So isStart() == false and isEnd() ==
+	 * false is possible and occurs if and only if getAnnotation() == nullptr.
+	 *
+	 * @return true if and only if this Anchor is the start Anchor of the
+	 *              AnnotationEntity it belongs to.
+	 */
+	bool isStart() const;
+
+	/**
+	 * Returns true if and only if this Anchor is the end Anchor of the
+	 * AnnotationEntity it belongs to. Note that this will return false also if
+	 * no AnnotationEntity is set yet. So isStart() == false and isEnd() ==
+	 * false is possible and occurs if and only if getAnnotation() == nullptr.
+	 *
+	 * @return true if and only if this Anchor is the end Anchor of the
+	 *              AnnotationEntity it belongs to.
+	 */
+	bool isEnd() const;
 };
 
 /**
@@ -679,22 +734,13 @@ public:
 	 *
 	 * @param s is the new start Anchor for this AnnotationEntity.
 	 */
-	void setStart(Handle<Anchor> s)
-	{
-		invalidate();
-		start = acquire(s);
-	}
-
+	void setStart(Handle<Anchor> s);
 	/**
 	 * Sets the end Anchor of this AnnotationEntity.
 	 *
 	 * @param e is the new end Anchor for this AnnotationEntity.
 	 */
-	void setEnd(Handle<Anchor> e)
-	{
-		invalidate();
-		end = acquire(e);
-	}
+	void setEnd(Handle<Anchor> e);
 };
 
 /**
diff --git a/src/core/model/Domain.cpp b/src/core/model/Domain.cpp
index 806b9b8..8288099 100644
--- a/src/core/model/Domain.cpp
+++ b/src/core/model/Domain.cpp
@@ -16,6 +16,8 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+#include <memory>
+#include <queue>
 #include <set>
 
 #include <core/common/RttiBuilder.hpp>
@@ -27,18 +29,16 @@ namespace ousia {
 
 /* Class FieldDescriptor */
 
-FieldDescriptor::FieldDescriptor(Manager &mgr, Handle<Descriptor> parent,
-                                 Handle<Type> primitiveType, std::string name,
-                                 bool optional)
+FieldDescriptor::FieldDescriptor(Manager &mgr, Handle<Type> primitiveType,
+                                 Handle<Descriptor> parent, FieldType fieldType,
+                                 std::string name, bool optional)
     : Node(mgr, std::move(name), parent),
       children(this),
-      fieldType(FieldType::PRIMITIVE),
+      fieldType(fieldType),
       primitiveType(acquire(primitiveType)),
-      optional(optional)
+      optional(optional),
+      primitive(true)
 {
-	if (parent != nullptr) {
-		parent->addFieldDescriptor(this);
-	}
 }
 
 FieldDescriptor::FieldDescriptor(Manager &mgr, Handle<Descriptor> parent,
@@ -47,11 +47,9 @@ FieldDescriptor::FieldDescriptor(Manager &mgr, Handle<Descriptor> parent,
     : Node(mgr, std::move(name), parent),
       children(this),
       fieldType(fieldType),
-      optional(optional)
+      optional(optional),
+      primitive(false)
 {
-	if (parent != nullptr) {
-		parent->addFieldDescriptor(this);
-	}
 }
 
 bool FieldDescriptor::doValidate(Logger &logger) const
@@ -59,45 +57,63 @@ bool FieldDescriptor::doValidate(Logger &logger) const
 	bool valid = true;
 	// check parent type
 	if (getParent() == nullptr) {
-		logger.error("This field has no parent!", *this);
+		logger.error(std::string("Field \"") + getName() + "\" has no parent!",
+		             *this);
 		valid = false;
 	} else if (!getParent()->isa(&RttiTypes::Descriptor)) {
-		logger.error("The parent of this field is not a descriptor!", *this);
+		logger.error(std::string("The parent of Field \"") + getName() +
+		                 "\" is not a descriptor!",
+		             *this);
 		valid = false;
 	}
 	// check name
-	if (getName() != DEFAULT_FIELD_NAME) {
+	if (getName().empty()) {
+		if (fieldType != FieldType::TREE) {
+			logger.error(std::string("Field \"") + getName() +
+			                 "\" is not the main field but has an empty name!",
+			             *this);
+			valid = false;
+		}
+	} else {
 		valid = valid & validateName(logger);
 	}
+
 	// check consistency of FieldType with the rest of the FieldDescriptor.
-	if (fieldType == FieldType::PRIMITIVE) {
+	if (primitive) {
 		if (children.size() > 0) {
-			logger.error(
-			    "This field is supposed to be primitive but has "
-			    "registered child classes!",
-			    *this);
+			logger.error(std::string("Field \"") + getName() +
+			                 "\" is supposed to be primitive but has "
+			                 "registered child classes!",
+			             *this);
 			valid = false;
 		}
 		if (primitiveType == nullptr) {
-			logger.error(
-			    "This field is supposed to be primitive but has "
-			    "no primitive type!",
-			    *this);
+			logger.error(std::string("Field \"") + getName() +
+			                 "\" is supposed to be primitive but has "
+			                 "no primitive type!",
+			             *this);
 			valid = false;
 		}
 	} else {
 		if (primitiveType != nullptr) {
-			logger.error(
-			    "This field is supposed to be non-primitive but has "
-			    "a primitive type!",
-			    *this);
+			logger.error(std::string("Field \"") + getName() +
+			                 "\" is supposed to be non-primitive but has "
+			                 "a primitive type!",
+			             *this);
+			valid = false;
+		}
+		// if this is not a primitive field we require at least one child.
+		if (children.empty()) {
+			logger.error(std::string("Field \"") + getName() +
+			                 "\" is non primitive but does not allow children!",
+			             *this);
 			valid = false;
 		}
 	}
 	/*
 	 * we are not allowed to call the validation functions of each child because
 	 * this might lead to cycles. What we should do, however, is to check if
-	 * there are no duplicates.
+	 * there are duplicates.
 	 */
 	std::set<std::string> names;
 	for (Handle<StructuredClass> c : children) {
@@ -140,10 +156,14 @@ bool Descriptor::doValidate(Logger &logger) const
 	bool valid = true;
 	// check parent type
 	if (getParent() == nullptr) {
-		logger.error("This Descriptor has no parent!", *this);
+		logger.error(
+		    std::string("Descriptor \"") + getName() + "\" has no parent!",
+		    *this);
 		valid = false;
 	} else if (!getParent()->isa(&RttiTypes::Domain)) {
-		logger.error("The parent of this Descriptor is not a Domain!", *this);
+		logger.error(std::string("The parent of Descriptor \"") + getName() +
+		                 "\" is not a Domain!",
+		             *this);
 		valid = false;
 	}
 	// check name
@@ -155,104 +175,348 @@ bool Descriptor::doValidate(Logger &logger) const
 	}
 	// ensure that no attribute with the key "name" exists.
 	if (attributesDescriptor == nullptr) {
-		logger.error("This Descriptor has no Attribute specification!");
+		logger.error(std::string("Descriptor \"") + getName() +
+		             "\" has no Attribute specification!");
 		valid = false;
 	} else {
 		if (attributesDescriptor->hasAttribute("name")) {
 			logger.error(
-			    "This Descriptor has an attribute \"name\" which is a reserved "
-			    "word!");
+			    std::string("Descriptor \"") + getName() +
+			    "\" has an attribute \"name\" which is a reserved word!");
 			valid = false;
 		}
 		valid = valid & attributesDescriptor->validate(logger);
 	}
+	// check that only one FieldDescriptor is of type TREE.
+	auto fds = Descriptor::getFieldDescriptors();
+	bool hasTREE = false;
+	for (auto fd : fds) {
+		if (fd->getFieldType() == FieldDescriptor::FieldType::TREE) {
+			if (!hasTREE) {
+				hasTREE = true;
+			} else {
+				logger.error(
+				    std::string("Descriptor \"") + getName() +
+				        "\" has multiple TREE fields, which is not permitted",
+				    *fd);
+				valid = false;
+				break;
+			}
+		}
+	}
 
 	// check attributes and the FieldDescriptors
-	return valid & continueValidationCheckDuplicates(fieldDescriptors, logger);
+	return valid & continueValidationCheckDuplicates(fds, logger);
 }
 
-std::vector<Rooted<Node>> Descriptor::pathTo(
-    Handle<StructuredClass> target) const
+struct PathState {
+	std::shared_ptr<PathState> pred;
+	Node *node;
+	size_t length;
+
+	PathState(std::shared_ptr<PathState> pred, Node *node)
+	    : pred(pred), node(node)
+	{
+		if (pred == nullptr) {
+			length = 1;
+		} else {
+			length = pred->length + 1;
+		}
+	}
+};
+
+static void constructPath(std::shared_ptr<PathState> state,
+                          NodeVector<Node> &vec)
 {
-	std::vector<Rooted<Node>> path;
-	continuePath(target, path);
-	return path;
+	if (state->pred != nullptr) {
+		constructPath(state->pred, vec);
+	}
+	vec.push_back(state->node);
 }
 
-bool Descriptor::continuePath(Handle<StructuredClass> target,
-                              std::vector<Rooted<Node>> &currentPath) const
+static NodeVector<Node> pathTo(const Descriptor *start, Logger &logger,
+                               Handle<Node> target, bool &success)
 {
-	// check if we are at the target already
-	if (this == target) {
-		return true;
+	success = false;
+	// shortest path.
+	NodeVector<Node> shortest;
+	// state queue for breadth-first search.
+	std::queue<std::shared_ptr<PathState>> states;
+	{
+		// initially put every field descriptor on the queue.
+		NodeVector<FieldDescriptor> fields = start->getFieldDescriptors();
+
+		for (auto fd : fields) {
+			if (fd == target) {
+				// if we have found the target directly, return without search.
+				success = true;
+				return shortest;
+			}
+			if (fd->getFieldType() == FieldDescriptor::FieldType::TREE) {
+				states.push(std::make_shared<PathState>(nullptr, fd.get()));
+			}
+		}
 	}
-	// a variable to determine if we already found a solution
-	bool found = false;
-	// the currently optimal path.
-	std::vector<Rooted<Node>> optimum;
-	// use recursive depth-first search from the top to reach the given child
-	// get the list of effective FieldDescriptors.
-	NodeVector<FieldDescriptor> fields = getFieldDescriptors();
+	// set of visited nodes.
+	std::unordered_set<const Node *> visited;
+	while (!states.empty()) {
+		std::shared_ptr<PathState> current = states.front();
+		states.pop();
+		// do not proceed if this node was already visited.
+		if (!visited.insert(current->node).second) {
+			continue;
+		}
+		// also do not proceed if we can't get better than the current shortest
+		// path anymore.
+		if (!shortest.empty() && current->length > shortest.size()) {
+			continue;
+		}
 
-	for (auto &fd : fields) {
-		for (auto &c : fd->getChildren()) {
-			// check if a child is the target node.
-			if (c == target) {
-				// if we have made the connection, stop the search.
-				currentPath.push_back(fd);
-				return true;
+		bool fin = false;
+		if (current->node->isa(&RttiTypes::StructuredClass)) {
+			const StructuredClass *strct =
+			    static_cast<const StructuredClass *>(current->node);
+
+			// look through all fields.
+			NodeVector<FieldDescriptor> fields = strct->getFieldDescriptors();
+			for (auto fd : fields) {
+				// if we found our target, break off the search in this branch.
+				if (fd == target) {
+					fin = true;
+					continue;
+				}
+				// only continue in the TREE field.
+				if (fd->getFieldType() == FieldDescriptor::FieldType::TREE) {
+					states.push(std::make_shared<PathState>(current, fd.get()));
+				}
 			}
-			// look for transparent intermediate nodes.
-			if (c->isTransparent()) {
-				// copy the path.
-				std::vector<Rooted<Node>> cPath = currentPath;
-				cPath.push_back(fd);
-				cPath.push_back(c);
-				// recursion.
-				if (c->continuePath(target, cPath) &&
-				    (!found || optimum.size() > cPath.size())) {
-					// look if this path is better than the current optimum.
-					optimum = std::move(cPath);
-					found = true;
+
+			/*
+			 * Furthermore we have to consider that all subclasses of this
+			 * StructuredClass are allowed in place of this StructuredClass as
+			 * well, so we continue the search for them as well.
+			 */
+
+			NodeVector<StructuredClass> subs = strct->getSubclasses();
+			for (auto sub : subs) {
+				// if we found our target, break off the search in this branch.
+				if (sub == target) {
+					fin = true;
+					current = current->pred;
+					continue;
+				}
+				// We only continue our path via transparent classes.
+				if (sub->isTransparent()) {
+					states.push(
+					    std::make_shared<PathState>(current->pred, sub.get()));
+				}
+			}
+		} else {
+			// otherwise this is a FieldDescriptor.
+			const FieldDescriptor *field =
+			    static_cast<const FieldDescriptor *>(current->node);
+			// and we proceed by visiting all permitted children.
+			for (auto c : field->getChildren()) {
+				// if we found our target, break off the search in this branch.
+				if (c == target) {
+					fin = true;
+					continue;
+				}
+				// We only allow to continue our path via transparent children.
+				if (c->isTransparent()) {
+					states.push(std::make_shared<PathState>(current, c.get()));
+				}
+			}
+		}
+		// check if we are finished.
+		if (fin) {
+			success = true;
+			// if so we look if we found a shorter path than the current minimum
+			if (shortest.empty() || current->length < shortest.size()) {
+				NodeVector<Node> newPath;
+				constructPath(current, newPath);
+				shortest = newPath;
+			} else if (current->length == shortest.size()) {
+				// if the length is the same the result is ambigous and we log
+				// an error.
+				NodeVector<Node> newPath;
+				constructPath(current, newPath);
+				logger.error(
+				    std::string("Can not unambigously create a path from \"") +
+				    start->getName() + "\" to \"" + target->getName() + "\".");
+				logger.note("Dismissed the path:", SourceLocation{},
+				            MessageMode::NO_CONTEXT);
+				for (auto n : newPath) {
+					logger.note(n->getName());
 				}
 			}
 		}
 	}
+	return shortest;
+}
 
-	if (isa(&RttiTypes::StructuredClass)) {
-		const StructuredClass *tis = static_cast<const StructuredClass *>(this);
-		// if this is a StructuredClass we also can call the subclasses.
-		for (auto &c : tis->getSubclasses()) {
-			// copy the path.
-			std::vector<Rooted<Node>> cPath = currentPath;
-			if (c->continuePath(target, cPath) &&
-			    (!found || optimum.size() > cPath.size())) {
-				// look if this path is better than the current optimum.
-				optimum = std::move(cPath);
-				found = true;
+NodeVector<Node> Descriptor::pathTo(Handle<StructuredClass> target,
+                                    Logger &logger) const
+{
+	bool success = false;
+	return ousia::pathTo(this, logger, target, success);
+}
+
+std::pair<NodeVector<Node>, bool> Descriptor::pathTo(
+    Handle<FieldDescriptor> field, Logger &logger) const
+{
+	bool success = false;
+	NodeVector<Node> path = ousia::pathTo(this, logger, field, success);
+	return std::make_pair(path, success);
+}
+
+template <typename F>
+static NodeVector<Node> collect(const Descriptor *start, F match)
+{
+	// result
+	NodeVector<Node> res;
+	// queue for breadth-first search of graph.
+	std::queue<Rooted<Node>> q;
+	{
+		// initially put every field descriptor on the queue.
+		NodeVector<FieldDescriptor> fields = start->getFieldDescriptors();
+
+		for (auto fd : fields) {
+			// note matches.
+			if (match(fd)) {
+				res.push_back(fd);
+			}
+			if (fd->getFieldType() == FieldDescriptor::FieldType::TREE) {
+				q.push(fd);
 			}
 		}
 	}
+	// set of visited nodes.
+	std::unordered_set<const Node *> visited;
+	while (!q.empty()) {
+		Rooted<Node> n = q.front();
+		q.pop();
+		// do not proceed if this node was already visited.
+		if (!visited.insert(n.get()).second) {
+			continue;
+		}
+
+		if (n->isa(&RttiTypes::StructuredClass)) {
+			Rooted<StructuredClass> strct = n.cast<StructuredClass>();
 
-	// put the optimum in the given path reference.
-	currentPath = std::move(optimum);
+			// look through all fields.
+			NodeVector<FieldDescriptor> fields = strct->getFieldDescriptors();
+			for (auto fd : fields) {
+				// note matches.
+				if (match(fd)) {
+					res.push_back(fd);
+				}
+				// only continue in the TREE field.
+				if (fd->getFieldType() == FieldDescriptor::FieldType::TREE) {
+					q.push(fd);
+				}
+			}
 
-	// return if we found something.
-	return found;
+			/*
+			 * Furthermore we have to consider that all subclasses of this
+			 * StructuredClass are allowed in place of this StructuredClass as
+			 * well, so we continue the search for them as well.
+			 */
+
+			NodeVector<StructuredClass> subs = strct->getSubclasses();
+			for (auto sub : subs) {
+				// note matches.
+				if (match(sub)) {
+					res.push_back(sub);
+				}
+				// We only continue our search via transparent classes.
+				if (sub->isTransparent()) {
+					q.push(sub);
+				}
+			}
+		} else {
+			// otherwise this is a FieldDescriptor.
+			Rooted<FieldDescriptor> field = n.cast<FieldDescriptor>();
+			// and we proceed by visiting all permitted children.
+			for (auto c : field->getChildren()) {
+				// note matches.
+				if (match(c)) {
+					res.push_back(c);
+				}
+				// We only continue our search via transparent children.
+				if (c->isTransparent()) {
+					q.push(c);
+				}
+			}
+		}
+	}
+	return res;
 }
 
-ssize_t Descriptor::getFieldDescriptorIndex(const std::string &name) const
+NodeVector<FieldDescriptor> Descriptor::getDefaultFields() const
 {
-	size_t f = 0;
-	for (auto &fd : getFieldDescriptors()) {
-		if (fd->getName() == name) {
+	// TODO: In principle a cast would be nicer here, but for now we copy.
+	NodeVector<Node> nodes = collect(this, [](Handle<Node> n) {
+		if (!n->isa(&RttiTypes::FieldDescriptor)) {
+			return false;
+		}
+		Handle<FieldDescriptor> f = n.cast<FieldDescriptor>();
+		return f->getFieldType() == FieldDescriptor::FieldType::TREE &&
+		       f->isPrimitive();
+	});
+	NodeVector<FieldDescriptor> res;
+	for (auto n : nodes) {
+		res.push_back(n.cast<FieldDescriptor>());
+	}
+	return res;
+}
+
+NodeVector<StructuredClass> Descriptor::getPermittedChildren() const
+{
+	// TODO: In principle a cast would be nicer here, but for now we copy.
+	NodeVector<Node> nodes = collect(this, [](Handle<Node> n) {
+		return n->isa(&RttiTypes::StructuredClass);
+	});
+	NodeVector<StructuredClass> res;
+	for (auto n : nodes) {
+		res.push_back(n.cast<StructuredClass>());
+	}
+	return res;
+}
+
+static ssize_t getFieldDescriptorIndex(const NodeVector<FieldDescriptor> &fds,
+                                       const std::string &name)
+{
+	if (fds.empty()) {
+		return -1;
+	}
+
+	if (name == DEFAULT_FIELD_NAME) {
+		if (fds.back()->getFieldType() == FieldDescriptor::FieldType::TREE) {
+			return fds.size() - 1;
+		} else {
+			/* The last field has to be the TREE field. If the last field does
+			 * not have the FieldType TREE no TREE-field exists at all. So we
+			 * return -1.
+			 */
+			return -1;
+		}
+	}
+
+	for (size_t f = 0; f < fds.size(); f++) {
+		if (fds[f]->getName() == name) {
 			return f;
 		}
-		f++;
 	}
 	return -1;
 }
 
+ssize_t Descriptor::getFieldDescriptorIndex(const std::string &name) const
+{
+	NodeVector<FieldDescriptor> fds = getFieldDescriptors();
+	return ousia::getFieldDescriptorIndex(fds, name);
+}
+
 ssize_t Descriptor::getFieldDescriptorIndex(Handle<FieldDescriptor> fd) const
 {
 	size_t f = 0;
@@ -268,33 +532,54 @@ ssize_t Descriptor::getFieldDescriptorIndex(Handle<FieldDescriptor> fd) const
 Rooted<FieldDescriptor> Descriptor::getFieldDescriptor(
     const std::string &name) const
 {
-	for (auto &fd : getFieldDescriptors()) {
-		if (fd->getName() == name) {
-			return fd;
-		}
+	NodeVector<FieldDescriptor> fds = getFieldDescriptors();
+	ssize_t idx = ousia::getFieldDescriptorIndex(fds, name);
+	if (idx != -1) {
+		return fds[idx];
+	} else {
+		return nullptr;
 	}
-	return nullptr;
 }
 
-void Descriptor::addFieldDescriptor(Handle<FieldDescriptor> fd)
+void Descriptor::addAndSortFieldDescriptor(Handle<FieldDescriptor> fd,
+                                           Logger &logger)
 {
 	// only add it if we need to.
-	if (fieldDescriptors.find(fd) == fieldDescriptors.end()) {
+	auto fds = getFieldDescriptors();
+	if (fds.find(fd) == fds.end()) {
 		invalidate();
-		fieldDescriptors.push_back(fd);
+		// check if the previous field is a tree field already.
+		if (!fds.empty() &&
+		    fds.back()->getFieldType() == FieldDescriptor::FieldType::TREE &&
+		    fd->getFieldType() != FieldDescriptor::FieldType::TREE) {
+			// if so we add the new field before the TREE field and log a
+			// warning.
+
+			logger.warning(
+			    std::string("Field \"") + fd->getName() +
+			        "\" was declared after main field \"" +
+			        fds.back()->getName() +
+			        "\". The order of fields was changed to make the "
+			        "main field the last field.",
+			    *fd);
+			fieldDescriptors.insert(fieldDescriptors.end() - 1, fd);
+		} else {
+			fieldDescriptors.push_back(fd);
+		}
 	}
+}
+
+void Descriptor::addFieldDescriptor(Handle<FieldDescriptor> fd, Logger &logger)
+{
+	addAndSortFieldDescriptor(fd, logger);
 	if (fd->getParent() == nullptr) {
 		fd->setParent(this);
 	}
 }
 
-void Descriptor::moveFieldDescriptor(Handle<FieldDescriptor> fd)
+void Descriptor::moveFieldDescriptor(Handle<FieldDescriptor> fd, Logger &logger)
 {
-	// only add it if we need to.
-	if (fieldDescriptors.find(fd) == fieldDescriptors.end()) {
-		invalidate();
-		fieldDescriptors.push_back(fd);
-	}
+	addAndSortFieldDescriptor(fd, logger);
 	Handle<Managed> par = fd->getParent();
 	if (par != this) {
 		if (par != nullptr) {
@@ -305,28 +590,26 @@ void Descriptor::moveFieldDescriptor(Handle<FieldDescriptor> fd)
 	}
 }
 
-void Descriptor::copyFieldDescriptor(Handle<FieldDescriptor> fd)
+void Descriptor::copyFieldDescriptor(Handle<FieldDescriptor> fd, Logger &logger)
 {
-	if (fd->getFieldType() == FieldDescriptor::FieldType::PRIMITIVE) {
-		/*
-		 * To call the "new" operation is enough here, because the
-		 * constructor will add the newly constructed FieldDescriptor to this
-		 * Descriptor automatically.
-		 */
-		new FieldDescriptor(getManager(), this, fd->getPrimitiveType(),
-		                    fd->getName(), fd->isOptional());
+	Rooted<FieldDescriptor> copy;
+	if (fd->isPrimitive()) {
+		copy = Rooted<FieldDescriptor>{new FieldDescriptor(
+		    getManager(), fd->getPrimitiveType(), this, fd->getFieldType(),
+		    fd->getName(), fd->isOptional())};
 	} else {
 		/*
 		 * In case of non-primitive FieldDescriptors we also want to copy the
 		 * child references.
 		 */
-		Rooted<FieldDescriptor> copy = {
+		copy = Rooted<FieldDescriptor>{
 		    new FieldDescriptor(getManager(), this, fd->getFieldType(),
 		                        fd->getName(), fd->isOptional())};
 		for (auto &c : fd->getChildren()) {
 			copy->addChild(c);
 		}
 	}
+	addFieldDescriptor(copy, logger);
 }
 
 bool Descriptor::removeFieldDescriptor(Handle<FieldDescriptor> fd)
@@ -342,17 +625,24 @@ bool Descriptor::removeFieldDescriptor(Handle<FieldDescriptor> fd)
 }
 
 Rooted<FieldDescriptor> Descriptor::createPrimitiveFieldDescriptor(
-    Handle<Type> primitiveType, std::string name, bool optional)
+    Handle<Type> primitiveType, Logger &logger,
+    FieldDescriptor::FieldType fieldType, std::string name, bool optional)
 {
-	return Rooted<FieldDescriptor>{new FieldDescriptor(
-	    getManager(), this, primitiveType, std::move(name), optional)};
+	Rooted<FieldDescriptor> fd{new FieldDescriptor(getManager(), primitiveType,
+	                                               this, fieldType,
+	                                               std::move(name), optional)};
+	addFieldDescriptor(fd, logger);
+	return fd;
 }
 
 Rooted<FieldDescriptor> Descriptor::createFieldDescriptor(
-    FieldDescriptor::FieldType fieldType, std::string name, bool optional)
+    Logger &logger, FieldDescriptor::FieldType fieldType, std::string name,
+    bool optional)
 {
-	return Rooted<FieldDescriptor>{new FieldDescriptor(
+	Rooted<FieldDescriptor> fd{new FieldDescriptor(
 	    getManager(), this, fieldType, std::move(name), optional)};
+	addFieldDescriptor(fd, logger);
+	return fd;
 }
 
 /* Class StructuredClass */
@@ -471,18 +761,35 @@ void StructuredClass::removeSubclass(Handle<StructuredClass> sc, Logger &logger)
 	sc->setSuperclass(nullptr, logger);
 }
 
-const void StructuredClass::gatherFieldDescriptors(
+void StructuredClass::gatherFieldDescriptors(
     NodeVector<FieldDescriptor> &current,
-    std::set<std::string> &overriddenFields) const
+    std::set<std::string> &overriddenFields, bool hasTREE) const
 {
 	// append all FieldDescriptors that are not overridden.
 	for (auto &f : Descriptor::getFieldDescriptors()) {
 		if (overriddenFields.insert(f->getName()).second) {
-			current.push_back(f);
+			bool isTREE = f->getFieldType() == FieldDescriptor::FieldType::TREE;
+			if (hasTREE) {
+				if (!isTREE) {
+					/*
+					 * If we already have a tree field it has to be at the end
+					 * of the current vector. So ensure that all new non-TREE
+					 * fields are inserted before the TREE field such that after
+					 * this method the TREE field is still at the end.
+					 */
+					current.insert(current.end() - 1, f);
+				}
+			} else {
+				if (isTREE) {
+					hasTREE = true;
+				}
+				current.push_back(f);
+			}
 		}
 	}
+	// if we have a superclass, go there.
 	if (superclass != nullptr) {
-		superclass->gatherFieldDescriptors(current, overriddenFields);
+		superclass->gatherFieldDescriptors(current, overriddenFields, hasTREE);
 	}
 }
 
@@ -491,7 +798,7 @@ NodeVector<FieldDescriptor> StructuredClass::getFieldDescriptors() const
 	// in this case we return a NodeVector of Rooted entries without owner.
 	NodeVector<FieldDescriptor> vec;
 	std::set<std::string> overriddenFields;
-	gatherFieldDescriptors(vec, overriddenFields);
+	gatherFieldDescriptors(vec, overriddenFields, false);
 	return vec;
 }
 
@@ -510,12 +817,12 @@ AnnotationClass::AnnotationClass(Manager &mgr, std::string name,
 
 void Domain::doResolve(ResolutionState &state)
 {
-	if (!continueResolveComposita(structuredClasses,
-	                              structuredClasses.getIndex(), state) |
-	    continueResolveComposita(annotationClasses,
-	                             annotationClasses.getIndex(), state)) {
-		continueResolveReferences(typesystems, state);
-	}
+	continueResolveComposita(structuredClasses, structuredClasses.getIndex(),
+	                         state);
+	continueResolveComposita(annotationClasses, annotationClasses.getIndex(),
+	                         state);
+	continueResolveReferences(typesystems, state);
+	continueResolveReferences(domains, state);
 }
 
 bool Domain::doValidate(Logger &logger) const
@@ -530,14 +837,17 @@ bool Domain::doValidate(Logger &logger) const
 
 void Domain::doReference(Handle<Node> node)
 {
-	if (node->isa(&RttiTypes::Domain)) {
+	if (node->isa(&RttiTypes::Typesystem)) {
 		referenceTypesystem(node.cast<Typesystem>());
 	}
+	if (node->isa(&RttiTypes::Domain)) {
+		referenceDomain(node.cast<Domain>());
+	}
 }
 
 RttiSet Domain::doGetReferenceTypes() const
 {
-	return RttiSet{&RttiTypes::Domain};
+	return RttiSet{&RttiTypes::Domain, &RttiTypes::Typesystem};
 }
 
 void Domain::addStructuredClass(Handle<StructuredClass> s)
diff --git a/src/core/model/Domain.hpp b/src/core/model/Domain.hpp
index 24199b1..d921a9c 100644
--- a/src/core/model/Domain.hpp
+++ b/src/core/model/Domain.hpp
@@ -34,74 +34,46 @@
  *
  * \code{.xml}
  * <domain name="book">
- * 	<structs>
- * 		<struct name="book" cardinality="1" isRoot="true">
- * 			<fields>
- * 				<field>
- * 					<children>
- * 						<child name="book.chapter"/>
- * 						<child name="book.paragraph"/>
- * 					</children>
- * 				</field>
- * 			</fields>
- * 		</struct>
- * 		<struct name="chapter">
- * 			<fields>
- * 				<field>
- * 					<children>
- * 						<child name="book.section"/>
- * 						<child name="book.paragraph"/>
- * 					</children>
- * 				</field>
- * 			</fields>
- * 		</struct>
- * 		<struct name="section">
- * 			<fields>
- * 				<field>
- * 					<children>
- * 						<child name="book.subsection"/>
- * 						<child name="book.paragraph"/>
- * 					</children>
- * 				</field>
- * 			</fields>
- * 		</struct>
- * 		<struct name="subsection">
- * 			<fields>
- * 				<field>
- * 					<children>
- * 						<child name="book.paragraph"/>
- * 					</children>
- * 				</field>
- * 			</fields>
- * 		</struct>
- * 		<struct name="paragraph" transparent="true" role="paragraph">
- * 			<fields>
- * 				<field>
- * 					<children>
- * 						<child name="book.text"/>
- * 					</children>
- * 				</field>
- * 			</fields>
- * 		</struct>
- * 		<struct name="text" transparent="true" role="text">
- * 			<fields>
- * 				<field name="content" type="PRIMITIVE" primitiveType="string"/>
- * 			</fields>
- * 		</struct>
- * 	</structs>
+ * 	<struct name="book" cardinality="1" isRoot="true">
+ * 		<field>
+ * 			<childRef ref="book.chapter"/>
+ * 			<childRef ref="book.paragraph"/>
+ * 		</field>
+ * 	</struct>
+ * 	<struct name="chapter">
+ * 		<field>
+ * 			<childRef ref="book.section"/>
+ * 			<childRef ref="book.paragraph"/>
+ * 		</field>
+ * 	</struct>
+ * 	<struct name="section">
+ * 		<field>
+ * 			<childRef ref="book.subsection"/>
+ * 			<childRef ref="book.paragraph"/>
+ * 		</field>
+ * 	</struct>
+ * 	<struct name="subsection">
+ * 		<field>
+ * 			<childRef ref="book.paragraph"/>
+ * 		</field>
+ * 	</struct>
+ * 	<struct name="paragraph" transparent="true">
+ * 		<field>
+ * 			<childRef ref="book.text"/>
+ * 		</field>
+ * 	</struct>
+ * 	<struct name="text" transparent="true">
+ * 		<primitive type="string"/>
+ * 	</struct>
  * </domain>
  * \endcode
  *
  * Note that we define one field as the TREE (meaning the main or default
  * document structure) and one mearly as SUBTREE, relating to supporting
  * information. You are not allowed to define more than one field of type
- * "TREE". Accordingly for each StructuredClass in the main TREE there must be
- * at least one possible primitive child or one TREE field. Otherwise the
- * grammar would be nonterminal. For SUBTREE fields no children may define a
- * TREE field and at least one permitted child must exist, either primitive or
- * as another StructuredClass.
+ * "TREE".
  *
- * The translation to context free grammars is as follows:
+ * The translation to a context free grammar is as follows:
  *
  * \code{.txt}
  * BOOK              := <book> BOOK_TREE </book>
@@ -128,21 +100,14 @@
  *
  * \code{.xml}
  * <domain name="headings">
- * 	<head>
- * 		<import rel="domain" src="book.oxm"/>
- * 	</head>
- * 	<structs>
- * 		<struct name="heading" cardinality="0-1" transparent="true">
- * 			<parents>
- * 				<parent name="book.book">
- * 					<field name="heading" type="SUBTREE"/>
- * 				</parent>
- * 				...
- * 			</parents>
- * 			<fields>
- * 				<fieldRef name="book.paragraph.">
- * 			</fields>
- * 	</structs>
+ *	<import rel="domain" src="./book_domain.osxml"/>
+ * 	<struct name="heading" cardinality="1" transparent="true">
+ * 		<parentRef ref="book.book">
+ * 			<field name="heading" isSubtree="true" optional="true"/>
+ * 		</parentRef>
+ * 		...
+ * 		<fieldRef name="book.paragraph.">
+ * 	</struct>
  * </domain>
  * \endcode
  *
@@ -161,36 +126,36 @@
  *
  * \code{.xml}
  * <domain name="comments">
- * 	<head>
- * 		<import rel="domain" src="book.oxm"/>
- * 	</head>
- * 	<annos>
- * 		<anno name="comment">
- * 			<fields>
- * 				<field name="replies" type="SUBTREE">
- * 					<children>
- * 						<child name="reply"/>
- * 					</children>
- * 				</field>
- * 			</fields>
- * 		</anno>
- * 	</annos>
- * 	<structs>
- * 		<struct name="reply">
- * 			<fields>
- * 				<field name="replies" type="SUBTREE">
- * 					<children>
- * 						<child name="reply"/>
- * 					</children>
- * 				</field>
- * 				<field name="content" type="SUBTREE">
- * 					<children>
- * 						<child name="book.paragraph"/>
- * 					</children>
- * 				</field>
- * 			</fields>
- * 		</struct>
- * 	</structs>
+ *	<import rel="domain" src="./book_domain.osxml"/>
+ *
+ *	<annotation name="comment">
+ *		<field name="content" isSubtree="true">
+ *			<childRef ref="book.paragraph"/>
+ *		</field>
+ *		<field name="replies" isSubtree="true">
+ *			<childRef ref="reply"/>
+ *		</field>
+ *	</annotation>
+ *
+ *	<struct name="comment">
+ *		<field name="content">
+ *			<childRef ref="book.paragraph"/>
+ *		</field>
+ *		<field name="replies" isSubtree="true">
+ *			<childRef ref="reply"/>
+ *		</field>
+ *		<parentRef ref="book.paragraph">
+ *			<fieldRef ref="$default"/>
+ *		</parentRef>
+ *	</struct>
+ *	<struct name="reply">
+ *		<field name="content" isSubtree="true">
+ *			<childRef ref="book.paragraph"/>
+ *		</field>
+ *		<field name="replies" isSubtree="true">
+ *			<childRef ref="reply"/>
+ *		</field>
+ *	</struct>
  * </domain>
  * \endcode
  *
@@ -227,25 +192,15 @@ static const std::string DEFAULT_FIELD_NAME = "$default";
  * accordingly typed content without further descending in the Structure
  * Hierarchy.
  *
- * As an example consider the "paragraph" StructuredClass, which might allow
+ * As an example consider the "text" StructuredClass, which might allow
  * the actual text content. Here is the according XML:
  *
  * \code{.xml}
- * <struct name="paragraph" transparent="true" role="paragraph">
- * 	<fields>
- * 		<field>
- * 			<children>
- * 				<child name="book.text"/>
- * 			</children>
- * 		</field>
- * 	</fields>
- * </struct>
+ * 	<struct name="text" transparent="true">
+ * 		<primitive type="string"/>
+ * 	</struct>
  * \endcode
  *
- * Accordingly the primitiveType field of a FieldDescriptor may only be
- * defined if the type is set to "PRIMITIVE". If the type is something else
- * at least one child must be defined and the primitiveType remains in an
- * undefined state.
  */
 class FieldDescriptor : public Node {
 	friend Descriptor;
@@ -253,32 +208,26 @@ class FieldDescriptor : public Node {
 public:
 	/**
 	 * This enum class contains all possible FieldTypes, meaning either the
-	 * main structure beneath this Descritor (TREE), supporting structure
-	 * (SUBTREE) or a primitive terminal (PRIMITIVE).
-	 *
-	 * Note the following rules (which are also mentioned above):
-	 * 1.) There may be only one TREE field in a Descriptor.
-	 * 2.) Each TREE field must allow for at least one child, which in turn has
-	 *     either a TREE field or a PRIMITIVE field.
-	 * 3.) SUBTREE fields may not allow for children with TREE fields.
-	 * 4.) SUBTREE fields must allow for at least one child with another SUBTREE
-	 *     or PRIMITIVE field.
+	 * main structure beneath this Descriptor (TREE) or supporting structure
+	 * (SUBTREE)
+	 *
+	 * Note that there may be only one TREE field in a descriptor.
 	 */
-	enum class FieldType { TREE, SUBTREE, PRIMITIVE };
+	enum class FieldType { TREE, SUBTREE };
 
 private:
 	NodeVector<StructuredClass> children;
 	FieldType fieldType;
 	Owned<Type> primitiveType;
 	bool optional;
+	bool primitive;
 
 protected:
 	bool doValidate(Logger &logger) const override;
 
 public:
 	/**
-	 * This is the constructor for primitive fields. The type is automatically
-	 * set to "PRIMITIVE".
+	 * This is the constructor for primitive fields.
 	 *
 	 * @param mgr           is the global Manager instance.
 	 * @param parent        is a handle of the Descriptor node that has this
@@ -290,10 +239,10 @@ public:
 	 *                      filled in order for an instance of the parent
 	 *                      Descriptor to be valid.
 	 */
-	FieldDescriptor(Manager &mgr, Handle<Descriptor> parent,
-	                Handle<Type> primitiveType,
-	                std::string name = DEFAULT_FIELD_NAME,
-	                bool optional = false);
+	FieldDescriptor(Manager &mgr, Handle<Type> primitiveType,
+	                Handle<Descriptor> parent,
+	                FieldType fieldType = FieldType::TREE,
+	                std::string name = "", bool optional = false);
 
 	/**
 	 * This is the constructor for non-primitive fields. You have to provide
@@ -312,8 +261,7 @@ public:
 	 */
 	FieldDescriptor(Manager &mgr, Handle<Descriptor> parent = nullptr,
 	                FieldType fieldType = FieldType::TREE,
-	                std::string name = DEFAULT_FIELD_NAME,
-	                bool optional = false);
+	                std::string name = "", bool optional = false);
 
 	/**
 	 * Returns a const reference to the NodeVector of StructuredClasses whose
@@ -377,11 +325,11 @@ public:
 	}
 
 	/**
-	 * Returns true if and only if the type of this field is PRIMITIVE.
+	 * Returns if this field is primitive.
 	 *
-	 * @return true if and only if the type of this field is PRIMITIVE.
+	 * @return true if and only if this field is primitive.
 	 */
-	bool isPrimitive() const { return fieldType == FieldType::PRIMITIVE; }
+	bool isPrimitive() const { return primitive; }
 
 	/**
 	 * Returns the primitive type of this field, which is only allowed to be
@@ -456,8 +404,7 @@ private:
 	Owned<StructType> attributesDescriptor;
 	NodeVector<FieldDescriptor> fieldDescriptors;
 
-	bool continuePath(Handle<StructuredClass> target,
-	                  std::vector<Rooted<Node>> &path) const;
+	void addAndSortFieldDescriptor(Handle<FieldDescriptor> fd, Logger &logger);
 
 protected:
 	void doResolve(ResolutionState &state) override;
@@ -546,20 +493,7 @@ public:
 	 *
 	 * @param fd is a FieldDescriptor.
 	 */
-	void addFieldDescriptor(Handle<FieldDescriptor> fd);
-
-	/**
-	 * Adds the given FieldDescriptors to this Descriptor. This also sets the
-	 * parent of each given FieldDescriptor if it is not set yet.
-	 *
-	 * @param fds are FieldDescriptors.
-	 */
-	void addFieldDescriptors(const std::vector<Handle<FieldDescriptor>> &fds)
-	{
-		for (Handle<FieldDescriptor> fd : fds) {
-			addFieldDescriptor(fd);
-		}
-	}
+	void addFieldDescriptor(Handle<FieldDescriptor> fd, Logger &logger);
 
 	/**
 	 * Adds the given FieldDescriptor to this Descriptor. This also sets the
@@ -568,21 +502,7 @@ public:
 	 *
 	 * @param fd is a FieldDescriptor.
 	 */
-	void moveFieldDescriptor(Handle<FieldDescriptor> fd);
-
-	/**
-	 * Adds the given FieldDescriptors to this Descriptor. This also sets the
-	 * parent of each given FieldDescriptor if it is not set to this Descriptor
-	 * already and removes it from the old parent Descriptor.
-	 *
-	 * @param fds are FieldDescriptors.
-	 */
-	void moveFieldDescriptors(const std::vector<Handle<FieldDescriptor>> &fds)
-	{
-		for (Handle<FieldDescriptor> fd : fds) {
-			moveFieldDescriptor(fd);
-		}
-	}
+	void moveFieldDescriptor(Handle<FieldDescriptor> fd, Logger &logger);
 
 	/**
 	 * Copies a FieldDescriptor that belongs to another Descriptor to this
@@ -590,7 +510,7 @@ public:
 	 *
 	 * @param fd some FieldDescriptor belonging to another Descriptor.
 	 */
-	void copyFieldDescriptor(Handle<FieldDescriptor> fd);
+	void copyFieldDescriptor(Handle<FieldDescriptor> fd, Logger &logger);
 
 	/**
 	 * Removes the given FieldDescriptor from this Descriptor. This also sets
@@ -616,8 +536,9 @@ public:
 	 * @return              the newly created FieldDescriptor.
 	 */
 	Rooted<FieldDescriptor> createPrimitiveFieldDescriptor(
-	    Handle<Type> primitiveType, std::string name = DEFAULT_FIELD_NAME,
-	    bool optional = false);
+	    Handle<Type> primitiveType, Logger &logger,
+	    FieldDescriptor::FieldType fieldType = FieldDescriptor::FieldType::TREE,
+	    std::string name = "", bool optional = false);
 
 	/**
 	 * This creates a new primitive FieldDescriptor and adds it to this
@@ -634,8 +555,9 @@ public:
 	 * @return              the newly created FieldDescriptor.
 	 */
 	Rooted<FieldDescriptor> createFieldDescriptor(
+	    Logger &logger,
 	    FieldDescriptor::FieldType fieldType = FieldDescriptor::FieldType::TREE,
-	    std::string name = DEFAULT_FIELD_NAME, bool optional = false);
+	    std::string name = "", bool optional = false);
 
 	/**
 	 * This tries to construct the shortest possible path of this Descriptor
@@ -656,6 +578,9 @@ public:
 	 * a path between book and section (via chapter), but chapter is not
 	 * transparent. Therefore that path is not allowed.
 	 *
+	 * Implicitly this does a breadth-first search on the graph of
+	 * StructuredClasses that are transparent. It also takes care of cycles.
+	 *
 	 * @param childDescriptor is a supposedly valid child Descriptor of this
 	 *                        Descriptor.
 	 * @return                either a path of FieldDescriptors and
@@ -664,8 +589,53 @@ public:
 	 *                        no such path can be constructed.
 	 *
 	 */
-	std::vector<Rooted<Node>> pathTo(
-	    Handle<StructuredClass> childDescriptor) const;
+	NodeVector<Node> pathTo(Handle<StructuredClass> childDescriptor,
+	                        Logger &logger) const;
+	/**
+	 * This tries to construct the shortest possible path of this Descriptor
+	 * to the given FieldDescriptor. Note that this method has the problem that
+	 * an empty return path does NOT strictly imply that no such path could
+	 * be constructed: We also return an empty vector if the given
+	 * FieldDescriptor is a direct child. Therefore we also return a bool value
+	 * indicating that the path is valid or not.
+	 *
+	 *
+	 * Implicitly this does a breadth-first search on the graph of
+	 * StructuredClasses that are transparent. It also takes care of cycles.
+	 *
+	 * @param field is a FieldDescriptor that may be allowed as child of this
+	 *              Descriptor.
+	 * @return      returns a tuple containing a path of FieldDescriptors and
+	 *              StructuredClasses between this Descriptor and the input
+	 *              FieldDescriptor and a bool value indicating if the
+	 *              construction was successful.
+	 */
+	std::pair<NodeVector<Node>, bool> pathTo(Handle<FieldDescriptor> field,
+	                                         Logger &logger) const;
+
+	/**
+	 * Returns a vector of all TREE fields that are allowed as structure tree
+	 * children of an instance of this Descriptor. This also makes use of
+	 * transparency.
+	 * The list is sorted by the number of transparent elements that have to be
+	 * constructed to arrive at the respective FieldDescriptor.
+	 *
+	 * @return a vector of all TREE fields that are allowed as structure tree
+	 *         children of an instance of this Descriptor.
+	 */
+	NodeVector<FieldDescriptor> getDefaultFields() const;
+
+	/**
+	 * Returns a vector of all StructuredClasses that are allowed as children
+	 * of an instance of this Descriptor in the structure tree. This also makes
+	 * use of transparency.
+	 * The list is sorted by the number of transparent elements that have to be
+	 * constructed to arrive at the respective FieldDescriptor.
+	 *
+	 * @return a vector of all StructuredClasses that are allowed as children
+	 *         of an instance of this Descriptor in the structure tree.
+	 */
+	NodeVector<StructuredClass> getPermittedChildren() const;
 };
 /*
  * TODO: We should discuss Cardinalities one more time. Is it smart to define
@@ -756,9 +726,9 @@ private:
 	/**
 	 * Helper method for getFieldDescriptors.
 	 */
-	const void gatherFieldDescriptors(
-	    NodeVector<FieldDescriptor> &current,
-	    std::set<std::string> &overriddenFields) const;
+	void gatherFieldDescriptors(NodeVector<FieldDescriptor> &current,
+	                            std::set<std::string> &overriddenFields,
+	                            bool hasTREE) const;
 
 protected:
 	bool doValidate(Logger &logger) const override;
@@ -943,6 +913,7 @@ private:
 	NodeVector<StructuredClass> structuredClasses;
 	NodeVector<AnnotationClass> annotationClasses;
 	NodeVector<Typesystem> typesystems;
+	NodeVector<Domain> domains;
 
 protected:
 	void doResolve(ResolutionState &state) override;
@@ -963,7 +934,8 @@ public:
 	    : RootNode(mgr, std::move(name), nullptr),
 	      structuredClasses(this),
 	      annotationClasses(this),
-	      typesystems(this)
+	      typesystems(this),
+	      domains(this)
 	{
 	}
 
@@ -1114,6 +1086,19 @@ public:
 	{
 		typesystems.insert(typesystems.end(), ts.begin(), ts.end());
 	}
+
+	/**
+	 * Adds a Domain reference to this Domain.
+	 */
+	void referenceDomain(Handle<Domain> d) { domains.push_back(d); }
+
+	/**
+	 * Adds multiple Domain references to this Domain.
+	 */
+	void referenceDomains(const std::vector<Handle<Domain>> &ds)
+	{
+		domains.insert(domains.end(), ds.begin(), ds.end());
+	}
 };
 
 namespace RttiTypes {
diff --git a/src/core/model/Typesystem.cpp b/src/core/model/Typesystem.cpp
index fb99f87..b34687e 100644
--- a/src/core/model/Typesystem.cpp
+++ b/src/core/model/Typesystem.cpp
@@ -21,6 +21,7 @@
 #include <core/common/RttiBuilder.hpp>
 #include <core/common/Utils.hpp>
 #include <core/common/VariantConverter.hpp>
+#include <core/common/VariantReader.hpp>
 
 namespace ousia {
 
@@ -67,6 +68,65 @@ bool Type::build(Variant &data, Logger &logger) const
 	return build(data, logger, NullMagicCallback);
 }
 
+std::pair<bool, Variant> Type::read(CharReader &reader, Logger &logger,
+                                    const std::unordered_set<char> &delims)
+{
+	// try all variant types of this type and use the first successful one.
+	Variant v;
+	bool success = false;
+	for (auto t : getVariantTypes()) {
+		auto res = VariantReader::parseTyped(t, reader, logger, delims);
+		if (res.first) {
+			v = res.second;
+			success = true;
+			break;
+		}
+	}
+
+	if (!success) {
+		return std::make_pair(false, Variant{});
+	}
+	if (!build(v, logger)) {
+		return std::make_pair(false, Variant{});
+	}
+	return std::make_pair(true, v);
+}
+
+std::pair<bool, Variant> Type::read(const std::string &str, Logger &logger,
+                                    SourceId sourceId, size_t offs)
+{
+	// try all variant types of this type and use the first successful one.
+	Variant v;
+	bool success = false;
+	std::vector<LoggerFork> forks;
+	auto vts = getVariantTypes();
+	for (auto vt : vts) {
+		forks.emplace_back(logger.fork());
+		auto res =
+		    VariantReader::parseTyped(vt, str, forks.back(), sourceId, offs);
+		if (res.first) {
+			v = res.second;
+			success = true;
+			forks.back().commit();
+			break;
+		}
+	}
+
+	if (!success) {
+		logger.error("Could not read data with any of the possible types:");
+		for (size_t t = 0; t < forks.size(); t++) {
+			logger.note(std::string(Variant::getTypeName(vts[t])) + ":",
+			            SourceLocation{}, MessageMode::NO_CONTEXT);
+			forks[t].commit();
+		}
+		return std::make_pair(false, Variant{});
+	}
+	if (!build(v, logger)) {
+		return std::make_pair(false, Variant{});
+	}
+	return std::make_pair(true, v);
+}
+
 bool Type::doCheckIsa(Handle<const Type> type) const { return false; }
 
 bool Type::checkIsa(Handle<const Type> type) const
diff --git a/src/core/model/Typesystem.hpp b/src/core/model/Typesystem.hpp
index 8e3a3bc..9f9470e 100644
--- a/src/core/model/Typesystem.hpp
+++ b/src/core/model/Typesystem.hpp
@@ -43,6 +43,7 @@
 namespace ousia {
 
 // Forward declarations
+class CharReader;
 class Rtti;
 class Typesystem;
 class SystemTypesystem;
@@ -168,6 +169,32 @@ public:
 	bool build(Variant &data, Logger &logger) const;
 
 	/**
+	 * Tries to parse an instance of this type from the given stream.
+	 *
+	 * @param reader is a reference to the CharReader instance which is
+	 * the source for the character data. The reader will be positioned
+	 * at the end of the type instance (or the delimiting character).
+	 * @param delims is a set of characters which will terminate the typed
+	 * instance if the according parser uses delimiting characters.
+	 * These characters are not included in the result. May not be nullptr.
+	 */
+	std::pair<bool, Variant> read(CharReader &reader, Logger &logger,
+	                              const std::unordered_set<char> &delims = {});
+
+	/**
+	 * Tries to parse an instance of this type from the given string.
+	 *
+	 * @param str is the string from which the value should be read.
+	 * @param sourceId is an optional descriptor of the source file from which
+	 * the element is being read.
+	 * @param offs is the by offset in the source file at which the string
+	 * starts.
+	 */
+	std::pair<bool, Variant> read(const std::string &str, Logger &logger,
+	                              SourceId sourceId = InvalidSourceId,
+	                              size_t offs = 0);
+
+	/**
 	 * Returns true if and only if the given Variant adheres to this Type. In
 	 * essence this just calls the build method on a copy of the input Variant.
 	 *
@@ -203,6 +230,23 @@ public:
 	{
 		return this->getParent().cast<Typesystem>();
 	}
+
+	/**
+	 * Returns the VariantTypes whose instances are proper input for building an
+	 * instance of this type.
+	 * More specifically: Every returned VariantType T should be such that:
+	 * If a string s can be parsed according to T to a Variant v then the call
+	 * build(v, logger) should only fail (return false) if the variant content
+	 * does not adhere to the specific type specification. But it should be a
+	 * properly typed input for build.
+	 * The order of the types returned by this function determines the order in
+	 * which a parser should try to interpret an input string s.
+	 *
+	 * @return the VariantTypes that arethe basis for parsing an instance of
+	 *this
+	 * type.
+	 */
+	virtual std::vector<VariantType> getVariantTypes() const = 0;
 };
 
 /**
@@ -243,6 +287,16 @@ public:
 	 * @return a variant containing an empty string.
 	 */
 	Variant create() const override { return Variant{""}; }
+
+	/**
+	 * Returns the String VariantType.
+	 *
+	 * @return the String VariantType.
+	 */
+	std::vector<VariantType> getVariantTypes() const override
+	{
+		return {VariantType::STRING};
+	}
 };
 
 /**
@@ -282,6 +336,16 @@ public:
 	 * @return the integer value zero.
 	 */
 	Variant create() const override { return Variant{0}; }
+
+	/**
+	 * Returns the Int VariantType.
+	 *
+	 * @return the Int VariantType.
+	 */
+	std::vector<VariantType> getVariantTypes() const override
+	{
+		return {VariantType::INT};
+	}
 };
 
 /**
@@ -321,6 +385,16 @@ public:
 	 * @return the double value zero.
 	 */
 	Variant create() const override { return Variant{0.0}; }
+
+	/**
+	 * Returns the Double VariantType.
+	 *
+	 * @return the Double VariantType.
+	 */
+	std::vector<VariantType> getVariantTypes() const override
+	{
+		return {VariantType::DOUBLE};
+	}
 };
 
 /**
@@ -360,6 +434,16 @@ public:
 	 * @return a Variant with the boolean value false.
 	 */
 	Variant create() const override { return Variant{false}; }
+
+	/**
+	 * Returns the bool VariantType.
+	 *
+	 * @return the bool VariantType.
+	 */
+	std::vector<VariantType> getVariantTypes() const override
+	{
+		return {VariantType::BOOL};
+	}
 };
 
 /**
@@ -476,6 +560,16 @@ public:
 	 * name. Throws a LoggableException if the string does not exist.
 	 */
 	Ordinal valueOf(const std::string &name) const;
+
+	/**
+	 * Returns the int and string VariantTypes.
+	 *
+	 * @return the int and string VariantTypes.
+	 */
+	std::vector<VariantType> getVariantTypes() const override
+	{
+		return {VariantType::INT, VariantType::STRING};
+	}
 };
 
 /**
@@ -911,6 +1005,15 @@ public:
 	 * @return true if the requested attribute name exists, false otherwise.
 	 */
 	bool hasAttribute(const std::string &name) const;
+	/**
+	 * Returns the array and map VariantTypes.
+	 *
+	 * @return the array and map VariantTypes.
+	 */
+	std::vector<VariantType> getVariantTypes() const override
+	{
+		return {VariantType::MAP};
+	}
 };
 
 /**
@@ -976,6 +1079,15 @@ public:
 	 * @return Rooted reference pointing at the innerType.
 	 */
 	Rooted<Type> getInnerType() { return innerType; }
+	/**
+	 * Returns the array VariantType.
+	 *
+	 * @return the array VariantType.
+	 */
+	std::vector<VariantType> getVariantTypes() const override
+	{
+		return {VariantType::ARRAY};
+	}
 };
 
 /**
@@ -1014,6 +1126,20 @@ public:
 	 * @return a Variant instance with nullptr value.
 	 */
 	Variant create() const override;
+	/**
+	 * Returns all parseable VariantTypes (bool, int, double, array, map,
+	 *cardinality, object, string).
+	 *
+	 * @return all parseable VariantTypes (bool, int, double, array, map,
+	 *cardinality, object, string).
+	 */
+	std::vector<VariantType> getVariantTypes() const override
+	{
+		return {VariantType::BOOL,   VariantType::INT,
+		        VariantType::DOUBLE, VariantType::ARRAY,
+		        VariantType::MAP,    VariantType::CARDINALITY,
+		        VariantType::OBJECT, VariantType::STRING};
+	}
 };
 
 /**