Define a Knowledge Object

This page describes how to define knowledge objects.

A knowledge object:

  • Is a JSON or YAML object that contains data in the form of key/value pairs.
  • Must adhere to the semantics and structure defined in its knowledge type.
  • Can be created by a developer, end user, or solution.

Fully Qualified ID (FQID)

A knowledge object is uniquely identified by its fully qualified ID (FQID). The FQID is used to identify a knowledge object at a specific layer and has the syntax <FQTN>/<objectId>;layerId=<layerId>;layerType=<layerType>. For more information on the fully qualified type name (FQTN), see Define a Knowledge Type.

For example, consider a knowledge object that:

  • belongs to the starjournal knowledge type which is defined by the spacefleet solution. This knowledge type has a FQTN of spacefleet:starjournal.
  • has an object ID of environment. The object ID is returned in the output when you create, fetch, list, and update knowledge objects.
  • is created at the SOLUTION layer.
  • is created by the solution extensibility.

The FQID for this knowledge object would be spacefleet:starjournal/environment;layerId=extensibility;layerType=SOLUTION. The FQID is returned in the output when you create, fetch, list, and update knowledge objects.

The following table displays examples of the FQID for knowledge objects at different layers:

FQTN Object ID Layer ID Layer Type FQID
spacefleet:starjournal extensibility:environment extensibility SOLUTION spacefleet:starjournal/extensibility:environment;layerId=extensibility;layerType=SOLUTION
spacefleet:starjournal test f509e00c-fec2-4a9f-a20e-f6958dbfb639 TENANT spacefleet:starjournal/test;layerId=f509e00c-fec2-4a9f-a20e-f6958dbfb639;layerType=TENANT
spacefleet:starjournal test f509e00c-fec2-4a9f-a20e-f6958dbfb639@user LOCALUSER spacefleet:starjournal/test;layerId=f509e00c-fec2-4a9f-a20e-f6958dbfb639@user;layerType=TENANT

Knowledge Object File with One Knowledge Object

The following example displays a knowledge object file that contains one knowledge object of the starjournal type:

{
    "name": "Entry-1701842808624",
    "journal": "Sample journal entry 1",
    "instrument": "instrumentX",
    "magnification": 10
}

name: Entry-1701842808624
journal: Sample journal entry 1
instrument: instrumentX
magnification: 10

Knowledge Object File with Multiple Knowledge Objects

(Optional) A knowledge object file can also contain an array of knowledge objects. This option can be used to group smaller knowledge objects and/or knowledge objects of the same type.

The following example displays a knowledge object file that contains multiple knowledge objects of the starjournal type:

[
    {
        "name": "Entry-1701842808624",
        "journal": "Sample journal entry 1",
        "instrument": "instrumentX",
        "magnification": 10
    },
    {
        "name": "Entry-1701842808625",
        "journal": "Sample journal entry 2",
        "instrument": "instrumentY",
        "magnification": 5
    }
]

- name: Entry-1701842808624
  journal: Sample journal entry 1
  instrument: instrumentX
  magnification: 10
- name: Entry-1701842808625
  journal: Sample journal entry 2
  instrument: instrumentY
  magnification: 5

Knowledge Object with Blob Properties

This section describes how to programmatically create a knowledge object that contains blob properties.

A blob property is a property value stored in blob storage. Storing a property value in a blob enables you to store larger and non-ASCII properties like images, configuration files, and other type of datas that cannot be easily stored in the other knowledge type properties.

To create a knowledge object with blob properties:

  1. Create the file for the blob property. Example blob file named blob1.js:

    let a = "test1";
console.log(a);

  2. Add the blob property file to the solution bundle. In this example, we're storing the blob file in a blobs folder in the root directory. You can store this folder in any path, and the folder can have any name.

    • Example solution bundle screenshot

  3. Add the blobProperties property to the knowledge type definition. Example knowledge type definition with blobProperties:

    Expand 
    {
  "name": "theme",
  "identifyingProperties": [
    "/name"
  ],
  "allowedLayers": [
    "SOLUTION",
    "TENANT",
    "LOCALUSER"
  ],
  "blobProperties": {
    "/address/homepic": {
      "contentTypesAllowed": ["application/javascript"],
      "maxContentSize": "100"
    },
     "/profilepic": {
      "contentTypesAllowed": ["application/javascript"],
      "maxContentSize": "100"
    }
  },
  "jsonSchema": {
    "$schema": "http://json-schema.org/draft-07/schema",
    "type": "object",
    "title": "E2E test config Schema",
    "description": "This schema defines structure of Synth monitoring objects",
    "required": [
      "name",
      "address"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "Name of synth config"
      },
       "profilepic": {
        "type": "string",
        "description": "Name of synth config"
      },
      "address": {
        "type": "object",
        "properties": {
          "homepic": {
              "type": "string"
            },
            "street": {
              "type": "string"
            },
            "state": {
              "type": "string"
            },
            "zipcode": {
              "type": "string"
            }
        },
        "required": ["street"],
        "description": "Array of params to be passed to the e2e test"
      }
    },
    "additionalProperties": false
  }
}

    name: theme
identifyingProperties:
- "/name"
allowedLayers:
- SOLUTION
- TENANT
- LOCALUSER
blobProperties:
  "/address/homepic":
    contentTypesAllowed:
    - application/javascript
    maxContentSize: '100'
  "/profilepic":
    contentTypesAllowed:
    - application/javascript
    maxContentSize: '100'
jsonSchema:
  "$schema": http://json-schema.org/draft-07/schema
  type: object
  title: E2E test config Schema
  description: This schema defines structure of Synth monitoring objects
  required:
  - name
  - address
  properties:
    name:
      type: string
      description: Name of synth config
    profilepic:
      type: string
      description: Name of synth config
    address:
      type: object
      properties:
        homepic:
          type: string
        street:
          type: string
        state:
          type: string
        zipcode:
          type: string
      required:
      - street
      description: Array of params to be passed to the e2e test
  additionalProperties: false

  4. Add the blob property file path to the knowledge object file. Example knowledge object file:

    {
"name": "test",
"profilepic": "blobs/blob1.js",
"address": {
    "street": "abce",
    "homepic": "blobs/blob1.js"
   }
}

    name: test
profilepic: blobs/blob1.js
address:
  street: abce
  homepic: blobs/blob1.js

Knowledge Object with Reference Properties

See Use References in Knowledge Types and Objects.

Tag a Knowledge Object

Tags can be used to categorize, retrieve, and filter knowledge objects. A tag is a key-value pair, where both the key and the value is a string.

Knowledge objects created at the TENANT and USER layer store tags. A SOLUTION-level object patched by a tenant or user does not layer tags.

To add tags to a knowledge object, use the temporary attribute __META__! to specify a tags field in your knowledge object file. __META__ can be used to specify certain fields that are part of the developer-exposed knowledge object fields, other than data.

Example Knowledge Object File Example Knowledge Object File with Tags 
[
    {
        "name": "Entry-1701842808624",
        "journal": "Sample journal entry 1",
        "instrument": "instrumentX",
        "magnification": 10
    },
    {
        "name": "Entry-1701842808625",
        "journal": "Sample journal entry 2",
        "instrument": "instrumentY",
        "magnification": 5
    }
]

- name: Entry-1701842808624
  journal: Sample journal entry 1
  instrument: instrumentX
  magnification: 10
- name: Entry-1701842808625
  journal: Sample journal entry 2
  instrument: instrumentY
  magnification: 5


[
    {
        "__META__!": {
            "tags": {"key1": "value1", "key2": "value2"}
        },
        "name": "Entry-1701842808624",
        "journal": "Sample journal entry 1",
        "instrument": "instrumentX",
        "magnification": 10
    },
    {
        "__META__!": {
            "tags": {"key1": "value1"}
        },
        "name": "Entry-1701842808625",
        "journal": "Sample journal entry 2",
        "instrument": "instrumentY",
        "magnification": 5
    }
]

- __META__!:
    tags:
      key1: value1
      key2: value2
  name: Entry-1701842808624
  journal: Sample journal entry 1
  instrument: instrumentX
  magnification: 10
- __META__!:
    tags:
      key1: value1
  name: Entry-1701842808625
  journal: Sample journal entry 2
  instrument: instrumentY
  magnification: 5

When the Knowledge Store installs the knowledge object, it removes the __META__ attribute from the template output. The output of the template processor, which is what the Knowledge Store inserts into Postgres, is stripped of tags and conforms to the required domain schema: 

{   
    "domainField1": 'foo',
    "domainField2": 'bar'
}

The Knowledge Store extracts the tags and stores it in a tags metadata attribute along with the knowledge object.

Use the Cisco Observability Platform Knowledge Store API

Using the Knowledge Store API, you can tag a knowledge object when you create or update it with API requests.