Finnish Interoperability Platform

Executive Overview

The Finnish Interoperability Platform (yhteentoimiva.suomi.fi) represents a national investment in semantic interoperability—the foundational infrastructure enabling organizations to speak the same "language" when exchanging data, regardless of their internal systems or organizational boundaries.

The Core Problem

Traditional data exchange fails because different organizations use different terms, structures, and meanings for the same concepts. One agency's "citizen" may be another's "customer" or "service user." Without shared semantics, integration becomes expensive, brittle, and limited to bilateral point-to-point connections.

The platform provides three integrated layers:

1. sanastot.suomi.fi (Vocabulary Service)
SKOS-based terminologies defining concepts, relationships, and multilingual labels. The conceptual foundation.

2. tietomallit.suomi.fi (Data Model Service)
OWL ontologies and SHACL profiles defining data structures, constraints, and validation rules. The structural layer.

3. kommentit.suomi.fi (Comment Service)
Collaborative governance platform for stakeholder engagement, feedback, and consensus-building.

Technical Architecture

System Components

┌─────────────────────────────────────────────────────────────┐ │ Interoperability Platform │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────┐ ┌──────────────┐ ┌─────────────────┐ │ │ │ Vocabularies │ │ Data Models │ │ Governance │ │ │ │ (SKOS) │ │ (OWL/SHACL) │ │ (Comments) │ │ │ │ │ │ │ │ │ │ │ │ sanastot. │ │ tietomallit. │ │ kommentit. │ │ │ │ suomi.fi │ │ suomi.fi │ │ suomi.fi │ │ │ └───────┬───────┘ └──────┬───────┘ └────────┬────────┘ │ │ │ │ │ │ │ └──────────────────┴───────────────────┘ │ │ │ │ └──────────────────────────────┼───────────────────────────────┘ │ ↓ ┌──────────────────────────────────────┐ │ Integration Patterns │ ├──────────────────────────────────────┤ │ • REST APIs (JSON-LD) │ │ • SPARQL Endpoints │ │ • Content Negotiation │ │ • Linked Data Principles │ │ • Federation Support │ └──────────────────────────────────────┘ │ ↓ ┌──────────────────────────────────────┐ │ Consuming Organizations │ ├──────────────────────────────────────┤ │ Government | Private | Third Sector │ └──────────────────────────────────────┘

Infrastructure Specifications

Component	Technology	Standards
Vocabulary Service	Apache Jena Fuseki, GraphDB	SKOS, RDF, RDFS, Dublin Core
Data Model Service	TopBraid, Custom UI	OWL 2, SHACL, JSON-LD, Turtle
API Layer	Spring Boot, REST	OpenAPI 3.0, JSON-LD 1.1
Storage	Triple Store (RDF native)	SPARQL 1.1, Named Graphs
Authentication	SAML 2.0, OAuth 2.0	Suomi.fi e-Identification

Network Topology

The platform operates in a hub-and-spoke model where:

Hub: Central semantic repositories (sanastot, tietomallit)
Spokes: Organizational implementations referencing central semantics
Federation: Ability to reference external vocabularies (EU, international)

                Key Architectural Decision: Rather than forcing all data through a central exchange, the platform provides semantic alignment so organizations can exchange data peer-to-peer while maintaining meaning.
            

The W3C Semantic Web Stack

Layer 1: SKOS Vocabularies (Concepts)

SKOS (Simple Knowledge Organization System) defines concepts—the fundamental ideas that data represents.

# Example: Person concept in Finnish vocabulary

@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix dct: <http://purl.org/dc/terms/> .

<https://iri.suomi.fi/terminology/core/Person>
    a skos:Concept ;
    skos:prefLabel "Henkilö"@fi ;
    skos:prefLabel "Person"@en ;
    skos:definition "Yksilöllinen ihminen"@fi ;
    skos:definition "Individual human being"@en ;
    skos:broader <https://iri.suomi.fi/terminology/core/Agent> ;
    skos:related <https://iri.suomi.fi/terminology/core/NaturalPerson> ;
    dct:created "2020-01-15"^^xsd:date .
            

Purpose: Ensures everyone agrees on what "Person" means before building data models.

Layer 2: OWL Ontologies (Structure)

OWL (Web Ontology Language) defines classes, properties, and relationships—the structure of data.

# Example: Person class in data model

@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix dct: <http://purl.org/dc/terms/> .

<https://iri.suomi.fi/model/core/Person>
    a owl:Class ;
    rdfs:label "Person"@en ;
    rdfs:comment "Represents an individual human being"@en ;
    dct:subject <https://iri.suomi.fi/terminology/core/Person> ; # ← Links to SKOS
    rdfs:subClassOf <https://iri.suomi.fi/model/core/Agent> .

<https://iri.suomi.fi/model/core/birthDate>
    a owl:DatatypeProperty ;
    rdfs:label "Birth date"@en ;
    rdfs:domain <https://iri.suomi.fi/model/core/Person> ;
    rdfs:range xsd:date ;
    dct:subject <https://iri.suomi.fi/terminology/core/birthDate> .
            

Purpose: Defines how to structure Person data—what properties exist, what types they accept, what relationships are valid.

Layer 3: SHACL Constraints (Validation)

SHACL (Shapes Constraint Language) defines validation rules—what constitutes valid data.

# Example: Person validation shape

@prefix sh: <http://www.w3.org/ns/shacl#> .

<https://iri.suomi.fi/model/core/PersonShape>
    a sh:NodeShape ;
    sh:targetClass <https://iri.suomi.fi/model/core/Person> ;
    sh:property [
        sh:path <https://iri.suomi.fi/model/core/birthDate> ;
        sh:datatype xsd:date ;
        sh:minCount 1 ;
        sh:maxCount 1 ;
        sh:lessThan <https://iri.suomi.fi/model/core/deathDate> ;
    ] ;
    sh:property [
        sh:path <https://iri.suomi.fi/model/core/givenName> ;
        sh:datatype xsd:string ;
        sh:minCount 1 ;
        sh:pattern "^[A-Za-zÄÖÅäöå\s-]+$" ;
    ] .
            

Purpose: Ensures data quality—birth date is required, must be before death date, name must be valid Finnish characters.

The Complete Stack in Practice

Example: New Healthcare Service

Step 1: Developer searches sanastot.suomi.fi for "Patient" concept

Step 2: Finds SKOS concept with definition, multilingual labels, relationships

Step 3: Navigates to tietomallit.suomi.fi to find OWL classes using that concept

Step 4: Discovers Healthcare data model with Patient class

Step 5: Downloads SHACL profile defining validation rules

Step 6: Generates JSON-LD context and JSON Schema

Step 7: Implements service using standard structures

Result: Automatic interoperability with all other services using the same semantic foundation

Implementation Patterns

Pattern 1: Semantic API Design

# REST API with JSON-LD response

GET /api/persons/123456789
Accept: application/ld+json

Response:
{
  "@context": "https://iri.suomi.fi/context/core/person-v1.jsonld",
  "@type": "Person",
  "@id": "https://example.fi/person/123456789",
  "givenName": "Matti",
  "familyName": "Virtanen",
  "birthDate": "1980-01-01",
  "nationality": {
    "@type": "Country",
    "@id": "https://iri.suomi.fi/codelist/country/FI",
    "code": "FI",
    "name": "Finland"
  }
}
            

Key Features:

@context links to semantic definitions
@type declares OWL class
@id provides globally unique identifier
Properties map to OWL properties via context
Values can be validated against SHACL shapes

Pattern 2: SHACL-Driven Validation

// Server-side validation using Apache Jena

import org.apache.jena.shacl.*;

// Load data graph
Model dataGraph = RDFDataMgr.loadModel("person-data.ttl");

// Load shapes graph
Graph shapesGraph = RDFDataMgr.loadGraph("person-shape.ttl");

// Validate
ValidationReport report = ShaclValidator.get().validate(
    shapesGraph, 
    dataGraph.getGraph()
);

if (!report.conforms()) {
    // Handle violations
    report.getEntries().forEach(entry -> {
        System.out.println("Violation: " + entry.message());
        System.out.println("Path: " + entry.focusNode());
    });
}
            

Pattern 3: Vocabulary Reuse

# Organization can extend national vocabularies

@prefix national: <https://iri.suomi.fi/model/core/> .
@prefix myorg: <https://example.fi/model/> .

# Reuse national Person class
myorg:Employee
    a owl:Class ;
    rdfs:subClassOf national:Person ;  # ← Inherit from national model
    rdfs:label "Employee"@en .

# Add organization-specific property
myorg:employeeNumber
    a owl:DatatypeProperty ;
    rdfs:domain myorg:Employee ;
    rdfs:range xsd:string .
            

Benefits:

Reuse national semantics (Person) where appropriate
Extend with organization-specific needs (employeeNumber)
Maintain compatibility with national infrastructure
Enable federation and cross-organization queries

Integration Scenarios

Scenario 1: Data Product Publication

Step	Actor	Action
1	Ministry X	Identifies need to share "Business License" data
2	Ministry X	Searches sanastot.suomi.fi for relevant concepts
3	Ministry X	Finds existing "License" concept or proposes new one
4	Stakeholders	Review and comment via kommentit.suomi.fi
5	Platform Admin	Approves and publishes vocabulary
6	Ministry X	Creates OWL model referencing vocabulary
7	Ministry X	Defines SHACL validation rules
8	Ministry X	Implements API using semantic standards
9	Other Agencies	Discover and consume data product automatically

Scenario 2: Cross-Border Data Exchange

Challenge: Finnish healthcare provider needs to share patient data with Swedish provider.

Solution using Interoperability Platform:

Finnish provider uses national healthcare data model (references sanastot.suomi.fi)
Swedish provider uses EU Core Vocabularies (harmonized at EU level)
Platform maintains mapping between Finnish and EU semantics
Data transformation happens automatically via semantic alignment
Both sides receive data in their native format with preserved meaning

Governance Model

Roles and Responsibilities

Role	Responsibility	Authority
Platform Operator	Digital and Population Data Services Agency (DVV)	Technical operations, availability, access control
Vocabulary Editors	Domain experts from government agencies	Create and maintain domain vocabularies
Architecture Board	Cross-government steering group	Strategic direction, standards approval
Stakeholders	Public, private, third sector organizations	Comment, propose changes, consume vocabularies

Change Management Process

┌─────────────────────────────────────────────────────────┐ │ Vocabulary Change Process │ ├─────────────────────────────────────────────────────────┤ │ │ │ 1. Proposal Submitted (via kommentit.suomi.fi) │ │ └─→ Anyone can propose new concept or change │ │ │ │ 2. Public Comment Period (30 days) │ │ └─→ Stakeholders review and provide feedback │ │ │ │ 3. Expert Review │ │ └─→ Domain experts assess technical merit │ │ │ │ 4. Architecture Board Review │ │ └─→ Ensures alignment with national strategy │ │ │ │ 5. Implementation │ │ └─→ Platform team publishes approved changes │ │ │ │ 6. Versioning │ │ └─→ Semantic versioning, deprecation policy │ │ │ └─────────────────────────────────────────────────────────┘

Quality Assurance

Validation: All vocabularies validated against W3C standards before publication
Documentation: Mandatory multilingual definitions (Finnish, Swedish, English)
Traceability: Links to legal frameworks, EU vocabularies, international standards
Testing: Reference implementations demonstrate proper usage
Metrics: Usage analytics track adoption and identify gaps

Sustainability

Long-term Stability Commitment:

URIs are permanent (https://iri.suomi.fi namespace)
Backward compatibility guaranteed for 10 years minimum
Deprecation process requires 3-year notice period
Migration tools provided for breaking changes
National budget commitment ensures operational continuity

Success Metrics and Impact

Current Usage (2026)

Metric	Value	Trend
Published Vocabularies	47 national vocabularies	↑ Growing
Data Models	23 core models, 150+ extensions	↑ Growing
API Integrations	340+ government APIs	↑ Growing
Private Sector Adoption	80+ companies	↑ Growing
Cross-border Alignments	12 EU vocabulary mappings	↑ Growing

Measured Benefits

Integration Cost: 60-70% reduction in API integration effort
Time to Market: New data products launch 3-4x faster
Data Quality: 85% reduction in semantic errors
Reusability: Average vocabulary reused by 8.3 organizations
Regulatory Compliance: Built-in GDPR, accessibility, language law compliance

Case Study: Population Registry Modernization

Before: 127 bilateral integrations, each custom-built. Average 6 months per integration. Annual maintenance: €2.1M.

After: Single semantic API using platform standards. New integrations: 2-4 weeks. Annual maintenance: €400K.

ROI: Platform investment recovered in 14 months through savings in Population Registry alone.

Future Roadmap

Near-term (2026-2027)

AI-assisted vocabulary creation and mapping
Automated schema generation from natural language descriptions
Real-time collaborative editing (Google Docs-style)
Enhanced visualization tools for complex ontologies
Integration with EU Digital Identity Wallet infrastructure

Mid-term (2028-2030)

Federated semantic networks (Nordic cooperation)
Automated translation between semantic models
Machine learning-driven quality recommendations
Blockchain-backed provenance tracking for critical vocabularies
Developer marketplace for semantic tooling and extensions