JSON schema to COBOL mapping

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

The CICS® assistants generate unique, valid field names for COBOL variables from the schema element names by using the following rules:
  1. COBOL reserved words are prefixed with 'X'.

    For example, DISPLAY becomes XDISPLAY.

  2. Characters other than A-Z, a-z, 0-9, or hyphen are replaced with 'X'.

    For example, monthly_total becomes monthlyXtotal.

  3. If the last character is a hyphen, it is replaced with 'X'.

    For example, ca-request- becomes ca-requestX.

  4. Duplicate names in the same scope are made unique by the addition of one or two numeric digits to the second and subsequent instances of the name.

    For example, three instances of year become year, year1, and year2.

    Should the above behavior be undesirable the user can specify MAPPING-OVERRIDES=NO-ARRAY-NAME-INDEXING as input to the utility which disables the addition of one or two numeric digits to the second and subsequent instances of the name.

  5. A JSON schema specifies that a variable has varying cardinality if it has a "type" value of "array", and the keywords "minItems" and "maxItems" are omitted or have different values. If the schema specifies that the variable has varying cardinality, then field names are created with suffixes of "_cont" and "_num".

    For more information, see Variable arrays of elements in DFHJS2LS.

  6. A JSON schema specifies that a variable is optional if it does not appear in the "required" keyword array that is associated with the enclosing JSON schema "object" type. For optional fields, an additional field is generated with a suffix of _num added to the element name. At run time this is zero to indicate the value was absent from the JSON data, and non-zero if the value was present in the JSON data.
  7. Field names are limited to 28 characters. If a generated name, including the prefix and suffix, exceeds this length, the element name is truncated.
DFHJS2LS map schema types to COBOL data description elements by using the specified mapping level according to the following table. Note the following points:
  • If the MAPPING-LEVEL parameter is set to 1.2 or higher and the CHAR-VARYING parameter is set to NULL, variable-length character data is mapped to null-terminated strings and an extra character is allocated for the null-terminator.
  • If the MAPPING-LEVEL parameter is set to 1.2 or higher and the CHAR-VARYING parameter is set to YES, variable-length character data is mapped to two related elements: a length field and a data field. For example: 
    "textString": {
   "type":"string",
   "maxLength":10000,
   "minLength":1
}
    maps to:
    15 textString-length    PIC S9999 COMP-5 SYNC
15 textString           PIC X(10000)
JSON Schema keyword COBOL data description
All of:
"type":"null"
"type": []
"enum": []
"allOf"
"anyOf"
"noneOf"
"not"

Not supported

 
"$schema":"http://json-schema.org/draft-04/schema#"

This keyword is ignored, but it is assumed to be compatible with the draft 04 JSON Schema specification.

 
"title": "same text"
"description": "more text"

These keywords are ignored.

 
"format": "<predefined values>"

The "format" keyword is used to modify either the generated structure or runtime value. See the information later in this table for the supported use of "format".

 
"type": "array",
"items": {<JSON Sub-schema>},
"additionalItems": false, 
"maxItems": m, 
"minItems": n

The only form of JSON array currently supported is a repeated number of same type values. The <JSON Sub-schema> must define a supported "type", but that "type" cannot be "array". This is a restriction on the language structure generated.

"additionalItems" is assumed to be false, and no other value is supported.

If both "minItems" and "maxItems" are present, and they are equal, then the array is treated as fixed cardinality, otherwise it is treated as varying cardinality. See Variable arrays of elements in DFHJS2LS.

 
"type": "array",
"uniqueItems": true

"uniqueItems" is not supported with JSON arrays.

 
"type": "object",
"additionalProperties": false,
"properties": { [ "<element name>": {<JSON Sub-schema>} [,] ]* } 
"required": [ [ "<element name>" [,] ]* ]

The only form of JSON object that is currently supported is a fixed set of named elements.

This generates a structure (or sub-structure) that uses the element names.

"additionalProperties" is assumed to be false, and no other value is supported.

Any element in the "properties" object is considered"optional" if it is not in the "required" array or if no "required" array exists. An "optional" element is given a variable ordinality of zero to X; where X is either 1 or the maximum number of items in the array, where that item is defined as an array. See Variable arrays of elements in DFHJS2LS.

 
"type": "object",
"maxProperties": m,
"minProperties": n,
"patternProperties": {},
"dependencies":

None of these keywords are supported with JSON objects.

 
"type":"string"
"maxLength":m
"pattern": "regular expression>",
"minLength": l

PIC X(z)

where the value of z is based on m, but dependent on the settings of the CHAR-VARYING parameter.

m is based on the "maxLength" keyword and treated as fixed length string.

"pattern" and "minLength" restrictions are passed through to the language structure only as a comment.

 
"type":"string"
"maxLength":m

When CCSID=1200 at mapping level 4.0 and higher:

PIC N(z) USAGE NATIONAL

where the value of z is based on m, but dependent on the settings of the CHAR-VARYING parameter.

m is based on the "maxLength" keyword and treated as fixed length string.

 
"*name*":{ 
   "type":"string",
   "format":"date-time"
}

PIC S9(15) COMP-3

All supported when DATETIME=PACKED15

Note that "maxLength" and "minLength" are not supported for this format

 
"*name*":{ 
   "type":"string",
   "format":"uri"
}

PIC X(m)

where m is based on the "maxLength" keyword and treated as fixed length string.

When CCSID=1200 at mapping level 4.0 and higher:

PIC N(m) USAGE NATIONAL

where m is based on the "maxLength" keyword and treated as fixed length string. 

"*name*":{ 
   "type":"string",
   "format":"base64Binary"
}

PIC X(m)

where m is based on the "maxLength" keyword

 
"*name*":{ 
   "type":"string",
   "format":"hexBinary"
}

PIC X(m)

where m is based on the "maxLength" keyword

 
"*name*":{ 
   "type":"string",
   "format":"<predefined>" 
}

PIC X(m)

where m is based on the "maxLength" keyword and treated as fixed length string, and where <predefined> is one of: email, hostname, ipv4, or ipv6. A relevant "pattern" is used and passed to the comment.

When CCSID=1200 at mapping level 4.0 and higher:

PIC N(m) USAGE NATIONAL

where m is based on the "maxLength" keyword and treated as fixed length string, and where <predefined> is one of: email, hostname, ipv4, or ipv6. A relevant "pattern" is used and passed to the comment.

 
"type":"boolean"

PIC X DISPLAY

The value x'00' implies false, x'01' implies true.

 
"type": "integer",
"maxExclusive": true,
"minExclusive": true,
"multipleOf": n

"maxExclusive" and "minExclusive" restrictions are passed to the language structure only as a comment.

"multipleOf" is ignored.

 
"type"="integer",
minimum=0,
maximum=255

Mapping level 3.0 and below:

PIC X DISPLAY

Mapping level 4.0 and above (or when the INTEGER-AS-PIC9 parameter has been specified, regardless of the mapping level) :

PIC 9(z) COMP-5 SYNC

or

PIC 9(z) DISPLAY

where 10(z-1) < m <= 10z

 
"type":"integer",
minimum:-128,
maximum:127

Mapping level 3.0 and below:

PIC X DISPLAY

Mapping level 4.0 and above (or when the INTEGER-AS-PIC9 parameter has been specified, regardless of the mapping level) :

PIC S9(z) COMP-5 SYNC

or

PIC S9(z) DISPLAY

where 10(z-1) < m <= 10z

 
"type":"integer",
minimum:0,
maximum;m

PIC 9(z) COMP-5 SYNC

or

PIC 9(z) DISPLAY

where 10(z-1) < m <= 10z

 
"type":"integer",
minimum:-m,
maximum:m-1

PIC S9(z) COMP-5 SYNC

or

PIC S9(z) DISPLAY

where 10(z-1) < m <= 10z

 
"type": "number",
"maximum": m,
"minimum": n,
"maxExclusive": true,
"minExclusive": true,
"multipleOf": n

"maximum", "minimum", "maxExclusive" and "minExclusive" restrictions are passed to the language structure only as a comment.

"multipleOf" is ignored.

 
"type":"number"
"format":"decimal"

PIC 9(p)V9(n) COMP-3

where p and n are default values.

 
"type":"number"
"format":"float"
Mapping level 1.1 and lower:
  • PIC X(32)
Mapping level 1.2 and higher:
  • COMP-1
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":"double"
Mapping level 1.1 and lower:
  • PIC X(32)
Mapping level 1.2 and higher:
  • COMP-2
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

.
Note: CICS cannot transform integer values greater than the maximum value for a signed long (2^63 - 1) unless they are enclosed within quotes.
Note: Minimum and maximum values specified in the schema for numeric types are used only to map to a COBOL datatype. Data is not validated against these values at run time.
Some of the schema types that are shown in the table map to a COBOL format of COMP-5 SYNC or of DISPLAY, depending on the values (if any) that are specified in the minimum and maximum keywords:
  • For signed types (short, int, and long), DISPLAY is used when the following are specified:
    "maximum":a
"minimum":-a
    where a is a string of '9's.
  • For unsigned types (unsignedShort, unsignedInt, and unsignedLong), DISPLAY is used when the following are specified:
    "maximum":a
"minimum":0
    where a is a string of '9's.
When any other value is specified, or no value is specified, COMP-5 SYNC is used.