Cisco Observability Platform

This documentation and the Cisco Observability Platform functionalities it describes are subject to change. Data saved on the platform may disappear and APIs may change without notice.

Define a Knowledge Type

A knowledge type is defined as a JSON or YAML file within your solution.

A knowledge type definition:

Is a schema that defines a knowledge object’s structure, properties, and valid values for those properties. Knowledge objects that are created for a particular knowledge type must adhere to the semantics and structure defined in the knowledge type.
Contains properties that identify how the knowledge type and its objects are stored and accessed in the Knowledge Store. For example, the layers on which the objects can exist, how to generate the ID of the object, and so on.
Must adhere to the knowledge type schema.

A knowledge type is identified by its fully qualified type name (FQTN), which has the syntax <solution-name>:<knowledge-type-name>. For example, the FQTN for the starjournal knowledge type in the spacefleet solution would be spacefleet:starjournal.

Knowledge type files are defined in a solution. When a solution is installed in the system, knowledge objects of the given knowledge type can be accessed via the Cisco Observability Platform Knowledge Store API at knowledge-store/v1/objects/<solution-name>:<knowledge-type-name>.

Knowledge Type Schema

Knowledge type definitions must adhere to the following schema:

Expand

json

yaml

Copy{
    "name": "type",
    "idGeneration": {
        "generateRandomId": false,
        "idGenerationMechanism": "{{object.solution}}:{{object.name}}",
        "enforceGlobalUniqueness": false
    },
    "displayNameGenerationMechanism": "{{object.solution}}:{{object.name}}",
    "allowedObjectFragments": false,
    "allowObjectFragments": false,
    "isProtectedType": true,
    "allowedLayers": [
        "SOLUTION"
    ],
    "referenceQualifiers": null,
    "propertyMutableLayers": {
        "$.identifyingProperties": []
    },
    "jsonSchema": {
        "$schema": "http://json-schema.org/draft-07/schema",
        "type": "object",
        "title": "Type Schema",
        "description": "This schema defines structure of type objects stored in the extensibility:types table",
        "required": [
            "name",
            "jsonSchema"
        ],
        "properties": {
            "name": {
                "type": "string",
                "pattern": "^[a-zA-Z][a-zA-Z0-9]*$",
                "maxLength": 25,
                "description": "Name of type in question"
            },
            "presets": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "propertyNames": {
                    "type": "string"
                }
            },
            "solution": {
                "type": "string",
                "description": "Name of the solution for which the type exists"
            },
            "idGeneration": {
                "type": "object",
                "properties": {
                    "generateRandomId": {
                        "type": "boolean",
                        "description": "Flag to be set to true if you want to generate a random ID for objects of this type"
                    },
                    "idGenerationMechanism": {
                        "type": "string",
                        "description": "Format for generating an id using mustache {{}} format"
                    },
                    "enforceGlobalUniqueness": {
                        "type": "boolean",
                        "description": "Flag to be set to true if you want all objects of this type to have a unique id"
                    }
                },
                "additionalProperties": false,
                "description": "Object specifying how the ID for objects of this type are generated"
            },
            "displayNameGenerationMechanism": {
                "type": "string",
                "description": "Method for generating display name for objects of this type"
            },
            "allowedObjectFragments": {
                "type": "boolean",
                "description": "Defines whether object could allow fragments, i.e. partial updates in each level(global, globalUser, solution, tenant and localUser)"
            },
            "allowObjectFragments": {
                "type": "boolean",
                "description": "Defines whether object could allow fragments, i.e. partial updates in each level(global, globalUser, solution, tenant and localUser). It will replace allowedObjectFragments"
            },
            "jsonSchema": {
                "type": "object",
                "properties": {
                    "$schema": {
                        "type": "string",
                        "description": "Link to explanation of json schema for an object"
                    },
                    "type": {
                        "anyOf": [
                            { "enum": [ "array", "boolean", "integer",  "null",  "number", "object",  "string" ] },
                            {
                                "type": "array",
                                "items": { "enum": [ "array", "boolean", "integer",  "null",  "number", "object",  "string" ] },
                                "minItems": 1,
                                "uniqueItems": true
                            }
                        ],
                        "description": "Return type for whatever is created by the defined json schema"
                    },
                    "$id": {
                        "type": "string",
                        "description": "JSON Schema $id reference path"
                    },
                    "title": {
                        "type": "string",
                        "description": "Title for objects of this type"
                    },
                    "description": {
                        "type": "string",
                        "description": "Description of objects of this type"
                    },
                    "required": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "description": "Required field for an object of a given type"
                        },
                        "description": "A list of fields that are required for creating objects of this type"
                    },
                    "examples": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "description": "Example object of the given type",
                            "patternProperties": {
                                ".*": {
                                  "description": "property value that is part of the example object of the given type"
                                }
                            },
                            "additionalProperties": false
                        },
                        "description": "A list of example objects that of the given type"
                    },
                    "default": {
                        "type": "object",
                        "description": "the default object of the given type",
                        "patternProperties": {
                            ".*": {
                              "description": "property value that is part of the json schema for the default object of the given type"
                            }
                          },
                          "additionalProperties": false
                    },
                    "properties": {
                        "type": "object",
                        "description": "Object that defines all of the properties which can exist for objects of the given type",
                        "patternProperties": {
                            ".*": {
                              "description": "property value that is part of the json schema for objects of the given type"
                            }
                        },
                        "additionalProperties": false
                    },
                    "additionalProperties": {
                        "description": "Flag set to signify if there should be additional properties allowed when performing json schema validation"
                    }
                },
                "additionalProperties": true,
                "description": "Defines the schema for objects of this type"
            },
            "isProtectedType": {
                "type": "boolean",
                "description": "Defines whether the type is protected and only system could create its objects"
            },
            "allowedLayers": {
                "type": "array",
                "items": {
                    "type": "string",
                    "enum": ["LOCALUSER", "ACCOUNT", "GLOBALUSER", "TENANT", "SOLUTION"],
                    "description": "Layer value at which the object can be edited"
                },
                "description": "Final scope reflects the level to which this object could be edited. Beyond that it is readonly"
            },
            "referenceQualifiers": {
                "type": ["object", "null"],
                "patternProperties": {
                    "^\\$\\..*": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "description": "Path where the property that is referenced is defined"
                      }
                    }
                },
                "additionalProperties": false,
                "description": "Defines the reference properties"
            },
            "blobProperties": {
                "anyOf": [
                    {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "description": "Blob property to be stored in object store"
                        },
                        "description": "[DEPRECATED] Array of blob properties with json paths as the string values. Blobs will be stored in object store"
                    },
                    {
                        "type": "object",
                        "patternProperties":{
                            "^\\/\\.*":{
                               "type":"object",
                               "properties":{
                                  "contentTypesAllowed":{
                                     "type":"array",
                                     "items":{
                                        "type":"string",
                                        "description":"Allowed mime types. Skip property for no restrictions."
                                     },
                                     "uniqueItems":true
                                  },
                                  "maxContentSize":{
                                     "type":"string",
                                     "description":"Max content size permissible in bytes(base 2)."
                                  }
                               },
                               "required": ["maxContentSize"]
                            }
                         },
                         "additionalProperties":false,
                         "description":"Defines the blob properties"
                    }
                ]
            },
            "referenceProperties": {
                "type": [
                  "object",
                  "null"
                ],
                "patternProperties": {
                    "^\\/\\.*": {
                        "type": "object",
                        "properties": {
                            "types": {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "description": "FQTN that reference object can belong to",
                                    "example": "extensibility:solution, fmm*:entity, *"
                                },
                                "description": "List of FQTNs that reference object can belong to"
                            },
                            "optional": {
                                "type": "boolean",
                                "description": "Indicates if the property is mandatory or not"
                            }
                        },
                        "additionalProperties": false
                    }
                },
                "additionalProperties": false,
                "examples": [{
                    "/solutionInfo": {
                        "types": ["extensibility:solution", "environment:solution"],
                        "optional": false
                    },
                    "/subscriptionInfo": {
                        "types": ["environment*:subscription"],
                        "optional": true
                    },
                    "/entityInfo": {
                        "types": "*",
                        "optional": false
                    }
                }],
                "description": "Defines the reference properties"
            },
            "secureProperties": {
                "type": "array",
                "items": {
                    "type": "string",
                    "description": "Secure property to be stored in secret vault"
                },
                "description": "Array of secure properties with json paths as the string values. Secure properties will be stored in a secret vault"
            },
            "propertyMutableLayers": {
                "type": "object",
                "patternProperties": {
                    "^\\$\\..*": {
                      "type": "array",
                      "items": {
                          "type": "string",
                          "enum": ["LOCALUSER", "ACCOUNT", "GLOBALUSER", "TENANT", "SOLUTION"],
                          "description": "Layer value at which the object can be edited"
                      }
                    }
                  },
                "description": "This is an object that defines the layers at which each property is modifiable",
                "nullable": true,
                "additionalProperties": false
            },
            "identifyingProperties": {
                "type": "array",
                "items": {
                    "type": "string",
                    "pattern": "^\/.*$",
                    "description": "JSONPointer of the identifying properties"
                },
                "minItems": 1,
                "maxItems": 3,
                "uniqueItems": true
            }
        },
        "additionalProperties": false
    }
}

Copyname: type
idGeneration:
  generateRandomId: false
  idGenerationMechanism: '{{object.solution}}:{{object.name}}'
  enforceGlobalUniqueness: false
displayNameGenerationMechanism: '{{object.solution}}:{{object.name}}'
allowedObjectFragments: false
allowObjectFragments: false
isProtectedType: true
allowedLayers:
  - SOLUTION
referenceQualifiers: null
propertyMutableLayers:
  $.identifyingProperties: []
jsonSchema:
  $schema: 'http://json-schema.org/draft-07/schema'
  type: object
  title: Type Schema
  description: >-
    This schema defines structure of type objects stored in the
    extensibility:types table
  required:
    - name
    - jsonSchema
  properties:
    name:
      type: string
      pattern: '^[a-zA-Z][a-zA-Z0-9]*$'
      maxLength: 25
      description: Name of type in question
    presets:
      type: object
      additionalProperties:
        type: string
      propertyNames:
        type: string
    solution:
      type: string
      description: Name of the solution for which the type exists
    idGeneration:
      type: object
      properties:
        generateRandomId:
          type: boolean
          description: >-
            Flag to be set to true if you want to generate a random ID for
            objects of this type
        idGenerationMechanism:
          type: string
          description: 'Format for generating an id using mustache {{}} format'
        enforceGlobalUniqueness:
          type: boolean
          description: >-
            Flag to be set to true if you want all objects of this type to have
            a unique id
      additionalProperties: false
      description: Object specifying how the ID for objects of this type are generated
    displayNameGenerationMechanism:
      type: string
      description: Method for generating display name for objects of this type
    allowedObjectFragments:
      type: boolean
      description: >-
        Defines whether object could allow fragments, i.e. partial updates in
        each level(global, globalUser, solution, tenant and localUser)
    allowObjectFragments:
      type: boolean
      description: >-
        Defines whether object could allow fragments, i.e. partial updates in
        each level(global, globalUser, solution, tenant and localUser). It will
        replace allowedObjectFragments
    jsonSchema:
      type: object
      properties:
        $schema:
          type: string
          description: Link to explanation of json schema for an object
        type:
          anyOf:
            - enum:
                - array
                - boolean
                - integer
                - 'null'
                - number
                - object
                - string
            - type: array
              items:
                enum:
                  - array
                  - boolean
                  - integer
                  - 'null'
                  - number
                  - object
                  - string
              minItems: 1
              uniqueItems: true
          description: Return type for whatever is created by the defined json schema
        $id:
          type: string
          description: JSON Schema $id reference path
        title:
          type: string
          description: Title for objects of this type
        description:
          type: string
          description: Description of objects of this type
        required:
          type: array
          items:
            type: string
            description: Required field for an object of a given type
          description: A list of fields that are required for creating objects of this type
        examples:
          type: array
          items:
            type: object
            description: Example object of the given type
            patternProperties:
              .*:
                description: >-
                  property value that is part of the example object of the given
                  type
            additionalProperties: false
          description: A list of example objects that of the given type
        default:
          type: object
          description: the default object of the given type
          patternProperties:
            .*:
              description: >-
                property value that is part of the json schema for the default
                object of the given type
          additionalProperties: false
        properties:
          type: object
          description: >-
            Object that defines all of the properties which can exist for
            objects of the given type
          patternProperties:
            .*:
              description: >-
                property value that is part of the json schema for objects of
                the given type
          additionalProperties: false
        additionalProperties:
          description: >-
            Flag set to signify if there should be additional properties allowed
            when performing json schema validation
      additionalProperties: true
      description: Defines the schema for objects of this type
    isProtectedType:
      type: boolean
      description: >-
        Defines whether the type is protected and only system could create its
        objects
    allowedLayers:
      type: array
      items:
        type: string
        enum:
          - LOCALUSER
          - ACCOUNT
          - GLOBALUSER
          - TENANT
          - SOLUTION
        description: Layer value at which the object can be edited
      description: >-
        Final scope reflects the level to which this object could be edited.
        Beyond that it is readonly
    referenceQualifiers:
      type:
        - object
        - 'null'
      patternProperties:
        ^\$\..*:
          type: array
          items:
            type: string
            description: Path where the property that is referenced is defined
      additionalProperties: false
      description: Defines the reference properties
    blobProperties:
      anyOf:
        - type: array
          items:
            type: string
            description: Blob property to be stored in object store
          description: >-
            [DEPRECATED] Array of blob properties with json paths as the string
            values. Blobs will be stored in object store
        - type: object
          patternProperties:
            ^\/\.*:
              type: object
              properties:
                contentTypesAllowed:
                  type: array
                  items:
                    type: string
                    description: Allowed mime types. Skip property for no restrictions.
                  uniqueItems: true
                maxContentSize:
                  type: string
                  description: Max content size permissible in bytes(base 2).
              required:
                - maxContentSize
          additionalProperties: false
          description: Defines the blob properties
    referenceProperties:
      type:
        - object
        - 'null'
      patternProperties:
        ^\/\.*:
          type: object
          properties:
            types:
              type: array
              items:
                type: string
                description: FQTN that reference object can belong to
                example: 'extensibility:solution, fmm*:entity, *'
              description: List of FQTNs that reference object can belong to
            optional:
              type: boolean
              description: Indicates if the property is mandatory or not
          additionalProperties: false
      additionalProperties: false
      examples:
        - /solutionInfo:
            types:
              - 'extensibility:solution'
              - 'environment:solution'
            optional: false
          /subscriptionInfo:
            types:
              - 'environment*:subscription'
            optional: true
          /entityInfo:
            types: '*'
            optional: false
      description: Defines the reference properties
    secureProperties:
      type: array
      items:
        type: string
        description: Secure property to be stored in secret vault
      description: >-
        Array of secure properties with json paths as the string values. Secure
        properties will be stored in a secret vault
    propertyMutableLayers:
      type: object
      patternProperties:
        ^\$\..*:
          type: array
          items:
            type: string
            enum:
              - LOCALUSER
              - ACCOUNT
              - GLOBALUSER
              - TENANT
              - SOLUTION
            description: Layer value at which the object can be edited
      description: >-
        This is an object that defines the layers at which each property is
        modifiable
      nullable: true
      additionalProperties: false
    identifyingProperties:
      type: array
      items:
        type: string
        pattern: ^/.*$
        description: JSONPointer of the identifying properties
      minItems: 1
      maxItems: 3
      uniqueItems: true
  additionalProperties: false

Knowledge Type Definition Example

Expand

json

yaml

Copy{
  "name": "synthconfig",
  "identifyingProperties": [
    "/name"
  ],
  "allowObjectFragments": true,
  "allowedLayers": [
    "SOLUTION",
    "TENANT",
    "LOCALUSER"
  ],
  "blobProperties": {
    "/address/homepic": {
      "contentTypesAllowed": [
        "application/javascript"
      ],
      "maxContentSize": "10000"
    },
    "/profilepic": {
      "contentTypesAllowed": [
        "application/javascript"
      ],
      "maxContentSize": "10000"
    }
  },
  "referenceProperties": {
    "/address/city": {
      "types": [
        "location:city"
      ],
      "optional": true
    }
  },
  "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"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "Name of synth config"
      },
      "params": {
        "type": "string",
        "description": "params 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"
          }
        },
        "description": "Array of params to be passed to the e2e test"
      }
    },
    "additionalProperties": true
  }
}

Copyname: synthconfig
identifyingProperties:
- "/name"
allowObjectFragments: true
allowedLayers:
- SOLUTION
- TENANT
- LOCALUSER
blobProperties:
  "/address/homepic":
    contentTypesAllowed:
    - application/javascript
    maxContentSize: '10000'
  "/profilepic":
    contentTypesAllowed:
    - application/javascript
    maxContentSize: '10000'
referenceProperties:
  "/address/city":
    types:
    - location:city
    optional: true
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
  properties:
    name:
      type: string
      description: Name of synth config
    params:
      type: string
      description: params 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
      description: Array of params to be passed to the e2e test
  additionalProperties: true

Knowledge Type Definition Properties

The following table displays the list of properties for a knowledge type definition:

Property	Description
`name`	A string representing the name of the knowledge type. Knowledge type names: Must adhere to the regular expression syntax of `^[a-zA-Z][a-zA-Z0-9]*$`. Can contain a maximum of 25 characters.
`allowedLayers`	A string array specifying the layers on which the knowledge object can exist. Accepted values: `SOLUTION`, `TENANT`, `LOCALUSER`. For more information on layering, see Layers.
`identifyingProperties`	The value of `identifyingProperties` is an array of JSONPath properties that are used to form the identity of an object. If the array contains a single property, e.g. ["/name"], the identity is the same as the value of the `name` property in the object data. Only the fields that are defined in the object data can be used to generate object IDs. If the `identifyingProperties` array contains multiple properties, e.g. ["/name", "/qualifier"], the identity will be `name=<valueOfName>;qualifier=<valueOfQualifier>`, where: `<valueOfName>` is the value of the name property in the object data `<valueOfQualifier>` is the value of the qualifier property in the object data In addition to the above rules, if the object belongs to the `SOLUTION` layer, the identity will be prefixed with `<solutionName>:`, where `<solutionName>` is the solution bundling the object.
`jsonSchema`	The JSON schema definition representing the desired data structure of your knowledge type.
`displayNameGenerationMechanism`	A string that defines the method for generating a custom display name for objects of this type.
`allowObjectFragments`	A boolean value that defines whether or not patching knowledge objects to create object fragments is allowed. If set to `false`, you can only create complete objects, not patched objects that override values at a lower layer. See Layers.
`isProtectedType`	A boolean value that defines whether or not the knowledge type is protected. If set to `true`, only the solution will be able to generate objects of this type and users will not be able to create objects via the REST API.
`propertyMutableLayers`	An object that enables you to control which properties are mutable at certain layers. For example, if you only want users to be able to change a certain property at the `LOCALUSER` layer, that property and layer must be defined in the `propertyMutableLayers` object. The keys inside the `propertyMutableLayers` object must follow the format of `$.propertyName` and the value must be an array of the layers at which the property is mutable.
`secureProperties`	A property that defines if the property value of a knowledge object is stored as a secret in an external secrets vault. See Manage Secrets in the Knowledge Store.
`additionalProperties`	A boolean value that specifies whether your schema is open-ended or strict. Set the value to `true` to specify that your schema is open-ended, meaning that you can have additional fields on knowledge objects that are not specified in the knowledge type schema. Set the value of this property to `false` to specify that your schema is strict. We recommend setting this property to `false`.
`blobProperties`	Specifies if there are blob properties in the knowledge type. A blob property is a property value stored in blob storage outside of the Knowledge Store. Storing a property value in a blob enables you to store larger and non-ASCII properties like images, configuration files, and other data types that cannot be easily stored in other knowledge type properties. The value of `blobProperties` is a map where: The key of the entry contains the JSONPath of the property that holds the blob. The value of the entry is an object with the following optional attributes: (Optional) `contentTypesAllowed`: An array of strings that specifies the allowed content type(s) for that blob. (Optional) `maxContentSize`: A string that specifies the maximum allowed file size in the blob property. The maximum file size supported is 1 GB. To create a knowledge object with a blob property, see Knowledge Object with Blob Properties.
`referenceProperties`	Specifies properties that refer to knowledge objects of the same knowledge type or other knowledge types in the Knowledge Store. Reference properties can be used to prevent duplication of information. The value of `referenceProperties` is a string array of JSON pointers to properties with the following attributes: `types`: Can be a FQTN or an array of FQTNs to indicate the possible knowledge types of the object the property can refer to. 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. For more information on using references, see Use References in Knowledge Types and Objects.