Appendix C - JSON PARSE Matching Algorithm

A name-matching algorithm controls the parsing operation, where the COBOL data structure must match the JSON text string exactly, except that omissions of complete elementary or group levels are tolerated in the JSON text.

The name matching between JSON names and COBOL data names is case insensitive. That is, for both the JSON name and the COBOL data name, each lowercase single-byte alphabetic letter (a-z) is considered to be equivalent to its corresponding single-byte uppercase alphabetic letter (A-Z). However, when the NAME phrase is specified, after the NAME phrase literal has been converted by the Compiler to Unicode UTF-8, the literal must match the JSON name exactly in a case sensitive match.

The JSON PARSE statement terminates without an exception, and with special registers JSON-STATUS and JSON-CODE containing zero if, for each elementary data item subordinate to identifier-2, there is exactly one matching appropriately qualified JSON name/value pair, regardless of the order in the JSON text.

There are a number of other conditions during execution that might result in a nonzero JSON-STATUS value, or an exception and a nonzero JSON-CODE value. For example, if any combination of JSON value and COBOL data type is invalid, the statement terminates with an exception condition.

If there are JSON name/value pairs that do not match any data item names in the COBOL group/elementary item, they are allowed, but result in setting the special register JSON-STATUS to a condition code, and can result in one or more runtime messages, under control of the WITH DETAIL phrase.

If there are no matching COBOL data items, the statement terminates with an exception condition, and the COBOL group/elementary item is unmodified.

The following examples show what is considered a match and what is considered a mismatch when the name-matching algorithm is executed.

The special values true and false are not supported, and result in an exception condition if present as the value of a JSON name that matches a data item in the receiver.

The following two examples are considered an exact match:

The COBOL data definition:

01. Grp-1.
    03 a.
       05 grk pic x(15).
       05 8_ pic 9.
       05 A-a pic x(5).

The JSON text:

{"grp-1": {"A": {"GrK": "ERK*VML", "8_": 8, "a-A": "VOID"}}}

If you were to use the JSON GENERATE statement, specifying the COBOL data definition, it would produce the following JSON text, which is also considered an exact match for the JSON text above:

{"Grp-1": {"a": {"grk": "ERK*VML", "8_": 8, "A-a": "Void"}}}

The COBOL data definition and JSON text can also match even if the JSON text omits certain elements of the structure, as long as the level matches. For example, the following examples are considered a match even though the JSON text has omitted the elementary item 8_ and group item AddTxt - a JSON PARSE operation would not modify those two items in the structure, and would generate a JSON-STATUS of 1 (a run-time message may also be produced if the WITH DETAIL phrase is specified):

The COBOL data definition:

01. Grp-1.
    03 a.
       05 grk pic x(15).
       05 8_ pic 9.
       05 A-a pic x(5). 
    03 AddTxt.
       05 dt pic 9(6).
       05 not pic x(50).

The JSON text:

{"grp-1": {"A": {"GrK": "ERK*VML", "a-A": "VOID"}}}

Conversely, additional items in the JSON text are tolerated, but generate non-zero JSON-STATUS codes and run-time messages. The following examples are compatible, and a JSON PARSE operation would completely populate Grp-1, but leave the JSON name/value pair "X-X": "Y" untouched. The statement would terminate without an exception code, but the special register JSON-STATUS is set to a reason code of 2:

01. Grp-1.
    03 a.
       05 grk pic x(15).
       05 8_ pic 9.
       05 A-a pic x(5).

The JSON text:

{"grp-1": {"A": {"GrK": "ERK*VML", "8_": 8, "X-X": "Y", "a-A": "VOID"}}}

These two examples are also considered fully compatible, even though the order of the items is mismatched:

01. Grp-1.
    03 a.
       05 grk pic x(15).
       05 8_ pic 9.
       05 A-a pic x(5).

The JSON text:

{"grp-1": {"A": {"a-A": "VOID", "GrK": "ERK*VML", "8_": 8}}}

Whereas, these two examples are not considered compatible, because the JSON text is missing a matching name equivalent to group item a. This operation would result in an exception condition, because no data item would be changed:

01. Grp-1.
    03 a.
       05 grk pic x(15).
       05 8_ pic 9.
       05 A-a pic x(5).

The JSON text:

{"grp-1": {"a-A": "VOID", "GrK": "ERK*VML", "8_": 8}}

These two examples are also not considered compatible, because the JSON text values and their COBOL data definition values are incompatible. This operation would result in an exception condition:

01. Grp-1.
    03 a.
       05 grk pic x(15).
       05 8_ pic 9.
       05 A-a pic x(5).

The JSON text:

{"grp-1": {"A": {"GrK": 33, "8_": "eight", "a-A": 657}}}

When JSON names contain characters that are not permitted to be used in COBOL data names, use the NAME phrase to supply a compliant alias for use as a COBOL data name. For example, the following JSON name is not permitted as a COBOL data name:

{"x>z":250}

Therefore, by specifying the NAME phrase in the JSON PARSE statement, you can continue to handle its JSON value with a valid COBOL name (my-sub):

JSON PARSE j-text into j-data
           NAME OF my-sub is "x>z"
END-JSON.

When using the NAME phrase, you must specify the JSON name exactly how it appears in the JSON string. Unlike the other matching algorithms, it is not case insensitive. Also, the NAME phrase must not result in an ambiguous name specification.