Changes between Version 3 and Version 4 of S3/S3XML


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

--

Legend:

Unmodified
Added
Removed
Modified
  • S3/S3XML

    v3 v4  
    6363
    6464=== Element Descriptions ===
     65
     66S3XML defines 4 element types:
     67
     68  - [#s3xml s3xml]
     69  - [#resource resource]
     70  - [#data data]
     71  - [#reference reference]
     72
     73==== s3xml ====
     74||'''Parent elements'''||''none (root element)''||
     75||'''Child elements'''||[#resource resource]||
     76||'''Contents'''||''empty''||
     77
     78The root element.
     79
     80**Attributes:
     81||'''Name'''||'''Type'''||'''Description'''||'''mandatory?'''||
     82||'''domain'''||string||the domain name of the data repository||''no''||
     83
     84==== resource ====
     85||'''Parent elements'''||[#s3xml s3xml], [#resource resource], [#reference reference]||
     86||'''Child elements'''||[#resource resource]||
     87||'''Contents'''||''empty''||
     88
     89Represents a record.
     90
     91**Attributes:
     92||'''Name'''||'''Type'''||'''Description'''||'''mandatory?'''||
     93||'''name'''||string||the name of the resource, usually the DB table name||''yes''||
     94||'''uuid'''||string||a unique identifier for the record||''no''*||
     95||'''tuid'''||string||a temporary unique identifier for the record||''no''*||
     96
     97(*) Records will be identified within the input file by their {{{uuid}}}, or, if no {{{uuid}}} is specified, by their {{{tuid}}}.
     98
     99The {{{uuid}}} will be stored in the database together with the record. If {{{uuid}}} is present and matches an existing record in the database, then this record will be updated. If there's no match or no {{{uuid}}} specified in the {{{resource}}} element, then the importer will create a new record in the database (and automatically generate a {{{uuid}}} if required).
     100
     101==== data ====
     102||'''Parent elements'''||[#resource resource]||
     103||'''Child elements'''||''none (leaf element)''||
     104||'''Contents'''||Text||
     105
     106Represents the value of a single field in the record.
     107
     108**Attributes:
     109||'''Name'''||'''Type'''||'''Description'''||'''mandatory?'''||
     110||'''field'''||string||the field name in the record||''yes''||
     111||'''value'''||JSON value||the native field value||''no''||
     112||'''url'''||URL||the URL to download the contents from*||''no''||
     113||'''filename'''||filename||the filename of the attached contents*||''no''||
     114
     115The text node in the {{{data}}} element provides a human-readable representation of the field value. If this representation is different from the original value in the database, then the original value must be provided by the ''value'' attribute.
     116
     117(*) If the field is for file upload, a {{{url}}} attribute should be provided to specify the location of the file. The importer will try to download and store the file (file transfer) from that URL (''pull''). It is also possible to send the file with the HTTP request - in this case the {{{filename}}} must be specified instead of {{{url}}} (''push''). The ''push'' variant for uploads is meant for peers which do not support pulling for some reason (e.g. mobile phones). Normal servers would always provide a URL for download in order to allow the consuming site decide which files to download and when (saves bandwidth).
     118
     119==== reference ====
     120||'''Parent elements'''||[#resource resource]||
     121||'''Child elements'''||[#resource resource]||
     122||'''Contents'''||Text||
     123
     124Represents a foreign key reference.
     125
     126**Attributes:
     127||'''Name'''||'''Type'''||'''Description'''||'''mandatory?'''||
     128||'''field'''||string||the field name in the record||''yes''||
     129||'''resource'''||string||the name of the referenced resource, usually the tablename||''yes''||
     130||'''uuid'''||string||the unique identifier of the referenced record (foreign key)*||''(yes)''!**||
     131||'''tuid'''||string||a temporary identifier for a referenced record (foreign key)*||''(yes)''!**||
     132
     133(*) Referenced records would always be exported in the same output file. If a referenced record is found in the same input file, then it will be automatically imported.
     134
     135(!**) Records will be identified within the input file by their {{{uuid}}}, or, if no {{{uuid}}} is specified, by their {{{tuid}}}.
     136
     137If the referenced record is enclosed in the ''reference'' element, then {{{uuid}}} and {{{tuid}}} can be omitted:
     138
     139{{{
     140<s3xml>
     141   <resource name="xxxyyy">
     142       <reference field="xy" resource="aaabbb">   <!-- the reference element, uuid/tuid can be omitted if -->
     143          <resource name="aaabbb">                <!-- the referenced record is enclosed in the reference -->
     144          </resource>
     145       </reference>
     146   </resource>
     147</s3xml>
     148}}}
    65149
    66150== JSON Format ==