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

If you created the root resource through the REST endpoint generator and did not add the resource to an integration graph, you must also update the shared apiconfig extension file.

The following table summarizes the names and locations of these files.

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
shared_ext-1.​0.​apiconfig.​yaml integration -> apis -> ext -> shared.​v1
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
shared_ext-1.​0.​apiconfig.​yaml integration -> apis -> ext -> shared.​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": {

    "<reso
urceName>": {
      "p
roperties": {
        "<foreignKeyPropertyName>": {
          "$r
ef": "#/definitions/SimpleReference",
          "x-gw-extensio
ns": {
     
       "re
sourceTy
pe": "<resourceThatForeignKeyPointsTo>"
          }
        }
      }
    }
  }
JSON

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"

          }

        }

      }

    }
  }
}
JSON

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
Java

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:

    "<reso
urceName>": {
      "p
roperties": {
        "<foreignKeyPropertyName>": {
          "path": "<pathToForeignKeyField>.RestV1_AsR
eference",

          "mapper": "#/mappers/ResourceReference"
        }
      }
    }
JSON

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"

        }

      }

    }
  }
JSON

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",

      ...
JSON

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:

The shared apiconfig file

The shared_ext-1.0.apiconfig.yaml maps shared element resource and collection resources to Gosu Resource files. It also specifies URI mappings for integration graphs. When you specify that you want to add a custom resource to a graph, the REST endpoint generator adds code to the corresponding shared_ext-1.0.apiconfig.yaml file.

If you do not add a resource to an integration graph, then you must manually add the URI mapping to the shared_ext-1.0.apiconfig.yaml. The syntax for the entry is as follows:
entityURIMappings:
 <resourceName>:
  uri: "${parentUri}/<endpointPathEnd>/${<pathToRestId>}"
  parent: "<pathFromRootResourceToParent>"
YAML

For example, suppose you had a custom entity that was not part of an integration graph. Its name is CustomEntity_Ext, the end of its endpoint path is custom-entities-ext, and its parent is Activity. The URI mapping would look like this: 

entityURIMappings:
 CustomEntity_Ext:
  uri: "${parentUri}/custom-entities-ext/${CustomEntity_Ext.RestId}"
  parent: "CustomEntity_Ext.Activity"
YAML