Changes between Version 78 and Version 79 of S3/S3XML


Ignore:
Timestamp:
10/22/14 19:28:42 (7 years ago)
Author:
Fran Boon
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • S3/S3XML

    v78 v79  
    190190
    191191==== Schema Documents ====
    192 
    193192'''Schema documents''' describe the data schema for a resource. Clients can use these documents e.g. for automatic generation of forms.
    194193
     
    222221  - the URL query parameter {{{?options=true}}} adds a list of field options to those fields where options are defined, and combined with the parameter {{{&reference=true}}}, even options for foreign key references will be included
    223222  - the URL query parameter {{{?meta=true}}} will include the meta fields (as <meta> elements). In data documents, the meta fields are to be encoded as attributes of the <resource> element
     223
    224224==== Field Option Documents ====
    225 
    226225'''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.
    227226
     
    246245  - In the current S3 implementation, transformation of field option documents is not supported. JSON conversion is possible, though.
    247246  - Field option documents can only be requested (GET). Future versions may also accept submissions of such documents to update the data schema.
     247
    248248==== Data Documents ====
    249 
    250249'''Data documents''' provide the current contents (data) of resources.
    251250
     
    275274
    276275==== Components ====
    277 
    278276Component resources are <resource> elements inside of their primary <resource> element.
    279277Component records will be automatically imported and the required key references be added (=no explicit reference-element required).
     
    286284
    287285==== References ====
    288 
    289286Foreign key references (except those linking components to their primary record) are represented by <reference> elements.
    290287
     
    300297
    301298==== s3xml ====
    302 
    303299The root element (in schema and data documents).
    304300
     
    322318||'''limit'''||integer||the maximum number of records returned (in paginated requests)||''no''||
    323319||'''latmin''', '''latmax''', '''lonmin''', '''lonmax'''||float||geo-location boundary box of the results||''no''||
     320
    324321==== resource ====
    325 
    326322Represents a record (in data documents) or a database table (in schema documents).
    327323
     
    371367
    372368MCI handling is optional for non-synchronizing interfaces.
     369
    373370==== data ====
    374 
    375371Represents the value of a single field in the record.
    376372
     
    403399
    404400==== reference ====
    405 
    406401Represents a foreign key reference.
    407402
     
    444439== JSON Format ==
    445440To create new resources PUT to {{{http://host.domain/eden/module/resource.s3json}}}
     441
     442To introspect a form, GET {{{http://host.domain/eden/module/resource.s3json?options=true&references=true}}}
     443
     444JSON format characteristics:
     445
     446 * The JSON output contains _no_ whitespace between elements, it's just added here by hand for better readability
     447
     448 * The outermost structure is always a JSON object (not a list)
     449 * All data is represented as strings (for security reasons)
     450
     451 * If @value is sent for a field, it overrides the element text ($) at import
     452 * however, the use of @value is not mandatory, data can simply be placed instead of element text
     453 * Note that there is no automatic data encoding: data must be sent in DB-encoded format
     454 * no attributes are mandatory at input
     455 * @tuid can be used instead of @uuid to link referenced records
     456
     457 * Multiple records of the same resource will be aggregated as lists like:
     458
     459{{{
     460{
     461    $_my_resource: [
     462        {
     463            // record1 of my_resource
     464        }
     465        {
     466            // record2 of my_resource
     467        }
     468    ]
     469}
     470}}}
    446471
    447472Example of creating a Disease Case:
     
    464489}
    465490}}}
     491
     492
    466493== CSV Format ==
    467 
    468494The S3XML importer can represent uploaded single-sheet CSV files in a very simple XML format, whereby it becomes available for transformation into S3XML and import into Sahana-Eden.
    469495
     
    496522
    497523A number of pre-defined XSLT stylesheets for CSV import including a respective CSV template can be found in the static/formats/s3csv folder.
     524
    498525== Examples ==
    499 
    500526=== XML Format ===
    501527
     
    563589
    564590=== JSON Format ===
    565 
    566591The data structure of the native S3JSON format is equivalent to the XML format (=element trees) - except that markup elements are represented by prefixes:
    567592
     
    607632}
    608633}}}
    609 
    610 '''JSON format characteristics:'''
    611 
    612   * The JSON output contains _no_ whitespace between elements, it's just added here by hand for better readability
    613 
    614   * The outermost structure is always a JSON object (not a list)
    615   * All data is represented as strings (for security reasons)
    616 
    617   * If @value is sent for a field, it overrides the element text ($) at import
    618   * however, the use of @value is not mandatory, data can simply be placed instead of element text
    619   * Note that there is no automatic data encoding: data must be sent in DB-encoded format
    620   * no attributes are mandatory at input
    621   * @tuid can be used instead of @uuid to link referenced records
    622 
    623   * Multiple records of the same resource will be aggregated as lists like:
    624 
    625 {{{
    626 {
    627     $_my_resource: [
    628         {
    629             // record1 of my_resource
    630         }
    631         {
    632             // record2 of my_resource
    633         }
    634     ]
    635 }
    636 }}}