Foreign keys in the schema configuration files

When you configure a schema, you typically modify the following files:

  • The schema extension file
    • The property definition references the SimpleReference schema
  • The mapping extension file
    • The mapper references the ResourceReference mapper
  • The updater extension file
    • The updater references a value resolver
    • In some cases, the referenced value resolver is one of the base configuration value resolvers
    • In other cases, you must first extend one of the abstract value resolvers, and then reference your extension value resolver
Filename Guidewire Studio node
<API>_ext-1.​0.​schema.​json integration -> schemas -> ext -> <API>.​v1
<API>_ext-1.​0.​mapping.​json integration -> mappers -> ext -> <API>.​v1
<API>_ext-1.​0.​updater.​json integration -> updaters -> ext -> <API>.​v1

The schema extension file

Each schema extension file for every API contains a definitions section. In the base configuration, this section is typically blank. You can add the name of one or more schemas to the definitions section. In each schema, you can define a properties section, which lists one or more properties defined for the schema.

For a foreign key property, the schema definition must specify $ref and resourceType.

The $ref property

$ref must be set to #/definitions/SimpleReference. SimpleReference refers to the SimpleReference schema, which is a schema used to simplify how foreign key information is embedded in a schema. The SimpleReference schema has the following fields, which are common to all resources:

  • displayName
  • id
  • jsonPath
  • refid
  • type
  • uri

The resourceType property

resourceType is a child property of the x-gw-extensions property. resourceType must be set to the name of the associated resource.

The syntax for setting these values is:
  "definitions": {
    "<resourceName>": {
      "properties": {
        "<foreignKeyPropertyName>": {
          "$ref": "#/definitions/SimpleReference",
          "x-gw-extensions": {
            "resourceType": "<resourceThatForeignKeyPointsTo>"
          }
        }
      }
    }
  }

Example schema definition

For example, suppose you want to designate a backup user for each activity. In the data model, you extend the Activity entity with a foreign key named BackupUser_Ext that points to the User entity. You also want to provide access to this BackupUser_Ext field in Cloud API. To do this, you would add the following to the common_ext-1.0.schema.json file:
  "definitions": {
    "Activity": {
      "properties": {
        "backupUser_Ext": {
          "title": "BackupUser_Ext",
          "description": "The backup user for the activity",
          "$ref": "#/definitions/SimpleReference",
          "x-gw-extensions": {
            "resourceType": "User"
          }
        }
      }
    }
  }
}

The mapping extension file

Each mapping extension file for every API contains a mappers section. In the base configuration, this section is typically blank. You can add the name of one or more schemas to the mappers section. In each schema, you can define a properties section, which lists one or more properties defined in the schema.

When adding a foreign key property to a resource, the mapping file must specify a path and mapper.

The path attribute identifies the field from the data model entity that stores the foreign key value. It also uses an extension named RestV1_AsReference. This extension provides information on how to map the various SimpleReference schema properties, such as jsonPath and uri. The syntax for the path attribute is:

<pathToForeignKeyField>.RestV1_AsReference

The mapper attribute is set to "#/mappers/ResourceReference". The ResourceReference mapper maps information from an entity into the fields defined by the SimpleReference schema.

The syntax for setting these values is:

    "<resourceName>": {
      "properties": {
        "<foreignKeyPropertyName>": {
          "path": "<pathToForeignKeyField>.RestV1_AsReference",
          "mapper": "#/mappers/ResourceReference"
        }
      }
    }

For example, suppose you want to implement the mapping for the BackupUser_Ext extension added to the Activity entity in the previous example. To do this, you would add the following to the common_ext-1.0.mapping.json file:

  "mappers": {
    "Activity": {
      "properties": {
        "backupUser_Ext": {
          "path": "Activity.BackupUser_Ext.RestV1_AsReference",
          "mapper": "#/mappers/ResourceReference"
        }
      }
    }
  }

The updater extension file

Each updater extension file for every API contains a updaters section. In the base configuration, this section is typically blank. You can add the name of one or more schemas to the updaters section. In each schema, you can define a properties section, which lists one or more properties defined in the schema.

In the updater file, you must specify a path and a valueResolver.

The path attribute specifies the path from the root entity to the foreign key field. For example, to specify the updater for the BackupUser_Ext field from the previous example, you would add the following to the updater file:
"Activity": {
  "properties": {
    "backupUser_Ext": {
      "path": "Activity.BackupUser_Ext",
      ...

A value resolver is a class used in updaters to return the resource that a foreign key property points to. The resource that the foreign key points to is sometimes referred to as the resolved value. The term resolving the reference refers to the act of determining the resource that the foreign key property will point to.

Cloud API provides value resolvers for some base configuration entities. It also provides a set of more generic value resolvers. The best value resolver to use depends on the type of relationship the root resource has with the foreign key resource. There are several possible relationships: