SemanticComputing · Ceetto · Jul 13, 2026 · Jul 14, 2026 · Jul 15, 2026 · Jul 15, 2026
diff --git a/client/package-lock.json b/client/package-lock.json
diff --git a/client/package.json b/client/package.json
@@ -36,6 +36,7 @@
     "express": "^4.21.1",
     "html-react-parser": "^1.4.4",
     "immutable": "^4.0.0-rc.12",
+    "jsonc-parser": "^3.3.1",
     "leaflet": "^1.7.1",
     "leaflet-draw": "^1.0.4",
     "leaflet-fullscreen": "^1.0.2",

diff --git a/client/src/stores/configsStore.js b/client/src/stores/configsStore.js
@@ -1,4 +1,5 @@
 import { create } from 'zustand'
+import { parse } from 'jsonc-parser'
 import { configHelpers } from 'stores/helpers'
 
 const apiUrl = process.env.API_URL
@@ -36,7 +37,7 @@ export const useConfigsStore = create((set, get) => ({
     if (get().portalConfig !== null) {
       return get().portalConfig
     } else {
-      const portal = await fetch(`${CONFIGS_URL}/portalConfig.json`).then(res => res.json())
+      const portal = await fetch(`${CONFIGS_URL}/portalConfig.json`).then(res => res.text()).then(text => parse(text))
       set({ portalConfig: portal })
       return portal
     }
@@ -49,7 +50,7 @@ export const useConfigsStore = create((set, get) => ({
     if (file in get().jsonConfigs) {
       return get().jsonConfigs[file]
     } else {
-      const jsonFile = await fetch(`${CONFIGS_URL}/${get().portalConfig.portalID}/${file}`).then(res => res.json())
+      const jsonFile = await fetch(`${CONFIGS_URL}/${get().portalConfig.portalID}/${file}`).then(res => res.text()).then(text => parse(text))
       set(state => ({
         jsonConfigs: { ...state.jsonConfigs, [file]: jsonFile }
       }))

diff --git a/docs/README.md b/docs/README.md
@@ -1,6 +1,18 @@
 # SAMPO-UI docs
 
-- [Introduction](pages/Introduction.md)
+Sampo-ui is a data visualisation framework designed to easily configure a browsable front end for sparql endpoints.
+
+Sampo consists of a core app and config files. A sampo app runs by mounting the configs into the core app containers,
+meaning when building a portal only config files need to be created.
+
+These docs are intended for developers using sampo-ui to build apps as well as for developers working on the sampo core.
+
+These documentations explain the current state of version 4.
+
+- [Portal Config](./pages/PortalConfig.md)
+- [Perspectives Config](./pages/PerspectiveConfig.md)
+- [Sparql Config](./pages/SparqlConfig.md)
+- [Locales](./pages/Locales.md)
 - [Custom Components](pages/CustomComponents.md)
 - [Deployment](pages/Deployment.md)
 - [Changelog](CHANGELOG.md)
diff --git a/docs/pages/Introduction.md b/docs/pages/Introduction.md
diff --git a/docs/pages/Locales.md b/docs/pages/Locales.md
@@ -0,0 +1,52 @@
+# Locales
+
+Locale config files are json config where the actual text content of the portal is written. A locale.json must be made
+per language the portal uses. 
+
+Each entry in this json file refers to some ID defined either in config or in sampo core.
+
+## General entries
+The upper half of the example locale files in this repository (up until `perspectives`) contains some general locale config
+that most portals will use. It is fine to copy this and edit the text to fit your portal or remove parts you do not need.
+
+
+## Properties
+In the `perspectives` object the text for facets and table columns gets defined. The most important thing to know here is that the same text gets used for column and facet labels and descriptions for the matching properties.
+
+## Text pages
+
+### Info dropdown
+All pages defined in the `infoDropdown` in `portalConfig.json` must have their page content defined in locales.
+
+For example:
+```
+"infoDropdown": [
+    {
+        "id": "about",
+        "externalLink": false,
+        "translatedText": "aboutPage",
+        "internalLink": "/about"
+    }
+]
+```
+must in the root of locales have something like:
+```
+"aboutPage": "htmlFile:pages/about_en.html"
+```
+and then put the actual content of the page in said html file. The content can also be put directly in the locale json as a string, but since that gets very dirty for large pages it is not recommended.
+
+
+### Dummy internal perspectives
+The above part can only put these pages in the info dropdown. It is also possible to add them as perspectives, meaning 
+they appear as their own button in the topbar and can have a card on the front page.
+
+To define that make a new perspective json file under ``search_perspectives`` and structure it like this:
+```
+{
+    "id": "about",
+    "searchMode": "dummy-internal",
+    "internalLink": "/about",
+    "hideTopPerspectiveButton": false
+}
+```
+Then also add it in `portalConfig.json` as if it were a normal perspective.
diff --git a/docs/pages/PerspectiveConfig.md b/docs/pages/PerspectiveConfig.md
@@ -0,0 +1,184 @@
+# Perspectives config
+
+Every perspective referenced in `portalConfig.json` needs a perspective json config file. Some example configs are presented here.
+
+## Search perspectives
+Search perspectives are the perspectives for faceted search pages.
+
+### General structure
+
+```
+{
+    "id": "corporations",
+    ... // more general config
+    "resultClasses": {
+        "corporations": {
+            "paginatedResultsConfig": {
+                "tabID": 0,
+                "component": "ResultTable",
+                ... // more resultclass config
+            },
+            "instanceConfig": {
+                ...
+                "instancePageResultClasses": {
+                    "instancePageTable": {
+                        "tabID": 0,
+                        "component": "InstancePageTable",
+                        ...
+                    }
+                }
+            }
+        },
+        "export": {
+            "tabID": 1,
+            "component": "ExportCSV",
+            ...
+        },
+        ... //more tabs
+    },
+    "properties": [
+        {
+            "id": "scobID",
+            ... // more property config
+        },
+        {
+            "id": "uri",
+            ...
+        },
+        ... // more properties
+    ],
+    "facets": {
+        "corporationName": {
+            ... // facet config
+        },
+        ... // more facets
+    }
+}
+```
+
+The id of the perspective is what you need to reference in `portalConfig.json`. 
+
+In resultClasses you define all the different tabs you want in your perspective, as well as eventually an instanceConfig if you want an instance page with the same properties as your table.
+
+Under properties, you can define all the columns shown in your table.
+
+Under facets, you can define all the filters and sorting predicates of your columns.
+
+---
+
+### General config properties
+```
+"id": "corporations",
+"endpoint": {
+    "url": "",
+    "useAuth": false,
+    "prefixesFile": "SparqlQueriesPrefixes.js",
+    "defaultSparql": true
+},
+"generalQueries": {
+    "facetResultSetQuery": "facetResultSetQueryCustom"
+},
+"sparqlQueriesFile": "SparqlQueriesScob.js",
+"baseURI": "http://example.com/resource",
+"URITemplate": "<BASE_URI>/corporation/<LOCAL_ID>",
+"facetClass": "bhf:Corporation",
+"frontPageImage": "main_page/events-452x262.jpg",
+"searchMode": "faceted-search",
+"defaultTab": "table",
+"defaultInstancePageTab": "table",
+```
+
+
+
+---
+
+### Table resultClass
+The most basic resultclass used in virtually every perspective is table with also an associated instance page. 
+
+#### ResultClass
+```
+"resultClasses": {
+  "yourTable": {
+      "paginatedResultsConfig": {
+          "tabID": 0,
+          "component": "ResultTable",
+          "tabPath": "table",
+          "tabIcon": "CalendarViewDay",
+          "propertiesQueryBlock": "yourQueryBlock",
+          "pagesize": 20,
+          "sortBy": null,
+          "sortDirection": null
+      },
+      "instanceConfig": {
+          "propertiesQueryBlock": "yourQueryBlock",
+          "instancePageResultClasses": {
+              "instancePageTable": {
+                  "tabID": 0,
+                  "component": "InstancePageTable",
+                  "tabPath": "table",
+                  "tabIcon": "CalendarViewDay"
+              }
+          }
+      }
+  },
+  ...
+},
+```
+See [sparql config](./SparqlConfig.md) for how to exactly config your sparql queries.
+
+#### Properties
+```
+"properties": [
+    {
+        "id": "ID",
+        "valueType": "object",
+        "makeLink": true,
+        "externalLink": false,
+        "sortValues": true,
+        "numberedList": false,
+        "minWidth": 30
+    },
+    {
+        "id": "uri",
+        "valueType": "object",
+        "makeLink": false,
+        "sortValues": true,
+        "onlyOnInstancePage": true
+    },
+    {
+        "id": "name",
+        "valueType": "object",
+        "makeLink": true,
+        "externalLink": false,
+        "sortValues": true,
+        "sortBy": "startDate",
+        "numberedList": false,
+        "minWidth": 250
+    },
+    ...
+],
+```
+The properties list lists all columns that can be displayed in the table. See [sparql config](./SparqlConfig.md) for how exactly to query the data to be displayed in the table. `onlyOnInstancePage` can be set to only display the value on instance pages as to not bloat the results table. `sortBy` defines by which field a cell with multiple entries will be sorted.
+
+#### Facets
+```
+"facets": {
+  "id": {
+      "sortByPredicate": "ex:id"
+  },
+  "name": {
+      "containerClass": "one",
+      "facetType": "text",
+      "filterType": "textFilter",
+      "sortByPredicate": "ex:hasName/rdfs:label",
+      "textQueryProperty": "ex:hasName/rdfs:label"
+  },
+}
+```
+
+Under facets the filter facets on the left side of the result components get defined. `sortByPredicate` can also be defined here which declares which predicate should be used to sort on the matching column. 
+
+Facets can use a variety of default components and filters. Custom facet components and filters are also supported as documented in [custom components](./CustomComponents.md).
+
+---
+