Changes between Version 4 and Version 5 of S3/S3XML


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

--

Legend:

Unmodified
Added
Removed
Modified
  • S3/S3XML

    v4 v5  
    154154== Examples ==
    155155
    156   - see [wiki:S3XRC]
    157 
     156{{{
     157<s3xml>
     158
     159  <resource                                                 <-- a record in the database -->
     160      created_on="2009-10-02 08:55:11"                      <-- date/time when the record was created -->
     161      modified_on="2009-10-02 08:56:03"                     <-- date/time when the record was last modified -->
     162      uuid="6e6e76dc-8ed7-408c-bb09-54476e3944ae"           <-- UUID of the record (if present in DB) -->
     163      created_by="None"                                     <-- Author -->
     164      modified_by="Dominic"                                 <-- Last Author -->
     165      name="pr_person">                                     <-- Resource Name -->
     166
     167    <reference                                              <-- Reference Field (foreign key) in the record -->
     168      field="pr_pe_id"                                      <-- Field name -->
     169      resource="pr_pentity"                                 <-- Name of the referenced resource -->
     170      uuid="6e6e76dc-8ed7-408c-bb09-54476e3944ae"/>         <-- UUID of the referenced entry -->
     171
     172    <data field="pr_pe_label">730421</data>                 <-- A field in the record -->
     173    <data field="first_name">Dominic</data>
     174    <data field="middle_name"/>
     175    <data field="last_name">König</data>
     176    <data field="preferred_name"/>
     177    <data field="local_name"/>
     178    <data field="opt_pr_gender" value="3">male</data>
     179    <data field="opt_pr_age_group" value="5">Adult (21-50)</data>
     180    <data field="email">dominic@nursix.org</data>
     181    <data field="mobile_phone"/>
     182    <data field="date_of_birth">1973-04-21</data>
     183    <data field="opt_pr_nationality" value="65">Germany</data>
     184    <data field="opt_pr_country" value="167">Sweden</data>
     185    <data field="opt_pr_religion" value="1">none</data>
     186    <data field="opt_pr_marital_status" value="3">married</data>
     187    <data field="occupation">Nurse</data>
     188    <data field="comment"/>
     189
     190    <resource                                               <-- A sub-resource (component) of the record -->
     191      created_on="2009-10-02 11:34:34"
     192      modified_on="2009-10-02 11:34:34"
     193      uuid="89217054-3c10-4f5d-959a-420254243498"
     194      name="pr_address">
     195
     196      <data
     197        field="opt_pr_address_type"                         <-- field name -->
     198        value="1">                                          <-- original value in the database -->
     199          Home Address                                      <-- value represented for human readability -->
     200      </data>
     201      <data field="co_name"/>
     202      <data field="street1">Lundgatan</data>
     203      <data field="street2"/>
     204      <data field="postcode">38031</data>
     205      <data field="city">Läckeby</data>
     206      <data field="state"/>
     207      <data field="opt_pr_country" value="167">Sweden</data>
     208      <data field="lat">56.78042</data>
     209      <data field="lon">16.27914</data>
     210      <data field="comment"/>
     211    </resource>
     212  </resource>
     213</s3xml>
     214}}}
     215
     216 * [wiki:UUID] - how we handle Unique IDs for records across heterogeneous systems
     217
     218== JSON Format ==
     219
     220The data structure of the native S3JSON format is equivalent to the XML format (=element trees) - except that markup elements are represented by prefixes:
     221
     222{{{
     223{
     224    "@domain": "yana",                                             // Server name
     225    "@url": "http://127.0.0.1:8000/eden"                           // Server URL
     226    "$_pr_person": {                                               // Resource, prefix: $_
     227        "@uuid": "44fc762e-02df-44e0-8bd1-9b58e3132894",           // Resource attribute, prefix: @
     228        "@url": "http://127.0.0.1:8000/eden/pr/person/1",
     229        "@created_on": "2009-11-16 22:33:35",
     230        "@created_by": "None",
     231        "@modified_on": "2009-11-19 21:32:19",
     232        "@modified_by": "Dominic",
     233        "first_name": "Dominic",                                   // Data field, no prefix
     234        "last_name": "K\u00f6nig",
     235        "email": "dominic@nursix.org",
     236        "opt_pr_age_group": {"@value": "1", "$": "unknown"},       // Data field with textual representation:
     237        "opt_pr_religion": {"@value": "1", "$": "none"},           // @value=Value, $=TextualRepresentation
     238        "opt_pr_gender": {"@value": "1", "$": "unknown"},
     239        "opt_pr_nationality": {"@value": "999", "$": "unknown"},
     240        "opt_pr_country": {"@value": "999", "$": "unknown"},
     241        "opt_pr_marital_status": {"@value": "1", "$": "unknown"},
     242        "$k_pr_pe_id": {                                           // External Reference (Key), prefix: $k_
     243            "@resource": "pr_pentity",                             // Key resource name
     244            "@uuid": "a2a945bd-4f43-41da-bcdb-e2e638a987ea",       // UUID of the key record
     245            "$": "Dominic K\u00f6nig [no label] (Person)"          // Textual representation of the reference
     246        },
     247        "$_pr_presence": {                                         // Sub-resource (Component):
     248            "@uuid": "14af2751-7277-4e90-b42b-0d0430684561",       // appears as component within the resource
     249            "@created_on": "2009-11-19 19:42:46",
     250            "@modified_on": "2009-11-19 19:42:46"
     251            "@url": "http://127.0.0.1:8000/eden/pr/person/1/presence/1",
     252            "opt_pr_presence_condition": {"@value": "4", "$": "Found"},
     253            "time": {"@value": "2009-11-19 18:42:00 +0000", "$": "2009-11-19 20:42:00"},
     254            "$k_reporter": {
     255                "@resource": "pr_person",
     256                "@uuid": "44fc762e-02df-44e0-8bd1-9b58e3132894",
     257                "$": "Dominic K\u00f6nig"
     258            },
     259        }
     260    },
     261}
     262}}}
     263
     264'''JSON format characteristics:'''
     265
     266  * The JSON output contains _no_ whitespace between elements, it's just added here by hand for better readability
     267
     268  * The outermost structure is always a JSON object (not a list)
     269  * All data is represented as strings (for security reasons)
     270
     271  * If @value is sent for a field, it overrides the element text ($) at import
     272  * however, the use of @value is not mandatory, data can simply be placed instead of element text
     273  * Note that there is no automatic data encoding: data must be sent in DB-encoded format
     274  * @resource, @name and @uuid attributes are mandatory at input, other attributes can be omitted
     275
     276  * Multiple records of the same resource will be aggregated as lists like:
     277
     278{{{
     279{
     280    $_my_resource: [
     281        {
     282            // record1 of my_resource
     283        }
     284        {
     285            // record2 of my_resource
     286        }
     287    ]
     288}
     289}}}
    158290== XML Format ==
    159291