Working with Schema
LightWave Client schema describes the data types used in API request and response data mappings. The schema definitions are stored as part of the API. Ordinarily, there is no need for you to create schema definitions directly. The LightWave Client Console API editor automatically creates schema definitions for you when, while defining an API, you create a request or response mapping and select "Add by Example" for 'Schema Type'. In addition, when importing an API definition from a Swagger or OpenAPI definition, the API editor translates the type definitions it contains to LightWave Client schema.
To view or edit the schema attached to your API, click the 'Edit API Schema' icon in the API detail view toolbar. The schema is defined in Javascript Object Notation (JSON) regardless if data types are serialized as JSON or XML.
Although the Console API editor ordinarily creates the schema for you, there are times that you may want to modify the generated schema. The reason for this is due to differences in JSON schema or XML schema used in REST APIs and the invariant structured data types used in HPE NonStop applications. Both JSON and XML support the concept of unbounded strings – character strings without a defined maximum length. Likewise, both JSON and XML support unbounded arrays – arrays without a defined maximum size. Because the programming languages (C, COBOL, TAL, etc.) used by client applications on NonStop do not support unbounded data structures, it's necessary for LightWave to impose a maximum limit on string length and array size. When the API editor generates schema, it uses a minimum default length for strings of 32 and a minimum default array size of 4. (If the structure provided 'by example' contains a longer string or larger array, the example size is used.) Fortunately, these limits may be modified – on an element-by-element basis – by modifying the schema the Console API editor has generated for you.
The image above shows the 'Add by Example' dialog. Note the simple example JSON object consisting of two properties, "aStringProperty" and "anArrayOfStrings", and their respective sample values. The image below shows schema generated by the examples above.
![](../../__attachments/59998391/image2019-4-11_10-55-4.png?inst-v=ce0017ea-d045-45e9-8fcf-803bdce9c79d)
![](../../__attachments/59998391/image2019-4-11_10-56-28.png?inst-v=ce0017ea-d045-45e9-8fcf-803bdce9c79d)
Each schema type definition consists of an array of elements describing the properties or fields of the object it's describing. Each element minimally has a 'name' and a 'type'. See Built-in primitive types, below, for a list of available types. There are additional properties that may be added to an element's schema to further describe the element. See Schema Element Properties, below for a list of those properties.
Note that aStringProperty has been given a default "size", or length, of 32. If we know that aStringProperty will never hold a value greater than 12 characters, we can modify the size property accordingly. Likewise, if we know that a value for aStringProperty may be as long as 100 characters, we must modify the size property accordingly. (If at run time, a web service returns a value longer than ‘size' allows, LightWave will copy 'size' characters to the buffer and return a 'field truncated' warning.) If your client application will use zero-padded or NULL terminated strings as a 'C’ or TAL language program typically would, be sure to account for the terminator when calculating 'size'. See stringPadding in Schema Element Properties, below.
Regarding anArrayOfStrings in the example, note that again, a default size of 32 has been generated. The size property should be adjusted as needed. Additionally, since anArrayOfStrings is an array, the schema generator has emitted the maxOccurs property and given it the default value of 4, meaning the array may hold a maximum of four elements. If we know that the array must hold more or less than that amount, we would modify the maxOccurs property accordingly. (If the number of array items returned by the web service exceeds maxOccurs, LightWave will return an 'array truncated' warning.) Finally, note the dependsOn property. The schema generator has inserted an 'array count' element named 'anArrayOfStrings-count' into the type definition to hold the logical length of the anArrayOfStrings array. During serialization, only anArrayOfStrings-count items will be serialized to JSON. During deserialization, LightWave will store the actual number of items converted from JSON and copied into anArrayOfStrings in anArrayOfStrings-count.
Another reason you may wish to modify schema generated by the API editor is to change the primitive data type (string, integer, float, etc.) of a schema element. JSON and XML primitive types do not map one-to-one with NonStop primitive types. When generating a schema 'by example', the API editor attempts to infer the corresponding NonStop data type and size of each example element's JSON or XML value. Sometimes the inference made by the API editor is incorrect – for example if the example data value is 1, the API editor infers a type of 'int' (32-bit), when the element, in fact, needs to hold values requiring a 64-bit integer. Again, you may edit the generated schema as needed to adjust any improperly inferred element data types.
Add Schema by Example for 'ExampleType'
{
"ProductCategory": 123
}
Generated Schema for Example Above
"ExampleType": {
"anonymous": false,
"elements": [
{
"name": "ProductCategory",
"type": "int"
}
]
}
Because the example value of CustomerNumber provided is 123, the schema generator infers that the data type for the property should be 'int', which can store values between –2,147,483,648 to 2,147,483,647. However, if we know that product category will never be greater than 65,635, for example, we can modify "type" to be "unsignedShort". This will decrease the amount of space in the interprocess message (IPM) buffer from four bytes to two. Likewise, if we know that ProductCategory can be larger, we can modify "type" to be "unsignedLongLong", for example.
Schema Element Properties
The following properties may be applied to elements in the schema. Note that properties prefixed with @Xml are a subset of Java JAXB annotations.
property name | description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
name | required; the name of the element | ||||||||||
type | required; the type of the element; either a primitive type, or a type defined elsewhere in the schema. See below for supported primitive types. | ||||||||||
ddlName | the name for the element that should be used in DDL generation; overrides the default name-to-ddlName mapping | ||||||||||
dependsOn | when the element represents an array (minOccurs > 0), the name of another element in the current type definition that contains the actual count of 'in use' array elements | ||||||||||
hide | boolean; specifies that the item should not be serialized, often used in an element targeted by dependsOn, sizeIs or scaleIs (synonymous with private) | ||||||||||
isNull | boolean; when type is "nillable", the name of another element in the current type definition that indicates whether or not the field contains the value null when de/serialized | ||||||||||
isSet | References an integer fields that indicates whether or not the field should be present in the request, or was present in the response. See Working with Optional Elements | ||||||||||
jsonType | the JSON type ("number", "string", or "boolean") that should be used to de/serialize the element; overrides the default primitive-type to JSON-type mapping | ||||||||||
map | specifies that the element represents a JSON map | ||||||||||
minOccurs | when "type" is "string", if minOccurs = 0, zero-length string values will not be serialized | ||||||||||
maxOccurs | indicates the element represents an array; the maximum number of array elements that can be de/serialized | ||||||||||
nillable | boolean; indicates that the field may contain the value null. | ||||||||||
private | boolean; specifies that the item should not be serialized, often used in an element targeted by dependsOn, sizeIs or scaleIs. (synonymous with hide) | ||||||||||
scale | for integer and numeric types, the scale that should be used in the generated DDL element | ||||||||||
size | when "type" is "string", "base64Binary" or "hexBinary", the maximum length of the value | ||||||||||
sizeIs | when "type" is "string", "base64Binary" or "hexBinary"; the name of another element in the current type definition that contains the actual length of the item de/serialized | ||||||||||
stringPadding | "spaces" or "zeros"; indicates how LightWave expects to receive, returns string values from the client application. The default value is set in the API definition (which can be overridden by a CLIENT command-line parameter). Typically only set on the element level if more that one setting is needed for separate elements in a single API. | ||||||||||
timestampFormat | when type="timestamp", indicates the de/serialization format: "ISO8601", "ISO8601:full-date", "RFC2822", or "XSD:dateTime" | ||||||||||
wrapped | boolean; indicates if an array is wrapped in an array container or a type/element is wrapped by its parent. Default is true. | ||||||||||
@XmlAttribute | object; indicates that the value of the field is an attribute of the parent type. The object may contain the following properties
JS
Yields
XML
| ||||||||||
@XmlElement | object; allows various properties to be applied to an XML element. The object may contain the following properties:
| ||||||||||
@XmlElementWrapper | object; causes a wrapper to be created around the element and is most commonly used to declare wrapped arrays. The object may contain the following properties:
For example:
JS
Yields
XML
| ||||||||||
@XmlRootElement | object; allows various properties to be applied to an XML document root element. The object may contain the following properties:
| ||||||||||
@XmlValue | object; causes the contents of the field to be mapped as the text content of the parent type. The object has no properties. For example:
JS
Yields
XML
Not
XML
|
Built-in 'primitive' Types
name | description | DDL type | JSON type |
---|---|---|---|
base64Binary | serialized as base-64 encoded string; n=size | PIC X(n) | string |
boolean | zero serialized as "false"; | BINARY 32 | boolean |
byte | -128 <= value <= 127 | BINARY 8 | number |
double | double precision floating point | FLOAT 64 | number |
float | single precision floating point | FLOAT 32 | number |
hexBinary | serialized hex binary string; n=size | PIC X(n) | string |
int | –2,147,483,648 to 2,147,483,647 | BINARY 32 | number |
long | same as int | BINARY 32 | number |
longlong | –9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 | BINARY 64 | number |
numeric | numeric string; n=precision; | PIC S9(n) | number |
numericSignEmbedded | numeric string; n=precision | PIC T9(n) | number |
numericSignTrailing | numeric string; n=precision | PIC 9(n)S | number |
numericSignTrailingEmbedded | numeric string; n=precision | PIC 9(n)T | number |
short | -32768 <= value <= 32767 | BINARY 16 | number |
string | character string | PIC X(s) | string |
timestamp | serialized as timestamp; | BINARY 64 | string |
unsignedByte | 0 <= x <= 256 | BINARY 8, UNSIGNED | number |
unsignedInt | 0 <= x <= 232 - 1 | BINARY 32, UNSIGNED | number |
unsignedLong | same as unsignedInt | BINARY 32, UNSIGNED | number |
unsignedLongLong | 0 <= x <= 264 - 1 | BINARY 64, UNSIGNED | number |
unsignedNumeric | number | ||
unsignedShort | 0 <= x <= 65535 | BINARY 16, UNSIGNED | number |