Migration Guide¶

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.

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.

Migration steps¶

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.

           

      • 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.

           

      • 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
                  }
              }
          }