Changes between Version 30 and Version 31 of S3/S3XML

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



  • S3/S3XML

    v30 v31  
    151151== XML Format ==
    153 === Types of Sources ===
    155 S3XML provides 3 types of sources:
     153=== Document Types and Structure ===
     155S3XML defines 3 types of documents:
    157157==== Schema ====
    159159'''Schema documents''' describe the data schema for a resource. Clients can use these documents e.g. for automatic generation of forms.
     161Document Tree:
     164  <resource>
     165    <field>
     166    ...
     167    <resource>
     168      <field>
     169      ...
     170    </resource>
     171  </resource>
    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.
     182Document Tree:
     185  <select>
     186    <option>
     187    <option>
     188    <option>
     189    ...
     190  </select>
     191  <select>
     192    ...
     193  </select>
     194  ...
     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.
    173204'''Data documents''' provide the current contents (data) of resources.
     206Document Tree:
     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>
     230==== Components ====
     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).
     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.
     236Components of components are not allowed (maximum depth 1), and where they appear in import sources, they will be ignored.
     238==== References ====
     240Foreign key references (except those linking components to their primary record) are represented by <reference> elements.
     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.
     244References inside referenced elements will be resolved (unlimited depth) and also be imported. Circular references will be detected and properly resolved.
     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.
     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.
    175250=== Element Descriptions ===