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:
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 locationsDocument
- 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 setformat: date-time
)geo
object
(does not support filtering by keys or values)array
(set theitems
property to one of these types - exceptarray
).
- 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 linkone-to-many
- an entity may have at most one incoming linkmany-to-one
- an entity may have at most one outgoing linkmany-to-many
- no restrictions
-
properties: you can add properties to links, the same as for entities