Migration Guide

To migrate breaking changes and deprecations introduced during the various releases of the Ontotext Metadata Studio, please follow the guide below.

Ontotext Metadata Studio 3.2.0 to 3.2.1

The following changes concerning the SOML schema have been introduced:

  • A new sys:label property is added to all ObjectClass SOML entities.

Note

The new property addition requires updating and reloading the SOML schema after completing the migration process. See how to do it in the Apply changes and reload SOML schema section below.

Migration steps

  • For the new sys:label property: If you are using the base schema and all changes are applied through GraphQL mutations, it is enough to just reload the base schema as described in the Apply changes and reload SOML schema section.

    1. Update the SOML schema when using a custom schema.

      1. Add the sys:label special prefix to sys:ObjectClass and sys:Property props section. See the snippet below:

        sys:ObjectClass:
                inherits: sys:SomlExtension
                descr: "Base class for extending SOML with new Objects"
                pattern: "${sys_id}"
                props:
                  sys:id: {min: 1, descr: "ID of the Object in the SOML"}
                  sys:kind: {descr: "Abstract or not", valuesIn: ["abstract", "object"]}
                  sys:inherits: {range: iri, descr: "Class to inherit from"}
                  sys:label: {descr: "Label of the Object in the SOML"}
                  sys:descr: {descr: "Description or clarification"}
                  sys:type: {max: inf, descr: "Array of type value IRIs (prefixed, relative, or absolute)"}
                  sys:typeProp: {descr: "Property that determines the business type"}
                  sys:sparqlFederatedService: {descr: "The ID of a SPARQL Federation Service"}
                  sys:meta: { range: sys:Meta, max: inf, descr: "Adds an additional meta directive in the GraphQL schema for the given property" }
                  sys:props: {range: sys:Property, max: inf, descr: "Array of Properties of the Object"}
        
          sys:Property:
                inherits: sys:SomlExtension
                descr: "Class representing a Property for SOML Extension"
                props:
                  sys:id: {min: 1, descr: "ID of the Property in the SOML"}
                  sys:label: {descr: "Label of the Property in the SOML"}
                  sys:descr: {descr: "Description or clarification"}
                  sys:rdfProp: {descr: "RDF property name (if not allowed in GraphQL or hard to read) or SPARQL Template"}
                  sys:range: {descr: "Datatype or SOML object type"}
                  sys:min: {range: int, descr: "Minimum number of values, integer (mutations)"}
                  sys:max: {descr: "Maximum number of values, integer. inf means unlimited (mutations)"}
                  sys:restrictive: {range: boolean, descr: "Controls the SPARQL generation. Properties set as true would not generate OPTIONAL"}
                  sys:meta: {range: sys:Meta, max: inf, descr: "Adds an additional meta directive in the GraphQL schema for the given property"}
        
      2. Update the project.

    2. Reload the schema.

Ontotext Metadata Studio 3.1.0 to 3.2.0

The following changes concerning the SOML schema have been introduced:

  • A new vocabIri special prefix: Used as an IRI prefix when SOML entities are generated and stored in GraphDB.
  • A new ObjectClass class: Used for creating SOML classes.

Note

The vocabIri special prefix change requires updating and reloading the SOML schema after completing the migration process. See how to do it in the Apply changes and reload SOML schema section below.

Furthermore, GraphQL mutations for creating, updating, and deleting Annotation classes or Document classes have a new syntax.

Note

The GraphQL mutation syntax change requires an update on the mutations that call the Metadata Studio Service directly, if such exist.

Migration steps

  • For the new vocabIri special prefix and ObjectClass class: If you are using the base schema and all changes are applied through GraphQL mutations, it is enough to just reload the base schema as described in the Apply changes and reload SOML schema section.

    1. Update the SOML schema when using a custom schema.

      1. Add the vocabIri special prefix to the specialPrefixes section and update the sys:ObjectClass as shown below:

        specialPrefixes:
          vocab_prefix: voc
        
        sys:ObjectClass:
          inherits: sys:SomlExtension
          descr: "Base class for extending SOML with new Objects"
          pattern: "${sys_id}"
          props:
            sys:id: {min: 1, descr: "ID of the Object in the SOML"}
            sys:kind: {descr: "Abstract or not", valuesIn: ["abstract", "object"]}
            sys:inherits: {range: iri, descr: "Class to inherit from"}
            sys:descr: {descr: "Description or clarification"}
            sys:type: {max: inf, descr: "Array of type value IRIs (prefixed, relative, or absolute)"}
            sys:typeProp: {descr: "Property that determines the business type"}
            sys:sparqlFederatedService: {descr: "The ID of a SPARQL Federation Service"}
            sys:meta: { range: sys:Meta, max: inf, descr: "Adds an additional meta directive in the GraphQL schema for the given property" }
            sys:props: {range: sys:Property, max: inf, descr: "Array of Properties of the Object"}
        
      2. Update the project.

    2. Reload the schema.

  • For the Annotations and Documents mutation change:

    1. Update your mutations following the examples below:

      • Create mutation:

        mutation create {
            create_sys_ObjectClass(objects: [
                {
                    sys_id: "PersonAnnotation"
                    sys_inherits: "voc:InlineAnnotation"
                }
            ]) {
                sys_ObjectClass {
                    id
                }
            }
        }
        
      • Update mutation:

        mutation update {
            update_sys_ObjectClass(where: {ID: ["http://example.com/PersonAnnotation"]}) {
                sys_ObjectClass {
                    id
                }
            }
        }
        
      • Delete mutation:

        mutation delete {
            delete_sys_ObjectClass(where: {ID: ["http://example.com/PersonAnnotation"]}) {
                sys_ObjectClass {
                    id
                }
            }
        }
        
    2. Execute the new mutations.

Ontotext Metadata Studio 3.0.0 to 3.1.0

An optional setting for default sort field of Document annotations has been introduced to the SOML schema. See here for more details.

A new ExternalService class has been introduced in the SOML schema. It defines the configured SPARQL federated services in Metadata Studio. The class is used in the Project class where a new property externalService is introduced. See here for more details.

Note

The External service change requires updating and reloading the SOML schema after completing the migration process. See how to do it in the Apply changes and reload SOML schema section below.

Note

During upgrade of the Ontotext Metadata Studio to a newer version (or just a different version in general), the base schema will be automatically updated in case there are any changes to it in the new version.

If you do not want to update the default schema, you need to set the omds.update.default.schema property in the values.overrides.yaml file to false like this:

service:
  configuration:
    omds.update.default.schema: "false"

After the upgrade, the old schema version will be backed up with ID /soml/mant_<previous-version>.

Migration steps

Hint

If you are using the base schema and all changes are applied through GraphQL mutations, it is enough to just reload the base schema as described in the Apply changes and reload SOML schema section.

  1. Update the SOML schema when using a custom schema.

    1. Add the ExternalService class:

      ExternalService:
        type: omds:ExternalService
        props:
          label:
            label: "External service name"
            min: 1
          url:
            label: "External service address"
            min: 1
      
    2. Add the externalService field to the Project class:

      Project:
        inherits: Timesensitive
        type: omds:Project
        props:
          label: {label: "Label", meta: {search: {visible: true, order: 1}, form: {visible: true}}}
          status: {label: "Status", meta: {search: {visible: true, order: 2}, form: {visible: true}}}
          metadata: {meta: {search: {visible: false}, form: {visible: false}}}
          corpus: {range: Corpus, max: inf, rdfProp: omds:corpus, meta: {search: {visible: false}, form: {visible: false}}}
          logo: {range: iri, rdfProp: omds:logo, meta: {search: {visible: false}, form: {visible: false}}}
          externalService: {range: ExternalService, max: inf, meta: {search: {visible: false}, form: {visible: false}}}
      
    3. Add the externalService property to the metadata field meta of all Concepts with defined sparqlFederatedService. The name of the service must match sparqlFederatedService.

      Person:
        inherits: Concept
        sparqlFederatedService: wikidata
        props:
          metadata: { meta: { externalService: "wikidata"} }
      
    4. Reload the schema.

  2. Update the project.

    1. Configure the services that are external to the project.

      • Using the Metadata Studio UI:

        1. Open the Projects View.

        2. Click the Configure project settings icon under Actions.

        3. Add all external services to the project via the Create new button.

          _images/add-external-service.png
      • Using a mutation:

        mutation CreateExternalService(
            $projectId: [ID!]
            $externalServiceName: String
            $externalServiceUrl: String
        ) {
            update_Project(
                where: { ID: $projectId }
                objects: {
                    externalService: {
                        externalService: {
                            label: $externalServiceName
                            url: $externalServiceUrl
                        }
                    }
                }
            ) {
                project {
                    externalService {
                        id
                        label
                        url
                    }
                }
            }
        }
        
    2. Update the Concept classes with the corresponding external service.

      • Using the Metadata Studio UI:

        1. In the Manage schema view, open the Extend class view of the Concept class.

        2. In the Class details ‣ SPARQL federated service field, select the corresponding external service.

          _images/update-concept-class-with-external-service.png
      • Using a mutation:

        • For all Concept classes that have metadata field, execute the following mutation:

          mutation createConceptMetadata(
              $classId: [ID!]
              $externalServiceName: String
          ) {
              update_Concept_Class(
                  where: { ID: $classId }
                  objects: {
                      sys_props: {
                          sys_Property: {
                              sys_id: "metadata"
                              sys_meta: {
                                  sys_Meta: { sys_key: "externalService", sys_values: $externalServiceName }
                              }
                          }
                      }
                  }
              ) {
                  affected_count {
                      kind
                      count
                  }
              }
          }
          
        • For all Concepts that do NOT have a metadata field, execute the following mutation:

          mutation UpdateConceptMetadata(
              $classId: [ID!]
              $externalServiceName: String
          ) {
              update_Concept_Class(
                  where: { ID: $classId }
                  objects: {
                      sys_props: {
                          where: { sys_id: { EQ: "metadata" } }
                          sys_Property: {
                              sys_meta: {
                                  replace: true
                                  sys_Meta: { sys_key: "externalService", sys_values: $externalServiceName }
                              }
                          }
                      }
                  }
              ) {
                  affected_count {
                      count
                      kind
                  }
              }
          }
          

Apply changes and reload SOML schema

Important

This step applies to every migration process regardless of the Metadata Studio version.

  • If using the base SOML schema and all changes are done through GraphQL mutations:

    1. Delete the otp-system system repository.
    2. Restart Metadata Studio.
  • If using a custom SOML schema, reload it as follows:

    1. Retrieve the SOML schema from the service:

      curl --location -X GET 'http://hostname/service/soml/{schemaName}' \
          -H 'X-Request-ID: some-uuid-correlation-id' \
          -H 'Accept: text/yaml' \
          -H 'Authorization: Bearer {validToken}'
      
    2. Apply any changes to the SOML schema.

    3. Upload the SOML schema to the service:

      curl --location -X PUT 'http://hostname/service/soml/{schemaName}' \
          -H 'Content-Type: text/yaml' \
          -H 'X-Request-ID: some-uuid-correlation-id' \
          -H 'Accept: application/ld+json' \
          -H 'Authorization: Bearer {validToken}' \
          -T schema.yaml