JSON schema to COBOL mapping
The DFHJS2LS utility program supports mappings between JSON schema and COBOL data structures.
- COBOL reserved words are prefixed with '
X
'.For example,
DISPLAY
becomesXDISPLAY
. - Characters other than A-Z, a-z, 0-9, or hyphen are replaced with '
X
'.For example,
monthly_total
becomesmonthlyXtotal
. - If the last character is a hyphen, it is replaced with '
X
'.For example,
ca-request-
becomesca-requestX
. - 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
becomeyear
,year1
, andyear2
.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. - 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.
- 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. - Field names are limited to 28 characters. If a generated name, including the prefix and suffix, exceeds this length, the element name is truncated.
- 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:
maps to:"textString": { "type":"string", "maxLength":10000, "minLength":1 }
15 textString-length PIC S9999 COMP-5 SYNC 15 textString PIC X(10000)
JSON Schema keyword | COBOL data description |
---|---|
All of:
|
Not supported |
|
This keyword is ignored, but it is assumed to be compatible with the draft 04 JSON Schema specification. |
|
These keywords are ignored. |
|
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". |
|
Multidimensional arrays are supported from mapping level 4.3 or higher, and mixed type arrays are not supported.
If both |
|
|
|
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.
Any element in the |
|
The object is mapped as in the previous example, with additional fields
that support additional properties. The additionalProperties property is assumed to
be false if not set in the ADDITIONAL-PROPERTIES-DEFAULT parameter. If
enabled, space is allocated up to the value specified in the
ADDITIONAL-PROPERTIES-MAX parameter. The number of characters in each space is
set by the ADDITIONAL-PROPERTIES-SIZE parameter. Each individual property is
mapped to a Note: There are
several ways to configure JSON support in CICS, including use of z/OS Connect for CICS. If you are
using the older CICS Java Pipeline technology,
Additional Properties are only
supported if the com.ibm.cics.json.enableAxis2Handlers JVM system property is not
set to true. |
|
None of these keywords are supported with JSON objects. |
|
where the value of z is based on m , but dependent on the settings of the CHAR-VARYING parameter.
m is based on the
|
|
When CCSID=1200 at mapping level 4.0 and higher:
where the value of z is based on m , but dependent on the settings of the CHAR-VARYING parameter.
m is based on the |
|
PIC S9(15) COMP-3 All supported when DATETIME=PACKED15 Note that |
|
where m is based on the When CCSID=1200 at mapping level 4.0 and higher:
where m is based on the |
|
where m is based on the |
|
where m is based on the |
|
where m is based on the When CCSID=1200 at mapping level 4.0 and higher:
where m is based on the |
|
The value |
|
|
|
Mapping level 3.0 and below:
Mapping level 4.0 and above (or when the INTEGER-AS-PIC9 parameter has been specified, regardless of the mapping level) :
or
where 10 ( z -1) < m <= 10 z |
|
Mapping level 3.0 and below:
Mapping level 4.0 and above (or when the INTEGER-AS-PIC9 parameter has been specified, regardless of the mapping level) :
or
where 10 ( z -1) < m <= 10 z |
|
or
where 10 ( z -1) < m <= 10 z |
|
or
where 10 ( z -1) < m <= 10 z |
|
|
|
where p and n are default values. |
|
Mapping level 1.1 and lower:
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. |
|
Mapping level 1.1 and lower:
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 . |
|
The logical paths through the array of options are merged together as
though a single Object had been defined of type It is possible for a JSON schema to define complex logical structures; however, the subtleties implied in the complex logical structures might be lost in the mapping to a language structure. The transformation process does not attempt to enforce the combinatorial rules from the schema; it only interacts with the language structure fields that indicate whether a given JSON property is present or absent. If the sub-options contain compatible definitions for the same property
name, DFHJS2LS attempts to merge the associated pattern of constraints, though some subtleties might
be lost in the process. For example, assume the following
definition:
"A"
is defined as either a string up to 5 characters long or a string between 7 and 8 characters long.
The merged composition might result in mappings to a string between 0 and 8 characters long, without
recognizing that length of 6 characters is invalid.Most scenarios involving logical composition will map to simple language structures, but complicated logical composition might result in compromises during the mapping process. For best results, avoid using logical composition in a JSON schema to define alternative declarations for the same JSON property. |
minimum
and
maximum
keywords: - For signed types (
short
,int
, andlong
), DISPLAY is used when the following are specified:
where"maximum": a "minimum": -a
a
is a string of '9's. - For unsigned types (
unsignedShort
,unsignedInt
, andunsignedLong
), DISPLAY is used when the following are specified:
where"maximum": a "minimum":0
a
is a string of '9's.