Foreign keys in the schema configuration files

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.

  "definitions": {
    "<resourceName>": {
      "properties": {
        "<foreignKeyPropertyName>": {
          "$ref": "#/definitions/SimpleReference",
          "x-gw-extensions": {
            "resourceType": "<resourceThatForeignKeyPointsTo>"
          }
        }
      }
    }
  }

  "definitions": {
    "Activity": {
      "properties": {
        "backupUser_Ext": {
          "title": "BackupUser_Ext",
          "description": "The backup user for the activity",
          "$ref": "#/definitions/SimpleReference",
          "x-gw-extensions": {
            "resourceType": "User"
          }
        }
      }
    }
  }
}

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

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.

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

• Updater case 1: Root and resolved value have no common ancestor
• Updater case 2: Root and resolved value have a common ancestor
• Update case 3: Accessibility of resolved value is conditional
• Update case 4: Resolved value cannot be easily resolved by id alone

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.

entityURIMappings:
 <resourceName>:
  uri: "${parentUri}/<endpointPathEnd>/${<pathToRestId>}"
  parent: "<pathFromRootResourceToParent>"

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"