UC 1.2 tutorial on creating JSON-LD context
Introduction
Public administrations often need to share information about their services with other organisations and the public. To do this effectively, the data must be easy to understand and work seamlessly across different systems. However, public services are becoming more complex, which means we need to capture more details, concepts, and relationships to handle various use cases.
The Core Public Service Vocabulary Application Profile (CPSV-AP) provides a generic framework to describe public services in a machine-readable way. It helps public administrations share and organise information about services. However, sometimes CPSV-AP needs to be extended with new concepts or restrictions to address more general or specific use cases.
For example, the terms Service and RequiredEvidence were introduced in CPSV-AP-NO to extend the CPSV-AP model such that it can fulfil the specific needs identified in Norway, where:
-
Service allows for describing not only public services but also general ones, enabling the representation of services provided through partnerships or private organisations.
-
RequiredEvidence provides a way to explicitly define the documentation or credentials needed to access a service, such as proof of address for health insurance registration. To make CPSV-AP more flexible and useful, creating a JSON-LD context is essential. JSON-LD helps structure the data so it can be easily shared and understood by different systems. This tutorial addresses the use case UC1.2, and will show how to create a JSON-LD context for an Application Profile that extends CPSV-AP with new concepts like Service and RequiredEvidence, which are defined by reusing concepts from the Core Business Vocabulary (CBV), following ideas from CPSV-AP-NO.
By extending CPSV-AP and using JSON-LD, public administrations can better organise their data, making it easier to share and integrate across systems while supporting a wider range of use cases.
Steps to Create a JSON-LD Context
Import or Define Elements:
Since CPSV-AP provides an existing JSON-LD context, we can import it in our own JSON-LD context using the @import statement. For example, in case of CPSV-AP version 3.2.0, the context can be directly reused like this:
"@context": {
"@import": "https://raw.githubusercontent.com/SEMICeu/CPSV-AP/master/releases/3.2.0/context/cpsv-ap.jsonld}
If a context that we can reuse does not exist, define the elements explicitly. For example, CPSV-AP uses specific terms like PublicService and ContactPoint. These terms must be mapped to URIs.
"{ "@context":{
"PublicService": "http://purl.org/vocab/cpsv#PublicService",
"ContactPoint": "http://data.europa.eu/m8g/ContactPoint"} }
If a context needs to be extended, define the new elements explicitly. For example, if we need new terms (classes), such as Service and RequiredEvidence, which are not in CPSV-AP these terms must be mapped to URIs (the examples are inspired from CPSV-AP-NO) :
{ "@context":{
"Service": "http://data.europa.eu/m8g/cpsvap#Service",
"RequiredEvidence": "http://data.europa.eu/m8g/cpsvap#RequiredEvidence" }
}
Shape the Structure
Once you’ve imported or defined the relevant terms, you need to structure your JSON-LD context to reflect the relationships between the classes and their properties. This allows you to describe public services and their details in a standardised and machine-readable format.
Let’s look at an example where we define a Service and some of its key properties, such as contactPoint, description, name and hasRequiredEvidence.
"@context":
"@import": "https://raw.githubusercontent.com/SEMICeu/CPSV-AP/master/releases/3.2.0/context/cpsv-ap.jsonld",
"Service": "http://data.europa.eu/m8g/cpsvap#Service",
"Service.hasRequiredEvidence": {
"@container": "@set",
"@id": "http://data.europa.eu/m8g/cpsvap#RequiredEvidence"},
"Service.description":{
"@container": "@set",
"@id": "http://purl.org/dc/terms/description",
"@type": "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString"},
"Service.contactPoint":{
"@container": "@set",
"@id": "http://data.europa.eu/m8g/contactPoint",
"@type": "@id" },
"Service.name":{
"@container": "@set",
"@id": "http://purl.org/dc/terms/title",
"@type": "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString"}
} }
Explanation of JSON-LD Keywords Used
-
@context: Defines the mapping between terms (e.g., PublicService) and their corresponding IRIs.
-
@container: Specifies how values are structured. For instance,
-
@set: Explicitly defines a property as an array of values. It ensures that even if the data includes just one value, it will still be treated as an array by JSON-LD processors. This makes post-processing of JSON-LD documents easier as the data is always in array form, even if the array only contains a single value
-
-
@id: Provides the unique identifier (IRI) for a term or property.
-
@type: Specifies the type of a value. Commonly used for linking to classes or data types.
-
@import: Imports another JSON-LD context, allowing reuse of its terms.
Example of a simple Service Instance
After defining the context and structure, you can now describe an actual Service instance by referencing the terms you defined earlier.
Example Scenario
Let’s assume a public administration offers a service called "Health Insurance Registration". This service allows citizens to register for health insurance, which requires certain documents (evidence) to complete the process. Citizens might need to contact the administration for guidance, and the service details should be structured in a way that makes it easy to share and integrate across systems.
To illustrate this, we’ve created a JSON-LD context representation of this service, highlighting
-
The required evidence for registration (e.g., Proof of Address).
-
The service’s name and description for clarity.
-
Contact information for users who may need assistance.
{"@context": { "@import": "https://raw.githubusercontent.com/SEMICeu/CPSV-AP/master/releases/3.2.0/context/cpsv-ap.jsonld"}, "Service": { "Service.hasRequiredEvidence": [ "http://example.org/RequiredEvidence/ProofOfAddress" ], "Service.name": "Health Insurance Registration", "Service.description": "A service for registering for health insurance.", "Service.contactPoint":{ "@type": "ContactPoint", "hasTelephone": "+420776723338" } } }
Extend the Context by reusing terms from Core Vocabularies
To highlight the reuse of terms from existing CVs, we can import the Core Business Vocabulary (CBV) context alongside the CPSV-AP context to gain access to business-related terms. This step ensures that you can use the additional terms from CBV, such as LegalEntity, Organisation, and ContactPoint, to enrich your Service descriptions.
{"@context": [ {
"@import": "https://raw.githubusercontent.com/SEMICeu/CPSV-AP/master/releases/3.2.0/context/cpsv-ap.jsonld" },
{ "@import": "https://raw.githubusercontent.com/SEMICeu/Core-Business-Vocabulary/master/releases/2.2.0/context/core-business-ap.jsonld"} ]}
Define Additional Properties from the Core Business Vocabulary
Add CBV terms to enhance the description of the Service entity.
{"@context": {
"Service": "http://data.europa.eu/m8g/cpsvap#Service",
"LegalEntity": "http://www.w3.org/ns/legal#LegalEntity",
"Service.providedBy": {
"@id": "http://www.w3.org/ns/legal#providedBy",
"@type": "LegalEntity"
} } }
Map Extended Properties in a Service Instance:
Use the extended properties to describe more aspects of Service instances. For example:
{ "@context": {
"@import": "https://raw.githubusercontent.com/SEMICeu/CPSV-AP/master/releases/3.2.0/context/cpsv-ap.jsonld" },
"Service": {
"Service.hasRequiredEvidence": [
"http://example.org/RequiredEvidence/ProofOfAddress"],
"Service.name": "Health Insurance Registration",
"Service.description": "A service for registering for health insurance.",
"Service.contactPoint": {
"@type": "ContactPoint",
"hasTelephone": "+420776723338"
},
"Service.providedBy": { "@id": "http://example.org/legalEntity/healthDepartment" }
} }
Final Review and Validation
Use an online tool like the JSON-LD Playground to validate JSON-LD context and make sure there are no errors.
