Skip to content

About

A package to build easily client-side interfaces to SKOS dictionaries

Topics

Resources

Stars

5 stars

Watchers

1 watching

Forks

Latest commit

 

History

41 Commits

Folders and files

Repository files navigation

SKOSClient

A lightweight tool for building client-side web interfaces for SKOS vocabularies and thesauri. SKOSClient converts RDF/SKOS files into optimized JSON formats and generates a ready-to-deploy single-page application with search, navigation, and multilingual support.

Features

  • 🚀 Zero backend required - Fully client-side application
  • 🌐 Multilingual support - Interface and content in multiple languages
  • 🔍 Full-text search - Fast label-based search with autocomplete
  • 📱 Responsive design - Works on desktop and mobile devices
  • ⚡ Optimized performance - JSON-based data structure for fast loading
  • 🔒 Privacy - All the query are performed client-side: no logs of the terms searched.

Installation

Install directly from GitHub:

pip install git+https://github.com/gpdsm/skosclient.git

Quick Start

  1. Generate the application from your SKOS file:
skosclient mydictionary.ttl

This creates a mydictionary/ directory containing the complete web application.

  1. Serve the application locally:

For testing purposes you can serve the application using python. Rember that http.server does not handle UTF-8 so some character might not be rendered correctly.

cd mydictionary
python -m http.server
  1. Open in browser: Navigate to http://localhost:8000/

How It Works

SKOSClient processes your SKOS/RDF vocabulary and generates:

  • JSON concept files (concepts_{lang}.json) - All SKOS concepts with their properties
  • Label-to-ID mappings (labels_to_concept_{lang}.json) - Optimized for fast search
  • Metadata file (thesaurus_metadata.json) - Configuration and available languages
  • Translation files (ui_translations_{lang}.json) - Interface localization
  • Static HTML/CSS/JS - Complete single-page application

The generated application uses vanilla JavaScript with no dependencies, making it lightweight and easy to deploy on any web server or CDN.

URL Structure and Permalinks

Default URLs

Concepts are accessible via query parameters:

/mydictionary/?concept={concept_id}&lang=en
/mydictionary/?concept={concept_id}&lang=it&ui=en

Query parameters:

  • concept or id - The concept identifier
  • lang - Content language (e.g., 'en', 'it', 'de')
  • ui or uilang - Interface language (optional, auto-detected from browser)

Clean URLs with Nginx

For SEO-friendly URLs, configure a reverse proxy to rewrite paths:

server {
    listen 80;
    server_name www.mywebsite.com;
    root /var/www/html;
    
    location /mydictionary/ {
        # Rewrite: /mydictionary/{concept_id} -> /mydictionary/?concept={concept_id}&lang=en
        rewrite ^/mydictionary/([^/]+)$ /mydictionary/?concept=$1&lang=en permanent;
        
        # Serve the application
        try_files $uri $uri/ /mydictionary/index.html;
    }
    
    # Serve JSON files with correct MIME type
    location ~ \.json$ {
        add_header Content-Type application/json;
        add_header Cache-Control "public, max-age=3600";
    }
}

This enables URLs like:

  • /mydictionary/backend → concept with ID "backend"
  • /mydictionary/formal_language → concept with ID "formal_language"

Advanced URL patterns

Support multiple languages in the URL path:

location /mydictionary/ {
    # Pattern: /mydictionary/{concept_id}/{lang}
    if ($request_uri ~* "^/mydictionary/([^/]+)/([^/?]+)$") {
        return 301 /mydictionary/?concept=$1&lang=$2;
    }
    
    # Pattern: /mydictionary/{concept_id}
    if ($request_uri ~* "^/mydictionary/([^/?]+)$") {
        return 301 /mydictionary/?concept=$1&lang=en;
    }
    
    try_files $uri $uri/ /mydictionary/index.html;
}

Metadata Configuration

The generated thesaurus_metadata.json file can be customized:

{
  "title": "My Thesaurus",
  "description": "A specialized vocabulary for my domain",
  "available_languages": ["en", "it", "fr", "de"],
  "ui_languages": ["en", "it"]
}

Customization

Styling

In the styles folder there are additional styles, you can copy and paste on the outpufolder.

Translations

Add new interface languages by creating ui_translations_{lang}.json files with translations for UI elements. Please summit a pull request if the translation is not available.

Linking with other search services

Skosclient allows you to perform an external search on linked coropora,for concepts and alternative lables using {id} as a placeholder for the id of the concept or the alternative label.

skosclient  .\dismi_vocabolario.ttl --concept-external-search-url "https://www.google.com/search?q={id}"   --alternative-labels-external-url "https://www.google.com/search?q={id}"
skosclient  .\dismi_vocabolario.ttl --concept-external-search-url "http://127.0.0.1:5000/?type=concept&q={id}"   --alternative-labels-external-url "http://127.0.0.1:5000/?type=alternativeLabel&q={id}"

Browser Support

  • Chrome/Edge 90+
  • Firefox 88+
  • Safari 14+
  • Any browser with ES6+ and Intl.DisplayNames support

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

Support

For issues and questions, please use the GitHub issue tracker.

Founding

Skosclient was developed during Forms of Italian Poetry project supported by the Fondazione Cassa di Risparmio di Padova e Rovigo as part of the "Ricerca Scientifica di Eccellenza 2023" project.

About

A package to build easily client-side interfaces to SKOS dictionaries

Topics

Resources

Stars

5 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages