Array Fields

Describes the structure of a JSON array field and how to accommodate that structure when defining a JSON (RESTful) service interface operation.

Restriction: This topic applies only when the Enterprise Server feature is enabled.

A JSON array field is defined somewhat differently than a SOAP or a COBOL array field. In SOAP, as in COBOL, arrays consist of an item defined with a nonzero occurs attribute, and such an item appears in the message repeated multiple times. For example, within the context of a SOAP service interface operation, an interface-field group array named group1, with an occurs value of 2, would be represented in a SOAP message as follows:

<group1>
  <field1>someValue1</field1>
  <field2>someValue2</field2>
</ group1>
< group1>
  <field1>someValue3</field1>
  <field2>someValue4</field2>
</ group1>

However, JSON array syntax is different. Unlike SOAP, instead of defining multiple instances of the same item, JSON defines a single array item containing repeated values. In the context of a JSON service interface operation, the JSON equivalent of the interface-field group array shown above in SOAP syntax would be as follows:

"group1":
[
  {
   "field1":"someValue1",
   "field2":"someValue2"
  },
  {
   "field1":"someValue3",
   "field2":"someValue4"
  }
]

Notice that in the JSON syntax, "group1" is not repeated, but rather appears only once, and contains the individual array-element values as repeated JSON objects enclosed in braces ({}).

You can define a JSON service interface operation that produces output that, like the SOAP output in this example, includes the "group1" item repeated for each array element value in the JSON message. Do this using the Interface Mapper to add a parent interface group field around the group1 interface group, and set the Occurs property for that parent field to a nonzero value instead of setting the Occurs property on the group1 field. The resulting JSON message would be:

"extraGroup":
[
  {
    "group1":
    {
      "field1":"someValue1",
      "field2":"someValue2"
    }
  },
  {
    "group1":
    {
      "field1":"someValue3",
      "field2":"someValue4"
    }
  }
]

For non-JSON service interfaces, a nonzero Occurs property indicates that an interface field is an array. However, for JSON service interfaces in particular, when the Occurs property on an interface field is specifically set to 1, it appears in the JSON message as a single object or primitive, without the JSON array syntax.