A modern web application for evaluating RDF metadata quality based on FAIR+C principles, built with React + TypeScript.

• Complete MQA evaluation with real metrics for DCAT-AP, DCAT-AP-ES and NTI-RISP
• Data Quality Analysis ISO/IEC 25012-based assessment for CSV/JSON distributions (Only backend enabled)
• Multi-format support RDF/XML, Turtle, JSON-LD, N-Triples, GeoJSON with auto-detection
• Remote URL processing to validate online datasets (Full option only if backend enabled)
• SPARQL endpoint integration with predefined queries for data portals
• Dashboard for monitoring and managing metadata quality results.
• Interactive visualization with FAIR+C radar charts and detailed tables
• Controlled vocabularies integrated (formats, licenses, access rights, etc.) from data.europa.eu
• Responsive interface with Bootstrap 5 and modern components
• Full TypeScript for safe and maintainable development

• Tech Stack
• Quick Start
• Configuration
  • MQA Profiles
  • Quality Metrics
  • SPARQL Configuration
• Development
• Deployment
  • Docker
  • GitHub Pages
• Backend API
• Architecture
• Internationalization
• Theming
• Troubleshooting

Prerequisites: Docker and Docker Compose installed

# Clone repository git clone https://github.com/mjanez/metadata-quality-react.git cd metadata-quality-react # Start with pre-built image from GHCR docker compose up -d # Or build locally IMAGE_TAG=local docker compose up -d --build

Prerequisites: Node.js >= 16.x, npm >= 8.x

# Quick start (both frontend and backend) ./dev-start.sh # Or manually: # Install dependencies npm install # Start development server (frontend only) npm start # Optional: Start backend server (in separate terminal) cd backend npm i && npm start

The application is configured through the src/config/mqa-config.json file, which centralizes all settings for profiles, metrics, and SPARQL endpoints. This configuration file follows a structured approach to support multiple metadata standards and quality assessment methodologies.

Profiles define the metadata standards (DCAT-AP, DCAT-AP-ES, NTI-RISP) with their specific versions and validation rules.

{ "profiles": { "profile_id": { "versions": { "version_number": { "name": "Display Name", "maxScore": 405, "icon": "img/icons/icon.svg", "url": "https://profile-documentation-url", "sampleUrl": "https://sample-data-url", "shaclFiles": [ "https://shacl-validation-file-1.ttl", "https://shacl-validation-file-2.ttl" ], "dimensions": { "findability": { "maxScore": 100 }, "accessibility": { "maxScore": 100 }, "interoperability": { "maxScore": 110 }, "reusability": { "maxScore": 75 }, "contextuality": { "maxScore": 20 } } } }, "defaultVersion": "version_number" } } }

1. Create the profile structure in mqa-config.json:

"my_custom_profile": { "versions": { "1.0.0": { "name": "My Custom Profile 1.0.0", "maxScore": 400, "icon": "img/icons/custom.svg", "url": "https://my-profile-docs.com", "sampleUrl": "https://my-sample-data.ttl", "shaclFiles": [ "https://my-shacl-validation.ttl" ], "dimensions": { "findability": { "maxScore": 100 }, "accessibility": { "maxScore": 100 }, "interoperability": { "maxScore": 100 }, "reusability": { "maxScore": 75 }, "contextuality": { "maxScore": 25 } } } }, "defaultVersion": "1.0.0" }

2. Add corresponding metrics in the profile_metrics section
3. Add icon file to public/img/icons/
4. Update translations in public/locales/en/translation.json and public/locales/es/translation.json

Metrics define how quality is measured for each FAIR+C dimension. Each metric has an ID, weight, and associated RDF property.

{ "profile_metrics": { "profile_id": { "dimension_name": [ { "id": "metric_identifier", "weight": 30, "property": "rdf:property" } ] } } }

1. Define the metric in the appropriate profile and dimension:

"findability": [ { "id": "my_custom_metric", "weight": 25, "property": "my:customProperty" } ]

2. Add metric labels to translation files:

{ "metrics": { "specific": { "my_custom_metric": "My Custom Metric" } } }

3. Implement evaluation logic in src/services/MQAService.ts if needed

The SPARQL configuration enables integration with data portals and endpoints for automated data retrieval and validation.

{ "sparql_config": { "default_endpoint": "https://sparql-endpoint-url", "queries": { "profile_id": [ { "id": "query_identifier", "name": "Human-readable name", "description": "Query description", "query": "SPARQL query string with {parameter} placeholders", "parameters": [ { "name": "parameter_name", "label": "Parameter Label", "type": "text", "required": true, "placeholder": "Enter value...", "description": "Parameter description" } ] } ] } } }

1. Define the query for a specific profile:

"my_profile": [ { "id": "my_custom_query", "name": "Custom Data Query", "description": "Retrieves custom dataset information", "query": "PREFIX dcat: <http://www.w3.org/ns/dcat#>\nCONSTRUCT {\n ?dataset a dcat:Dataset ;\n dct:title ?title .\n}\nWHERE {\n ?dataset a dcat:Dataset ;\n dct:publisher ?publisher ;\n dct:title ?title .\n FILTER (regex(str(?publisher), \"{org_id}\", \"i\"))\n}\nLIMIT {limit}", "parameters": [ { "name": "org_id", "label": "Organization ID", "type": "text", "required": true, "placeholder": "e.g., ministry-of-health", "description": "Identifier of the organization" }, { "name": "limit", "label": "Result Limit", "type": "number", "required": false, "placeholder": "50", "description": "Maximum number of results" } ] } ]

2. Parameter Types Available:

   • text: Text input
   • number: Numeric input
   • select: Dropdown (requires options array)
   • textarea: Multi-line text

3. Query Features:

   • Parameter substitution: Use {parameter_name} in queries
   • CONSTRUCT queries: Preferred for generating valid RDF
   • Endpoint testing: Use debug queries to test connectivity

Special debug queries help test endpoint connectivity:

"debug": [ { "id": "test_endpoint", "name": "Test Endpoint", "description": "Verify endpoint connectivity", "query": "SELECT * WHERE { ?s ?p ?o } LIMIT 10", "parameters": [] } ]

1. Profile Naming: Use consistent IDs (dcat_ap, dcat_ap_es, dcat_ap_es_hvd nti_risp, dcat_ap_es_legacy)
2. Version Management: Support multiple versions per profile
3. Metric Weights: Ensure weights sum to reasonable totals per dimension
4. SPARQL Queries: Use CONSTRUCT queries for better RDF generation
5. Parameter Validation: Provide clear descriptions and examples
6. Icon Management: Store icons in public/img/icons/ as SVG
7. Translation Keys: Keep metric IDs consistent across profiles

react-app/ ├── public/ │ ├── data/ # JSONL vocabularies │ │ ├── access_rights.jsonl │ │ ├── file_types.jsonl │ │ ├── licenses.jsonl │ │ └── ... │ ├── locales/ # i18n translations │ │ ├── en/translation.json # English translations + metrics labels │ │ └── es/translation.json # Spanish translations + metrics labels │ └── img/icons/ # Profile icons ├── src/ │ ├── components/ # React components │ │ ├── ValidationForm.tsx # Input form + SPARQL integration │ │ ├── ValidationResults.tsx # Results and charts │ │ ├── QualityChart.tsx # FAIR+C radar chart │ │ └── ... │ ├── services/ # Business logic │ │ ├── MQAService.ts # Main MQA engine + metric evaluation │ │ ├── SPARQLService.ts # SPARQL endpoint integration │ │ └── RDFService.ts # RDF processing │ ├── config/ # Configuration │ │ └── mqa-config.json # **Central configuration file** │ ├── types/ # TypeScript types │ └── i18n/ # Internationalization setup └── package.json 

This application can be deployed on multiple platforms with different configurations.

# Disable backend features sed -i 's/"enabled": true/"enabled": false/g' src/config/mqa-config.json npm run deploy

Features: Full control, both frontend and backend, custom domain support

{ "backend_server": { "enabled": true, "url": "" }, "data_quality": { "enabled": true, "require_backend": true } }

# 1. Clone and configure git clone https://github.com/mjanez/metadata-quality-react.git cd metadata-quality-react cp .env.example .env # 2. Start with pre-built image (recommended) docker compose up -d # Or build locally IMAGE_TAG=local docker compose up -d --build # 3. Access application # Frontend: https://localhost:443 # Backend API: https://localhost:443/api/health

services: mqa-backend: # Express.js Backend API ports: - "3001:3001" # Backend API (not exposed by default) mqa-frontend: # React Frontend Application ports: - "3000:3000" # Frontend (not exposed by default) nginx: # Nginx Reverse Proxy ports: - "80:80" # HTTP (redirects to HTTPS) - "443:443" # HTTPS (main entry point)

Service Architecture:

• mqa-backend: Node.js API for data validation, quality assessment, and SHACL validation
• mqa-frontend: Static React app served with serve
• nginx: Reverse proxy that routes requests to frontend and /api to backend

Default Access:

• All traffic goes through Nginx (https://localhost)
• Backend and frontend ports are internal to Docker network
• For direct service access during debugging, expose ports in docker-compose.yml

Environment Variables (.env file):

# Image Configuration IMAGE_TAG=latest # Port Configuration FRONTEND_PORT=3000 BACKEND_PORT=3001 # Service Hosts (Docker internal networking) BACKEND_HOST=mqa-backend FRONTEND_HOST=mqa-frontend # Nginx Configuration NGINX_HTTP_PORT=80 NGINX_HTTPS_PORT=443 # Application PUBLIC_URL=/ REACT_APP_BACKEND_URL=/api NODE_ENV=production # Security Configuration NODE_TLS_REJECT_UNAUTHORIZED=1 ALLOWED_DOMAINS=

Custom Configuration:

services: mqa-frontend: volumes: # Mount custom MQA config - ./mqa-config.json:/app/build/config/mqa-config.json:ro # Mount custom vocabularies - ./public/data:/app/build/data:ro mqa-backend: environment: # Security: Whitelist allowed domains for SSRF protection - ALLOWED_DOMAINS=datos.gob.es,semiceu.github.io # Disable SSL verification (development only!) - NODE_TLS_REJECT_UNAUTHORIZED=0

# View logs for all services docker compose logs -f # View specific service logs docker compose logs -f mqa-backend docker compose logs -f mqa-frontend docker compose logs -f nginx # Restart services docker compose restart # Stop and remove docker compose down # Update and rebuild docker compose up -d --build # Health check (via nginx) curl -k https://localhost/health curl -k https://localhost/api/health # Direct service health check (within containers) docker exec mqa-frontend curl http://localhost:3000/ docker exec mqa-backend curl http://localhost:3001/api/health # Using Makefile (recommended) make logs-backend # View backend logs make logs-frontend # View frontend logs make logs-nginx # View nginx logs make health # Check all services health make shell-backend # Open shell in backend container

Pre-built Docker images are automatically published to GitHub Container Registry on every push and pull request.

Available Images:

• Backend: ghcr.io/mjanez/metadata-quality-react-backend
• Frontend: ghcr.io/mjanez/metadata-quality-react-frontend

Quick Deploy:

# Pull latest stable versions docker pull ghcr.io/mjanez/metadata-quality-react-backend:latest docker pull ghcr.io/mjanez/metadata-quality-react-frontend:latest # Or use docker-compose (recommended) cat > docker-compose.yml << EOF services:  mqa-backend:  image: ghcr.io/mjanez/metadata-quality-react-backend:latest  environment:  - NODE_ENV=production  - PORT=3001  restart: unless-stopped  networks:  - mqa-network   mqa-frontend:  image: ghcr.io/mjanez/metadata-quality-react-frontend:latest  environment:  - NODE_ENV=production  restart: unless-stopped  networks:  - mqa-network  depends_on:  - mqa-backend   nginx:  image: nginx:alpine  ports:  - "80:80"  - "443:443"  volumes:  - ./nginx.conf:/etc/nginx/nginx.conf:ro  depends_on:  - mqa-frontend  - mqa-backend  restart: unless-stopped  networks:  - mqa-network  networks:  mqa-network:  driver: bridge EOF docker compose up -d

Available Tags:

• latest - Latest stable version (main branch)
• develop - Development version (develop branch)
• pr-<number> - Pull request specific images
• v1.2.3 - Semantic versioning tags

Multi-Architecture Support: Images built for linux/amd64 and linux/arm64 (Apple Silicon/ARM servers)

See: GHCR Documentation for complete details on image tags, security scanning, and usage.

1. Generate SSL certificates (automatic self-signed for development):

# Generate self-signed certificate (local development) make ssl-generate # or ./docker/nginx/generate-ssl.sh # For production: replace with valid certificates # See docker/README.md#ssl-configuration

2. Start with nginx profile:

# HTTP automatically redirects to HTTPS docker compose up -d # or make up-prod

3. Access via HTTPS:

https://localhost (development - will show browser warning) https://your-domain.com (production with valid certificate) 

For complete deployment with API backend (Python FastAPI):

git clone https://github.com/mjanez/metadata-quality-stack cd metadata-quality-stack docker compose up -d

Includes:

• React frontend (this project)
• Python FastAPI backend
• Streamlit dashboard
• Nginx reverse proxy
• Volume persistence

Features: Simple static hosting, free for public repos, no backend support

{ "backend_server": { "enabled": false }, "data_quality": { "enabled": false } }

• Repository must be public
• GitHub Pages must be enabled in repository settings

# Deploy to GitHub Pages npm run deploy

This command:

1. Builds the application with correct PUBLIC_URL
2. Deploys to gh-pages branch
3. Makes it available at: https://{username}.github.io/{repo-name}/

# 1. Build with correct base path npm run build # 2. Deploy using gh-pages npx gh-pages -d build

For complete local development including backend:

# Install dependencies and start both servers ./dev-start.sh # If ports are occupied, clean up first: ./dev-cleanup.sh && ./dev-start.sh

# Terminal 1: Start backend server cd backend npm install npm start # Backend running on http://localhost:3001 # Terminal 2: Start React app npm install npm start # Frontend running on http://localhost:3000

Environment Setup:

The .env.local file is automatically configured for local development:

# Local development configuration (already configured) BROWSER=none PORT=3000 BACKEND_PORT=3001 REACT_APP_BACKEND_URL=http://localhost:3001/api REACT_APP_ENV=development

Custom Configuration:

To modify ports or settings, edit .env.local:

# Change frontend port PORT=3005 # Change backend port BACKEND_PORT=3002 REACT_APP_BACKEND_URL=http://localhost:3002/api

Development Script Features:

The ./dev-start.sh script automatically:

• Checks Node.js and npm installation
• Installs dependencies if missing
• Loads environment variables from .env.local
• Starts backend server on configured port (default: 3001)
• Starts frontend development server on configured port (default: 3000)
• Verifies backend health check
• Handles graceful shutdown on Ctrl+C

Backend Configuration:

The backend (backend/server.js) provides:

• CORS proxy for accessing external RDF data
• URL validation to check accessibility
• Data download with SSL certificate handling
• Health check endpoint
• Batch URL validation for performance

API Endpoints:

GET /api/health # Health check POST /api/validate-url # Single URL validation POST /api/validate-urls-batch # Batch URL validation (performance) POST /api/download-data # Download and proxy data

Port Configuration:

The backend provides a REST API for programmatic access to quality assessment and SHACL validation. Full documentation available in backend/API.md.

# Quality assessment curl -X POST http://localhost:3001/api/v1/quality \ -H "Content-Type: application/json" \ -d '{"url": "https://example.org/catalog.ttl", "profile": "dcat_ap_es"}' # SHACL validation with Turtle output curl -X POST http://localhost:3001/api/v1/shacl \ -H "Content-Type: application/json" \ -d '{"url": "https://example.org/catalog.ttl", "outputFormat": "turtle"}' # DQV format (W3C Data Quality Vocabulary) curl -X POST http://localhost:3001/api/v1/quality \ -H "Content-Type: application/json" \ -d '{"url": "https://example.org/catalog.ttl", "outputFormat": "dqv"}'

The JSON output from the API can be loaded directly into the Dashboard. The frontend auto-detects the API format and converts it:

1. Call /api/v1/validate and save the response
2. Go to Dashboard > Upload Data
3. Upload the JSON file - both metrics and SHACL data load automatically

flowchart TB subgraph Client ["Browser"] App["React App\n(Frontend)"] end subgraph Nginx ["Nginx Reverse Proxy"] RP["/:443\n(HTTPS)"] end subgraph Frontend ["Frontend Container"] VF["ValidationForm"] VR["ValidationResults"] MQA["MQAService"] RDF["RDFService"] end subgraph Backend ["Backend Container"] API["Express API\n:3001"] VAL["URL Validation"] PROXY["Data Download"] QAPI["Quality API v1"] end Client --> Nginx Nginx -->|/| Frontend Nginx -->|/api| Backend Frontend -->|API Calls| Backend Backend -->|External RDF| Internet((Internet)) 

Service Architecture:

• Frontend: Static React app with quality assessment logic
• Backend: Node.js API for data fetching, validation, and SHACL
• Nginx: Routes traffic between services, handles SSL/TLS

1. Configuration Loading: mqa-config.json → Services
2. User Input: Form data → ValidationForm
3. SPARQL Integration: Queries → SPARQLService → RDF data
4. RDF Processing: Raw data → RDFService → Parsed triples
5. Quality Assessment: Triples → MQAService → Metrics scores
6. Visualization: Scores → Chart components → User interface

• DCAT-AP 2.1.1: 405 maximum points
• DCAT-AP 3.0.0: 405 maximum points
• DCAT-AP-ES 1.0.0: 405 maximum points
• NTI-RISP 2013: 305 maximum points

• English (default)
• Spanish (Español)

1. Create translation file in public/locales/{lang}/translation.json
2. Add language option to LanguageSelector component
3. Update i18n configuration in src/i18n/index.ts

Translation files in public/locales/{lang}/translation.json include both UI labels and metric definitions:

{ "common": { "title": "Metadata Quality Assessment", "loading": "Loading...", "validate": "Validate" }, "dimensions": { "findability": "Findability", "accessibility": "Accessibility", "interoperability": "Interoperability", "reusability": "Reusability", "contextuality": "Contextuality" }, "metrics": { "labels": { "name": "Métrica", "score": "Puntuación", ... }, "specific": { "dcat_keyword": "Palabras clave", "dcat_theme": "Temas/Categorías", "dct_spatial": "Cobertura espacial", "dct_temporal": "Cobertura temporal", "dcat_access_url_status": "Disponibilidad de la URL de acceso" ... } } }

The metrics.specific section contains all quality metric translations and is integrated with the MQA evaluation system.

Edit these files:

• src/App.css - Main application styles
• src/components/*.css - Component-specific styles
• Bootstrap variables can be overridden in CSS

:root { --bs-primary: #0d6efd; --mqa-chart-bg: #ffffff; --mqa-text-color: #212529; } [data-bs-theme="dark"] { --mqa-chart-bg: #212529; --mqa-text-color: #ffffff; }

Controlled vocabularies are stored in public/data/ as JSONL files for efficient loading:

# Convert CSV vocabularies to JSONL format python3 scripts/vocabs_csv2jsonl.py

# Clear cache rm -rf node_modules/.cache npm run build

# Check types without build npx tsc --noEmit

# Check gh-pages branch git checkout gh-pages git log --oneline -5 # Force redeploy npm run deploy -- --force

# Check translation files cat public/locales/en/translation.json cat public/locales/es/translation.json

# Validate mqa-config.json syntax npm run build 2>&1 | grep -i "config\|json" # Check for missing metric labels grep -r "metrics.specific" public/locales/

Backend Server Configuration Errors:

# Check current backend_server configuration grep -A 10 '"backend_server"' src/config/mqa-config.json # Common fixes: # For GitHub Pages: Set "enabled": false # For Docker: Set "enabled": true, "url": "" # For local dev: Set "enabled": true, "url": "http://localhost:3001/api"

Data Quality Configuration Errors:

# Check current data_quality configuration  grep -A 5 '"data_quality"' src/config/mqa-config.json # GitHub Pages: Must be "enabled": false (no backend support) # Docker/Local: Can be "enabled": true (backend available)

Configuration by Deployment Type:

# Port already in use error ./dev-cleanup.sh # Clean up occupied ports ./dev-start.sh # Restart development servers # Backend connection issues curl http://localhost:3001/api/health # Check backend health cat .env.local # Verify configuration # Frontend can't reach backend # Check that REACT_APP_BACKEND_URL matches actual backend port grep REACT_APP_BACKEND_URL .env.local

# Analyze bundle size npm run build && npx webpack-bundle-analyzer build/static/js/*.js # Check for memory leaks in development npm start -- --profile

1. New Profile Support:

   • Update mqa-config.json with profile definition
   • Add SHACL validation files
   • Create profile icon in public/img/icons/
   • Add translations for profile name and metrics

2. New Quality Metrics:

   • Define metric in profile_metrics section
   • Implement evaluation logic in MQAService.ts
   • Add metric labels to translation files
   • Update documentation

3. SPARQL Queries:

   • Add queries to sparql_config.queries
   • Test with debug queries first
   • Document parameter usage
   • Provide sample data URLs

• TypeScript: Strict mode enabled, no any types
• React: Functional components with hooks
• CSS: Bootstrap 5 + custom CSS variables
• i18n: All user-facing text must be translatable
• Testing: Add tests for new services and components

This project is licensed under the MIT License. See the LICENSE file for details.

Built with ❤️ for the Open Data community