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 n



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 n



PIC S9(
15
) 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 n


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.