OOTS-CS-Query-Validator (0.2.6)
Installation
pip install --index-url About this package
A query validator for the Common Services of the Once-Only Technical System
OOTS Common Services Query Validator
Read about the launch of the OCQV in this article, published by the European Commission.
The OCQV is a simple WSGI-based HTTP server that allows queries, meant for the Once-Only Technical System (OOTS) Common Services, to be validated. More specifically, this concerns queries to the Evidence Broker (EB) and the Data Services Directory. In this case, validation means that we check whether the query specifies all necessary parameters with the correct values so that the Common Services are able to provide a valid response.
A detailed description of the development of this tool can be found here.
This software is published under the AGPLv3.0 license.
Features
- Validates OOTS Common Services queries with XML-based reporting.
- Ensures all required parameters are present and correctly formatted.
- Runs as a standalone HTTP server or within a WSGI/Docker environment.
- Includes a lightweight development server for quick testing.
Installation
Three methods of installation are available:
- PyPI
The validator is published on PyPI and can be installed with:pip install OOTS-CS-Query-Validator - Docker
A prebuilt Docker image is available: pcfal/ocqv
Example run:docker run -p 80:80 pcfal/ocqv:latest - From source
You can build the code yourself. Clone this repo, update the submodule, and install withpip:git clone git@forgejo.parcifal.dev:parcifal/ocqv.git cd ocqv git submodule update --init --recursive pip install .
Debugging
A very basic (and definitely not production-ready) web server is included
using werkzeug. This is ideal for development purposes. With OCQV
installed from PyPI or directly from source (as described above), the server
can be started using the ocqv command. Advanced users can also achieve
this by running the ocqv/app.py-script directly. ocqv allows for some
configuration through its arguments, all of which are shown with ocqv --help.
Example output:
usage: ocqv [-h] [-H HOST] [-p PORT] [-r] [-d] [-t]
Run the OOTS Common Services Query Validator development server.
optional arguments:
-h, --help show this help message and exit
-H HOST, --host HOST hostname or IP address to bind to (default: localhost)
-p PORT, --port PORT port to listen on (default: 5000)
-r, --no-reload disable auto-reloader
-d, --no-debug disable interactive debugger
-t, --threaded enable multithreading
Usage
For a more permanent setup, Docker is recommended. Internally, the validator exposes:
- HTTP socket at port 80
- WSGI socket at port 5000
Example production-like run:
docker run -d --name ocqv -p localhost:80:80 pcfal/ocqv:latest
API
The validator exposes an HTTP endpoint for validating queries. In debug-mode,
this defaults to http://localhost:5000/1.2.0/rest/search. Using curl or a
web browser, reports can be generated for queries. For example, consider the
following (rather lengthy) URL.
http://localhost:5000/1.2.0/rest/search?queryId=urn:fdc:oots:dsd:ebxml-regrep:queries:dataservices-by-evidencetype-and-jurisdiction&evidence-type-classification=http://example.com&jurisdiction-admin-l2=spam&spam=bacon
The resulting report is as follows (notice that all possible variations of verdicts appear in the evaluation of the parameters):
<?xml version="1.0" encoding="UTF-8"?>
<ocqv:QueryReport xmlns:ocqv="https://www.parcifal.dev/ns/oots-cs-query-validator/2025-08"
version="0.1.0"
apiVersion="1.2.0"
createdAt="2025-08-12T20:47:00.581476+00:00">
<ocqv:ParameterEvaluation name="queryId"
value="urn:fdc:oots:dsd:ebxml-regrep:queries:dataservices-by-evidencetype-and-jurisdiction"
verdict="valid"/>
<ocqv:ParameterEvaluation name="evidence-type-classification"
value="http://example.com"
verdict="valid"/>
<ocqv:ParameterEvaluation name="jurisdiction-admin-l2"
value="spam"
verdict="invalid"/>
<ocqv:ParameterEvaluation name="spam"
value="bacon"
verdict="unknown"/>
<ocqv:ParameterEvaluation name="country-code"
verdict="missing"/>
</ocqv:QueryReport>
Queries for both the EB and the DSD are to be submitted to the same endpoint. At this moment, only the 1.2.0-version of the query specification is available. A full overview of the available queries and parameters for both the EB and the DSD are available on the OOTS HUB.
Development
To work on the codebase locally, clone the repository and install the dependencies, including those needed for running the unit tests and the linter.
git clone git@forgejo.parcifal.dev:parcifal/ocqv.git
cd ocqv
git submodule --init --recursive
pip install .[dev]
To run the development server, run python -m ocqv.app.
Use the following command to run the unit tests.
python -m unittest discover -s test
Configuration for pylint is also supported, run it as follows.
pylint ocqv test