Ontotext Platform Documentation Release 3.4 Ontotext Apr 16, 2021 CONTENTS 1 Overview 1 1.1 30,000ft ................................................ 2 1.2 Layered View ............................................ 2 1.2.1 Application Layer ...................................... 3 1.2.1.1 Ontotext Platform Workbench .......................... 3 1.2.1.2 GraphDB Workbench ............................... 4 1.2.2 Service Layer ........................................ 5 1.2.2.1 Semantic Objects (GraphQL) ........................... 5 1.2.2.2 GraphQL Federation (Apollo GraphQL Federation) ............... 5 1.2.2.3 Text Analytics Service ............................... 6 1.2.2.4 Annotation Service ................................ 7 1.2.3 Data Layer ......................................... 7 1.2.3.1 Graph Database (GraphDB) ........................... 7 1.2.3.2 Semantic Object Schema Storage (MongoDB) ................. 7 1.2.3.3 Semantic Objects for MongoDB ......................... 8 1.2.3.4 Semantic Object for Elasticsearch ........................ 8 1.2.4 Authentication and Authorization ............................. 8 1.2.4.1 FusionAuth ..................................... 8 1.2.4.2 Semantic Objects RBAC ............................. 9 1.2.5 Kubernetes ......................................... 9 1.2.5.1 Ingress and GW .................................. 9 1.2.6 Operation Layer ....................................... 10 1.2.6.1 Health Checking .................................. 10 1.2.6.2 Telegraf ....................................... 10 1.2.6.3 InfluxDB ...................................... 11 1.2.6.4 Grafana ....................................... 11 1.2.7 Build Process ........................................ 11 1.2.7.1 Source Code Management ............................ 11 1.2.7.2 Automated Builds and Tests ........................... 12 1.2.7.3 Docker Images and Repository .......................... 12 1.2.7.4 Security Vulnerabilities .............................. 12 1.2.7.5 License Chart ................................... 12 1.2.8 Deployment ......................................... 12 2 Installation 15 3 Semantic Objects Service 17 3.1 Introduction .............................................. 18 3.2 Motivation .............................................. 18 3.3 Overview ............................................... 19 i 3.4 Quick Start .............................................. 19 3.4.1 Installation .......................................... 19 3.4.1.1 Docker ....................................... 19 3.4.1.2 Docker Compose ................................. 19 3.4.1.3 Curl ......................................... 20 3.4.2 Start the Service ...................................... 20 3.4.3 Initialize GraphDB ..................................... 21 3.4.4 Put Star Wars Data into GraphDB ............................. 21 3.4.5 Define Star Wars Semantic Objects ............................ 22 3.4.6 Run a Star Wars GraphQL Query ............................. 22 3.4.7 Stop the Service ...................................... 23 3.5 Tutorials ............................................... 23 3.5.1 GraphQL Query ....................................... 23 3.5.2 GraphQL Mutation ..................................... 23 3.5.3 Fragment, Aliases, and Directives ............................. 23 3.5.4 GraphQL Introspection ................................... 23 3.6 Monitoring .............................................. 23 3.6.1 Health Checks ....................................... 23 3.6.2 Good to Go ......................................... 27 3.6.3 Troubleshooting ....................................... 27 3.6.4 About ............................................ 28 3.7 Administration ............................................ 28 3.7.1 Logging ........................................... 28 3.7.2 Correlation and X-Request-ID ............................... 30 3.7.3 Application/Service Access ................................ 30 3.7.4 Configuration ........................................ 31 3.7.5 Sizing and Hardware Requirements ........................... 38 3.8 Validations .............................................. 40 3.8.1 Dynamic Validators ..................................... 40 3.8.2 Static Validators ....................................... 41 3.8.2.1 Schema Management ............................... 42 3.8.2.2 Shape Prefix .................................... 44 3.8.2.3 Example SOML Schema ............................. 44 3.8.2.4 Example Generated SHACL Schema ...................... 45 3.8.3 Validation Process ..................................... 47 4 Semantic Objects Search 49 4.1 Overview ............................................... 49 4.2 Data Indexing ............................................ 50 4.3 Quick Start .............................................. 50 4.4 GraphQL API ............................................. 51 4.5 Tutorials ............................................... 51 4.5.1 Queries ........................................... 51 4.5.2 Paging ............................................ 51 4.5.3 Sorting ............................................ 52 4.5.4 Aggregations ........................................ 52 4.6 Monitoring .............................................. 52 4.6.1 Health Checks ....................................... 52 4.6.2 Good to Go ......................................... 54 4.6.3 Troubleshooting ....................................... 55 4.6.4 About ............................................ 55 4.7 Administration ............................................ 55 4.7.1 Schema Management API ................................. 55 4.7.2 Service Configurations ................................... 56 ii 4.7.3 Semantic Objects Service Configuration ......................... 57 5 Semantic Object Modeling 59 5.1 Introduction .............................................. 59 5.1.1 Overview .......................................... 59 5.1.2 YAML ............................................ 60 5.1.3 Influences .......................................... 60 5.1.4 Terminology ......................................... 61 5.1.5 Overall Structure ...................................... 62 5.2 Preamble ............................................... 63 5.2.1 Schema Metadata ..................................... 63 5.2.2 Schema Configuration ................................... 64 5.2.3 Special Prefixes ....................................... 66 5.2.4 Predefined Prefixes ..................................... 66 5.2.5 Own Prefixes ........................................ 67 5.2.6 Naming Convention and IRI Processing ......................... 67 5.2.7 Reserved Words ...................................... 68 5.2.8 GraphQL descr Directive .................................. 69 5.3 Datatypes .............................................. 69 5.3.1 GraphQL Extension Datatypes .............................. 73 5.3.2 Literals and Union Datatypes ............................... 73 5.3.3 Lexical vs Value Space ................................... 74 5.3.4 Timezones ......................................... 75 5.3.5 Additional Resources .................................... 76 5.4 Properties .............................................. 76 5.4.1 Property Characteristics .................................. 77 5.4.2 Characteristic Inheritance ................................. 79 5.4.3 Name and IRI ........................................ 80 5.4.4 Domain and Range ..................................... 80 5.4.5 rangeCheck and typeCast ................................. 80 5.4.6 Cardinality .......................................... 81 5.4.7 Nullability .......................................... 82 5.4.8 Immutability ......................................... 83 5.4.9 Inverses ........................................... 83 5.4.10 Inverses and rangeCheck ................................. 84 5.4.11 Pattern and Prefix ..................................... 85 5.4.12 Language Configurations ................................. 85 5.4.13 Predefined Properties ................................... 87 5.4.14 Property Examples ..................................... 87 5.5 Objects ................................................ 89 5.5.1 Object Characteristics ................................... 90 5.5.2 Object Defaults ....................................... 90 5.5.3 ID (IRI) Generation ..................................... 91 5.5.3.1 ID Generation Using Prefixes ........................... 92 5.5.3.2 ID Generation Using Other Properties and Literals ............... 93 5.5.3.3 ID Generation Using Integrated Functions .................... 94 5.5.3.4 ID Generation Validations ............................. 95 5.5.4 Object Typing ........................................ 95 5.5.5 Inheritance ......................................... 97 5.5.6 Interface Object ....................................... 99 5.5.7 Interface Nameable ..................................... 99 5.5.7.1 Name Example .................................. 103 5.6 Queries ................................................ 106 5.6.1 Example Schema ...................................... 107 iii 5.6.2 Limit and Offset ....................................... 108 5.6.2.1 Performance Considerations ........................... 108 5.6.3 OrderBy ........................................... 109 5.6.3.1 OrderBy Inputs ................................... 109 5.6.3.2 Scalar Ordering .................................. 110 5.6.4 ID Filtering .........................................