JSON schema file specification

General information

Relation to JSON Schema Draft 4
JSON Schema support within Guidewire InsuranceSuite is based on JSON Schema Draft 4. However, the support is for a very limited subset of Draft 4. Guidewire must allow for consistency and simplicity across use cases. For example, this consistency and simplicity must be available for integration mappings that target a schema and for wrapper class generation. To facilitate consistency and simplicity, Guidewire imposes significant constraints on the shape of the schemas you can use. Among these constraints are the following:
  • No support for allOf, anyOf, or oneOf keywords
  • No support for patternProperties keyword
  • No support for nested object definitions. You must explicitly name all object definitions. Afterwards, you can reference these top-level definitions.
  • No support for named definitions that are not object types
  • No support for items that have an array type. For example, you cannot use nested arrays.
  • No support for heterogeneous items within a property
Note: Some of these restrictions match restrictions that the Guidewire flavor of Swagger 2.0 imposes. In addition, the Guidewire flavors of JSON Schema Draft 4 and Swagger 2.0 have many custom features.
Requiredness

Properties designated as required are not always necessary in every schema document. You must consider such properties in light of the entire combined schema.

For example, properties generally must specify one of either a type or $ref property. However, a special case arises if a schema is merely overriding the description on a property that the schema inherits from a combined schema. In this case, the extension schema does not legally have to specify either the type or $ref property.

Combination styles
The combination of schema files is roughly equivalent to an ordered, textual merge of the files. However, there are some nuances around how the merge works. Depending on the object and property, the following styles are possible:
merged
The referenced subobjects are merged together based on the rules for combining the particular object.
merged by key
The merged by key combination style involves matching up objects based on the keys in a map. For example, elements under the properties property with the same key are merged.
merge extensions
Extensions objects are merged by taking the first defined value for each key even if that defined value is explicitly null.
merge names
Required property names combine together to form a single list. A schema that combines cannot eliminate the required nature of a property from a definition that the schema is inheriting.
first non-null
Given N objects to be merged together, the mapping takes the first non-null value for the given property.
not inherited
The property is explicitly not inherited across files. This style is generally for root-level defaults that are propagated within only a given file.
n/a
The containing object or property is always treated as an atomic unit and never merged. For example, the name property on an Items XML Object is never merged. The mapping treats the two properties as a single unit that can be replaced wholesale such that the properties on the name object are never combined.
Documentation only properties

Many properties are listed as "Documentation only" for their behavior. Guidewire InsuranceSuite does not use the value of such properties to determine runtime behavior. However, InsuranceSuite does include the properties when it publishes a JSON schema for external consumption. Tools that consume a JSON schema or Swagger schema that contains these properties can use them.

Root object

Property Type Required Format Behavior Combination Style
$schema string Yes http://json-schema.org/draft-04/schema# Defines the JSON Schema SDL version not inherited
title string No Documentation only first non-null
description string No Documentation only first non-null
x-gw-combine string[] No Array of fully-qualified JSON schema names Specifies the schemas to combine with this file not inherited
x-gw-import map<string, string> No Keys are alias names. Values are fully-qualified JSON schema names. Defines aliases for other schema files to which this schema file can refer merged by key
x-gw-xml Root XML Object No Allows configuration of the namespace for the XSD into which this schema can be translated first non-null
definitions map<string, Definition Object> No Keys are the names of the definitions. The schema type definitions for this schema merged by key

Root XML object

Property Type Required Format Behavior Combination Style
namespace string Yes Must be a valid XSD namespace Overrides the default namespace for the XSD with this value n/a

Definition object

Property Type Required Format Behavior Combination Style
type string Yes Must be object Defines the type of JSON value to which this definition applies. Guidewire InsuranceSuite only supports definitions for JSON objects. First non-null
title string No Documentation only First non-null
description string No Documentation only First non-null
properties map<string, Property Object> No The string keys in the map serve as the names of the properties. Defines the properties that this schema definition explicitly names. If a JSON object includes one of these specified properties, the object must match the type and constraints set forth in the associated property definition. Merged by key
additionalProperties Property Object No This optional property indicates that the object can have arbitrary property values. Any property value that you do not explicitly name in the properties property must match the additionalProperties property definition. Merged
required string[] No Array of property names JSON objects that conform to this definition must always specify the properties listed in the required property. If you do not specify the additionalProperties property, the names in the required property must all be valid named properties on this definition. Note that a property with a null value satisfies this constraint if the property specifies x-gw-nullable with a value of true. PolicyCenter reports a validation error only if the required property is undefined on the JSON object. Merge names
x-gw-extensions map<string, any> No This property is an arbitrary map of property keys to values. The keys can be any string. The values can be any object, including JSON objects or arrays. Values in extensions are available to IRestValidatorFactoryPlugin objects for use in building custom validations. Merge extensions

Property object

Property Type Required Format Behavior Combination Style
type string Either type or $ref is required. One of array, boolean, integer, number, or string Defines the type of JSON value that this property is expected to have. If the property is a JSON object, set the $ref property instead. The $ref property indicates the expected object schema. For scalar types, the type, format, and x-gw-type properties define how data is serialized and deserialized. This combination also defines the mappings from JSON data to Java object types. First non-null
title string No Documentation only First non-null
description string No Documentation only First non-null
format string No The type, format, and x-gw-type properties define how data is serialized and deserialized. This combination also defines the mappings from JSON data to Java object types. First non-null
x-gw-type string No The type, format, and x-gw-type properties define how data is serialized and deserialized. This combination also defines the mappings from JSON data to Java object types. First non-null
$ref string Either type or $ref is required. Either #/definitions/<name> or <alias>#/definitions/<name> Defines a reference to the schema definition to which this property generally conforms. The reference can be to another type defined within this schema. In the alternative, the reference can use an import alias to specify a definition from an imported file. First non-null
items Items Object Required if type is array. Otherwise, the items property is not allowed. Defines the items schema to which elements within this array must conform Merged
default any No Each element must be a JSON value that can be parsed based on the type, format, and x-gw-type of this property.

Defines a default value for this property in cases where the property is not defined on the input JSON object. The REST framework converts the default value as if it is a standard input value. The value is generally a valid JSON value for the type, format, and x-gw-type properties.

For example, if the type property is string and the format property is gw-bigdecimal, the default value is generally a decimal string and not a JSON number. The default property is relevant only for scalar properties.

 First non-null
maximum number No

Specifies the maximum value the property can have. The comparison is either inclusive or exclusive, depending upon the value of the exclusiveMaximum property. PolicyCenter parses the value of the maximum property as a fixed-point value with no loss of precision. PolicyCenter then converts the fixed-point value to the internal Java representation that the runtime parameter uses for comparison purposes.

Take the following scenarios for examples. On the one hand, suppose that the value of the type property is integer and the value of the format property is int32. In this case, the value of the maximum property must be a valid integer. PolicyCenter thus converts the value of the maximum property to an Integer at runtime.

On the other hand, suppose that the respective values of the type and format properties are string and gw-bigdecimal. In this case, PolicyCenter converts the value of the maximum property to a BigDecimal for comparison at runtime. Note that PolicyCenter permits the maximum property to have a value only if the runtime type is numeric.

 First non-null
exclusiveMaximum boolean No Determines if the maximum value is treated as inclusive or exclusive. The default value of the exclusiveMaximum property is false. This means that the value of the maximum property is inclusive. PolicyCenter permits the exclusiveMaximum property to have a value only if you specify the maximum property. First non-null
minimum number No Specifies the minimum value the property can have. Otherwise, the minimum property behaves in the same way as the maximum property. Note that PolicyCenter permits the minimum property to have a value only if the runtime type is numeric. First non-null
exclusiveMinimum boolean No Determines if the minimum value is treated as inclusive or exclusive. The default value of the exclusiveMaximum property is false. This means that the value of the minimum property is inclusive. PolicyCenter permits the exclusiveMinimum property to have a value only if you specify the maximum property. First non-null
maxLength integer No Determines the maximum length of the property value. The value of the maximum length is inclusive. For PolicyCenter to permit the maxLength property to have a value, the property must have a runtime type of String. First non-null
minLength integer No Determines the minimum length of the property value. The value of the minimum length is inclusive. For PolicyCenter to permit the minLength property to have a value, the property must have a runtime type of String. First non-null
pattern string No Specifies a regular expression that the property value must match. The regular expression is not implicitly anchored. If you want the expression to match the entire input, explicitly anchor the expression with ^ and $. In this case, PolicyCenter evaluates the regular expression using the Java regular expression engine. The regular expression generally matches the Java syntax. This syntax has minor differences from the Javascript syntax and therefore represents a slight deviation from the JSON Schema specification. For PolicyCenter to permit the pattern property to have a value, the property must have a runtime type of String. First non-null
maxItems integer No Specifies the maximum number of elements allowed in an array. This value is inclusive. PolicyCenter permits maxItems for properties only of type array. First non-null
minItems integer No Specifies the minimum number of elements allowed in an array. This value is inclusive. PolicyCenter permits minItems for properties only of type array. First non-null
uniqueItems boolean No If set to true, this property indicates that the elements of the array must be unique. This uniqueness is as defined by the equals() and hashCode() methods of the deserialized values. The default value is false. PolicyCenter permits uniqueItems for properties only of type array. First non-null
multipleOf number No

Specifies that the property value must be a multiple of the specified value. PolicyCenter parses the value of the multipleOf property as a fixed-point value with no loss of precision. PolicyCenter then converts the fixed-point value to the internal Java representation that the runtime parameter uses for comparison purposes. Take the following scenarios for examples.

On the one hand, suppose that the value of the type property is integer and the value of the format property is int32. In this case, the value of the multipleOf property must be a valid integer. PolicyCenter thus converts the value of the multipleOf property to an Integer at runtime.

On the other hand, suppose that the respective values of the type and format properties are string and gw-bigdecimal. In this case, PolicyCenter converts the value of the multipleOf property to a BigDecimal for comparison at runtime. Note that PolicyCenter permits the multipleOf property to have a value only if the runtime type is numeric.

 First non-null
readOnly boolean No Specifies that a given property value ought not be set for a JSON object that serves as an input to a REST API. The Swagger extensions to JSON Schema define the readOnly property. This property allows the same schema definition to be used for both input and output. First non-null
enum any[] No Each element must be a JSON value that can be parsed based on the type, format, and x-gw-type of this property. Specifies a list of values one of which the property value must match. PolicyCenter converts the enum values in the schema into Java objects at runtime. PolicyCenter then compares the enum values against the property value using the equals and hashCode methods. First non-null
x-gw-xml Property XML Object No Allows configuration of how PolicyCenter maps the property definition into an XSD. First non-null
x-gw-export-enumeration boolean No If the value of this property is true, PolicyCenter writes typekey values out as an enum property while creating a schema for external clients. This property is only valid if enum is not set and x-gw-type is a typekey type. The default value is false. First non-null
x-gw-nullable boolean No Specifies that this property can have an explicit null value. This property defaults to false. A value of false means that the property must either be undefined on the object or must have an explicit non-null value. First non-null
x-gw-extensions map<string, any> No This can be an arbitrary map of property keys to values. The keys can be any string. The values can be any object, including JSON objects or arrays. Values in extensions are available to IRestValidatorFactoryPlugin objects for use in building custom validations. Merge extensions

Property XML object

Property Type Required Format Behavior Combination Style
attribute boolean Yes Specifies that a property is preferably mapped to an XML attribute rather than an XML element. The attribute property is not valid when x-gw-nullable has a value of true. The default value is false. In this case, schema properties are serialized as XML child elements. n/a

Items object

Property Type Required Format Behavior Combination Style
type string Either type or $ref is required. One of boolean, number, or string The type, format, and x-gw-type properties define how array items are serialized and deserialized. This combination also defines the mappings from JSON data to Java object types. First non-null
format string No The type, format, and x-gw-type properties define how array items are serialized and deserialized. This combination also defines the mappings from JSON data to Java object types. First non-null
x-gw-type string No The type, format, and x-gw-type properties define how array items are serialized and deserialized. This combination also defines the mappings from JSON data to Java object types. First non-null
$ref string Either type or $ref is required. Either #/definitions/<name> or <alias>#/definitions/<name> Defines a reference to the schema definition to which this property generally conforms. The reference can be to another type defined within this schema. In the alternative, the reference can use an import alias to specify a definition from an imported file. First non-null
maximum number No Specifies the maximum value property items are allowed to have. Otherwise, the behavior for the maximum property is identical to the behavior defined for the maximum property in the property object table. First non-null
exclusiveMaximum boolean No See the behavior for the exclusiveMaximum property in the property object table. First non-null
minimum number No Specifies the minimum value property items are allowed to have. Otherwise, the behavior for the minimum property is identical to the behavior defined for the minimum property in the property object table. First non-null
exclusiveMinimum boolean No See the behavior for the exclusiveMinimum property in the property object table. First non-null
maxLength integer No Determines the maximum length of property items. Otherwise, the behavior for the maxLength property is identical to the behavior defined for the maxLength property in the property object table. First non-null
minLength integer No Determines the minimum length of property items. Otherwise, the behavior for the minLength property is identical to the behavior defined for the minLength property in the property object table. First non-null
pattern string No Specifies a regular expression that property items must match. Otherwise, the behavior for the pattern property is identical to the behavior defined for the pattern property in the property object table. First non-null
multipleOf number No Specifies that the item values must be a multiple of the specified value. Otherwise, the behavior for the multipleOf property is identical to the behavior defined for the pattern property in the property object table. First non-null
enum any[] No Each element must be a JSON value that can be parsed based on the type, format, and x-gw-type of this item. Specifies a list of values at least one of which item values must match. PolicyCenter turns the enum values in the schema into Java objects at runtime. PolicyCenter then compare the enum values against the item value using the equals and hashCode methods. First non-null
x-gw-xml Items XML Object No Allows configuration of how PolicyCenter maps the item definition into an XSD. First non-null
x-gw-export-enumeration boolean No If the value of this property is true, PolicyCenter writes typekey values out as an enum property if creating a schema for external clients. This property is only valid if enum is not set and x-gw-type is a typekey type. The default value is false. First non-null
x-gw-nullable boolean No Specifies that this property can have items with an explicit null value. This property defaults to false. First non-null
x-gw-extensions map<string, any> No This can be an arbitrary map of property keys to values. The keys can be any string. The values can be any object, including JSON objects or arrays. Values in extensions are available to IRestValidatorFactoryPlugin objects for use in building custom validations. Merge extensions

Items XML object

Property Type Required Format Behavior Combination Style
name string Yes Must be a valid XML element or attribute name. Used for the name of XML elements that wrap each item in the list. By default, for an object array, the element name is the name of the referenced object definition. For scalar arrays, the default element name is the name of the containing property. n/a

See also