Difference between revisions of "JSON"

From DataFlex Wiki
Jump to navigationJump to search
m (Add link to Starzen library)
m (Change)
 
(6 intermediate revisions by the same user not shown)
Line 2: Line 2:
  
 
It is a format that is often used in RESTful webservices and as such it is important to be able to use it from within DataFlex.
 
It is a format that is often used in RESTful webservices and as such it is important to be able to use it from within DataFlex.
 +
 +
==JSON Format==
 +
 +
JSON is a very simple format, derived from [[JavaScript]]'s [https://www.dyn-web.com/tutorials/object-literal/ Object Literal notation], consisting of a series of [https://en.wikipedia.org/wiki/Attribute%E2%80%93value_pair name/value pairs] with arbitrarily deep nesting.
 +
 +
The names are quoted with <u>double-quote</u> characters: <font color="blue">"''name''"</font>.
 +
 +
How values are written depends on the data-type (see below).
 +
 +
Names are separated from values by colons: <font color="blue">"name":''value''</font>.
 +
 +
The pairs are separated from each other with commas: <font color="blue">"name1":''value1'', "name2":''value2'', "name3":''value3''...</font> (the last pair in such a series should <u>not</u> be followed by a comma however).
 +
 +
Special characters may be "escaped" in string values (or indeed names) with a backslash: <font color="blue">'''\'''</font>
 +
*'''\\''' represents '''<font color="blue">\'''</font> (backslash)
 +
*'''\/''' represents '''<font color="blue">/'''</font> (forward slash)
 +
*'''\"''' represents '''<font color="blue">"'''</font> (double-quote)
 +
*'''\b''' represents backspace (ASCII 8)
 +
*'''\f''' represents formfeed (ASCII 12)
 +
*'''\n''' represents newline (ASCII 10)
 +
*'''\r''' represents carriage-return (ASCII 13)
 +
*'''\t''' represents tab (ASCII 9)
 +
 +
[https://en.wikipedia.org/wiki/Unicode Unicode] characters (up to FFFF: 65,535, which covers the [https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane basic multilingual plane]) may be represented by '''\u''HHHH''''', where "'''''H'''''" is a hexadecimal-digit (0-F).
 +
 +
==JSON Data Types==
 +
 +
JSON values can be one of six data-types - four "primitive" and two "compound":
 +
 +
====Primitive:====
 +
*'''Strings''', which, like names, must be quoted with <u>double-quote</u> characters: <font color="blue">"value"</font>
 +
*'''Numbers''', which can be simple integers, or decimal values, or exponentiated (using either "e" or "E") and may be negative:
 +
**<font color="blue">6</font>
 +
**<font color="blue">13429064</font>
 +
**<font color="blue">-9645</font>
 +
**<font color="blue">23.657685</font>
 +
**<font color="blue">-29.41</font>
 +
**<font color="blue">1.23456e7</font> (indicating 12,345,600)
 +
**<font color="blue">-456.789E5</font> (indicating -45,678,900)
 +
**<font color="blue">6.281e-6</font> (indicating 0.000006281)
 +
*'''Boolean''', which can have the value of either <font color="blue">true</font> or <font color="blue">false</font> (unquoted)
 +
*'''Null''', which is simply represented by <font color="blue">null</font> (unquoted)
 +
 +
====Compound:====
 +
*'''Objects''', which are enclosed in '''{''' ... '''}''' characters and generally contain additional name/value pairs: <font color="blue">{"surname":"Peat", "forename":"Mike", "age":21, "is male":true, "salary":null}</font>
 +
*'''Arrays''', which are enclosed in '''[''' ... ''']''' characters and are made up of values separated by commas: <font color="blue">[5, "Mike", false, 14.70912, null, -5.34108e9]</font>
 +
 +
==Prettifying==
 +
Whitespace is irrelevant <u>outside</u> of double-quotes (although both names and string values may contain whitespace).  Because of this, JSON may be formatted for easier human-readability (''prettified'') with spaces and line breaks, so:
 +
 +
<font color="blue">{"first name":"Mike","last name":"Peat","age":21,"is male":true,"salary":null,"address":{"house":22,"street":"Acacia Avenue","town":"Dullsville","county":"Midhamptonshire"},"test scores":[56,87,19,11,70,64]}</font>.
 +
 +
Is the same, from a machine standpoint, as the rather more human-readable:
 +
 +
<font color="blue">{
 +
    "first name": "Mike",
 +
    "last name": "Peat",
 +
    "age": 21,
 +
    "is male": true,
 +
    "salary": null,
 +
    "address": {
 +
        "house": 22,
 +
        "street": "Acacia Avenue",
 +
        "town": "Dullsville",
 +
        "county": "Midhamptonshire"
 +
    },
 +
    "test scores": [56, 87, 19, 11, 70, 64]
 +
}</font>
 +
 +
Which is only slightly less compact "on the wire" (by around 25 bytes).
 +
 +
==JSON in DataFlex==
  
 
Before DataFlex 19.0 you had to resort to external libraries in order to use JSON, see for example [http://support.dataaccess.com/Forums/showthread.php?54830-JSON-Parsing-the-beginnings-of-an-alternative-approach JSON Parsing ... the beginnings of an alternative approach]
 
Before DataFlex 19.0 you had to resort to external libraries in order to use JSON, see for example [http://support.dataaccess.com/Forums/showthread.php?54830-JSON-Parsing-the-beginnings-of-an-alternative-approach JSON Parsing ... the beginnings of an alternative approach]
Line 8: Line 80:
 
This functionality is offered via the [https://docs.dataaccess.com/dataflexhelp/mergedProjects/VDFClassRef/cJsonObject.htm cJsonObject]
 
This functionality is offered via the [https://docs.dataaccess.com/dataflexhelp/mergedProjects/VDFClassRef/cJsonObject.htm cJsonObject]
  
One of the great features in that class is that you can move all your data from JSON into a struct with just one command and vice versa.
+
One of the great features in that class is that you can move all your data from JSON into a struct with just one function or procedure call, and vice versa. In order to transfer your data from JSON to a struct you would use the [https://docs.dataaccess.com/dataflexhelp/mergedProjects/VDFClassRef/cJsonObject-Function-JsonToDataType.htm JsonToDataType] function and if you have to convert data from a struct to JSON then you can use the [https://docs.dataaccess.com/dataflexhelp/mergedProjects/VDFClassRef/cJsonObject-Procedure-DataTypeToJson.htm DataTypeToJson] procedure.
In order to transfer your data from JSON to a struct you would use the [https://docs.dataaccess.com/dataflexhelp/mergedProjects/VDFClassRef/cJsonObject-Function-JsonToDataType.htm JsonToDataType] function and if you have to convert data from a struct to JSON then you can use [https://docs.dataaccess.com/dataflexhelp/mergedProjects/VDFClassRef/cJsonObject-Procedure-DataTypeToJson.htm DataTypeToJson].
 
 
 
When migrating data from JSON to a struct sometimes a member might be missing from the JSON data. For example because the element you are looking for is empty. In that case the runtime will trigger a runtime error. You can disable that by setting the [https://docs.dataaccess.com/dataflexhelp/mergedProjects/VDFClassRef/cJsonObject-Property-pbRequireAllMembers.htm pbRequireAllMembers] property of the DataFlex Json object to false.
 
  
If you have a struct that uses reserved words then since DataFlex 19.1 you can now use a non reserved name and assign a different name for the conversion via meta-data tags. This is sometimes referred to as the [https://docs.dataaccess.com/dataflexhelp/mergedProjects/Tools/Name_Meta-Data_Tag.htm altName member]
+
When migrating data from JSON to a struct sometimes a member might be missing from the JSON data. For example because the element you are looking for is empty, so it has simply been omitted from the JSON. In that case the runtime will trigger a runtime error. You can disable that by setting the [https://docs.dataaccess.com/dataflexhelp/mergedProjects/VDFClassRef/cJsonObject-Property-pbRequireAllMembers.htm pbRequireAllMembers] property of the DataFlex Json object to false.
  
 +
If you need to deal with JSON which uses DataFlex reserved words in its member names (or other invalid values, such as those containing spaces in the example above: e.g. "first name") then, since DataFlex 19.1, you can now use a valid name in your struct and assign a different name for the conversion via meta-data tags. This is sometimes referred to as the [https://docs.dataaccess.com/dataflexhelp/mergedProjects/Tools/Name_Meta-Data_Tag.htm altName member]
  
 
== External references ==
 
== External references ==

Latest revision as of 11:52, 14 August 2019

JSON stands for JavaScript Object Notation and is a format used for data exchange that has some similarities to XML.

It is a format that is often used in RESTful webservices and as such it is important to be able to use it from within DataFlex.

JSON Format

JSON is a very simple format, derived from JavaScript's Object Literal notation, consisting of a series of name/value pairs with arbitrarily deep nesting.

The names are quoted with double-quote characters: "name".

How values are written depends on the data-type (see below).

Names are separated from values by colons: "name":value.

The pairs are separated from each other with commas: "name1":value1, "name2":value2, "name3":value3... (the last pair in such a series should not be followed by a comma however).

Special characters may be "escaped" in string values (or indeed names) with a backslash: \

  • \\ represents \ (backslash)
  • \/ represents / (forward slash)
  • \" represents " (double-quote)
  • \b represents backspace (ASCII 8)
  • \f represents formfeed (ASCII 12)
  • \n represents newline (ASCII 10)
  • \r represents carriage-return (ASCII 13)
  • \t represents tab (ASCII 9)

Unicode characters (up to FFFF: 65,535, which covers the basic multilingual plane) may be represented by \uHHHH, where "H" is a hexadecimal-digit (0-F).

JSON Data Types

JSON values can be one of six data-types - four "primitive" and two "compound":

Primitive:

  • Strings, which, like names, must be quoted with double-quote characters: "value"
  • Numbers, which can be simple integers, or decimal values, or exponentiated (using either "e" or "E") and may be negative:
    • 6
    • 13429064
    • -9645
    • 23.657685
    • -29.41
    • 1.23456e7 (indicating 12,345,600)
    • -456.789E5 (indicating -45,678,900)
    • 6.281e-6 (indicating 0.000006281)
  • Boolean, which can have the value of either true or false (unquoted)
  • Null, which is simply represented by null (unquoted)

Compound:

  • Objects, which are enclosed in { ... } characters and generally contain additional name/value pairs: {"surname":"Peat", "forename":"Mike", "age":21, "is male":true, "salary":null}
  • Arrays, which are enclosed in [ ... ] characters and are made up of values separated by commas: [5, "Mike", false, 14.70912, null, -5.34108e9]

Prettifying

Whitespace is irrelevant outside of double-quotes (although both names and string values may contain whitespace). Because of this, JSON may be formatted for easier human-readability (prettified) with spaces and line breaks, so:

{"first name":"Mike","last name":"Peat","age":21,"is male":true,"salary":null,"address":{"house":22,"street":"Acacia Avenue","town":"Dullsville","county":"Midhamptonshire"},"test scores":[56,87,19,11,70,64]}.

Is the same, from a machine standpoint, as the rather more human-readable:

{
   "first name": "Mike",
   "last name": "Peat",
   "age": 21,
   "is male": true,
   "salary": null,
   "address": {
       "house": 22,
       "street": "Acacia Avenue",
       "town": "Dullsville",
       "county": "Midhamptonshire"
   },
   "test scores": [56, 87, 19, 11, 70, 64]
}

Which is only slightly less compact "on the wire" (by around 25 bytes).

JSON in DataFlex

Before DataFlex 19.0 you had to resort to external libraries in order to use JSON, see for example JSON Parsing ... the beginnings of an alternative approach

As of DataFlex 19.0 we have native support for JSON objects and can access and directly work with these data structures. This functionality is offered via the cJsonObject

One of the great features in that class is that you can move all your data from JSON into a struct with just one function or procedure call, and vice versa. In order to transfer your data from JSON to a struct you would use the JsonToDataType function and if you have to convert data from a struct to JSON then you can use the DataTypeToJson procedure.

When migrating data from JSON to a struct sometimes a member might be missing from the JSON data. For example because the element you are looking for is empty, so it has simply been omitted from the JSON. In that case the runtime will trigger a runtime error. You can disable that by setting the pbRequireAllMembers property of the DataFlex Json object to false.

If you need to deal with JSON which uses DataFlex reserved words in its member names (or other invalid values, such as those containing spaces in the example above: e.g. "first name") then, since DataFlex 19.1, you can now use a valid name in your struct and assign a different name for the conversion via meta-data tags. This is sometimes referred to as the altName member

External references