Fixing Pygeoapi Config Schema: Process Manager Connection Error

Nov 12, 2025 by Alex Johnson 64 views

Introduction

In the world of geospatial data and APIs, pygeoapi stands out as a powerful and flexible framework. However, like any software, it can have its quirks and challenges. One common issue users encounter is a configuration schema error related to the process manager connection. This article dives deep into this issue, explaining the root cause, how to identify it, and, most importantly, how to fix it. If you're struggling with the pygeoapi config validate command throwing errors about the process manager connection needing to be a string when it should be an object, you're in the right place.

Understanding the Problem

The core of the issue lies in a discrepancy between the documentation and the JSON schema definition within pygeoapi. The documentation for the PostgreSQL process manager correctly states that the connection requires multiple properties, such as the host, port, database name, username, and password. This makes perfect sense because connecting to a database typically involves more than just a single string. You need specific details to establish a secure and functional connection.

However, the JSON schema, which is used to validate the pygeoapi.config.yml file, incorrectly specifies that the process manager connection should be a string. This mismatch causes the pygeoapi config validate command to fail with a jsonschema.exceptions.ValidationError. The error message clearly indicates that an object (like a dictionary containing connection properties) is not of the expected type, which is a string. This error can be frustrating because it prevents the configuration from being validated, even if all the necessary information is provided in the configuration file.

To put it simply, the config schema incorrectly states that the process manager connection must be a string, while in reality, it requires an object containing several connection details. This mix-up leads to validation errors and can hinder the proper setup and functioning of pygeoapi.

Decoding the Error Message

When you run pygeoapi config validate --config pygeoapi.config.yml and encounter this issue, you'll likely see an error message similar to this:

jsonschema.exceptions.ValidationError: {'host': '127.0.0.1', 'port': 5432, 'database': 'db', 'user': 'postgres', 'password': 'password'} is not of type 'string'

Failed validating 'type' in schema['properties']['server']['properties']['manager']['properties']['connection']:
    {'type': 'string',
     'description': 'connection info to store jobs (e.g. filepath)'}

On instance['server']['manager']['connection']:
    {'host': '127.0.0.1',
     'port': 5432,
     'database': 'db',
     'user': 'postgres',
     'password': 'password'}

Let's break down this error message to understand what it's telling us:

jsonschema.exceptions.ValidationError: This indicates that the JSON schema validation has failed.
{'host': '127.0.0.1', ...} is not of type 'string': This is the core of the problem. It states that the value provided for the connection (which is an object containing connection details) does not match the expected type, which is a string.
Failed validating 'type' in schema['properties']['server']['properties']['manager']['properties']['connection']: This pinpoints the exact location in the schema where the validation failed. It's telling us that the connection property within the server.manager section of the configuration is causing the issue.
{'type': 'string', ...}: This shows the schema definition that's causing the error. It confirms that the schema expects the connection to be a string.
On instance['server']['manager']['connection']: This indicates the specific part of your configuration file that's being validated.

By understanding this error message, you can quickly identify the problem and focus on the relevant part of your pygeoapi.config.yml file.

Identifying the Root Cause

The root cause of this issue lies in the JSON schema definition for pygeoapi. Specifically, the schema located at pygeoapi/resources/schemas/config/pygeoapi-config-0.x.yml (where 0.x represents the pygeoapi version) incorrectly defines the connection property for the process manager as a string.

If you examine this file, you'll find the following snippet:

properties:
  server:
    properties:
      manager:
        properties:
          connection:
            type: string
            description: connection info to store jobs (e.g. filepath)

This snippet clearly shows that the type for the connection property is set to string. This is the reason why the validation fails when you provide an object containing connection details like host, port, username, and password.

The key takeaway here is that the schema needs to be updated to correctly reflect the expected format for the process manager connection, which is an object with multiple properties, not just a single string.

How to Fix the pygeoapi Config Schema Error

Now that we understand the problem and its root cause, let's dive into the solution. There are a couple of ways to address this issue, depending on your comfort level and the specific pygeoapi setup you're using.

1. Modifying the JSON Schema (Advanced)

This approach involves directly modifying the JSON schema file (pygeoapi/resources/schemas/config/pygeoapi-config-0.x.yml) to correctly define the connection property. This is a more permanent solution but requires caution as it involves directly editing pygeoapi's internal files.

Here's how you can do it:

Locate the schema file: Find the pygeoapi-config-0.x.yml file in your pygeoapi installation. The exact path may vary depending on how you installed pygeoapi (e.g., using pip, conda, or from source).
Edit the file: Open the file in a text editor and navigate to the connection property definition within the server.manager section.

Update the schema: Replace the existing connection definition with the following:

connection:
  type: object
  description: Connection info for the process manager (e.g., database connection details).
  properties:
    host:
      type: string
      description: Hostname or IP address of the database server.
    port:
      type: integer
      description: Port number of the database server.
    database:
      type: string
      description: Name of the database.
    user:
      type: string
      description: Username for database authentication.
    password:
      type: string
      description: Password for database authentication.
required:
  - host
  - port
  - database
  - user
  - password

This updated schema defines connection as an object with the required properties for a database connection: host, port, database, user, and password.

Save the file: Save the changes to the pygeoapi-config-0.x.yml file.
Validate your configuration: Run pygeoapi config validate --config pygeoapi.config.yml to confirm that the error is resolved.

Important Note: Modifying pygeoapi's internal files directly can have implications for future updates. When you upgrade pygeoapi, your changes might be overwritten. Therefore, it's recommended to keep track of your modifications and reapply them after each update.

2. Using Environment Variables (Recommended)

A more flexible and recommended approach is to use environment variables to define the process manager connection details. This method avoids directly modifying the schema and allows you to easily configure your pygeoapi instance in different environments without changing the configuration file.

Here's how it works:

Modify your pygeoapi.config.yml: In your pygeoapi.config.yml file, replace the connection property under server.manager with the following:
```
server:
  manager:
    name: postgresql
    connection: |
      PGHOST: ${PGHOST}
      PGPORT: ${PGPORT}
      PGDATABASE: ${PGDATABASE}
      PGUSER: ${PGUSER}
      PGPASSWORD: ${PGPASSWORD}
```
This configuration uses the | (literal block scalar) to define a multi-line string for the connection. The ${...} syntax indicates environment variables that will be substituted at runtime.
Set environment variables: Set the necessary environment variables in your system or shell. For example:
```
export PGHOST=127.0.0.1
export PGPORT=5432
export PGDATABASE=your_database_name
export PGUSER=your_username
export PGPASSWORD=your_password
```
Replace the placeholder values with your actual database connection details.
Validate your configuration: Run pygeoapi config validate --config pygeoapi.config.yml to confirm that the error is resolved.

Benefits of using environment variables:

Flexibility: Easily switch between different database configurations without modifying the configuration file.
Security: Keep sensitive information like passwords out of your configuration file.
Portability: Deploy pygeoapi in different environments (e.g., development, staging, production) with different configurations.

3. Addressing the Issue in pygeoapi Itself (Contributing)

If you're feeling adventurous and want to contribute to the pygeoapi project, you can submit a pull request to fix the schema directly. This will benefit all pygeoapi users and ensure that the issue is resolved in future releases.

Here's the general process:

Fork the pygeoapi repository: Go to the pygeoapi GitHub repository and click the