Changes between Version 30 and Version 31 of S3/S3XML


Ignore:
Timestamp:
07/19/11 13:24:08 (11 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • S3/S3XML

    v30 v31  
    151151== XML Format ==
    152152
    153 === Types of Sources ===
    154 
    155 S3XML provides 3 types of sources:
     153=== Document Types and Structure ===
     154
     155S3XML defines 3 types of documents:
    156156
    157157==== Schema ====
    158158
    159159'''Schema documents''' describe the data schema for a resource. Clients can use these documents e.g. for automatic generation of forms.
     160
     161Document Tree:
     162{{{
     163<s3xml>
     164  <resource>
     165    <field>
     166    ...
     167    <resource>
     168      <field>
     169      ...
     170    </resource>
     171  </resource>
     172</s3xml>
     173}}}
    160174
    161175''Note:''
     
    166180'''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.
    167181
     182Document Tree:
     183{{{
     184<options>
     185  <select>
     186    <option>
     187    <option>
     188    <option>
     189    ...
     190  </select>
     191  <select>
     192    ...
     193  </select>
     194  ...
     195</options>
     196}}}
     197
    168198''Note:''
     199  - 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)
    169200  - In the current S3 implementation, transformation of field option documents is not supported. JSON conversion is possible, though.
    170201  - Field option documents can only be requested (GET). Future versions may also accept submissions of such documents to update the data schema.
     
    172203
    173204'''Data documents''' provide the current contents (data) of resources.
     205
     206Document Tree:
     207{{{
     208<s3xml>
     209  <resource> <!-- primary resource element -->
     210    <data> <!-- field data -->
     211    <data>
     212    ...
     213    <resource> <!-- component resource inside the primary resource -->
     214      <data>
     215      <data>
     216      <reference/> <!-- reference -->
     217      ...
     218    </resource>
     219    <reference/> <!-- reference -->
     220    <reference> <!-- reference with embedded resource element -->
     221       <resource>
     222         <data>
     223         ...
     224       </resource>
     225    </reference>
     226  </resource>
     227</s3xml>
     228}}}
     229
     230==== Components ====
     231
     232Component 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).
     233
     234Foreign key references of component records to their primary record will not be exported, and where they appear in import sources, they will be ignored.
     235
     236Components of components are not allowed (maximum depth 1), and where they appear in import sources, they will be ignored.
     237
     238==== References ====
     239
     240Foreign key references (except those linking components to their primary record) are represented by <reference> elements.
     241
     242Foreign 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.
     243
     244References inside referenced elements will be resolved (unlimited depth) and also be imported. Circular references will be detected and properly resolved.
     245
     246Multi-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.
     247
     248If 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.
    174249
    175250=== Element Descriptions ===