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