GUIDES FOR PRACTICAL IMPLEMENTATIONS

The Core Public Service Vocabulary Application Profile (CPSV-AP) is a reusable and extensible data specification used for harmonising the way public services are described in a machine-readable format. CPSV-AP captures fundamental characteristics of a public service, such as the name, description, competent public organisation, output, etc. Public administrations and service providers can therefore use this approach to describe their services and guarantee a level of cross-domain and cross-border interoperability at European, national and local level.

The CPSV-AP includes the cardinality and data type of the properties, while specifying mandatory and optional elements to be used. According to the latest version, only 2 classes are mandatory: public service and public organisation, the rest being optional classes. Mandatory classes and properties indicate the minimum requirements to comply with CPSV-AP, while other elements are optional. A minimal implementation of the CPSV-AP at least provides information on the mandatory properties of the mandatory classes. Optional classes can still have mandatory properties for which information should be provided when the particular class is used in the description of public services and business events. 

Below you will find various guides and practical examples. 

  1. From tabular data to linked data
  2. From technical interoperability to semantic interoperability (JSON to JSON-LD) 
  3. Being compliant with CPSV-AP with manual and automatic validation
  4. Reusing CPSV-AP - the Flemish Government example

7

1. From tabular data to linked data

Public Administrations might have descriptions of public services in the form of tabular data such as a spreadsheet.

In the Catalogue of Service Action, a CPSV-AP Harvester was built to convert different formats, including a spreadsheet, to linked data, in line with the CPSV-AP data model.

The CSPV-AP harvester has a REST API component that is responsible for converting a spreadsheet template, containing the classes and properties of CPSV-AP, into RDF, in accordance with the CPSV-AP data model. 

In the example below, it is demonstrated how the spreadsheet could be filled:

CPSV-AP Spreadsheet, example of public service

Each single concept, like Public Service or Public Organisation, has its own URI, indicated in the first column. This URI is used to link concepts between each other, for example, the 'has Competent Authority' column contains the URI of the Public Organization, PO_DPDSA, indicated in the Public Organisation sheet (see below):

CPSV-AP spreadsheet, Public Organization description

Once the spreadsheet has been completed, it should be made publicly available as URL where it can be downloaded, for example:

http://adms-ap.semic.eu/cpsv-ap_harvester/Finnish_data/MarriageFinland.xlsx

Now, it can be used by the CPSV-AP Harvester API as shown below.

https://adms-ap.semic.eu/intapi/v1/importSpreadsheetFromURL?spreadsheetURL=http://adms-ap.semic.eu/cpsv-ap_harvester/Finnish_data/MarriageFinland.xlsx

This will return the result in a JSON-LD format. An extract of the JSON-LD can be found below:

CPSV-AP as JSON-LD result of CSPV-AP Harvester

 

 

2. From technical interoperability to semantic interoperability (JSON to JSON-LD)

Public Administrations that have already reached technical interoperability provide REST API to describe or interact with Public Services.

If these API return a JSON response, semantic interoperability could be reached by enriching these API with a JSON-LD context, provided by CPSV-AP. An example of an output of a REST API reusing the CPSV-AP JSON-LD context can be found below:

{
    "@context": "https://raw.githubusercontent.com/catalogue-of-services-isa/CPSV-AP/master/releases/2.2.1/CPSV-AP_v2.2.1.jsonld",
    "id": "http://data.europa.eu/FI/Fireinspections",
    "isTypeOf": "PublicService",
    "identifier": "Building stability inspections",
    "title": "Building stability inspections",
    "description": "Bulding stability inspections are the responsibility of the joint municipal rescue authority.",
    "spatial": {
        "isTypeOf": "Location",
        "id": "http://data.europa.eu/Finland/Location/Mikkeli",
        "title": "Mikkeli"
    },
    "sector": {
        "isTypeOf": "Concept",
        "id": "http://data.europa.eu/Finland/Sector/PublicAdministrationDefenceCompulsorySocialSecurity",
        "prefLabel": "PublicAdministration Defence Compulsory SocialSecurity"
    },
    "isGroupedBy": {
        "isTypeOf": ["BusinessEvent","Event"],
        "id": "http://data.europa.eu/BE/DoingBusiness",
        "title": "Periodic Inspections",
        "identifier": "PI"
    },
    "hasCost": {
        "isTypeOf": "Cost",
        "id": "http://data.europa.eu/FI/subjectToCharge",
        "identifier": "subjectToCharge",
        "description": "Subject to charge"
    },
    "hasCompetentAuthority": {
        "isTypeOf": "PublicOrganisation",
        "id": "http://127.0.0.1:3362/0165116-3",
        "title": "City of Mikkeli",
        "identifier": "0165116-3",
        "prefLabel": "City of Mikkeli",
        "spatial": {
            "isTypeOf": "Location",
            "id": "http://data.europa.eu/Finland/Location/Mikkeli",
            "title": "Mikkeli"
        }
    }
}

On the top of the JSON structure, you will find an URL which is the value of the @context property, this URL corresponds with the CSPV-AP JSON-LD context.

After assuring that all the properties in the JSON are described with an URI inside the JSON-LD context, it is possible to turn the JSON in JSON-LD, and by copying the example below in the JSON-LD playground, we can see the RDF generated:

JSON-LD playground, CPSV-AP example

3. Being compliant with CPSV-AP with manual validation

Validator

The Interoperability Test Bed provides a validation service allowing public administrations to validate their data against the CPSV-AP data model by integrating the SHACL shapes provided by CPSV-AP.

You can access the CPSV-AP validator via this link.

Steps:

  1. Select the file type (File, URI or direct input) and your file.
  2. Choose the content syntax (Optional for content provided as a file or a URI if a known file extension is detected)
  3. Validate

If your file is validated against the CPSV-AP data model, you will see the below validation message:

(You can test the example below with the document)

Example of error message 

validator

Corrected -  As the Competent Authority relation is mandatory in CPSV-AP, the following line is added in order to fix the issue:

cv:hasCompetentAuthority <http://127.0.0.1:3362/0165116-3&gt; .

CORRECTED version 2

3. Being compliant with CPSV-AP with automatic validation

 

Via the SHACL Validator REST API, you are able to validate a single or multiple RDF instances against SHACL shapes. 

Validate a single RDF instance

Validate a single RDF instance. The content can be provided either within the request as a BASE64 encoded string or remotely as a URL. The RDF syntax for the input can be determined in the request as well as the syntax to produce the resulting SHACL validation report.

You can access the CPSV-AP validator via this link. 

Steps:

  1. Under the domain you have to include: CPSV-AP
  2. In the Request body, the example from the document attached here is included.

Automatic validation with CSPV-AP Validator

The example created a RDF file, serialised as Turtle, via its URL, requesting results in JSON-LD.

3. Press the "Execute" button, you should see the response below:

Response from the cpsv-ap validator

The response indicates, like in the previous example, that the file does not pass the validation (see the line: "sh:conforms": false), because the property cv:hasCompetentAuthority is not present.

 

4. Reusing CPSV-AP - the Flemish Government example

Concepts in CPSV-AP, like Public Service, can be reused by pointing at the same URI (http://purl.org/vocab/cpsv#PublicService in the case) when having the same meaning. The example below shows how OSLO (Open Standard for Linking Organisations), an initiative by the Flemish government, reuses the concept Public Service together with its properties (OSLO Dienstencataloog).

 Public Services

The reuse of the same URI is reflected in the JSON LD context:
 

JSON-LD Public Service