COBOL to JSON schema mapping

The DFHLS2JS utility program supports mappings between COBOL data structures and JSON schema definitions.

COBOL names are converted to JSON names according to the following rules:

Duplicate names are made unique by the addition of one or more numeric digits.
For example, two instances of year become year and year1.
Hyphens are replaced by underscores. Strings of contiguous hyphens are replaced by contiguous underscores.
For example, current-user--id becomes current_user__id.
Segments of names that are delimited by hyphens and that contain only uppercase characters are converted to lowercase.
For example, CA-REQUEST-ID becomes ca_request_id.
A leading underscore is added to names that start with a numeric character.
For example, 9A-REQUEST-ID becomes _9a_request_id.

CICS® maps COBOL data description elements to schema elements according to the following table. COBOL data description elements that are not shown in the table are not supported by DFHLS2JS. The following restrictions also apply:

Data description items with level numbers of 66 and 77 are not supported. Data description items with a level number of 88 are ignored.
The following clauses on data description entries are not supported:
- REDEFINES
- RENAMES; that is level 66
- DATE FORMAT
The following clauses on data description items are ignored:
- BLANK WHEN ZERO
- JUSTIFIED
- VALUE
The SIGN clause SIGN TRAILING is supported. The SIGN clause SIGN LEADING is supported only when the mapping level specified in DFHLS2JS is 1.2 or higher.
SEPARATE CHARACTER is supported at a mapping level of 1.2 or higher for both SIGN TRAILING and SIGN LEADING clauses.
The following phrases on the USAGE clause are not supported:
- OBJECT REFERENCE
- POINTER
- FUNCTION-POINTER
- PROCEDURE-POINTER
The following phrases on the USAGE clause are supported at a mapping level of 1.2 or higher:
- COMPUTATIONAL-1
- COMPUTATIONAL-2
The only PICTURE characters that are supported for DISPLAY and COMPUTATIONAL-5 data description items are 9, S, and Z.
The PICTURE characters that are supported for PACKED-DECIMAL data description items are 9, S, V, and Z.
The only PICTURE characters that are supported for edited numeric data description items are 9 and Z.
If the MAPPING-LEVEL parameter is set to 1.2 or higher and the CHAR-VARYING parameter is set to NULL, character arrays are mapped to a string and are processed as null-terminated strings.
If the MAPPING-LEVEL parameter is set to 1.2 or higher and the CHAR-VARYING parameter is set to BINARY, character arrays are mapped to a string and are processed as binary data.
If the MAPPING-LEVEL parameter is set to 1.2 or higher and the CHAR-VARYING parameter is set to COLLAPSE, trailing white space is ignored for strings.
The OCCURS DEPENDING ON clause is supported at a mapping level of 4.0 or higher. Complex OCCURS DEPENDING ON is not supported. This means that OCCURS DEPENDING ON is only supported for the last field of a structure.
The OCCURS INDEXED BY clause is supported at any mapping level.

COBOL data description	JSON schema definition
`PIC X(n)` `PIC A(n)` `PIC G(n) DISPLAY-1` `PIC N(n)`	`"type":"string", "maxLength":n`
`PIC S9 DISPLAY` `PIC S99 DISPLAY` `PIC S999 DISPLAY` `PIC S9999 DISPLAY` `PIC S9(n) DISPLAY` `PIC S9(n) COMP` `PIC S9(n) COMP-4` `PIC S9(n) COMP-5` `PIC S9(n) BINARY`	`"type":"integer", "minimum":- (n + 1), "maximum":n` where `n` is the maximum value that can be represented by the pattern of '9' characters.
`PIC 9 DISPLAY` `PIC 99 DISPLAY` `PIC 999 DISPLAY` `PIC 9999 DISPLAY` `PIC 9(n) DISPLAY` `PIC 9(n) COMP` `PIC 9(n) COMP-4` `PIC 9(n) COMP-5` `PIC 9(n) BINARY`	`"type":"integer", "minimum":0, "maximum":n` where `n` is the maximum value that can be represented by the pattern of '9' characters.
`PIC S9(m)V9(n) COMP-3`	`"type":"number", "format":"decimal", "minimum": x, "maximum": y, "multipleOf": z` where: `x` is the minimum value that can be represented by the pattern of '9' characters `y` is the maximum value that can be represented by the pattern of '9' characters `z` is the smallest unit available = 1 / 10ⁿ
`PIC 9(m)V9(n) COMP-3`	`"type":"number", "format":"decimal", "minimum": 0, "maximum": y, "multipleOf": z` where: `y` is the maximum value that can be represented by the pattern of '9' characters `z` is the smallest unit available = 1 / 10ⁿ
`PIC S9(m) COMP-3` Supported at mapping level 3.0 when `DATETIME=PACKED15`	`"type":"string", "format":"date-time"` The format of the time stamp is defined by RFC3339.
`PIC S9(m)V9(n) DISPLAY` Supported at mapping level 1.2 and higher	`"type":"number", "format":"decimal", "minimum": x, "maximum": y, "multipleOf": z` where: `x` is the minimum value that can be represented by the pattern of '9' characters `y` is the maximum value that can be represented by the pattern of '9' characters `z` is the smallest unit available = 1 / 10ⁿ
`COMP-1` Supported at mapping level 1.2 and higher Note: The IBM® Hexadecimal Floating Point (HFP) data representation is not exactly the same as the IEEE-754-1985 representation used for JSON. Some values might not convert exactly from one representation to the other. Some extremely large or small values might not be valid for float data types. Some values might lose precision when converted to or from HFP representation. If precise conversions are important, consider replacing use of COMP-1 data types with fixed precision alternatives.	`"type":"number", "format":"float"`
`COMP-2` Supported at mapping level 1.2 and higher Note: The IBM Hexadecimal Floating Point (HFP) data representation is not exactly the same as the IEEE-754-1985 representation used for JSON. Some values might not convert exactly from one representation to the other. Some extremely large or small values might not be valid for double data types. Some values might lose precision when converted to or from HFP representation. If precise conversions are important, consider replacing use of COMP-2 data types with fixed precision alternatives .	`"type":"number", "format":"double"`
`data description` `OCCURS` `n` `TIMES`	At mapping level 4.0 and lower For primitives: `"type":"array" "maxItems":n "minItems":n "items":{ "type":"object", "properties":{ name:{ data description JSON } } "required":[ name ] }` For structures: `"type":"array" "maxItems":n "minItems":n "items":{ data description JSON }` Where `data description JSON` is the JSON schema representation of the COBOL `data description` and `name` is the name of the COBOL `data description`. At mapping level 4.1 and higher TRUNCATE-NULL-ARRAYS=DISABLED Both structured and primitive arrays map as follows. `"type":"array" "maxItems":n "minItems":n "items":{ data description JSON }` TRUNCATE-NULL-ARRAYS=ENABLED Primitive arrays map as above, and structured arrays as follows. `"type":"array" "maxItems":n "minItems":0 "items":{ data description JSON }`
`data description` `OCCURS` `n` `TO` `m` `TIMES DEPENDING ON` `t` Supported at mapping level 4.0	`"field-name":{ "type":"array", "maxItems":m "minItems":n "items":{ ... } }` The content of the array item depends on the datatype used.
`PIC X OCCURS` `n` `TIMES` `PIC A OCCURS` `n` `TIMES` `PIC G DISPLAY-1 OCCURS` `n` `TIMES` `PIC N OCCURS` `n` `TIMES`	When CHAR-OCCURS`=STRING`: `"field-name":{ "type":"string", "maxLength":n }` This is a string. When CHAR-OCCURS`=ARRAY`: At mapping level 4.0 and lower `"field-name":{ "maxItems":m, "minItems":n, "items":{ "type":"object", "properties":{ "field-name":{ "type":"string", "maxLength":1 } }, "required":[ "field-name" ] } }` This is an array of single characters. At mapping level 4.1 and higher TRUNCATE-NULL-ARRAYS=DISABLED Both structured and primitive arrays map as follows. `"type":"array" "maxItems":n "minItems":n "items":{ data description JSON }` TRUNCATE-NULL-ARRAYS=ENABLED Primitive arrays map as above, and structured arrays as follows. `"type":"array" "maxItems":n "minItems":0 "items":{ data description JSON }`
`PIC X OCCURS` `n` `TO` `m` `TIMES DEPENDING ON` `t` `PIC A OCCURS` `n` `TO` `m` `TIMES DEPENDING ON` `t` `PIC G DISPLAY-1 OCCURS` `n` `TO` `m` `TIMES DEPENDING ON` `t` `PIC N OCCURS` `n` `TO` `m` `TIMES DEPENDING ON` `t`	When CHAR-OCCURS`=STRING`: `"field-name":{ "type":"string", "maxLength":m "minLength":n }`
`PIC N(` `n) USAGE NATIONAL` When CHAR-USAGE`=NATIONAL`: `PIC N(n)`	At mapping level 4.0 and higher: `"type":"string", "maxLength":n` At run time, CICS populates the application data structure field with UTF-16 data.