Metadata-Version: 2.4
Name: OOTS-CS-Query-Validator
Version: 0.2.6
Summary: A query validator for the Common Services of the Once-Only Technical System
Author-email: "M.P. van de Weerd" <michael@parcifal.dev>
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://forgejo.parcifal.dev/parcifal/ocqv
Project-URL: Bug Tracker, https://forgejo.parcifal.dev/parcifal/ocqv/issues
Keywords: Single Digital Gateway,SDG,Once-Only Technical System,OOTS,Common Services,Evidence Broker,Data Services Directory,Semantic Repository
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Other Environment
Classifier: Intended Audience :: Developers
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: werkzeug
Requires-Dist: tomli
Provides-Extra: dev
Requires-Dist: lxml; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Provides-Extra: prod
Requires-Dist: uwsgi; extra == "prod"
Dynamic: license-file

# OOTS Common Services Query Validator

[![release](https://img.shields.io/gitea/v/release/parcifal/ocqv?gitea_url=https%3A%2F%2Fforgejo.parcifal.dev&label=latest+release)][release]
[![pypi](https://img.shields.io/pypi/v/OOTS-CS-Query-Validator?label=pypi+release)][pypi]
[![develop](https://forgejo.parcifal.dev/parcifal/ocqv/badges/workflows/push.yml/badge.svg?label=develop&branch=develop)][develop]
[![master](https://forgejo.parcifal.dev/parcifal/ocqv/badges/workflows/push.yml/badge.svg?label=master&branch=master)][master]
[![gitlab](https://img.shields.io/gitlab/last-commit/parcifal%2Focqv?label=gitlab+mirror)][gitlab]
[![github](https://img.shields.io/github/last-commit/parcifal%2Focqv?label=github+mirror)][github]

![OCQV Logo][logo]

 > **Read about the launch of the OCQV in [this article][ec], 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][memo].

 > This software is published under the [AGPLv3.0 license][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:

 1. **PyPI**<br>
    The validator is published on [PyPI][pypi] and can be installed with:
    ```bash
    pip install OOTS-CS-Query-Validator
    ```
 2. **Docker**<br>
    A prebuilt Docker image is available:
    [pcfal/ocqv][docker]<br>
    Example run:
    ```bash
    docker run -p 80:80 pcfal/ocqv:latest
    ```
 3. **From source**<br> 
    You can build the code yourself. Clone this repo, update the submodule, 
    and install with `pip`:
    ```bash
    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:

```bash
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:

```bash
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.

```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
<?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][eb] and the [DSD][dsd] are available on the [OOTS HUB][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.

```bash
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.

```bash
python -m unittest discover -s test
```

Configuration for `pylint` is also supported, run it as follows.

```bash
pylint ocqv test
```

[ec]: https://ec.europa.eu/digital-building-blocks/sites/spaces/OOTS/pages/920063579/Dutch+national+coordinator+publishes+OOTS+Common+Services+Query+Validator

[logo]: https://forgejo.parcifal.dev/parcifal/ocqv/raw/branch/master/assets/logo.png

[license]: https://forgejo.parcifal.dev/parcifal/ocqv/src/branch/master/LICENSE

[release]: https://forgejo.parcifal.dev/parcifal/ocqv/releases/latest
[gitlab]: https://gitlab.com/parcifal/ocqv
[github]: https://github.com/parcifal/ocqv
[develop]: https://forgejo.parcifal.dev/parcifal/ocqv/src/branch/develop
[master]: https://forgejo.parcifal.dev/parcifal/ocqv/src/branch/master

[memo]:   https://www.van-de-weerd.net/~michael/memo/ocqv.html
[pypi]:   https://pypi.org/project/OOTS-CS-Query-Validator/
[docker]: https://hub.docker.com/r/pcfal/ocqv

[eb]:  https://oots.pages.code.europa.eu/tdd/apidoc/evidence-broker
[dsd]: https://oots.pages.code.europa.eu/tdd/apidoc/data-services-directory
[hub]: https://ec.europa.eu/digital-building-blocks/sites/display/OOTS/OOTSHUB+Home
