Use References in Knowledge Types and Objects

This page describes how to use reference properties in knowledge type and object definitions.

A reference property is a property in a knowledge type that refers to a knowledge object in the same knowledge type or another knowledge type. Reference properties can be used to prevent duplication of information.

Use References

These are the high-level steps:

1. Update the Knowledge Type Definition
2. Update the Knowledge Object Definition

1. Update the Knowledge Type Definition

1. Open the knowledge type definition and add the referenceProperties attribute.
2. Use JSON pointers to specify the list of knowledge object properties that are references to knowledge objects of the same knowledge type or other knowledge type(s).
3. Set the following attributes for each property:
   • types:
     • If the value is set to a fully qualified type name (FQTN) or an array of FQTNs, the property value can refer to a knowledge object belonging to one of the specified knowledge type(s).
     • If the value is set to *, the property can refer to any knowledge type in the Knowledge Store.
   • optional:
     • If set to false, the referenced knowledge object must exist when the new knowledge object is created or updated. If the referenced knowledge object does not exist, you will receive an error and the request will fail.
     • If set to true, the referenced knowledge object does not need to exist when the new knowledge object is created or updated.
4. Save the knowledge type definition.

Example knowledge type definition snippet:

{
  "name": "typeX",
  "jsonSchema": {
      ...
  },
  "referenceProperties": {
    "/property1": {
      "types": [
        "solution1:typeA",
        "solution1:typeB"
      ],
      "optional": false
    },
    "/property3": {
      "types": [
        "*"
      ],
      "optional": false
    }
  }
}

name: typeX
...
jsonSchema: {}
referenceProperties:
  /property1:
    types:
      - 'solution1:typeA'
      - 'solution1:typeB'
    optional: false
  /property3:
    types:
      - '*'
    optional: false

In this example:

• property1's value can refer to any of the knowledge objects of type solution1:typeA or solution1:typeB.
• property3's value can refer to a knowledge object of any type.
• The knowledge objects referenced in property1 and property2 must exist when the new knowledge object is created.

2. Update the Knowledge Object Definition

1. Open the knowledge object definition.
2. Set the value of the reference properties to the fully qualified ID (FQID) of the knowledge object you want to refer to.
3. Save the knowledge object definition.

Example knowledge object definition snippet:

{
  "property1": "spacefleet:starjournal/environment;layerId=extensibility;layerType=SOLUTION",
  "property2": "spacefleet:starjournal/entry;layerId=extensibility;layerType=SOLUTION"
}

property1: 'spacefleet:starjournal/environment;layerId=extensibility;layerType=SOLUTION'
property2: 'spacefleet:starjournal/entry;layerId=extensibility;layerType=SOLUTION'

Prefetch Reference Properties

See Fetch a Knowledge Object by ID.

Limits on References

The Knowledge Store currently places the following limits on references:

• There can be a maximum of 10 reference properties in a knowledge type.
• There can be a maximum of 10 references in a knowledge object.
• When you fetch a knowledge object that contains reference properties and set the required flags for prefetching, the maximum depth fetched is 2 knowledge objects.
  • Example: If object A → object B → object C → object D, only object A and B are fetched.
• Cyclic references are allowed. However, if you prefetch cyclic references when you fetch a knowledge object, each knowledge object will only be fetched once.
  • Example: If object A <-> object B, object A and B are only fetched once.