XML Document

Normed Structure

As of now, there exist 3 different 'Norms' for XML Documents used in the context of this API Server. Documents that do not match the criteria described in this page are considered invalid. The three types are:

• minimal XML Document
• full XML Document
• partial XML Document

Full XML Document

The full XML document is in general considered to be the XML document which contains everything that exists in the scope of the according user. Meaning everything that is saved or should be saved has to be inside the full XML document. The entries are located in one registry node and there should only be one registry node. The registry node should have an version attribute and it's value is as of now supposed to be "1.0" (although it's not really used as of now) later there may also come a features attribute listing the features the registry requires or supports. Parallel to the registry node there may exist a meta node which can contain general info about the document. In case the meta node is used it should hold the version and features attributes as child nodes instead

Minimal XML Document

Is simply a full XML Document but with an empty registry. Basically the minimal XML Document is an document only containing necessary items but holds no actual information

Partial XML Document

The partial XML Document contains only a part of the full XML Document. This is useful when only one Element in the registry is really of interest. With partial Documents there is no registry allowed to exist, instead (since v2) a part node exists which holds a meta and a data node . The meta node is mandatory in the partial XML Document. The meta node is a sibling of the data node and contains information about the document itself and especially on important information otherwise missing (e.g. a list of all ID's existing in the full document so new IDs can be safely generated)

Known Fields

The information in an XML document is held by multiple directory and entry nodes. directory nodes can hold further entry and other directory notes, as well as one single info node which provides information around the directory itself. info and entry nodes contain other sub-nodes to describe the behavior and properties of the according element. In principle those sub-nodes can be called anything you like and contain anything you wish, however for the sake of simplicity and interoperability you can find a list of known sub-nodes with a description in this section. Some of these nodes can enable extra functionality from the server side. In theory it is encouraged to keep this list of sub-nodes in mind when implementing clients as this aims to push interoperability between clients forward. Sub-node names are expected to be in lower case and clients shouldn't rely on the presence of any sub-nodes.

(a sub-node with the name 'note' and the value 'no notes' looks like this: <note>no notes</note>)

Name	Expected Value Type	Description
type	String	What 'kind' the element is (e.g. 'Todo')
name	String	The name of the element
description	String	A description of the element
due	Integer	A Unix Timestamp of when the element is due (Note: elements may be overdue so they shouldn't be deleted on the base of this value)
expires	Integer	A Unix Timestamp of when the element is expired and is allowed to be deleted without further notice
color	String	A color in which the element may be colored (could be hex (e.g. '#FF00FF') or a keyword (e.g. 'red'))
note	String	A note to the element
requires	More Nodes	A list of what is required for this element to take place. Contains sub-nodes for further information (atm undefined)
repeats	String	Defines that this element repeats. When and how it repeats is defined using cron expressions
priority	Integer	The priority of the node (0 is highest) this is saved as an u16 leaving you with 65535 different priority levels
preparation	More Nodes	Defines what preparation is needed (e.g. time, description)