Changes between Version 30 and Version 31 of S3/S3XML

Timestamp:

07/19/11 13:24:08 (14 years ago)

Author:

Dominic König

Comment:

--

S3/S3XML

@@ -151 +151 @@
 == XML Format ==
 
-=== Types of Sources ===
-
-S3XML provides 3 types of sources:
+=== Document Types and Structure ===
+
+S3XML defines 3 types of documents:
 
 ==== Schema ====
 
 '''Schema documents''' describe the data schema for a resource. Clients can use these documents e.g. for automatic generation of forms.
+
+Document Tree:
+{{{
+<s3xml>
+  <resource>
+    <field>
+    ...
+    <resource>
+      <field>
+      ...
+    </resource>
+  </resource>
+</s3xml>
+}}}
 
 ''Note:''
@@ -166 +180 @@
 '''Field option documents''' describe the currently acceptable options for fields in a resource. Clients can use these documents e.g. for automatic generation and/or client-side validation of forms.
 
+Document Tree:
+{{{
+<options>
+  <select>
+    <option>
+    <option>
+    <option>
+    ...
+  </select>
+  <select>
+    ...
+  </select>
+  ...
+</options>
+}}}
+
 ''Note:''
+  - if the ''field'' URL variable is used to specify a particular field in the resource, the enclosing <options> element is omitted (i.e. <select> becomes root element)
   - In the current S3 implementation, transformation of field option documents is not supported. JSON conversion is possible, though.
   - Field option documents can only be requested (GET). Future versions may also accept submissions of such documents to update the data schema.
@@ -172 +203 @@
 
 '''Data documents''' provide the current contents (data) of resources.
+
+Document Tree:
+{{{
+<s3xml>
+  <resource> <!-- primary resource element -->
+    <data> <!-- field data -->
+    <data>
+    ...
+    <resource> <!-- component resource inside the primary resource -->
+      <data>
+      <data>
+      <reference/> <!-- reference -->
+      ...
+    </resource>
+    <reference/> <!-- reference -->
+    <reference> <!-- reference with embedded resource element -->
+       <resource>
+         <data>
+         ...
+       </resource>
+    </reference>
+  </resource>
+</s3xml>
+}}}
+
+==== Components ====
+
+Component resources are <resource> elements inside of their primary <resource> element. Component records will be automatically imported. Upon import, the required key references will be automatically added (=no explicit reference-element required).
+
+Foreign key references of component records to their primary record will not be exported, and where they appear in import sources, they will be ignored.
+
+Components of components are not allowed (maximum depth 1), and where they appear in import sources, they will be ignored.
+
+==== References ====
+
+Foreign key references (except those linking components to their primary record) are represented by <reference> elements.
+
+Foreign keys can be importable UIDs (''uuid''-attribute, which will be both imported and used to find and/or link to existing records in the DB) or temporary UIDs (''tuid''-attribute, which will not be imported but only used to find records within the current tree), If a <resource> element with a matching UID key attribute is found in the same tree, it will be automatically imported.
+
+References inside referenced elements will be resolved (unlimited depth) and also be imported. Circular references will be detected and properly resolved.
+
+Multi-references (list:reference type in web2py) use a list of UID keys separated by vertical dashes like {{{uuid=|uid1|uid2|uid3|}}}. The leading and trailing vertical dashes must be present.
+
+If a <resource> element is embedded inside the <reference>, either or both of the UID keys can be omitted. Where both keys are however used, they must match. Multiple embedded <resource> elements are allowed for multi-references.
 
 === Element Descriptions ===