[Fiware-ngsi] JSON rendering proposal

[Fermín Galán Márquez]

Hi,

Thank you for your feedback!

We strongly believe (and that though drives our proposal) that breaking XML alignment is a small price to pay if we achieve to lower the adoption barrier among developers. Let us illustrate (with a fragment of Python code - one of the "JSON-friendly" languages that developers happen to love) how a developer would use both approaches in his/her source code to access one of the deeper elements in a request tree:

Following the TI cited example ("JSON like the XML"):

doc.updateContextRequest.contextElementList.contextElement[0].contextAttributeList.contextAttribute[0].metadata.contextMetadata[0].name

Using our proposal:

doc.contextElements.contextElement[0].attributes[0].metadatas[0].name

The second code fragment is far more readable, don't you agree? From the point of view of developers it is definitely more desirable. Also, a more compact JSON format has another very important advantage: imagine we have lots and lots of data and very large messages for discovery and query requests. The entire system will be slowed down due to sending so much redundant stuff.

Regarding XML-JSON alignment, if we believe that the developers using our software are our main concern (and if you are fully involved and committed with FI-LAB I think you agree with me in that main concern) then the right strategy, in our opinion, is to provide a "sexy" JSON binding right now. Later would be too late. Then, after having this used for some time and getting feedback, probably we can close the loop and modify the XML binding to have something simpler and more aligned with the final JSON format accepted in the developers community. Possibly the current "largely overheaded" XML format will not be so much used. Wouldn't it be a pity to go for a JSON that is based on an XML that is no longer in use?

We will try to get the opinion from the developers of the Wirecloud NGSI library to know what they thinks about this (although they belong to FI-WARE, this is probably the most similar to "external developers" that we have at hand outside the NGSI task force). We think they could provide a valuable piece of feedback in this matter.

Best regards,

------
Fermín

PD. I will be on vacation from September 19th to September 27th. I will sync on this discussion at my return.

El 17/09/2013 17:14, Rolando Sergio (Guest) escribió:

Hi Fermin, and hi all,
At the beginning of our implementation, TI Context Broker supported only JSON, and then XML was added.

The JSON format implemented in TI CB is strictly related to the XML binding specification, preserving every tag in both formats, in order to have easy interoperability.
The XML attributes (as "type" in "entityId" tag) are transformed as a standard JSON field, as shown in the following fragments (and also as assumed in your proposal):

XML:
<entityId type="urn:username">
     <id>urn:username:cristinaF</id>
</entityId>

JSON:
 "entityId": {
       "id": "urn:username:cristinaF",
       "type": "urn:username"
 }

Here is an example of the same UpdateContextRequest message (sorry for the TI-like example :-) ) in both XML and JSON format:

XML:
<updateContextRequest>
    <contextElementList>
        <contextElement>
            <entityId type="urn:username">
               <id>urn:username:cristinaF</id>
            </entityId>
            <contextAttributeList>
                <contextAttribute>
                    <name>cell</name>
                    <contextValue>
                        <cgi>222-1-61101-7065</cgi>
                    </contextValue>
                    <metadata>
                        <contextMetadata>
                            <name>Timestamp</name>
                            <value>2012-06-13T15:04:52+01:00</value>
                        </contextMetadata>
                        <contextMetadata>
                            <name>Expires</name>
                            <value>2012-06-13T15:04:52+01:00</value>
                        </contextMetadata>
                        <contextMetadata>
                            <name>Source</name>
                            <value>teamlife_1.0</value>
                        </contextMetadata>
                    </metadata>
                </contextAttribute>
             </contextAttributeList>
        </contextElement>
    </contextElementList>
    <updateAction>UPDATE</updateAction>
</updateContextRequest>

JSON:
{
  "updateContextRequest": {
    "contextElementList": {
      "contextElement": [
        {
          "entityId": {
            "id": "urn:username:cristinaF",
            "type": "urn:username"
          },
          "contextAttributeList": {
            "contextAttribute": [
              {
                "name": "cell",
                "metadata": {
                  "contextMetadata": [
                    {
                      "name": "Timestamp",
                      "value": "2012-06-13T15:04:52+01:00"
                    },
                    {
                      "name": "Expires",
                      "value": "2012-06-13T15:04:52+01:00"
                    },
                    {
                      "name": "Source",
                      "value": "TeamLife_1.0"
                    }
                  ]
                },
                "contextValue": {
                  "cgi": "222-1-61101-7065"
                }
              }
            ]
          }
        }
      ]
    },
    "updateAction": "UPDATE"
  }
}

Your proposal for JSON binding is more compact, and it would be a great solution if there was no legacy of XML binding, but it is pretty different from the XML binding specification. Specifically, some tags are missing, e.g.:
- first external tag identifying the message type (e.g. "updateContextElement")
- "entity" in updateContextElement message (there is only "id"/"type"/"isPattern", assuming that they are related to the entity)
- tags ending in -List for list of structures.

We have also to consider that the XML binding specification was built based on the standard NGSI specification, and the XML messages strictly match the standard NGSI data structures, so it could be a further reason to preserve it also in JSON.
It would be interesting to know the opinion of Salvatore and Tobias from NEC, who studied and developed the XML binding.

Best regards,
Sergio


-----Original Message-----
From: fiware-ngsi-bounces at lists.fi-ware.eu<mailto:fiware-ngsi-bounces at lists.fi-ware.eu> [mailto:fiware-ngsi-bounces at lists.fi-ware.eu] On Behalf Of Fermín Galán Márquez
Sent: martedì 17 settembre 2013 13.23
To: fiware-ngsi at lists.fi-ware.eu<mailto:fiware-ngsi at lists.fi-ware.eu>
Subject: [Fiware-ngsi] JSON rendering proposal

Hi,

As previously discussed in this list (see
https://lists.fi-ware.eu/private/fiware-ngsi/2013-September/000490.html), please
find attached TID's proposal for NGSI JSON rendering. We will start this
week implementing JSON support in Orion Context Broker based in it.

Any feedback is highly welcome!

Best regards,

------
Fermín

________________________________

Este mensaje se dirige exclusivamente a su destinatario. Puede consultar nuestra política de envío y recepción de correo electrónico en el enlace situado más abajo.
This message is intended exclusively for its addressee. We only send and receive email on the basis of the terms set out at:
http://www.tid.es/ES/PAGINAS/disclaimer.aspx



________________________________

Este mensaje se dirige exclusivamente a su destinatario. Puede consultar nuestra política de envío y recepción de correo electrónico en el enlace situado más abajo.
This message is intended exclusively for its addressee. We only send and receive email on the basis of the terms set out at:
http://www.tid.es/ES/PAGINAS/disclaimer.aspx
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.fiware.org/private/fiware-ngsi/attachments/20130918/53af1f6a/attachment.html>