Using JSON in IRIS
Tags: json, beginners, tutorial, programming
Published: 2023-10-22 16:46:56

Saw the other day an article with the usage of the `%ZEN` package when working with JSON and decided to write an article describing a more modern approach. At some recent point, there was a big switch from using `%ZEN.Auxiliary.*` to dedicated JSON classes. This allowed to work with JSONs more organically.

Thus, at this point there are basically 3 main classes to work with JSON:

  * [`%Library.DynamicObject`](https://docs.intersystems.com/irislatest/csp/documatic/%25CSP.Documatic.cls?LIBRARY=%25SYS&CLASSNAME=%25Library.DynamicObject) - provides a simple and efficient way to encapsulate and work with standard **JSON documents**. Also, there is a possibility instead of writing the usual code for creating an instance of a class like

<pre class="codeblock-container" idlang="0" lang="ObjectScript" tabsize="4"><code class="language-cls hljs cos"><span class="hljs-keyword">set</span> obj = <span class="hljs-keyword">##class</span>(<span class="hljs-built_in">%Library.DynamicObject</span>).<span class="hljs-built_in">%New</span>()</code></pre>

<p style="margin-left: 40px;">
  it is possible to use the following syntax
</p>

<pre class="codeblock-container" idlang="0" lang="ObjectScript" tabsize="4"><code class="language-cls hljs cos"><span class="hljs-keyword">set</span> obj = {}</code></pre>

  * <div>
      <a href="https://docs.intersystems.com/irislatest/csp/documatic/%25CSP.Documatic.cls?LIBRARY=%25SYS&CLASSNAME=%25Library.DynamicArray"><code>%Library.DynamicArray</code></a> - provides a simple yet efficient way to encapsulate and work with standard <strong>JSON  arrays</strong>. With arrays you can use the same approach as with objects, meaning that yu can either create an instance of the class
    </div>

<div>
  <pre class="codeblock-container" idlang="0" lang="ObjectScript" tabsize="4"><code class="language-cls hljs cos"><span class="hljs-keyword">set</span> array = <span class="hljs-keyword">##class</span>(<span class="hljs-built_in">%DynamicArray</span>).<span class="hljs-built_in">%New</span>()</code></pre>
  
  <p style="margin-left: 40px;">
    or you can do it by using brackets []
  </p>
  
  <pre class="codeblock-container" idlang="0" lang="ObjectScript" tabsize="4"><code class="language-cls hljs cos"><span class="hljs-keyword">set</span> array = []</code></pre>
  
  <ul>
    <li>
      <a href="https://docs.intersystems.com/irisforhealthlatest/csp/documatic/%25CSP.Documatic.cls?LIBRARY=%25SYS&CLASSNAME=%25JSON.Adaptor"><code>%JSON.Adaptor</code></a> is a means for mapping ObjectScript objects (registered, serial or persistent) to JSON text or dynamic entities.
    </li>
  </ul>
</div>

<div>
Let's look at them a bit closer. 
  
<p>
Let's say I'm working with a RESTful client and I need to send some info generated on the go that's not a database object but some parts of it. I can just create a new instance of %DynamicObject and just set it's properties. In a way, it's similar to what was done before with <code>%ZEN.ProxyObject</code>. And of course, I can have built-in objects and built-in arrays as properties (or JSON fields):
</p>
  
<pre class="codeblock-container" idlang="0" lang="ObjectScript" tabsize="4"><code class="language-cls hljs cos"><span class="hljs-keyword">Set</span> result={}
<span class="hljs-keyword">set</span> result.Group = <span class="hljs-string">"TB-41"</span>
<span class="hljs-keyword">set</span> result.Name = <span class="hljs-string">"Iryna Mykhailova"</span>
<span class="hljs-keyword">set</span> result.Questions = [<span class="hljs-string">"What is JSON?"</span>, <span class="hljs-string">"Create instance of class Test and set all it's properties."</span>]
</code></pre>
  
<p>
As a result of these lines of code, we will get the following JSON string:
</p>
  
<p>
<basefont name="Courier New"> <basefont name="Courier New"> <code><font color="#000000">{"Group":"TB-41","Name":"Iryna Mykhailova","Questions":["What is JSON?","Create instance of class Test and set all it's properties."]}</font></code>&lt;/p> &lt;/div> 
    
<p>
Apart from just setting the properties or simply writing the JSON string inside the brackets
</p>
    
<pre class="codeblock-container" idlang="0" lang="ObjectScript" tabsize="4"><code class="language-cls hljs cos"><span class="hljs-keyword">Set</span> result={<span class="hljs-string">"Group"</span>:<span class="hljs-string">"TB-41"</span>, <span class="hljs-string">"Name"</span>:<span class="hljs-string">"Iryna Mykhailova"</span>, <span class="hljs-string">"Questions"</span>:[<span class="hljs-string">"What is JSON?"</span>, <span class="hljs-string">"Create instance of class Test and set all it's properties."</span>]}
 </code></pre>
    
<p>
there is a possibility to use methods to set ( <a href="https://docs.intersystems.com/irislatest/csp/documatic/%25CSP.Documatic.cls?LIBRARY=%25SYS&CLASSNAME=%25Library.DynamicObject#%25Set" title="%Set()">%Set()</a> ), get ( <a href="https://docs.intersystems.com/irislatest/csp/documatic/%25CSP.Documatic.cls?LIBRARY=%25SYS&CLASSNAME=%25Library.DynamicObject#%25Get" title="%Get()">%Get()</a> ) and delete ( <a href="https://docs.intersystems.com/irislatest/csp/documatic/%25CSP.Documatic.cls?LIBRARY=%25SYS&CLASSNAME=%25Library.DynamicObject#%25Remove" title="%Remove()">%Remove()</a> ) the values of the properties. The same is true for the arrays.
</p>
    
<p>
And the last basic class <code>%JSON.Adaptor</code> is used as a superclass to enable JSON capabilities to the existing classes. So if there is a<font color="#000080"> </font>class data from which is used in RESTful service, it's easy to get a JSON representation by using the method<code> <font color="#0000ff">%ToJSON</font><font color="#000000">()</font></code> <span> </span>and the opposite action - <basefont name="Courier New"> <code><font color="#0000ff">%FromJSON()</font></code>. There is also a possibility to serialize and deserialize JSON enabled classes to strings and streams if there's a need to do it.&lt;/p> 
      
<p>
        This concludes this very brief tutorial about JSON classes and their usage. Hope it helps figure out the best way to do things.
</p></body></html>