📖 Overview

While working on Pyxel’s JSON Schema auto-generation, an issue was identified where schema generation could fail or produce inconsistent results if the order of parameters in a function’s docstring differed from the order in the function signature.

This situation can occur naturally over time as functions evolve and documentation is updated independently. The goal of this change was to make schema generation resilient to such differences, without requiring perfectly synchronized ordering.

Project Details

• Project: Pyxel – ESA GitLab
• Branch: fix-json-schema-param-order
• Area: continuous_integration/scripts/create_json_schema.py
• Type: Tooling / Schema Generation / Robustness

🧠 Problem Description

The JSON Schema generator relied on information extracted from both the function signature and the NumPy-style docstring. When parameter ordering differed between the two, schema generation logic could behave incorrectly or raise errors during processing.

This made the schema generation process fragile and unnecessarily strict, especially for a large and evolving codebase.

🛠️ Solution

The schema generation logic was updated to:

1. Use the function signature as the authoritative source for parameter order.
2. Match docstring parameters by name instead of position.
3. Preserve accurate descriptions while ensuring consistent ordering.

This change makes the generator more robust and tolerant of documentation differences, while still enforcing correctness.

🧪 Testing Notes

Due to the size of Pyxel’s dependency tree, full execution of the JSON Schema generation pipeline was not possible locally without installing a large number of optional scientific dependencies.

However, the changes were:

• Validated through direct code inspection.
• Checked for syntax and logical correctness.
• Scoped narrowly to avoid impacting unrelated functionality.

📌 Outcome

With this change, JSON Schema generation is no longer sensitive to mismatched parameter ordering between docstrings and function signatures, improving reliability and maintainability for both developers and users.

🦕 Authored by: Doby Baxter
🌌 Contribution to: ESA Pyxel Project