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:

Knowledge Object File with One Knowledge Object

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

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

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

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

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

   js

   Copylet 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.

   • 

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

   Expand

   json

   yaml

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

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

   json

   yaml

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

   Copyname: 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.

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

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

Copy
[
    {
        "__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
    }
]

Copy- __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: 

Copy{   
    "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.