Schema definition extension syntax

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.

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 and Configuration 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
    },
    . . .
  }
}