Schema definition extension syntax
A schema definition extension adheres to the following syntactic conventions:
- The extension for the target resource is defined by a JSON object contained in the
definitions
field of the schema extension file - The name of the extension must match that of the schema definition for the target resource
- The extension must have a
properties
attribute to contain the extended properties - Each extended property has the
_Ext
suffix appended to its name - Each extended property contains a value type declaration
The following example shows a schema definition extension for the Activity resource in the
Common API. The extension adds the shortSubject_Ext
property to the resource,
and defines the property value type as a string:
{
. . .
"definitions": {
"Activity": {
"properties": {
"shortSubject_Ext": {
"type": "string"
}
}
}
}
}
Activity
: The name of the schema definition for the resource that is being extendedshortSubject_Ext
: The name of the property extensiontype
: A declaration of the property value type
Property names
Guidewire recommends that you render property names in mixed case, with the first letter
being lowercase, and that you append _Ext
to the property name. This
namespacing is important to avoid upgrade conflicts if a property with the same name is
added to the core product in the future. The _Ext
suffix is required even
when adding properties from a base entity.
For example, if a PolicyCenter entity field name is
ShortSubject
, then the name of the extended resource property would be
shortSubject_Ext
.
Property value types
Each property extended by the schema definition must include a declaration of the property value type, and that type must align with the field type of the associated PolicyCenter entity. These types fall into the following general categories:
- Scalars
- Objects
- Arrays
Furthermore, property value types can be defined with one of the following attributes:
type
: Takes a string that indicates the property value type. Use this attribute for scalars and array value types.$ref
: Takes a URI reference to a definition elsewhere in the schema. Use this attribute for object value types.
Scalars
You can declare a property value type for a scalar by adding a type
attribute to the resource property and assigning it a JSON Schema primitive type of either
boolean
, integer
, number
, or
string
. If the scalar is a date or datetime type, then you would also add
a format
attribute and give it a value of either date
or
date-time
, respectively.
PolicyCenter scalar type | JSON primitive type |
---|---|
bit |
boolean |
dateonly |
string in date format |
datetime |
string in date-time format |
decimal |
number |
integer |
integer |
longint |
integer |
longtext |
string |
mediumtext |
string |
money |
number |
percentage |
number |
shorttext |
string |
text |
string |
varchar |
string |
The following example depicts base resource properties that support PolicyCenter datetime, bit, and varchar value types:
{
. . .
"definitions": {
"Activity": {
"properties": {
"closeDate": {
"type": "string",
"format": "date-time"
},
"mandatory": {
"type": "boolean"
},
"shortSubject": {
"type": "string"
}
}
}
}
}
Objects
You can declare a property value type for an object by assigning it a URI reference to an
inline resource schema. Typically, objects are formatted through the
SimpleReference
schema. For further details on inline resources, see the
Cloud API Business Flows Guide.
In the following example, assignedByUser_Ext
is a property extension whose
value type is object. That value type is declared through a URI reference to the
SimpleReference
schema:
{
. . .
"definitions": {
"Activity": {
"properties": {
"assignedByUser_Ext": {
"$ref": "#/definitions/SimpleReference"
}
}
}
}
}
In the schemas generally, property value types that align with PolicyCenter typekeys are formatted as objects. To declare a property
value type for a typekey, assign it a URI reference to the TypeKeyReference
schema. It is also necessary to explicitly associate the typekey with its PolicyCenter typelist through the
x-gw-extensions.typelist
attribute.
The example below shows an assignmentStatus_Ext
property extension. Its
value type is a typekey that is associated with the AssignmentStatus
typelist:
{
. . .
"definitions": {
"Activity": {
"properties": {
"assignmentStatus_Ext": {
"$ref": "#/definitions/TypeKeyReference",
"x-gw-extensions": {
"typelist": "AssignmentStatus"
}
}
}
}
}
}
Arrays
You can declare a property value type for an array by adding a type
attribute to the resource property and assigning it the value of array
. It
is also necessary to indicate the value type of the array members, which can be done by
adding an items.type
attribute for scalars or a URI reference for
objects.
The following property declaration is for an array of strings:
{
. . .
"definitions": {
"Activity": {
"properties": {
"exceptionSubtypes_Ext": {
"type": "array",
"items": {
"type": string"
}
}
}
}
}
}
The following property declaration, for the data
property of the
RelatedCollections
resource, uses a URI reference to set the array member
type as an object that conforms to the SimpleReference
schema:
{
. . .
"definitions": {
"RelatedCollection": {
"properties": {
. . .
"data": {
"type": "array",
"items": {
"$ref": "#/definitions/SimpleReference"
}
}
}
}
}
}
Virtual properties
Many PolicyCenter entity fields are virtual properties that derive their value through a Gosu method. The value returned from the method is typically dynamic, such as a concatenation of other fields, or a pointer to a specific member of an array (such as the member added most recently). In the PolicyCenter Data Dictionary, the field entry for virtual property lists the return type of the method that underlies the field. That type will be either a scalar, object, typekey, or array, as described previously. After identifying the return type, you can then follow the specific formatting guidance as described above.
Foreign keys
PolicyCenter entity fields are frequently based on foreign keys to other entities or typelists. To declare a property value type for a foreign key, you must first identify the terminating value type of the foreign key reference in the originating source. That type will be either a scalar, object, typekey, array, or virtual property, as described previously. You can then follow the specific formatting guidance for the type.
For example, the AccountContact
entity has a foreign key to
the Contact
entity, which has a DisplayName
property that
is a string type. The chained name of this property is
AccountContact.Contact.DisplayName
. The schema definition for this
property is as follows:
"AccountContact": {
"type": "object",
"x-gw-extensions": {
"discriminatorProperty": "contactSubtype"
},
"properties": {
. . .
"displayName": {
"type": "string",
"readOnly": true
},
. . .
}
}