Kinds

[joschne]

Problem Description

We found that Toolbox users often fail to identify existing Geographical Places and create duplicates. One of the reasons why they fail is the language of labels in the community version of entity previews. This has to be discussed in another issue. We belief the main reason for the failure is the current way of associating Geographical Places with Types. This is discussed here.

Example

The following example illustrates the problem:

Let's assume there was a medieval village called "Foo". The village grew and became a city in modern times.

Geovistory Project A works on medieval history and creates a Geographical Place "Foo" with type "Village".

Geovistory Project B works on contemporary history and starts adding a Geographical Place "Foo". It sees the existing Geographical Place "Foo - Village". Although this is in fact the same entity, Project B identifies "Foo - Village" as a different entity, because it considers "Foo" to be a city. Project B creates a second instance "Foo - City".

Problem Analysis

• Problem A: Village is not a Type but a classification that describes the Geographical Place for a certain time. This issue was solved by introducing the sdh:C48 Geographical Place Classification class (see below) that allows to express a time related classification of a Geographical Place (as generally considered suitable by researchers — but different classifications are possible)

• Problem B: The type Village is not identifying. Today Toolbox projects are free to manage the controlled vocabulary of Geographical Place Types but they are not aware of the implications on the identification of Geographical Places by other projects/users. Therefore the projects should not be in the position of defining the controlled vocabulary used to type Geographical Places (as they can today).

We see that Problem B also applies to "sources classes" like Manifestation Singleton (Archival Record) and their types like "artwork", "manuscript", "letter". Here we mitigated the problem by copying a set of Types to each new Project on creation. Nevertheless a Project can change its controlled vocabulary of Manifestation Singleton Type at any time.

The fact that the problem is not uniquely related to Geographical Places demands a generic solution that allows us to configure the system according to our needs.

Current model

flowchart

  geoplace[crm:C13 Geographical Place]
  geoplacetype[crm:C14 Geographical Place Type]
  geoplace-->| crm:P2 has type|geoplacetype

Proposed Solution

Proposed model

flowchart

  gp[crm:C13 Geographical Place]
  gpt[crm:C14 Geographical Place Type]
  gpc[sdh:C48 Geographical Place Classification]
  gpk[sdh:C51 Geographical Place Kind]

  gpc-->|sdh:P63 classifies|gp
  gpc-->|sdh:P64 classifies with|gpt
  gp-->|sdh:P20 has kind| gpk

We propose to address Problems A and B so:

• Resolving Problem A: The time related classification of a Geographical Place is modeled with sdh:C48 Geographical Place Classification (subclass of C30 Connotation) associating the Geographical Place with a Geographical Place Type and a Time Span. Toolbox users are still free to manage the controlled vocabulary of Geographical Place Types. But these Types are not used to type the Geographical Place but to classify it. This solution is already implemented as standard in the Toolbox.

• Resolving Problem B: For the identification of a Geographical Place it may nevertheless be important to have more information than a name (due to homonyms). We therefore add a property "has identifying type" (in fact with reuse the sdh:P20 has identifying geographical place type as it has the same meaning) associating the Geographical Place with a Geographical Place Kind. The controlled vocabulary of Geographical Place Kind is not managed by the project but by the Geovistory team.

Requirements Specs

The proposed solution implies a major feature (epic) for the Toolbox that could be called "platform vocabularies".

The requirements of "platform vocabularies" can an be broken down into smaller issues:

Define a project for controlled vocabularies of Kind instances

In the system configuration, Geovistory admins can define a Geovistory project (id) that has the exclusive permission to add, edit and delete instances of sdh:C50 Kind-subclasses.

In the following description, this a configuration is called a platform-vocabulary-config. A platform-vocabulary-config consists of a parent_or_ancestor_class_id and a project_id. A class with a matching parent or ancestor class is called a platform-vocabulary-class and the project is called a platform-vocabulary-project.

A platform-vocabulary-config has a set of implications in the UI, as described below.

Add entity menu

A platform-vocabulary-class is excluded from the menu for all projects except for the platform-vocabulary-project.

Add statement dialog

Add statement dialog pointing to a platform-vocabulary-class has to:

• disable the left part of the dialog where users can create a new instance.
• search in the platform-vocabulary-project

Once a platform-vocabulary-class instance like "Settlement" is selected, a statement (here "has-kind") is added to the project referencing the selected instance. While the statement is added to the project, the referenced instance is not added to the project.

It has to be defined, what label to show in the list. From a user perspective the displayed label and description should be in the language of the user project (or english as a fallback).

For the admins of a platform-vocabulary-project it seems possible to curate labels and definitions for a set of important platform languages (like english, french, german, italian).

We currently have no language-aware entity previews. Currently we have at hand: One entity-preview generated for the platform-vocabulary-project, one generated for the community. The labels of both depend on the favorite label selected by platform-vocabulary-project and are independent of the language.

Thus we need multi-language support on community entity labels. This has to be defined in another ticket (as mentioned above), so that the list can show the community label in the project language (or english).

Implementation Plan

Phase 1

Prepare OntoME Profile for Phase 2:

• [x] Creation of the classes Kind et Geographical Place Kind (done)
• [x] Add a new OntoME profile in Geovistory project called Identifying Types (Temp)
• [x] In Geovistory (prod), create a project Vocabulary of Geographical Place Kinds
• [x] In Geovistory (prod), restrict profile Identifying Types (Kinds) to project Vocabulary of Geographical Place Kinds. This prevents other projects from activating the profile before Phase 2 is done.
• [x] In the profile Identifying Types (Kinds) add the class sdh:C51 Geographical Place Kind, activate the publication of the profile via API.

Phase 2

Create Vocabulary

• [x] In Geovistory (prod) project Vocabulary of Geographical Place Kinds, activate the profile Identifying Types (Kinds) and create the instances of Geographical Place Kind. [SH]

Develop Toolbox

• [x] In Geovistory (dev) system config add a new setting "platformVocabularies" allowing to add pairs of platform-vocabulary-class-id and platform-vocabulary-project-id, referencing the Kind class and the project that manages the vocabulary.
• [x] Load the kind instances (like the has type instances) for each platform-vocabulary-config into memory on startup (similar to QTypesOfProject)
• [x] In the view-field-add-hooks add a hook for platform-vocabulary-classes and open an interface to select the existing kind instances. This interface can load the community entity previews for all instances of the class registered in memory.
• [x] On select, it removes existing statements of that source entity and add a new one, without adding the kind instance itself.
• [x] In add entity menu, exclude platform-vocabulary-class for all projects except for the platform-vocabulary-project, so that projects can't create own instances.
• [x] In settings -> controlled vocabularies, exclude platform-vocabulary-class for all projects except for the platform-vocabulary-project
• [x] Deploy to prod
• [x] Configure System of Prod by adding this snippet: "platformVocabularies": [ { "parentOrAncestorClassId": 1209, "projectId": <PROJECT_ID> } ]

Phase 3

Migrate the data and cleanup OntoME profiles:

• [x] Duplication of the information linked to sdh:P20 has identifying geographical place type to sdh:C48 Geographical Place Classification and related properties, so that in information documented is preserved. Insert 2 new statements and one classification entity for each statement of property sdh:P20 [GM]
• [x] Creation of a correspondence table between the vocabulary terms used by the different projects to the Kinds created in the phase 2 [SH & FB & VA]
• [x] Prepare OntoME Profile Geovistory Basics: Add class C51 Geographical Place Kind. This makes it available to all projects (readonly, as specified above). [SH & FB]
• [x] Modify the property sdh:P20 has identifying geographical place type in OntoMe so that it's linked to the class C51 Geographical Place Kind. [SH & FB]
• [x] Modify the statements with sdh:P20 property by replacing the target Place Type with the correponding Kind instance — and deleting, if needed, redundant statements about the same entity. Update the fk_object_info of the statements. [GM]
• [x] In OntoME profile Identifying Types (Temp): Remove the classes Geographical Place and Geographical Place Kind, and the properties XYZ and. [JS]
• [x] We keep the restriction of profile Identifying Types (Kinds) to project Vocabulary of Geographical Place Kinds for future "Kinds-migrations" [JS]
• [x] The Manual has to be updated. [SH]
• [x] E-Mail to the community. [SH]

[atterebf]

From Stephen Hart's comment (https://github.com/Semantic-Data-for-Humanities/Alignement_symogih.org/issues/30#issuecomment-1521325705) with some FB changes:

Because statements need to be preserved in the Geovistory model, it is important that the shift from sdh:P20 has identifying geographical place type to Geographical Place Kind is done in different steps:

1. Creation of the classes Kind and Geographical Place Kind (done)
2. Duplication of the information linked to sdh:P20 has identifying geographical place type to [sdh:C48 Geographical Place Classification] (https://ontome.net/class/1076/namespace/3) and related properties, so that in information documented is preserved.
3. Creation of the Kind vocabulary, and creation of the C51 Geographical Place Kind instances
4. Creation of a correspondence table between the vocabulary terms used by the different projects to the Kinds created in the step 3
5. Modify the property sdh:P20 has identifying geographical place type in OntoMe so that it's linked to the instances of C51 Geographical Place Kind.
6. Modify the statements with sdh:P20 property by replacing the target Place Type with the correponding Kind instance — and deleting, if needed, redundant statements about the same entity

This should allow the preservation of the statements.

[joschne]

@atterebf I added an implementation plan with 3 phases (see above).

Can you please review this part?

[joschne]

as reported by @atterebf, this button must be hidden.