Discover 25.2
Discover Help

# Define the Entity Schema

OpenText recommends that you define the schema for the graph database before you deploy the application. After you deploy Discover for the first time, there are limitations on how the schema can be modified.

You can:

- create and delete entity types and link types
- create and delete allowed links between entity types
- create and delete properties
- change metadata fields such as description and isTitle

But you cannot:

- add a required property to an existing entity type
- change an existing property from optional to required

To extend the default schema, modify the file `data/entity/custom.yaml`.

## Example Custom Schema

The following example extends the "person" entity in the default schema:

Copy

    entities:

      PersonEntity:
        description: A human.
        category: Entity
        extension: true
        properties:
          name:
            isTitle: true
            required: true
            filterable: true
            valueSchema:
              type: string
          bio:
            searchable: true
            valueSchema:
              type: string
          profession:
            filterable: true
            sortable: true
            canAggregate: true
            valueSchema:
              type: string
          age:
            filterable: true
            sortable: true
            valueSchema:
              type: integer
          employment:
            filterable: true
            sortable: true
            canAggregate: true
            valueSchema:
              type: string
              enum:
                - Full time
                - Part time
                - Unemployed

        links:
          entities:
            PersonEntity:
              - Knows

    links:
      Knows:
        multiplicity: many-to-many
        category: Entity

## Schema Properties

Entities are configured in the `entities` section of the configuration file, which maps entity type IDs to type definitions. By convention, entity type IDs are in title case and end with "Entity" - for example, `PersonEntity`. OpenText recommends that entity type IDs contain only alphabetical characters. An entity type definition can include:

- description

- category: set the category to one of the following values:

  - `Entity` - for most user-facing entities, such as people and locations
  - `Document` - represents a document of some form: a web page, social media post, PDF and so on
- extensible: whether this type may be extended with required properties (default: true). Some of the entities in the default schema can be extended, but you cannot add additional required properties to them if this is `true`.
- extension: set to true to extend an existing entity (default: false)

- properties: a map from property name to property definition. OpenText recommends that property names contain only alphabetical characters. Each property definition can include:

  - description

  - valueSchema: A JSON Schema restricting allowed values. You might set this property to:

    - `boolean`
    - `integer`
    - `number`
    - `string` (if the string represents a date you can also set `format: date-time`)
    - `geo`
    - `object` (does not support filtering by keys or values)
    - `array` (set the `items` property to one of these types - except `array`).
  - sortable: whether to allow sorting by values of this property (default: false). The following types can be sorted: `boolean`, `integer`, `number`, `string`, `date`.
  - filterable: whether to allow filtering by values of this property (default: false). The following types support filtering: `boolean`, `integer`, `number`, `string`, `date`, `geo`.
  - searchable: whether to allow searching for values of this property (to search, the property must be of type `string`) (default: false)
  - required: whether all entities of this type must have a value for this property (default: false)
  - isTitle: whether this property should be treated as a title for the entity, for use in displaying or previewing it. To set this to `true`, the property must be a string.

  - canAggregate: whether to allow grouping entities by the value of a property (similar to a parametric field in your IDOL index). The default is true for filterable integers, numbers, booleans, dates, and enum strings, otherwise false. This cannot be true for arrays.

    NOTE: Setting this to true for a string property allows clients to retrieve all values of the property, even values for entities the user doesn't have access to.

- links:

  - baseEntities: a list of link types which can be used to link from this entity type to any type of entity
  - entities: this entity type can link to the entity types listed here. This is a map from allowed entity types to a list of allowed link types

Links between entities are configured in the `links` section of the configuration file, which maps link type IDs to type definitions. OpenText recommends that link type IDs contain only alphabetical characters. A link type definition can include:

- description

- category: set the category to one of the following values:

  - `General` - links with a general meaning, such as 'A contains B'
  - `Entity` - links specific to user-facing entities, such as events and organizations

- multiplicity: restricts how many links of this type may connect to the same entity in the same direction.

  - `one-to-one` - an entity may have at most one incoming or outgoing link
  - `one-to-many` - an entity may have at most one incoming link
  - `many-to-one` - an entity may have at most one outgoing link
  - `many-to-many` - no restrictions

- properties: you can add properties to links, the same as for entities

Copyright 2021-2025 Open Text
Version 25.2 | Last updated April 2025

Send documentation feedback

Close

Send documentation feedback

To send feedback using your default email client, open an email window.

Otherwise, send your feedback and the information below to MFI-swpdl.idoldocsfeedback@opentext.com.

We appreciate your feedback!

Product: Knowledge Discovery Discover 25.2

Topic Title: Define the Entity Schema