[[TOC]] = S3XML = S3XML is a generic RESTful data exchange interface for the S3 framework. It comes with a genuine XML data format, but also provides built-in data format conversion and transformation to support a variety of custom XML, JSON and CSV formats and schemas. == Minimum Requirements for Implementation == === Clients === Interfaces which want to exchange data with S3XML interfaces must implement the following: - an HTTP client which can perform GET and POST requests - the native S3XML data format ''Note:'' - Where the target interface has built-in support for data format conversion/transformation (as in S3), it is sufficient if the client implements an S3XML-compatible data format (XML, JSON or CSV). - S3 comes with a number of built-in transformation stylesheets for some standard data formats. Where other formats shall be used, clients can also provide their own XSLT transformation stylesheets. === Servers === Interfaces which want to provide native S3XML capabilities (e.g. for Synchronization) must implement the following: - an HTTP server interface accepting and performing GET, PUT and POST requests - the RESTful API as described in this document - the native S3XML data format Optionally they can provide: - JSON/CSV to S3XML conversion - S3XML to JSON/CSV conversion - XSLT-1.0 transformation == Conventions == === Name Space === Where a name space identifier for the native S3XML format is to be used, it shall be: - "http://eden.sahanafoundation.org/S3XML" In the current implementation of S3, no name space identifier shall be used. This is though subject to change in future versions. === Character Encoding === XML documents to be used for S3XML can specify their character encoding in the XML header. Where JSON or CSV formats are used, they are expected to be UTF-8 encoded. S3XML interfaces can support other encodings for JSON/CSV, but this is not a requirement. All exported data are always UTF-8 encoded. === URL format === Data format extensions in URLs must be all-lowercase. Where uppercase characters are used, they are converted into lowercase. == Interface == == XML Format == === Types of Sources === === Element Descriptions === == JSON Format == == CSV Format == == Examples == - see [wiki:S3XRC] == XML Format == {{{ created_on="2009-10-02 08:55:11" <-- date/time when the record was created --> modified_on="2009-10-02 08:56:03" <-- date/time when the record was last modified --> uuid="6e6e76dc-8ed7-408c-bb09-54476e3944ae" <-- UUID of the record (if present in DB) --> created_by="None" <-- Author --> modified_by="Dominic" <-- Last Author --> name="pr_person"> <-- Resource Name --> field="pr_pe_id" <-- Field name --> resource="pr_pentity" <-- Name of the referenced resource --> uuid="6e6e76dc-8ed7-408c-bb09-54476e3944ae"/> <-- UUID of the referenced entry --> 730421 <-- A field in the record --> Dominic König male Adult (21-50) dominic@nursix.org 1973-04-21 Germany Sweden none married Nurse created_on="2009-10-02 11:34:34" modified_on="2009-10-02 11:34:34" uuid="89217054-3c10-4f5d-959a-420254243498" name="pr_address"> value="1"> <-- original value in the database --> Home Address <-- value represented for human readability --> Lundgatan 38031 Läckeby Sweden 56.78042 16.27914 }}} * [wiki:UUID] - how we handle Unique IDs for records across heterogeneous systems == JSON Format == The data structure of the JSON format is equivalent to the XML format (=element trees) - except that markup elements are represented by prefixes: {{{ { "@domain": "yana", // Server name "@url": "http://127.0.0.1:8000/eden" // Server URL "$_pr_person": { // Resource, prefix: $_ "@uuid": "44fc762e-02df-44e0-8bd1-9b58e3132894", // Resource attribute, prefix: @ "@url": "http://127.0.0.1:8000/eden/pr/person/1", "@created_on": "2009-11-16 22:33:35", "@created_by": "None", "@modified_on": "2009-11-19 21:32:19", "@modified_by": "Dominic", "first_name": "Dominic", // Data field, no prefix "last_name": "K\u00f6nig", "email": "dominic@nursix.org", "opt_pr_age_group": {"@value": "1", "$": "unknown"}, // Data field with textual representation: "opt_pr_religion": {"@value": "1", "$": "none"}, // @value=Value, $=TextualRepresentation "opt_pr_gender": {"@value": "1", "$": "unknown"}, "opt_pr_nationality": {"@value": "999", "$": "unknown"}, "opt_pr_country": {"@value": "999", "$": "unknown"}, "opt_pr_marital_status": {"@value": "1", "$": "unknown"}, "$k_pr_pe_id": { // External Reference (Key), prefix: $k_ "@resource": "pr_pentity", // Key resource name "@uuid": "a2a945bd-4f43-41da-bcdb-e2e638a987ea", // UUID of the key record "$": "Dominic K\u00f6nig [no label] (Person)" // Textual representation of the reference }, "$_pr_presence": { // Joined Resource (Component): "@uuid": "14af2751-7277-4e90-b42b-0d0430684561", // appears as component within the resource "@created_on": "2009-11-19 19:42:46", "@modified_on": "2009-11-19 19:42:46" "@url": "http://127.0.0.1:8000/eden/pr/person/1/presence/1", "opt_pr_presence_condition": {"@value": "4", "$": "Found"}, "time": {"@value": "2009-11-19 18:42:00 +0000", "$": "2009-11-19 20:42:00"}, "$k_reporter": { "@resource": "pr_person", "@uuid": "44fc762e-02df-44e0-8bd1-9b58e3132894", "$": "Dominic K\u00f6nig" }, } }, } }}} '''JSON format characteristics:''' * The JSON output contains _no_ whitespace between elements, it's just added here by hand for better readability * The outermost structure is always a JSON object (not a list) * All data is represented as strings (for security reasons) * If @value is sent for a field, it overrides the element text ($) at import * however, the use of @value is not mandatory, data can simply be placed instead of element text * Note that there is no automatic data encoding: data must be sent in DB-encoded format * @resource, @name and @uuid attributes are mandatory at input, other attributes can be omitted * Multiple records of the same resource will be aggregated as lists like: {{{ { $_my_resource: [ { // record1 of my_resource } { // record2 of my_resource } ] } }}}