CINXE.COM

<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-11346334-10']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script> <title>Configuration — Metadata Studio 3.11.0 documentation</title> <link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="stylesheet" href="_static/css/bootstrap.min.css" type="text/css" /> <link rel="stylesheet" href="_static/css/bootstrap-ontotext-theme.css" type="text/css" /> <link rel="stylesheet" href="_static/css/custom.css" type="text/css" /> <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> <script src="_static/jquery.js"></script> <script src="_static/underscore.js"></script> <script src="_static/doctools.js"></script> <script src="_static/language_data.js"></script> <script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Usage" href="usage.html" /> <link rel="prev" title="Installation" href="installation.html" /> <meta charset='utf-8'> <meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'> <meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'> <meta name="apple-mobile-web-app-capable" content="yes">  <link rel="apple-touch-icon" sizes="180x180" href="/omds/3.11/_static/apple-touch-icon.png"> <link rel="icon" type="image/png" sizes="32x32" href="/omds/3.11/_static/favicon-32x32.png"> <link rel="icon" type="image/png" sizes="16x16" href="/omds/3.11/_static/favicon-16x16.png"> <link rel="manifest" type="application/manifest+json" href="/omds/3.11/_static/site.webmanifest"> <script src="/omds/3.11/_static/js/jquery-1.12.4.min.js"></script> <script src="/omds/3.11/_static/js/jquery-fix.js"></script> <script src="/omds/3.11/_static/bootstrap-sphinx.js"></script>  <script src="https://cdnjs.cloudflare.com/ajax/libs/tether/1.4.0/js/tether.min.js" integrity="sha384-DztdAPBWPRXSA/3eYEEUWrWCy7G5KFbe8fFjk5JAIxUYHKkDx6Qin1DkWx51bBrb" crossorigin="anonymous"></script> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.6/js/bootstrap.min.js" integrity="sha384-vBWWzlZJ8ea9aCX4pEW3rVHjgjt7zpkNpZk+02D9phzyeVkE+jo0ieGizqPLForn" crossorigin="anonymous"></script> <script type="text/javascript"> //temporary solution to remove sphinx css $(document).ready(function() { $("link[href*='basic.css']").remove(); $("link[href*='bootstrap-sphinx.css']").remove(); }); //hide the other collapsible elements on collapsing a menu item var $myGroup = $('#side-menu-accoridion'); $myGroup.on('show.bs.collapse','.collapse', function() { $myGroup.find('.collapse.show').collapse('hide'); }); $(function () { $('[data-toggle="tooltip"]').tooltip(); $('#scrollToTop').click( function() { $('html, body').animate({scrollTop: '0px'}, 300); }); }); </script>  <script src="https://cdn.jsdelivr.net/react/15.4.2/react.min.js"></script> <script src="https://cdn.jsdelivr.net/react/15.4.2/react-dom.min.js"></script> <script src="https://cdn.jsdelivr.net/gh/jazzyray/sphinx-graphiql@master/static/graphiql/graphiql.min.js"></script> <link href="https://cdn.jsdelivr.net/gh/jazzyray/sphinx-graphiql@master/static/graphiql/graphiql.css" rel="stylesheet"> <link href="https://cdn.jsdelivr.net/gh/jazzyray/sphinx-graphiql@a048f5e9c6fb3932d7ba3bcea8c56e1d918903d0/static/styles.css" rel="stylesheet"> <script type="text/javascript"> // graphql query fetcher const graphQLFetcher = function(endpoint, token, insecure) { endpoint = endpoint || "https://swapi-platform.ontotext.com/graphql"; insecure = insecure || false return function(graphQLParams) { const params = { method: 'post', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + token }, body: JSON.stringify(graphQLParams), credentials: 'include', insecure: true, }; return fetch(endpoint, params) .then(function (response) { return response.text(); }) .then(function (responseBody) { try { return JSON.parse(responseBody); } catch (error) { return responseBody; } }); } }; // create GraphiQL components and embed into HTML const setupGraphiQL = function() { if (typeof(React) === 'undefined' || typeof(ReactDOM) === 'undefined' || typeof(GraphiQL) === 'undefined') { return; } const targets = document.getElementsByClassName('graphiql'); for (let i = 0; i < targets.length; i++) { const target = targets[i]; const endpoint = target.getElementsByClassName("endpoint")[0].innerHTML.trim(); let token = target.getElementsByClassName("token") if ((token === null) || (token[0].innerHTML.trim() === "")) { // No token so default it to a pre-baked ReadOnly Token // Expires 20 April 2022 token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkhYajdRQndWRzVPVERuMjlobWJsUDZLVHVKLTZZdnpUIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE2NTA4NjAwNjAsImlhdCI6MTU4Nzc0NjE1NiwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiMDNhNDlkZjQtMGQwOS00NmNmLWFhNWUtNjVhNzNiNmYxN2ZmIiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXX0.iZiHf-vgNddiNOCBXT6cdYDOnpR_fk1EQn6UICBTETY" } else { token = token[0].innerHTML.trim(); } const insecure = target.getElementsByClassName("insecure")[0].innerHTML.trim(); const query = target.getElementsByClassName("query")[0].innerHTML.trim(); const response = target.getElementsByClassName("response")[0].innerHTML.trim(); const graphiQLElement = React.createElement(GraphiQL, { fetcher: graphQLFetcher(endpoint, token, insecure), schema: undefined, query: query, response: response, token: token }); ReactDOM.render(graphiQLElement, target); } }; $(document).ready(function() { // if graphiql elements present, setup graphiql if (document.getElementsByClassName('graphiql').length > 0) { setupGraphiQL(); } }) </script> <meta name="msapplication-TileImage" content="/search/documentation/home/images/visual_Logo_GraphDB_02_12_2015.png"> </head><body> <div id="page"> <div id="sidebar" class="bs-sidenav bg-lightgray" data-spy="affix"> <div class="hidden-xs hidden-sm"> <div class="bg-secondary d-flex"> <a href="/omds/3.11/index.html" class="brand" title="Metadata Studio 3.11"> <img src="/omds/3.11/_static/metadata-studio.png" alt="Metadata Studio logo" height="44" class="logo"> 3.11 </a> <a class="ml-auto btn btn-primary hidden-lg-up d-flex" data-toggle="collapse" href="#collapseSideNav" aria-expanded="false" aria-controls="collapseExample"> </a> </div> <div id="collapseSideNav" class="hidden-mobile-nav"> <div class="p-3"> <form action="/omds/3.11/search.html" method="get"> <div class="input-group input-group-sm"> <input type="text" name="q" class="form-control" placeholder="Search the documentation..."> <input type="hidden" name="check_keywords" value="yes"> <input type="hidden" name="area" value="default"> </div> </form> <div class="mt-3"> <div class="dropdown d-inline-block"> <button class="btn btn-link dropdown-toggle p-0" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> Metadata Studio </button> <script type="text/javascript"> var xmlHttp = new XMLHttpRequest(); xmlHttp.open( "GET", "https://platform.ontotext.com/services.txt", false ); xmlHttp.send( null ); var services = xmlHttp.responseText; var servicesSplit = services.split("\n"); for (var i = 0; i < servicesSplit.length; i++) { var serviceSplit = servicesSplit[i]; if (serviceSplit.length !== 0) { document.write('<a class="dropdown-item" href="/' + serviceSplit.split(",")[1] + '">' + serviceSplit.split(",")[0] + '</a>'); } } </script> </div> </div> </div> <div class="sidebar-menu"> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="index.html">General</a></li> <li class="toctree-l1"><a class="reference internal" href="architecture-and-components.html">Architecture & Components</a></li> <li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">Configuration</a><ul> <li class="toctree-l2"><a class="reference internal" href="#introduction">Introduction</a></li> <li class="toctree-l2"><a class="reference internal" href="#classes-model">Classes Model</a><ul> <li class="toctree-l3"><a class="reference internal" href="#rdf-model">RDF model</a></li> <li class="toctree-l3"><a class="reference internal" href="#custom-document-classes">Custom document classes</a></li> <li class="toctree-l3"><a class="reference internal" href="#custom-annotation-classes">Custom annotation classes</a></li> <li class="toctree-l3"><a class="reference internal" href="#custom-concept-classes">Custom concept classes</a></li> <li class="toctree-l3"><a class="reference internal" href="#custom-form-classes">Custom form classes</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#creating-objects">Creating Objects</a><ul> <li class="toctree-l3"><a class="reference internal" href="#creating-projects">Creating projects</a></li> <li class="toctree-l3"><a class="reference internal" href="#creating-corpora">Creating corpora</a></li> <li class="toctree-l3"><a class="reference internal" href="#creating-documents">Creating documents</a></li> <li class="toctree-l3"><a class="reference internal" href="#creating-annotations">Creating annotations</a></li> <li class="toctree-l3"><a class="reference internal" href="#creating-forms">Creating forms</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#validating-objects">Validating Objects</a><ul> <li class="toctree-l3"><a class="reference internal" href="#validating-annotation-fields">Validating Annotation fields</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#conditional-objects">Conditional Objects</a><ul> <li class="toctree-l3"><a class="reference internal" href="#conditional-form-fields">Conditional Form fields</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#users">Users</a></li> <li class="toctree-l2"><a class="reference internal" href="#creating-annotation-services">Creating Annotation Services</a><ul> <li class="toctree-l3"><a class="reference internal" href="#registration-query">Registration query</a></li> <li class="toctree-l3"><a class="reference internal" href="#annotation-query">Annotation query</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#creating-external-services">Creating External Services</a><ul> <li class="toctree-l3"><a class="reference internal" href="#wikidata-external-service">Wikidata external service</a></li> <li class="toctree-l3"><a class="reference internal" href="#now-external-service">NOW external service</a></li> </ul> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="usage.html">Usage</a></li> <li class="toctree-l1"><a class="reference internal" href="release-notes.html">Release Notes</a></li> <li class="toctree-l1"><a class="reference internal" href="migration-guide.html">Migration Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="dependencies-and-license.html">Dependencies & License</a></li> <li class="toctree-l1"><a class="reference internal" href="support.html">Support</a></li> </ul> </div> <hr class="m-0"> <div class="sidebar-menu"> <ul id="side-menu-accoridion" role="tablist" aria-multiselectable="true"> <li class="toctree-l1"> <a data-toggle="collapse" data-parent="#side-menu-accoridion" href="#collapse7" aria-expanded="false" aria-controls="collapse7"> Previous versions </a> <ul id="collapse7" class="collapse" role="tabpanel" aria-labelledby="heading7" aria-expanded="true">  </ul> </li> </ul> </div></div> </div> </div> <div class="main-container pb-5"> <div class="container-fluid"> <div class="section" id="configuration"> <h1>Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline">¶</a></h1> <div class="contents local topic" id="what-s-in-this-document"> <cite>What’s in this document?</cite> <ul class="simple"> <li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li> <li><a class="reference internal" href="#classes-model" id="id2">Classes Model</a><ul> <li><a class="reference internal" href="#rdf-model" id="id3">RDF model</a><ul> <li><a class="reference internal" href="#objects-and-predicates" id="id4">Objects and predicates</a></li> </ul> </li> <li><a class="reference internal" href="#custom-document-classes" id="id5">Custom document classes</a></li> <li><a class="reference internal" href="#custom-annotation-classes" id="id6">Custom annotation classes</a><ul> <li><a class="reference internal" href="#documentannotation-classes" id="id7">DocumentAnnotation classes</a></li> <li><a class="reference internal" href="#inlineannotation-classes" id="id8">InlineAnnotation classes</a></li> </ul> </li> <li><a class="reference internal" href="#custom-concept-classes" id="id9">Custom concept classes</a></li> <li><a class="reference internal" href="#custom-form-classes" id="id10">Custom form classes</a></li> </ul> </li> <li><a class="reference internal" href="#creating-objects" id="id11">Creating Objects</a><ul> <li><a class="reference internal" href="#creating-projects" id="id12">Creating projects</a></li> <li><a class="reference internal" href="#creating-corpora" id="id13">Creating corpora</a></li> <li><a class="reference internal" href="#creating-documents" id="id14">Creating documents</a></li> <li><a class="reference internal" href="#creating-annotations" id="id15">Creating annotations</a><ul> <li><a class="reference internal" href="#applying-human-validation-workflow-to-annotations" id="id16">Applying Human Validation workflow to annotations</a></li> </ul> </li> <li><a class="reference internal" href="#creating-forms" id="id17">Creating forms</a></li> </ul> </li> <li><a class="reference internal" href="#validating-objects" id="id18">Validating Objects</a><ul> <li><a class="reference internal" href="#validating-annotation-fields" id="id19">Validating Annotation fields</a></li> </ul> </li> <li><a class="reference internal" href="#conditional-objects" id="id20">Conditional Objects</a><ul> <li><a class="reference internal" href="#conditional-form-fields" id="id21">Conditional Form fields</a></li> </ul> </li> <li><a class="reference internal" href="#users" id="id22">Users</a></li> <li><a class="reference internal" href="#creating-annotation-services" id="id23">Creating Annotation Services</a><ul> <li><a class="reference internal" href="#registration-query" id="id24">Registration query</a></li> <li><a class="reference internal" href="#annotation-query" id="id25">Annotation query</a></li> </ul> </li> <li><a class="reference internal" href="#creating-external-services" id="id26">Creating External Services</a><ul> <li><a class="reference internal" href="#wikidata-external-service" id="id27">Wikidata external service</a></li> <li><a class="reference internal" href="#now-external-service" id="id28">NOW external service</a></li> </ul> </li> </ul> </div> The following section describes how Metadata Studio can be configured with custom data and schema for a particular use case. It is to be used by users who integrate Metadata Studio in their specific projects and environments. <div class="admonition note"> Note This documentation does not attempt to describe deployment specifics. See <a class="reference internal" href="installation.html">here</a> for deployment instructions. </div> <div class="section" id="introduction"> <h2><a class="toc-backref" href="#what-s-in-this-document">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> As described in more detail in the application’s <a class="reference internal" href="architecture-and-components.html#architecture-and-components-data-model">data model</a>, the main objects in the Metadata Studio are: <ul class="simple"> <li>Users</li> <li>Projects</li> <li>Corpora</li> <li>Documents</li> <li>Annotations</li> <li>Concepts</li> <li>SavedReports</li> <li>Annotation Services</li> </ul> Metadata Studio configurations are kept in GraphDB. The configuration is split into two segments: <ul class="simple"> <li>The model of the configuration data #classes-model - defines the classes with which Metadata Studio works. It is described as a SOML schema.</li> <li>The concrete objects in a Metadata Studio installation - based on the defined schema model, objects can be created either through RDF or by applying runtime create objects mutations.</li> </ul> By default, no Annotation services are configured, so if you want to use third-party text mining API services, you would need to <a class="reference internal" href="#configuration-annotation-service-creation">configure them</a> as well. The following is a configuration example of a schema request body customized for our <a class="reference external" href="https://github.com/diffbot/knowledge-net">Knowledge Net</a> use case, which defines a specific simple document class and a Person inline annotation class that links to Wikidata people concepts. It comprises two segments: <ul id="configuration-default-schema"> <li>the default SOML schema <blockquote> <div><div class="admonition important"> Important This part of the schema is identical for all Metadata Studio projects. It is not recommended to modify it in any way. </div> <div class="highlight-yaml notranslate"><div class="highlight"><pre>id: /soml/knowledge-net label: MANT vocabulary created: 2021-08-13 versionInfo: 1.0 config: {lang: "ALL:en,NONE", implicit: "en", enable_mutations: true, disabledChecks: "rangeCheck", exposeSomlInGraphQL: true} prefixes: # common prefixes so: "http://www.ontotext.com/semantic-object/" dct: "http://purl.org/dc/terms/" gn: "http://www.geonames.org/ontology#" owl: "http://www.w3.org/2002/07/owl#" puml: "http://plantuml.com/ontology#" rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#" rdfs: "http://www.w3.org/2000/01/rdf-schema#" skos: "http://www.w3.org/2004/02/skos/core#" void: "http://rdfs.org/ns/void#" wgs84: "http://www.w3.org/2003/01/geo/wgs84_pos#" xsd: "http://www.w3.org/2001/XMLSchema#" sys: "http://ontotext.com/soml/" omds: "http://www.ontotext.com/metadatastudio#" usr: "http://www.ontotext.com/metadatastudio/user/" rev-status: "http://www.ontotext.com/metadatastudio/review-status/" wd: "http://www.wikidata.org/entity/" wdt: "http://www.wikidata.org/prop/direct/" inst: "http://www.ontotext.com/connectors/elasticsearch/instance#" elastic: "http://www.ontotext.com/connectors/elasticsearch#" specialPrefixes: vocab_prefix: voc base_iri: http://knowledge.net/ vocab_iri: http://knowledge.net/ properties: metadata: {range: Metadata, max: inf, rdfProp: omds:metadata} updateable: {range: boolean, min: 0, max: 1, rdfProp: omds:updateable} label: {rdfProp: rdfs:label, min: 1} status: {range: string, max: 1, rdfProp: omds:status, descr: "The object status, like ACTIVE or ARCHIVED etc."} types: reviewStatus: values: - {name: REJECTED, value: rev-status:Rejected, label: "Rejected"} objects: ### SOML Extension ### sys:SomlExtension: kind: abstract descr: "Base class for SOML Extension classes" props: sys:somlId: {descr: "ID of the SOML for which the Object is created"} sys:SpecialPrefixes: inherits: sys:SomlExtension descr: "Special prefixes (namespaces)" props: sys:baseIri: {descr: "Base IRI for data (resources), used in SOML characteristics such as type and prefix"} sys:vocabIri: {descr: "Default namespace for vocabulary (ontology) terms, i.e. object and prop names"} sys:Prefix: inherits: sys:SomlExtension descr: "Known prefix (namespace)" props: sys:id: {min: 1, descr: "Namespace prefix"} sys:iri: {min: 1, descr: "Namespace IRI"} 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"} sys:Meta: descr: "Metadata for a given SOML Object/Property" props: sys:key: {min: 1, descr: "Key of the data"} sys:values: {min: 1, descr: "Value of the data"} ### Metadata Studio System ### Object: kind: abstract props: id: label: "ID" range: iri min: 1 meta: {search: {visible: true, order: 0}, form: {visible: true, editable: false, order: 0}} type: range: iri max: inf meta: {search: {visible: false}, form: {visible: false}} NamedEntity: kind: abstract props: id: label: annotationContext: {inverseAlias: createdBy, range: Annotation, rangeCheck: false} User: type: omds:User inherits: NamedEntity pattern: "usr:${username}" props: # OMDS expects properties with names 'username' where the user's username would go # and also a 'label' where if configured the user display name will go label: {readOnly: true} username: {readOnly: true, rdfProp: omds:username} fullName: {readOnly: true, rdfProp: omds:fullName} email: {readOnly: true, rdfProp: omds:email} avatar: {rdfProp: omds:avatar} settings: {rdfProp: omds:settings} Timesensitive: kind: abstract props: metadata: {meta: {search: {visible: false}, form: {visible: false}}} createdAt: label: "Created at" range: dateTime min: 1 max: 1 rdfProp: omds:createdAt meta: {search: {visible: true, order: 5}, form: {visible: true, editable: false, order: 5}} createdBy: label: "Created by" range: NamedEntity min: 1 max: 1 rdfProp: omds:createdBy meta: {search: {visible: true, order: 6}, form: {visible: true, editable: false, order: 6}} modifiedAt: label: "Modified at" range: dateTime min: 0 max: 1 rdfProp: omds:modifiedAt meta: {search: {visible: true, order: 7}, form: {visible: true, editable: false, order: 7}} modifiedBy: label: "Modified by" range: NamedEntity min: 0 max: 1 rdfProp: omds:modifiedBy meta: {search: {visible: true, order: 8}, form: {visible: true, editable: false, order: 8}} SavedReport: inherits: Timesensitive type: omds:SavedReport props: corpusId: label: reportType: label: "The report type" data: label: "Holds report generated data as serialized JSON" config: label: "Holds configuration used during report generation" 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}}} Corpus: inherits: Timesensitive type: omds:Corpus 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}}} allowedUsers: {max: inf, rdfProp: omds:allowedUsers, meta: {search: {visible: false}, form: {visible: false}}} document: {range: Document, max: inf, rdfProp: omds:document, meta: {search: {visible: false}, form: {visible: false}}} documentCount: label: "Documents count" meta: {search: {visible: true, order: 10}, form: {visible: false}} range: int max: 1 rdfProp: | select ?_subject (count(?documentId) as ?_value) where { ?_subject omds:document ?documentId. } group by ?_subject VALUES ?_subject {} project: {range: Project, inverseAlias: corpus, meta: {search: {visible: false}, form: {visible: false}}} Document: inherits: Timesensitive kind: abstract props: label: {label: "Label", min: 0, range: stringOrLangString, meta: {search: {visible: true, order: 1}, form: {visible: true, editable: true}}} metadata: {meta: {search: {visible: false}, form: {visible: false}}} text: {label: "Text", min: 1, max: 1, rdfProp: omds:text, meta: {search: {visible: false}, form: {visible: true, editable: true}}} annotations: {range: Annotation, max: inf, rdfProp: omds:annotations, meta: {search: {visible: false}, form: {visible: false}}} annotationsCount: label: "Annotations count" meta: {search: {visible: true, order: 10}, form: {visible: false}} range: int max: 1 rdfProp: | select ?_subject (count(?annotationId) as ?_value) where { ?_subject omds:annotations ?annotationId. } group by ?_subject annotationsModifiedAt: label: "Annotations modified at" meta: {search: {visible: true, order: 11}, form: {visible: false}} range: dateTime max: 1 rdfProp: | select ?_subject (?lastModified as ?_value) where { ?_subject omds:annotations ?annotationId. ?annotationId omds:createdAt|omds:modifiedAt ?lastModified . } order by DESC (?lastModified) limit 1 VALUES ?_subject { } corpus: {range: Corpus, inverseAlias: document, meta: {search: {visible: false}, form: {visible: false}}} Metadata: type: omds:Metadata props: field: {min: 1, max: 1, rdfProp: omds:field} values: {max: inf, range: string, rdfProp: omds:values} AnnotationService: inherits: NamedEntity type: omds:AnnotationService props: label: serviceId: {min: 1} annotationQuery: {rdfProp: omds:annotationQuery, min: 1, max: 1} registrationQuery: {rdfProp: omds:registrationQuery, min: 1, max: 1} metadata: {meta: {search: {visible: false}, form: {visible: false}}} createdAt: {label: "Created at", range: dateTime, min: 1, max: 1, rdfProp: omds:createdAt, meta: {search: {visible: true, order: 5}, form: {visible: true, order: 5}}} createdBy: {label: "Created by", range: iri, min: 1, max: 1, rdfProp: omds:createdBy, meta: {search: {visible: true, order: 6}, form: {visible: true, order: 6}}} modifiedAt: {label: "Modified at", range: dateTime, min: 0, max: 1, rdfProp: omds:modifiedAt, meta: {search: {visible: true, order: 7}, form: {visible: true, order: 7}}} modifiedBy: {label: "Modified by", range: iri, min: 0, max: 1, rdfProp: omds:modifiedBy, meta: {search: {visible: true, order: 8}, form: {visible: true, order: 8}}} Concept: kind: abstract name: label props: label: {label: "Label", max: inf, range: stringOrLangString, meta: {search: {visible: true, order: 1}, form: {visible: true, order: 1}}} metadata: {meta: {preview: {fields: ["label"]}, search: {visible: false}, form: {visible: false, editable: false}}} Annotation: kind: abstract inherits: Timesensitive props: name: {label: "Name", meta: {search: {visible: true, editable: false, order: 1}, form: {visible: false, editable: false}}} type: {meta: {search: {visible: false}, form: {visible: false}}} document: {range: Document, inverseAlias: annotations, meta: {search: {visible: false}, form: {visible: false}}} reviewStatus: {label: "Status", min: 0, max: 1, range: reviewStatus, rdfProp: omds:reviewStatus, meta: {search: {visible: true}, form: {visible: true, editable: false}}} InlineAnnotation: kind: abstract inherits: Annotation props: metadata: { meta: { preview: { fields: [ "key" ] } } } annotationStart: {label: "Annotation start", range: int, rdfProp: omds:annotationStart, meta: {search: {visible: true}, form: {visible: true, order: 2}}} annotationEnd: {label: "Annotation end", range: int, rdfProp: omds:annotationEnd, meta: {search: {visible: true}, form: {visible: true, order: 3}}} key: meta: {search: {visible: false}, form: {visible: false}} max: inf rdfProp: | ?_subject ^omds:annotations/omds:text ?text ; omds:annotationStart ?start ; omds:annotationEnd ?end . bind (SUBSTR(?text, ?start + 1, ?end - ?start) as ?_value) snippet: meta: {search: {visible: false}, form: {visible: false}} max: inf rdfProp: | ?_subject ^omds:annotations/omds:text ?text ; omds:annotationStart ?start ; omds:annotationEnd ?end . bind (<http://www.ontotext.com/js#getSnippet>(?text, ?start, ?end) as ?_value) DocumentAnnotation: kind: abstract inherits: Annotation props: metadata: { meta: {preview: {fields: ["id", "wikidata.label", "wikidata.id"]}, search: {visible: false}, form: {visible: false, editable: false}} } Form: kind: abstract </pre></div> </div> </div></blockquote> </li> <li>project-specific definitions: also a required part of the schema, but customized for the respective project </li> </ul> <div class="highlight-yaml notranslate"><div class="highlight"><pre> SimpleDocument: inherits: Document type: omds:Document Person: inherits: Concept sparqlFederatedService: wikidata typeProp: generatedType type: wd:Q5 props: generatedType: {rdfProp: "wdt:P31", meta: {search: {visible: false}, form: {visible: false}}} search: meta: {search: {visible: false}, form: {visible: false}} restrictive: true rdfProp: | ?_subject rdfs:label ?label. filter (regex(str(?label), {{query}}, \"i\")). PersonAnnotation: inherits: InlineAnnotation type: http://knowledge.net/Annotation/Person props: wikidata: {range: Person, meta: {search: {visible: true}, form: {visible: true, editable: true}}} metadata: {meta: {preview: {fields: ["wikidata.label"]}, search: {visible: false}, form: {visible: false, editable: false}}} ### RBAC definitions ### rbac: roles: Default: description: "Everyone can read everything" actions: - "*/*/*" Admin: description: "Administrator role, can read, write and delete objects" actions: - "*/*/*" Curator: actions: - "Project/*/read" - "Corpus/*/read" - "Document/*/read" - "Document/annotations/*" - "Concept/*/read" - "Concept/id/write" - "Annotation/*/*/(where: {createdBy: {_ifUser: {username: {IRE: ${ctx.claims.preferred_username}}}}})" </pre></div> </div> </div> <div class="section" id="classes-model"> <h2><a class="toc-backref" href="#what-s-in-this-document">Classes Model</a><a class="headerlink" href="#classes-model" title="Permalink to this headline">¶</a></h2> By default, Metadata Studio is started with a <a class="reference external" href="https://gitlab.ontotext.com/sol/omds/metadata-studio/-/blob/master/service/src/main/resources/mant.yaml">SOML schema describing the basic Metadata Studio classes</a> based on a specific <a class="reference internal" href="architecture-and-components.html#architecture-and-components-data-model">RDF model</a>. The schema is kept in the <code class="docutils literal notranslate">otp-system</code> repository in GraphDB. Any data that comes in through runtime mutations is validated against this model. The schema must describe any specific document classes, concept classes, and annotations based on the specific user needs. The default schema can be overwritten in any of the following ways: <ul class="simple"> <li>by changing the initial schema on deployment</li> <li>at runtime through GraphQL mutations</li> <li>at runtime through the Metadata Studio UI</li> </ul> The schema does not contain any specific Concepts or Annotations classes. The following classes can be configured through the UI: <ul class="simple"> <li>Documents</li> <li>Annotations</li> <li>Concepts</li> </ul> Currently, Metadata Studio does not support the defining of custom Projects, Corpora, SavedReports, Users and AnnotationServices types that extend the original ones. The following sections talk about defining custom <a class="reference internal" href="#configuration-classes-model-custom-document-classes">Document</a>, <a class="reference internal" href="#configuration-classes-model-custom-annotation-classes">Annotation</a>, and <a class="reference internal" href="#configuration-classes-model-custom-concept-classes">Concept</a> classes. <div class="section" id="rdf-model"> <h3><a class="toc-backref" href="#what-s-in-this-document">RDF model</a><a class="headerlink" href="#rdf-model" title="Permalink to this headline">¶</a></h3> In the <a class="reference internal" href="architecture-and-components.html#architecture-and-components-data-model">base RDF model</a> of Metadata Studio, predicates that are part of the abstract classes are inherited in the more specific TimeSensitive and NamedEntity classes. <div class="section" id="objects-and-predicates"> <h4><a class="toc-backref" href="#what-s-in-this-document">Objects and predicates</a><a class="headerlink" href="#objects-and-predicates" title="Permalink to this headline">¶</a></h4> Metadata Studio uses the depicted objects and predicates for each object as follows: <ul> <li><code class="docutils literal notranslate">omds:Metadata</code>: Key-value object that contains various metadata. <blockquote> <div><ul class="simple"> <li><code class="docutils literal notranslate">omds:field</code>: The name of the field.</li> <li><code class="docutils literal notranslate">omds:value</code>: The value for the field.</li> </ul> </div></blockquote> </li> <li><code class="docutils literal notranslate">omds:TimeSensitive</code> <blockquote> <div><ul class="simple"> <li><code class="docutils literal notranslate">omds:createdAt</code>: The time at which the resource was created.</li> <li><code class="docutils literal notranslate">omds:createdBy</code>: Link to the user IRI that created the resource.</li> <li><code class="docutils literal notranslate">omds:modifiedAt</code>: The time at which the resource was last modified. Note that the change of this value is handled by the Metadata Studio UI, so whenever you apply a mutation to an object through the <code class="docutils literal notranslate">/graphql</code> endpoint or through RDF, you need to update the <code class="docutils literal notranslate">modifiedAt</code> value for this object yourself.</li> <li><code class="docutils literal notranslate">omds:modifiedBy</code>: Link to the user’s IRI that was the last one to modified the resource. Note that the change of this value is handled by the Metadata Studio UI, so whenever you apply a mutation to an object through the <code class="docutils literal notranslate">/graphql</code> endpoint or through RDF, you need to update the <code class="docutils literal notranslate">modifiedBy</code> value for this object yourself.</li> </ul> </div></blockquote> </li> <li><code class="docutils literal notranslate">omds:Project</code>: The project type. <blockquote> <div><ul class="simple"> <li><code class="docutils literal notranslate">omds:status</code>: The status of the project. Possible values are “ACTIVE” and “ARCHIVED”. Archived projects cannot be edited further.</li> <li><code class="docutils literal notranslate">omds:corpus</code>: Link to a corpus that is part of the project.</li> <li><code class="docutils literal notranslate">rdfs:label</code>: The label of the project that is displayed in the Metadata Studio UI <a class="reference internal" href="projects-view.html">Projects view</a>.</li> </ul> </div></blockquote> </li> <li><code class="docutils literal notranslate">omds:Corpus</code>: The corpus type. <blockquote> <div><ul class="simple"> <li><code class="docutils literal notranslate">omds:status</code>: The status of the corpus. Possible values are “ACTIVE” and “ARCHIVED”. Archived corpora cannot be edited further.</li> <li><code class="docutils literal notranslate">omds:document</code> : Link to a document that is part of the corpus.</li> <li><code class="docutils literal notranslate">rdfs:label</code>: The label of the corpus that is displayed in the Metadata Studio UI <a class="reference internal" href="projects-view.html">Projects view</a>.</li> </ul> </div></blockquote> </li> <li><code class="docutils literal notranslate">omds:Document</code>: The abstract document type. <blockquote> <div><ul class="simple"> <li><code class="docutils literal notranslate">omds:text</code>: The content of the document.</li> <li><code class="docutils literal notranslate">rdfs:label</code>: The label of the document that is displayed in the Metadata Studio UI <a class="reference internal" href="corpora-view.html">Corpus view</a>.</li> </ul> </div></blockquote> </li> <li><code class="docutils literal notranslate">omds:Annotation</code>: The abstract base annotation type. It cannot be extended directly - instead, either the InlineAnnotation or the DocumentAnnotation class must be extended. </li> <li><code class="docutils literal notranslate">omds:DocumentAnnotation</code>: The abstract document annotation type. </li> <li><code class="docutils literal notranslate">omds:InlineAnnotation</code>: The abstract inline annotation type. <blockquote> <div><ul class="simple"> <li><code class="docutils literal notranslate">omds:annotationStart</code>: The start positioning offset of the inline annotation.</li> <li><code class="docutils literal notranslate">omds:annotationEnd</code>: The end positioning offset of the inline annotation.</li> </ul> </div></blockquote> </li> <li><code class="docutils literal notranslate">omds:Concept</code>: The abstract concept type. </li> <li><code class="docutils literal notranslate">omds:SavedReport</code>: The saved report’s type. <blockquote> <div><ul class="simple"> <li><code class="docutils literal notranslate">base-iri:corpusId</code>: The IRI of the corpus as a string value.</li> <li><code class="docutils literal notranslate">base-iri:data</code>: The report results serialized in JSON.</li> <li><code class="docutils literal notranslate">base-iri:config</code>: The report configurations serialized in JSON.</li> <li><code class="docutils literal notranslate">base-iri:reportType</code>: The type of the report - either “FREQUENCY_COOCCURRENCE” or “F1” .</li> <li><code class="docutils literal notranslate">rdfs:label</code>: The label of the report that will be visualized in the Metadata Studio UI <a class="reference internal" href="reports-view.html">Reports view</a>.</li> </ul> </div></blockquote> </li> <li><code class="docutils literal notranslate">omds:NamedEntity</code>: The abstract class that is the range value for <code class="docutils literal notranslate">omds:createdBy</code> and <code class="docutils literal notranslate">omds:modifiedBy</code> values for all resources. </li> <li><code class="docutils literal notranslate">omds:User</code>: The user type. <blockquote> <div><ul class="simple"> <li><code class="docutils literal notranslate">omds:username</code>: The username of the user. By default, this value is used to build the user’s identifier as described in the <a class="reference internal" href="#configuration-users">users creation</a> section, so it needs to satisfy the requirements described in the section.</li> <li><code class="docutils literal notranslate">rdfs:label</code>: The label for the user that is presented in the Metadata Studio UI.</li> </ul> </div></blockquote> </li> <li><code class="docutils literal notranslate">omds:AnnotationService</code>: The annotation service type. Unlike all the other objects in Metadata Studio which are stored in the <code class="docutils literal notranslate">omds</code> GraphDB repository, some of the information about annotation services is stored in the <code class="docutils literal notranslate">otp-system</code> repository. <blockquote> <div><ul class="simple"> <li><code class="docutils literal notranslate">omds:annotationQuery</code> (in <code class="docutils literal notranslate">otp-system</code> repository): The query that is used during corpus annotation for the particular annotation service.</li> <li><code class="docutils literal notranslate">omds:registrationQuery</code> (in <code class="docutils literal notranslate">otp-system</code> repository): The query with which the particular annotation service was registered in the <code class="docutils literal notranslate">omds</code> repository.</li> <li><code class="docutils literal notranslate">base-iri:serviceId</code> (in <code class="docutils literal notranslate">otp-system</code> repository): The ID of the annotation service used by the UI.</li> <li><code class="docutils literal notranslate">rdfs:label</code> (in <code class="docutils literal notranslate">omds</code> repository): The label for the annotation service to visualize in the UI.</li> </ul> </div></blockquote> </li> </ul> </div> </div> <div class="section" id="custom-document-classes"> <h3><a class="toc-backref" href="#what-s-in-this-document">Custom document classes</a><a class="headerlink" href="#custom-document-classes" title="Permalink to this headline">¶</a></h3> The default document class in Metadata Studio is defined as <code class="docutils literal notranslate">abstract</code>. This means that the application relies on custom non-abstract document classes to be defined. In the default Metadata Studio schema, this is the <code class="docutils literal notranslate">SimpleDocument</code> object. A custom document class can be introduced, for example – <code class="docutils literal notranslate">Article</code>, <code class="docutils literal notranslate">Heard</code>, <code class="docutils literal notranslate">CV</code>, <code class="docutils literal notranslate">MedicalPrescription</code>, etc. The custom document class can have custom fields that the user can input. These fields can be visualized in the <a class="reference internal" href="corpora-view.html">Corpora view</a> or they can be used for filtering the documents in the Corpora view and in the <a class="reference internal" href="reports-view.html">Reports</a>. For example, if you want to define a Legal Contract document and specify the business activity purpose of the document as a category (such as Joint Venture agreement, NDA agreement, Employment contracts, etc), you can do this from the <a class="reference internal" href="projects-view.html#projects-view-manage-schema">Manage schema</a> view in the UI, or you can define a custom document class in the SOML schema as follows: <div class="highlight-yaml notranslate"><div class="highlight"><pre>LegalContract: inherits: Document type: omds:LegalContract props: category: {label: "Category", range: string, min: 1, max: 1, rdfProp: omds:category, meta: {search: {visible: true}, form: {visible: true, editable: true}}} </pre></div> </div> Alternatively, you can apply the following mutation at runtime against the Metadata Studio backend <code class="docutils literal notranslate">/graphql</code> endpoint: <div class="highlight-GraphQL notranslate"><div class="highlight"><pre>mutation createCustomDocument { create_sys_ObjectClass( objects: { sys_id: "LegalContract" sys_inherits: "voc:Document" sys_type: "omds:LegalContract" sys_props: { sys_Property: [ { sys_id: "category" sys_range: "string" sys_rdfProp: "omds:category" sys_meta: { sys_Meta: [ { sys_key: "search", sys_values: "{ visible: true}" } { sys_key: "form" sys_values: "{ visible: true, editable: true}" } ] } } ] } } ) { sys_ObjectClass { id } } } </pre></div> </div> Once you have declared your custom document class, you can create actual documents in your corpus either through the Metadata Studio UI client or by <a class="reference internal" href="#configuration-creating-objects-creating-documents">inserting RDF data in GraphDB</a>. </div> <div class="section" id="custom-annotation-classes"> <h3><a class="toc-backref" href="#what-s-in-this-document">Custom annotation classes</a><a class="headerlink" href="#custom-annotation-classes" title="Permalink to this headline">¶</a></h3> Specific annotation classes that you would like to create in your corpus need to be configured by you. Each custom annotation class must extend one of the base annotation classes - either <code class="docutils literal notranslate">DocumentAnnotation</code> (assigned as document tags) or <code class="docutils literal notranslate">InlineAnnotation</code> (assigned to specific a substring of the document). Besides the properties inherited from the base annotation class, each custom annotation can have custom properties. Each property must be defined with its property characteristics. A subset of the property characteristics supported by the <a class="reference external" href="https://platform.ontotext.com/semantic-objects/soml/properties.html#property-characteristics">Ontotext Platform Semantic Objects</a> are also supported in Metadata Studio: <ul class="simple"> <li><code class="docutils literal notranslate">range</code>: Specifies the class of the values of the property.</li> <li><code class="docutils literal notranslate">rdfProp</code>: Specifies the RDF predicate with which the property is stored in GraphDB.</li> <li><code class="docutils literal notranslate">min</code>: Currently, the highest supported value for all properties is 1. If the min cardinality for a field is 1, the UI enforces the user to enter a value for this field when creating annotations.</li> <li><code class="docutils literal notranslate">max</code>: Currently, the highest supported value for all properties is 1.</li> </ul> In addition, a new property characteristic called <code class="docutils literal notranslate">meta</code> is introduced. It controls how the UI visualizes and uses the property. The <code class="docutils literal notranslate">meta</code> characteristic supports the following nested fields: <ul> <li><code class="docutils literal notranslate">search</code>: controls how the field is considered when the object is visualized in search views: <blockquote> <div><ul class="simple"> <li><code class="docutils literal notranslate">visible</code> (type:boolean, default=false): Determines if the field is visible in search views, for example in the Document List view and in the Entity Linking view.</li> <li><code class="docutils literal notranslate">order</code> (type: integer, default=-1): Determines the order in which the field is visualized, if visible. The fields are ordered in ascending order and all fields with order -1 are placed last.</li> </ul> </div></blockquote> </li> <li><code class="docutils literal notranslate">form</code>: Controls how the field is considered when an instance of the class is created from or visualized in the UI: <blockquote> <div><ul class="simple"> <li><code class="docutils literal notranslate">visible</code> (type: boolean, default=false): Whether to visualize the field in creation/preview forms.</li> <li><code class="docutils literal notranslate">editable</code> (type: boolean, default=true): If visible=true, whether the user is allowed to edit the field or not.</li> <li><code class="docutils literal notranslate">order</code> (type: integer, default=-1): The order in which the fields are ordered. The fields are ordered in ascending order and all fields with order -1 are placed last.</li> </ul> </div></blockquote> </li> </ul> These <code class="docutils literal notranslate">meta</code> characteristics are configurable through the SOML schema and GraphQL mutations, but are not yet exposed for configuration from the Metadata Studio UI. For more information on the properties, please see the <a class="reference external" href="https://gitlab.ontotext.com/sol/omds/metadata-studio/-/blob/master/web/docs/developers-guide.md#class-fields-presentation-configuration">developers documentation</a>. Custom annotation classes can inherit either the <code class="docutils literal notranslate">DocumentAnnotation</code> or the <code class="docutils literal notranslate">InlineAnnotation</code> class. <div class="section" id="documentannotation-classes"> <h4><a class="toc-backref" href="#what-s-in-this-document">DocumentAnnotation classes</a><a class="headerlink" href="#documentannotation-classes" title="Permalink to this headline">¶</a></h4> Document annotations are annotations created for the whole document as opposed to for a specific part of the text. This is the more general way to create annotations that will fit most use cases where it is not vital to know where exactly in the document something was mentioned. Document annotations can have custom fields assigned to them with specific metadata. For example, if we want to define a custom document annotation type for legal contract agreement dates, besides doing that through the <a class="reference internal" href="projects-view.html#projects-view-manage-schema">Manage schema</a> view, we could have the following configuration in the SOML schema: <div class="highlight-yaml notranslate"><div class="highlight"><pre>AgreementDate: inherits: DocumentAnnotation type: http://cuad.ontotext.com/DocumentAnnotation/AgreementDate props: value: { range: string, rdfProp: omds:value, meta: { search: { visible: true, order: 1 }, form: { visible: true, editable: true, order: 1 } } } relevanceScore: { range: double, rdfProp: omds:relevanceScore, meta: { search: { visible: true, order: 2 }, form: { visible: true, editable: true, order: 2 } } } </pre></div> </div> where the <code class="docutils literal notranslate">value</code> property will contain the actual date, for example “20 Nov 1991”. Alternatively, the GraphQL mutation for registering this document annotation type would be: <div class="highlight-GraphQL notranslate"><div class="highlight"><pre>mutation createCustomDocumentAnnotation { create_sys_ObjectClass( objects: { sys_id: "AgreementDate" sys_inherits: "voc:DocumentAnnotation" sys_type: "http://cuad.ontotext.com/DocumentAnnotation/AgreementDate" sys_props: { sys_Property: [ { sys_id: "value" sys_range: "string" sys_rdfProp: "omds:value" sys_meta: { sys_Meta: [ { sys_key: "search", sys_values: "{ visible: true, order: 1}" } { sys_key: "form" sys_values: "{ visible: true, editable: true, order: 1}" } ] } } { sys_id: "relevanceScore" sys_range: "double" sys_rdfProp: "omds:relevanceScore" sys_meta: { sys_Meta: [ { sys_key: "search", sys_values: "{ visible: true, order: 2}" } { sys_key: "form" sys_values: "{ visible: true, editable: true, order: 2}" } ] } } ] } } ) { sys_ObjectClass { id } } } </pre></div> </div> Or you can use the UI <a class="reference internal" href="projects-view.html#projects-view-manage-schema">Manage schema</a> view to extend the DocumentAnnotation class with your custom definition. In addition to custom fields, Metadata Studio also supports a <code class="docutils literal notranslate">metadata</code> field with a <code class="docutils literal notranslate">meta</code> characteristic specifying a <code class="docutils literal notranslate">preview</code> field that controls how the object is visualized in simple previews. The <code class="docutils literal notranslate">preview</code> option has a <code class="docutils literal notranslate">fields</code> argument – a list of fields to be visualized in object preview. This is useful for limiting the information shown in the document annotation previews by removing unreadable fields with little value to the user such as identifiers, <code class="docutils literal notranslate">modifiedBy</code> fields, etc. This feature currently applies to annotations only and does not impact Corpora, Projects, and Documents. If we want to define an <code class="docutils literal notranslate">AgreementDate</code> document annotation, which contains the value of the date in the annotation preview, we would add the <code class="docutils literal notranslate">metadata</code> field like this: <div class="highlight-yaml notranslate"><div class="highlight"><pre>AgreementDate: inherits: DocumentAnnotation type: http://cuad.ontotext.com/DocumentAnnotation/AgreementDate props: value: { range: string, rdfProp: omds:value, meta: { search: { visible: true, order: 1 }, form: { visible: true, editable: true, order: 1 } } } relevanceScore: { range: double, rdfProp: omds:relevanceScore, meta: { search: { visible: true, order: 2 }, form: { visible: true, editable: true, order: 2 } } } metadata: { meta: { preview: { fields: [ "value" ] }, search: { visible: false }, form: { visible: false, editable: false } } } </pre></div> </div> The above SOML definition is equivalent to applying the following GraphQL mutation to the Metadata Studio backend: <div class="highlight-GraphQL notranslate"><div class="highlight"><pre>mutation createCustomDocumentAnnotation { create_sys_ObjectClass( objects: { sys_id: "AgreementDate" sys_inherits: "voc:DocumentAnnotation" sys_type: "http://cuad.ontotext.com/DocumentAnnotation/AgreementDate" sys_props: { sys_Property: [ { sys_id: "value" sys_range: "string" sys_rdfProp: "omds:value" sys_meta: { sys_Meta: [ { sys_key: "search", sys_values: "{ visible: true, order: 1}" } { sys_key: "form" sys_values: "{ visible: true, editable: true, order: 1}" } ] } } { sys_id: "relevanceScore" sys_range: "double" sys_rdfProp: "omds:relevanceScore" sys_meta: { sys_Meta: [ { sys_key: "search", sys_values: "{ visible: true, order: 2}" } { sys_key: "form" sys_values: "{ visible: true, editable: true, order: 2}" } ] } } { sys_id: "metadata" sys_meta: { sys_Meta: [ { sys_key: "preview", sys_values: "{ fields: [value] }" } { sys_key: "search", sys_values: "{ visible: false }" } { sys_key: "form" sys_values: "{ visible: false, editable: false }" } ] } } ] } } ) { sys_ObjectClass { id } } } </pre></div> </div> All of the fields of the annotations can be used to sort the document annotations in the Document view. If you would like to have the annotations sorted by a specific field by default, you can provide a <code class="docutils literal notranslate">defaultSortField</code> to the <code class="docutils literal notranslate">preview</code> with the name of the field that you want to perform base sorting on. Upon opening the Document view, the document annotations are then sorted by the specified field value in ascending order. The last sorting selection in the document view is saved as the user’s sorting preference, so from then on the sorting will appear based on the last sorting selection. For example: <div class="highlight-GraphQL notranslate"><div class="highlight"><pre>mutation createCustomDocumentAnnotation { create_sys_ObjectClass( objects: { sys_id: "AgreementDate" sys_inherits: "voc:DocumentAnnotation" sys_type: "http://cuad.ontotext.com/DocumentAnnotation/AgreementDate" sys_props: { sys_Property: [ { sys_id: "value" sys_range: "string" sys_rdfProp: "omds:value" sys_meta: { sys_Meta: [ { sys_key: "search", sys_values: "{ visible: true, order: 1}" } { sys_key: "form" sys_values: "{ visible: true, editable: true, order: 1}" } ] } } { sys_id: "relevanceScore" sys_range: "double" sys_rdfProp: "omds:relevanceScore" sys_meta: { sys_Meta: [ { sys_key: "search", sys_values: "{ visible: true, order: 2}" } { sys_key: "form" sys_values: "{ visible: true, editable: true, order: 2}" } ] } } { sys_id: "metadata" sys_range: "string" sys_rdfProp: "omds:value" sys_meta: { sys_Meta: [ { sys_key: "preview" sys_values: "{ fields: [\"value\", \"relevanceScore\"], defaultSortField: \"relevanceScore\"}" } ] } } ] } } ) { sys_ObjectClass { id } } } </pre></div> </div> </div> <div class="section" id="inlineannotation-classes"> <h4><a class="toc-backref" href="#what-s-in-this-document">InlineAnnotation classes</a><a class="headerlink" href="#inlineannotation-classes" title="Permalink to this headline">¶</a></h4> Inline annotations are annotations that are applicable only to a specific subset of a document. They are used when it is important to know where exactly in the document something was mentioned. This information is particularly important when preparing gold standard corpora for machine learning purposes, as it is useful for the algorithm to have this data. For example, if you want to be able to create inline tags for people in your documents, you can add the following snippet to your SOML schema: <div class="highlight-yaml notranslate"><div class="highlight"><pre>PersonAnnotation: inherits: InlineAnnotation type: http://knowledge.net/Annotation/Person props: name: {range: string, rdfProp: omds:name, meta: {search: {visible: true, order: 1}, form: {visible: true, editable: true, order: 1}}} </pre></div> </div> This is equivalent to applying the following GraphQL mutation to the Metadata Studio backend: <div class="highlight-GraphQL notranslate"><div class="highlight"><pre>mutation createCustomInlineAnnotation { create_sys_ObjectClass( objects: { sys_id: "PersonAnnotation" sys_inherits: "voc:InlineAnnotation" sys_type: "http://knowledge.net/Annotation/Person" sys_props: { sys_Property: [ { sys_id: "name" sys_range: "string" sys_rdfProp: "omds:name" sys_meta: { sys_Meta: [ { sys_key: "search", sys_values: "{ visible: true, order: 1}" } { sys_key: "form" sys_values: "{ visible: true, editable: true, order: 1}" } ] } } ] } } ) { sys_ObjectClass { id } } } </pre></div> </div> If you have People concepts present in your database and you want to link concepts from your reference dataset to the annotations (i.e., perform entity linking), you need to declare your custom concept class as part of the schema (see how to <a class="reference internal" href="#configuration-classes-model-custom-concept-classes">customize concept classes</a>). Then, use the concept class you created as a <code class="docutils literal notranslate">range</code> of the property through which you would like to establish the link. For example, the following snippet defines a PersonAnnotation inline annotation class that has a <code class="docutils literal notranslate">personEntity</code> property whose values are of instances of class <code class="docutils literal notranslate">Person</code>: <div class="highlight-yaml notranslate"><div class="highlight"><pre>PersonAnnotation: inherits: InlineAnnotation type: http://knowledge.net/Annotation/Person props: personEntity: {range: Person, rdfProp: omds:person, meta: {search: {visible: true, order: 1}, form: {visible: true, editable: true, order: 1}}} </pre></div> </div> Or you can use a GraphQL mutation instead: <div class="highlight-GraphQL notranslate"><div class="highlight"><pre>mutation createCustomInlineAnnotation { create_sys_ObjectClass(objects: { sys_id: "PersonAnnotation" sys_inherits: "voc:InlineAnnotation" sys_type: "http://knowledge.net/Annotation/Person" sys_props: {sys_Property: [ {sys_id: "personEntity", sys_range: "Person", sys_rdfProp: "omds:person", sys_meta: { sys_Meta:[ {sys_key: "search", sys_values: "{ visible: true, order: 1}"}, {sys_key: "form", sys_values: "{ visible: true, editable: true, order: 1}"} ] } } ]} }) { sys_ObjectClass { id } } } </pre></div> </div> In addition, relation annotations can be modeled to link to more than one concept from the reference dataset. For example, if we want to model a CEO relation annotation between a person and an organization, we can add the following snippet to our SOML schema: <div class="highlight-yaml notranslate"><div class="highlight"><pre>CEOAnnotation: inherits: InlineAnnotation type: http://knowledge.net/Annotation/CEO props: subject: { label: "Subject", range: PersonAnnotation, meta: { search: { visible: false, order: 1 }, form: { visible: true, editable: true, order: 1 } } } object: { label: "Object", range: OrganizationAnnotation, meta: { search: { visible: false, order: 2 }, form: { visible: true, editable: true, order: 2 } } } </pre></div> </div> Or we can apply the following mutation to the <code class="docutils literal notranslate">/graphql</code> endpoint of the Metadata Studio backend: <div class="highlight-GraphQL notranslate"><div class="highlight"><pre>mutation createCustomInlineAnnotation { create_sys_ObjectClass( objects: { sys_id: "CEOAnnotation" sys_inherits: "voc:InlineAnnotation" sys_type: "http://knowledge.net/Annotation/CEO" sys_props: { sys_Property: [ { sys_id: "subject" sys_range: "PersonAnnotation" sys_rdfProp: "omds:subject" sys_meta: { sys_Meta: [ { sys_key: "search", sys_values: "{ visible: true, order: 1}" } { sys_key: "form" sys_values: "{ visible: true, editable: true, order: 1}" } ] } } { sys_id: "object" sys_range: "OrganizationAnnotation" sys_rdfProp: "omds:object" sys_meta: { sys_Meta: [ { sys_key: "search", sys_values: "{ visible: true, order: 2}" } { sys_key: "form" sys_values: "{ visible: true, editable: true, order: 2}" } ] } } ] } } ) { sys_ObjectClass { id } } } </pre></div> </div> There are two ways to model a relation annotation: <ul class="simple"> <li>It can be modeled to point to other annotations (as in the example above). In this case, when selecting a text in the Metadata Studio UI, you will be allowed to create such a relation only if the nested annotation types have already been created over a substring of the selected text.</li> <li>It can be modeled to point to the objects from the reference dataset directly - in the above example, these are Person and Organization. When creating the relation annotation, you will be prompted to search for the concepts from the reference dataset for the nested entities.</li> </ul> </div> </div> <div class="section" id="custom-concept-classes"> <h3><a class="toc-backref" href="#what-s-in-this-document">Custom concept classes</a><a class="headerlink" href="#custom-concept-classes" title="Permalink to this headline">¶</a></h3> When creating corpora for entity linking tasks, you might want to define custom concept classes. This will allow you to link instances of these classes as part of your annotations. Your custom classes must inherit the default <code class="docutils literal notranslate">Concept</code> class. Similarly to the <a class="reference internal" href="#configuration-classes-model-custom-annotation-classes">annotations configurations</a>, the <code class="docutils literal notranslate">meta</code> property defines which concept fields will be visualized when doing entity linking. The search property defines a query that will be executed when the user creates PersonAnnotations and searches for People with names that match specific text. The <code class="docutils literal notranslate">{{query}}</code> template is replaced at runtime with the specific text that you search for. The following is an example for a declaration of a Person concept class: <div class="highlight-yaml notranslate"><div class="highlight"><pre>Person: inherits: Concept type: mycustomprefix:Person props: description: {rdfProp: "mycustomprefix:description", meta: {search: {visible: true}, form: {visible: true}}} search: meta: {search: {visible: false}, form: {visible: false}} restrictive: true rdfProp: | ?_subject skos:prefLabel|skos:altLabel ?label. filter (regex(str(?label), {{query}}, \"i\")) </pre></div> </div> In case you have GraphDB Elasticsearch/Lucene connectors for better full-text search, these can be used as well. For example: <div class="highlight-yaml notranslate"><div class="highlight"><pre>search: meta: {search: {visible: false}, form: {visible: false}} restrictive: true rdfProp: | ?search a inst:people_omds ; elastic:query ''' { "query": { "function_score": { "query": { "match_phrase_prefix": { "name": {{query}} } }, "script_score": { "script": { "source": "if (!doc.containsKey('rdfRank') || doc.get('rdfRank').isEmpty()) { return 1; } double rdfRank = doc['rdfRank'].value; return 1 + Math.max(0, Math.log10(rdfRank * 100))" } } } } }''' ; elastic:entities ?_subject . </pre></div> </div> Your GraphDB repository (defined through the <code class="docutils literal notranslate">sparql_endpoint_repository</code> property of the Metadata Studio API) must contain instances for the custom concept classes. If this data is located in a different SPARQL repository, you can use a federated service: <div class="highlight-yaml notranslate"><div class="highlight"><pre>Person: inherits: Concept sparqlFederatedService: wikidata typeProp: generatedType type: wd:Q5 props: ... </pre></div> </div> where the HTTP endpoint location of the Wikidata federated service is configured with the <code class="docutils literal notranslate">sparql.federated.services.wikidata</code> property of the Metadata Studio backend. If you would like to integrate an external service that contains visualizations of the concepts from your custom concept class, you can define the <a class="reference internal" href="#configuration-external-service-creation">external service</a> in your Metadata Studio deployment and link your custom concept class to to this service by pointing to the label of the service: <div class="highlight-yaml notranslate"><div class="highlight"><pre>Person: inherits: Concept type: mycustomprefix:Person props: metadata: {search: {visible: false}, form: {visible: false}, externalService: "Wikidata"} .... </pre></div> </div> </div> <div class="section" id="custom-form-classes"> <h3><a class="toc-backref" href="#what-s-in-this-document">Custom form classes</a><a class="headerlink" href="#custom-form-classes" title="Permalink to this headline">¶</a></h3> When creating corpora for entity linking tasks, you might want to define custom form classes. This will allow users to follow a form based approach when the users do not know the types of annotations they need to create. In this case, the users populate a form which refers to a number of predefined annotation types. Your custom classes must inherit the default abstract <code class="docutils literal notranslate">Form</code> class. The properties in your custom Form class must either be with range Form or with range Annotation. The label of the Form will be shown in the form header. The following is an example for a declaration of a Discharge form class: <div class="highlight-yaml notranslate"><div class="highlight"><pre>DischargeForm: inherits: Form label: "Discharge Questionnaire" props: addmission: range: Admission meta: form: order: 1 hospitalization: range: Hospitalization meta: form: order: 2 Admission: inherits: Form label: "Admission data" props: patientAge: label: "Patient's age" range: PatientAge meta: form: order: 1 </pre></div> </div> In order to visualize Forms for any documents, the document classes used must have <cite>documentForm</cite> field of the <cite>meta</cite> property set. For example: <div class="highlight-yaml notranslate"><div class="highlight"><pre>SimpleFormDocument: inherits: Document props: metadata: meta: documentForm: DischargeForm </pre></div> </div> </div> </div> <div class="section" id="creating-objects"> <h2><a class="toc-backref" href="#what-s-in-this-document">Creating Objects</a><a class="headerlink" href="#creating-objects" title="Permalink to this headline">¶</a></h2> This section describes how Metadata Studio can be filled with data by creating concrete objects. Generally, there are two approaches - creating objects through the UI or through RDF. Currently, the UI supports creating instances for all classes except for <a class="reference internal" href="#configuration-users">Users</a> and <a class="reference internal" href="#configuration-annotation-service-creation">Annotation Services</a>, which need to be set up through GraphQL mutations or RDF data. <div class="section" id="creating-projects"> <h3><a class="toc-backref" href="#what-s-in-this-document">Creating projects</a><a class="headerlink" href="#creating-projects" title="Permalink to this headline">¶</a></h3> The following is an example for the statements that can be inserted in the GraphDB repository (defined through the <code class="docutils literal notranslate">sparql_endpoint_repository</code> property of the Metadata Studio API) in order for a project to appear in the UI: <div class="highlight-turtle notranslate"><div class="highlight"><pre><projectIRI> a omds:Project ; omds:createdAt "2022-02-10T14:59:00"^^xsd:dateTime ; omds:createdBy <userIRI> ; omds:modifiedAt "2022-03-23T09:45:00"^^xsd:dateTime ; omds:modifiedBy <userIRI> ; omds:status "ACTIVE" ; rdfs:label "Project Name" . </pre></div> </div> If you want to enable an <a class="reference internal" href="#configuration-external-service-creation">external service</a> in your project, you need to bind it either through the Metadata Studio UI or through SPARQL like so: <div class="highlight-yaml notranslate"><div class="highlight"><pre><projectIRI> a omds:Project ; omds:createdAt "2022-02-10T14:59:00"^^xsd:dateTime ; omds:createdBy <userIRI> ; omds:modifiedAt "2022-03-23T09:45:00"^^xsd:dateTime ; omds:modifiedBy <userIRI> ; omds:status "ACTIVE" ; omds:externalService <externalServiceIRI> ; rdfs:label "Project Name" . </pre></div> </div> </div> <div class="section" id="creating-corpora"> <h3><a class="toc-backref" href="#what-s-in-this-document">Creating corpora</a><a class="headerlink" href="#creating-corpora" title="Permalink to this headline">¶</a></h3> The following is an example for the statements that can be inserted in the GraphDB repository in order for a corpus to appear in the UI: <div class="highlight-turtle notranslate"><div class="highlight"><pre><projectIRI> omds:corpus <corpusIRI> . <corpusIRI> a omds:Corpus ; omds:createdAt "2022-03-23T09:45:00"^^xsd:dateTime ; omds:createdBy <userIRI> ; omds:modifiedAt "2022-03-23T09:45:00"^^xsd:dateTime ; omds:modifiedBy <userIRI> ; omds:status "ACTIVE" ; rdfs:label "Corpus Name" . </pre></div> </div> </div> <div class="section" id="creating-documents"> <h3><a class="toc-backref" href="#what-s-in-this-document">Creating documents</a><a class="headerlink" href="#creating-documents" title="Permalink to this headline">¶</a></h3> The following is an example for the statements that can be inserted in the GraphDB repository in order for a document to appear in the UI: <div class="highlight-turtle notranslate"><div class="highlight"><pre><corpusIRI> omds:document <documentIRI> . <documentIRI> rdf:type omds:LegalContract ; rdfs:label "Berkshire Hills Bancorp Inc 2012-08-09" ; omds:text "Document content in plain text" ; omds:category "Endorsement Agreement" ; omds:createdBy <userIRI> ; omds:modifiedBy <userIRI> ; omds:createdAt "2022-05-20T08:00:00"^^xsd:dateTime ; omds:modifiedAt "2022-05-20T08:00:00"^^xsd:dateTime . </pre></div> </div> </div> <div class="section" id="creating-annotations"> <h3><a class="toc-backref" href="#what-s-in-this-document">Creating annotations</a><a class="headerlink" href="#creating-annotations" title="Permalink to this headline">¶</a></h3> The following is an example for the statements that can be inserted in the GraphDB repository in order for an annotation to appear in the UI: <div class="highlight-turtle notranslate"><div class="highlight"><pre><documentIRI> omds:annotations <annotationIRI> . <annotationIRI> rdf:type <customAnnotationTypeIRI> ; omds:createdAt "2022-05-20T08:00:00"^^xsd:dateTime ; omds:modifiedAt "2022-05-20T08:00:00"^^xsd:dateTime ; omds:createdBy <userIRI> ; omds:modifiedBy <userIRI> . </pre></div> </div> In case we are working with inline annotations, the following two statements must also be set: <div class="highlight-turtle notranslate"><div class="highlight"><pre><annotationIRI> omds:annotationStart "10"^^xsd:int ; omds:annotationEnd "20"^^xsd:int . </pre></div> </div> If the specific annotation type contains custom fields, they can be added to the triples above. <div class="section" id="applying-human-validation-workflow-to-annotations"> <h4><a class="toc-backref" href="#what-s-in-this-document">Applying Human Validation workflow to annotations</a><a class="headerlink" href="#applying-human-validation-workflow-to-annotations" title="Permalink to this headline">¶</a></h4> The following is an example for the statements that are inserted in the GraphDB repository when an annotation is reviewed in the UI. This can be done using the <a class="reference internal" href="document-view.html#document-view-form-workflow-human-validation-workflow">Human Validation workflow</a>. When an annotation is reviewed as accepted (thumbs up) the fields based on which it has been accepted are deep-copied in a new annotation object. The creator of this annotation is the user doing the review process. <div class="highlight-turtle notranslate"><div class="highlight"><pre><documentIRI> omds:annotations <annotationIRI> . <annotationIRI> rdf:type <customAnnotationTypeIRI> ; omds:createdAt "2022-05-20T08:00:00"^^xsd:dateTime ; omds:modifiedAt "2022-05-20T08:00:00"^^xsd:dateTime ; omds:createdBy <userIRI> ; omds:modifiedBy <userIRI> . </pre></div> </div> When an annotation is reviewed as rejected (thumbs down) the fields based on which it has been rejected are deep-copied in а new annotation object. The creator of this annotation is the user doing the review process. In addition, an explicit statement in GraphDB is written to signify this is a rejection. <div class="highlight-turtle notranslate"><div class="highlight"><pre><documentIRI> omds:annotations <annotationIRI> . <annotationIRI> rdf:type <customAnnotationTypeIRI> ; omds:reviewStatus <http://www.ontotext.com/metadatastudio/review-status/Rejected> ; omds:createdAt "2022-05-20T08:00:00"^^xsd:dateTime ; omds:modifiedAt "2022-05-20T08:00:00"^^xsd:dateTime ; omds:createdBy <userIRI> ; omds:modifiedBy <userIRI> . </pre></div> </div> <div class="admonition note"> Note OMDS UI includes in the annotation review process all form fields modeled as visible and editable. More information on how to model form fields available in the Custom annotation classes section. </div> </div> </div> <div class="section" id="creating-forms"> <h3><a class="toc-backref" href="#what-s-in-this-document">Creating forms</a><a class="headerlink" href="#creating-forms" title="Permalink to this headline">¶</a></h3> There is no need to create instances of type Form in GraphDB repository. Whenever new forms need to be added or the forms structure is changed, the changes should be reflected in the SOML configuration of the form types, their labels and properties. <div class="admonition warning"> Warning During the design of the annotation schema, make sure all form properties are unique, as duplication will lead to unwanted behaviour in the Form view in the Document view, such as seemingly identical values to annotations pointing to identical range objects. </div> </div> </div> <div class="section" id="validating-objects"> <h2><a class="toc-backref" href="#what-s-in-this-document">Validating Objects</a><a class="headerlink" href="#validating-objects" title="Permalink to this headline">¶</a></h2> This section describes how Metadata Studio can be configured to apply field validations upon creation of concrete objects. Generally, validation happens on the backend so validation constraints need to be configured in the SOML. Currently, the SOML validation will be picked up by the UI when the SOML has the following configuration that is present in the default SOML: <div class="highlight-yaml notranslate"><div class="highlight"><pre>config: exposeSomlInGraphQL: true </pre></div> </div> All possible validation characteristics are listed in the <a class="reference external" href="https://platform.ontotext.com/semantic-objects/soml/properties.html#property-characteristics">Property Characteristics</a> section of the Semantic Objects. <div class="section" id="validating-annotation-fields"> <h3><a class="toc-backref" href="#what-s-in-this-document">Validating Annotation fields</a><a class="headerlink" href="#validating-annotation-fields" title="Permalink to this headline">¶</a></h3> Any object class fields can be configured with validation constraints. The following is an example how “age” field in a PersonalInformation annotation objects is configured to be an integer within the range of 0 to 120. <div class="highlight-yaml notranslate"><div class="highlight"><pre>PersonalInformation: inherits: DocumentAnnotation props: name: { range: string, min: 1, meta: { form: { visible: true, editable: true, order: 0 } } } age: { range: integer, minInclusive: 0, maxInclusive: 120 , meta: { form: { visible: true, editable: true, order: 1 } } } </pre></div> </div> </div> </div> <div class="section" id="conditional-objects"> <h2><a class="toc-backref" href="#what-s-in-this-document">Conditional Objects</a><a class="headerlink" href="#conditional-objects" title="Permalink to this headline">¶</a></h2> This section describes how Metadata Studio can be configured to show specific object’s properties only when given conditions are met. This is a feature supported in the Form view. There are two things that need to be configured: <ul class="simple"> <li>a condition using SPARQL is defined as a property in the <code class="docutils literal notranslate">FormConditions</code> object.</li> <li>a specific Form property references the condition in its <code class="docutils literal notranslate">meta: form: visibleCondition</code> field.</li> </ul> <div class="section" id="conditional-form-fields"> <h3><a class="toc-backref" href="#what-s-in-this-document">Conditional Form fields</a><a class="headerlink" href="#conditional-form-fields" title="Permalink to this headline">¶</a></h3> Any Form field can be conditional - meaning it will appear visible in Metadata Studio only if certain condition is met. The following is an example how “DrivingLicense” annotation in a PersonalInformation form section is configured to be visible only if a person is of legal age. <div class="highlight-yaml notranslate"><div class="highlight"><pre>FormConditions: typeProp: none props: legalAgeCondition: range: boolean rdfProp: | BIND("conditions" as ?_subject). { select (count(?ann) as ?exists) where { {{document:iri}} omds:annotations ?ann. ?ann a voc:PersonAge. ?ann voc:age ?age. FILTER(?age > 18). } } BIND(?exists > 0 AS ?_value) PersonalInformation: inherits: Form label: "Provide Personal Information" props: personAge: label: "Age" range: PersonAge meta: form: order: 1 drivingLicense: label: "Driving License" range: DrivingLicense meta: form: order: 2 visibleCondition: legalAgeCondition </pre></div> </div> </div> </div> <div class="section" id="users"> <h2><a class="toc-backref" href="#what-s-in-this-document">Users</a><a class="headerlink" href="#users" title="Permalink to this headline">¶</a></h2> Depending on the OAuth2 service that you would like to use, the users need to be configured in the specific service storage. The Metadata Studio deployment comes with <a class="reference external" href="https://www.keycloak.org">Keycloak</a> as a default user management solution. <div class="admonition note"> Note Usernames cannot contain whitespace characters. The reason is that the Metadata Studio tool relies on the convention that the concatenation between <code class="docutils literal notranslate">http://www.ontotext.com/metadatastudio/user/</code> and the username must result in a valid IRI. </div> Once you log in to Metadata Studio with a specific user, all objects that this user creates are assigned with <code class="docutils literal notranslate">createdBy</code> and <code class="docutils literal notranslate">modifiedBy</code> fields that point to the specific user identifier. If you set up initial RDF data for projects, corpora, documents, or annotations, in order for the UI to be able to visualize the user references from the <code class="docutils literal notranslate">createdBy</code> and <code class="docutils literal notranslate">modifiedBy</code> predicates, a username must be defined in the database: <div class="highlight-turtle notranslate"><div class="highlight"><pre>PREFIX omds: <http://www.ontotext.com/metadatastudio#> <http://www.ontotext.com/metadatastudio/user/borislav> a omds:User; omds:username "Borislav" . </pre></div> </div> Note that the exact predicate for the username needs to be synced with the predicate defined for the user’s <code class="docutils literal notranslate">username</code> field in the <a class="reference internal" href="#configuration-default-schema">default SOML schema</a>, which by default looks like this: <div class="highlight-yaml notranslate"><div class="highlight"><pre>User: props: username: {readOnly: true, rdfProp: omds:username} ... </pre></div> </div> By default, Metadata Studio has the following user roles: <ul class="simple"> <li><code class="docutils literal notranslate">Default</code>: Restricts access to everything if the logged-in user does not have any roles assigned.</li> <li><code class="docutils literal notranslate">Curator</code>: Grants read access to all resources as well as right to create annotations for existing documents.</li> <li><code class="docutils literal notranslate">Admin</code>: Grants all actions on all objects and their properties to a user with that role.</li> <li><code class="docutils literal notranslate">SchemaRBACAdmin</code>: Allows the user to modify the SOML schema.</li> </ul> New roles can be added and modified by a user with a <code class="docutils literal notranslate">SchemaRBACAdmin</code> role. For more information on the syntax of the RBAC schema, see the official Ontotext Platform Semantic Objects <a class="reference external" href="https://platform.ontotext.com/semantic-objects/soml/rbac.html">documentation</a>. </div> <div class="section" id="creating-annotation-services"> <h2><a class="toc-backref" href="#what-s-in-this-document">Creating Annotation Services</a><a class="headerlink" href="#creating-annotation-services" title="Permalink to this headline">¶</a></h2> If a third-party text analysis annotation service needs to be integrated in Metadata Studio, a query to register the text analysis service and to handle the annotation needs to be configured. Metadata Studio relies on the GraphDB Text Mining plugin to integrate with arbitrary third-party text analysis services. Unlike the other configurable components, the text mining annotation query cannot be configured through the Metadata Studio UI yet. It needs to be set up by applying a GraphQL mutation to the Metadata Studio API. The mutation registers the annotation service with: <ul class="simple"> <li>a specific text mining plugin registration query</li> <li>a specific annotation query</li> </ul> The <code class="docutils literal notranslate">AnnotationService</code> object has a <code class="docutils literal notranslate">label</code> and a <code class="docutils literal notranslate">serviceId</code>. The <code class="docutils literal notranslate">label</code> controls the label with which the <code class="docutils literal notranslate">annotationService</code> will be visualized in the UI under the Annotation services drop-down. <div class="section" id="registration-query"> <h3><a class="toc-backref" href="#what-s-in-this-document">Registration query</a><a class="headerlink" href="#registration-query" title="Permalink to this headline">¶</a></h3> The registration query is a query that instantiates the <a class="reference external" href="https://graphdb.ontotext.com/documentation/10.1/text-mining-plugin.html">GraphDB Text Mining plugin</a>. It must specify the URL to the text mining service, the headers that must be sent during annotation requests, and any specific transformations that should be applied over the annotation response. In addition, it creates a label for the annotation service that the UI uses to visualize the service creator source. For more information on how to register text mining plugins, check the <a class="reference external" href="https://graphdb.ontotext.com/documentation/10.1/text-mining-plugin.html">GraphDB documentation</a>. <div class="highlight-default notranslate"><div class="highlight"><pre>mutation createLegalTaggerServiceExample { create_AnnotationService( objects: { label: "Legal Tagger", serviceId: "http://cuad.ontotext.com/legalTagger", createdBy: "some-user-identifier", createdAt: "some-timestamp", registrationQuery: """ PREFIX : <http://www.ontotext.com/textmining#> PREFIX inst: <http://www.ontotext.com/textmining/instance#> PREFIX cuad: <http://cuad.ontotext.com/> INSERT DATA { inst:legalTagger :connect :Ces; :service "some-url-here" ; :header "Accept: application/vnd.ontotext.ces+json;charset=utf-8"; :header "Content-type: text/plain". cuad:legalTagger a <http://www.ontotext.com/metadatastudio#AnnotationService> ; rdfs:label "Legal Tagger" . } """, annotationQuery: .... .... } ) { annotationService { id } } } </pre></div> </div> It is recommended that the IRI identifier that we declare as an annotation service and the specific <code class="docutils literal notranslate">rdfs:label</code> match the <code class="docutils literal notranslate">serviceId</code> and <code class="docutils literal notranslate">label</code> values from the mutation. </div> <div class="section" id="annotation-query"> <h3><a class="toc-backref" href="#what-s-in-this-document">Annotation query</a><a class="headerlink" href="#annotation-query" title="Permalink to this headline">¶</a></h3> Upon selection of a specific annotation service for a particular corpus, the Metadata Studio backend splits the documents from the corpus into batches of ten documents. It then sends the documents from each batch to the text mining API service to generate annotations for these documents. The annotation query defines how the documents should be sent for annotation and how the response should be stored in GraphDB. It is entirely configurable by the user, which makes this process compatible with any third-party services accessible through HTTP, which produce annotations with text position offsets. The annotation query also takes care of cleaning up previously existing annotations from the same text mining API service, which allows you to execute multiple annotation processes over the same corpus over time. <div class="admonition tip"> Tip It is a good practice to keep the annotations from each annotation service in a specific context, as this makes the maintenance of the data easier. The format in which the annotations are stored should correspond to the format defined in the <a class="reference internal" href="#configuration-classes-model-custom-annotation-classes">Custom annotations</a> section. The <code class="docutils literal notranslate">createdBy</code> and <code class="docutils literal notranslate">modifiedBy</code> fields should point to the IRI of the specific annotation service. </div> Following is an example for an annotation query that creates inline annotations returned from the Legal tagger: <div class="highlight-GraphQL notranslate"><div class="highlight"><pre>mutation createLegalTaggerServiceExample { create_AnnotationService( objects: { label: "Legal Tagger", serviceId: "http://cuad.ontotext.com/legalTagger", createdBy: "some-user-identifier", createdAt: "some-timestamp", registrationQuery: ....., annotationQuery: """ PREFIX inst: <http://www.ontotext.com/textmining/instance#> PREFIX : <http://www.ontotext.com/textmining#> PREFIX xsd: <http://www.w3.org/2001/XMLSchema#> PREFIX omds: <http://www.ontotext.com/metadatastudio#> PREFIX cuad: <http://cuad.ontotext.com/> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> DELETE { GRAPH <http://cuad.ontotext.com/legalTagger> { ?document omds:annotations ?oldAnnotation . ?oldAnnotation ?oldPredicate ?oldObject } } INSERT { GRAPH <http://cuad.ontotext.com/legalTagger> { ?annotationId omds:annotationStart ?annotationStart ; omds:annotationEnd ?annotationEnd ; omds:document ?document ; a omds:Annotation ; a ?annotationType ; omds:createdBy cuad:legalTagger ; omds:createdAt ?time ; omds:modifiedBy cuad:legalTagger ; omds:modifiedAt ?time ; ?answerPredicate ?answer . ?document omds:annotations ?annotationId . } } WHERE { { ?service a inst:tagService; :text ?text ; :serviceErrors -1 . { SELECT ?text ?document ?time WHERE { VALUES ?document { {{documents}} } ?document omds:text ?text . BIND(NOW() as ?time) } } graph inst:legalTagger { ?annotatedDocument :annotations ?annotation . ?annotation :annotationText ?answer ; :annotationType ?type ; :annotationStart ?annotationStartLong ; :annotationEnd ?annotationEndLong . ?annotation :features/:class ?class . } BIND(xsd:int(?annotationStartLong) as ?annotationStart) BIND(xsd:int(?annotationEndLong) as ?annotationEnd) BIND(IRI(CONCAT("http://cuad.ontotext.com/InlineAnnotation/", ?type)) as ?annotationType) BIND(IRI(CONCAT(CONCAT("http://cuad.ontotext.com/InlineAnnotation/", "Tagger/", STRUUID()), STRAFTER(STR(?annotation),"-something-that-is-not-present-"))) as ?annotationId) } UNION # Use union to select also the annotations from previous annotation processes in order to delete them { GRAPH <http://cuad.ontotext.com/legalTagger> { ?document omds:annotations ?oldAnnotation . VALUES ?document { {{documents}} } ?oldAnnotation omds:createdAt ?createdAt . ?oldAnnotation ?oldPredicate ?oldObject . filter (?createdAt != ?time) } } } """, .... } ) { annotationService { id } } } </pre></div> </div> When the annotation processes is triggered from the UI for a particular corpus, the Metadata Studio backend retrieves all documents from this corpus. It splits the documents to batches of ten and processes all batches sequentially by replacing the <code class="docutils literal notranslate">{{documents}}</code> placeholder with the documents ids from each batch. </div> </div> <div class="section" id="creating-external-services"> <h2><a class="toc-backref" href="#what-s-in-this-document">Creating External Services</a><a class="headerlink" href="#creating-external-services" title="Permalink to this headline">¶</a></h2> External services improve the annotation workflow in Metadata Studio by providing quick access to external tools that visualize the concepts from the reference dataset that you are working with. For example, if you create annotations against Wikidata, you can integrate Metadata Studio with the Wikidata Web interface. As a result, whenever you click on annotations for a concept, you will be redirected to the Wikidata page containing the information about this concept. To define external services, you need to insert an RDF definition for these services in GraphDB. This includes the label that this service will be referenced by in your SOML schema as well as how to compute the URL to the external service based on the Concept’s IRI. For the latter, you can make use of the <code class="docutils literal notranslate"><concept-iri></code> variable. Thus, the external service must provide a GET REST endpoint that accepts the concept’s IRI as a path or as a request parameter. <div class="admonition note"> Note To use the External services, you must have referenced them both in the <a class="reference internal" href="#configuration-creating-objects-creating-projects">Project configuration</a> and the <a class="reference internal" href="#configuration-classes-model-custom-concept-classes">Concept class definition</a>. </div> <div class="section" id="wikidata-external-service"> <h3><a class="toc-backref" href="#what-s-in-this-document">Wikidata external service</a><a class="headerlink" href="#wikidata-external-service" title="Permalink to this headline">¶</a></h3> To resolve the URLs for Wikidata, you can use the Wikidata concept ID directly, as this points to the corresponding concept Wikidata page. <div class="highlight-turtle notranslate"><div class="highlight"><pre>@prefix omds: <http://www.ontotext.com/metadatastudio#> . @prefix omds-ext: <http://www.ontotext.com/metadatastudio#extService/> . omds-ext:WikidataService a omds:ExternalService ; rdfs:label "Wikidata" ; omds:url "<concept-iri>". </pre></div> </div> </div> <div class="section" id="now-external-service"> <h3><a class="toc-backref" href="#what-s-in-this-document">NOW external service</a><a class="headerlink" href="#now-external-service" title="Permalink to this headline">¶</a></h3> For integration with services such as now.ontotext.com, in which the concept information page is built by applying the concept IRI as a suffix to a URL, you can use the following RDF: <div class="highlight-turtle notranslate"><div class="highlight"><pre>@prefix omds: <http://www.ontotext.com/metadatastudio#> . @prefix omds-ext: <http://www.ontotext.com/metadatastudio#extService/> . omds-ext:NOWService a omds:ExternalService ; rdfs:label "NOW" ; omds:url "https://now.ontotext.com/#/concept&uri=<concept-iri>". </pre></div> </div> </div> </div> </div> </div> </div> <hr class="m-0"> <footer class="main-container py-5"> <div class="container-fluid"> <div class="row"> <div class="col-12 col-sm-6 col-lg-4"> <h4>Download documentation</h4> <ul class="list-inline"> <li class="list-inline-item"> <a href="/omds/3.11/pdf/Metadata-Studio.pdf" download class="btn btn-link text-secondary px-0" target="_blank"> PDF</a> </li> <li class="list-inline-item"> <a href="/omds/3.11/epub/Metadata-Studio.epub" download class="btn btn-link text-secondary px-0" target="_blank"> ePUB</a> </li> </ul> </div> <div class="col-12 col-sm-6 col-lg-4"> <h4>Contacts</h4> <ul class="list-unstyled mb-4"> <li class="m-0"> <a href="mailto:platform-support@ontotext.com" class="btn btn-link text-secondary px-0" target="_blank"> Support · platform-support@ontotext.com </a> </li> <li class="m-0"> <a href="mailto:sales@ontotext.com" class="btn btn-link text-secondary px-0" target="_blank"> Sales · sales@ontotext.com </a> </li> <li class="m-0 mb-3"> <a href="mailto:info@ontotext.com" class="btn btn-link text-secondary px-0" target="_blank"> General · info@ontotext.com </a> </li> <li class="m-0"> US (toll free) · 1-866-972-6686</li> <li class="m-0"> Europe · +359 2 974 61 60</li> </ul> </div> <div class="col-12 col-sm-6 col-lg-4 mb-4"> <h4>More info</h4> <ul class="list-unstyled mb-4"> <li class="m-0"><a href="http://www.ontotext.com/company/" class="btn btn-link text-secondary px-0" target="_blank"> About Ontotext</a></li> <li class="m-0"><a href="https://www.w3.org/standards/semanticweb/" class="btn btn-link text-secondary px-0" target="_blank"> Semantic web</a></li> </ul> <h4>Follow us</h4> <div class="mb-4"> <a data-toggle="tooltip" title="" href="https://www.linkedin.com/company/ontotext-ad" class="btn btn-link px-0" target="_blank" data-original-title="LinkedIn"></a> <a data-toggle="tooltip" title="" href="https://twitter.com/ontotext" class="btn btn-link px-0" target="_blank" data-original-title="Twitter"></a> <a data-toggle="tooltip" title="" href="https://www.facebook.com/Ontotext" class="btn btn-link px-0" target="_blank" data-original-title="Facebook"></a> <a data-toggle="tooltip" title="" href="https://www.youtube.com/ontotext" class="btn btn-link px-0" target="_blank" data-original-title="Youtube"></a>  </div> </div> </div>  <div class="text-muted small d-flex align-items-center"> <div> <a href="http://ontotext.com/" target="_blank" class="d-inline-block mb-3 mb-md-0 mr-2"><img src="_static/ot-logo.svg" class="m-0" height="26" alt="Ontotext logo"></a> © Copyright 2024, Ontotext. Last updated on 20 December, 2024. | <a href="https://ontotext.com/privacy-policy-2/">Privacy</a> </div> <div class="ml-auto"> <button id="scrollToTop" class="btn btn-link" data-toggle="tooltip" data-placement="top" title="" data-original-title="Back to top"></button> </div> </div> </div> </footer> </div> </body> </html>