Enhancement/model sync by iimpulse · Pull Request #4 · P2GX/beacon-api

iimpulse · 2026-02-11T17:07:28Z

No description provided.

Copilot

Pull request overview

Syncs the API models and responses closer to Beacon v2 schemas, adds catalog-driven configuration endpoints, and introduces tooling to detect schema/model drift.

Changes:

Updated Pydantic models (responses + entities) with aliases/typed nested structures and added common Beacon types.
Standardized response building via new response_utils helpers and added /configuration, /entry_types, /map endpoints.
Added schema sync/bundling and drift comparison scripts, plus documentation.

Reviewed changes

Copilot reviewed 24 out of 26 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/beacon_api/models/response.py	Aligns response models with Beacon v2 (aliases, handovers, collections result shape).
src/beacon_api/models/entities.py	Replaces many `dict` fields with structured types and adds JSON aliases.
src/beacon_api/models/common_types.py	Introduces shared nested types (OntologyTerm, Disease, Procedure, etc.).
src/beacon_api/models/common.py	Updates `SchemaReference` shape to match new catalog/schema usage.
src/beacon_api/main.py	Registers new routers for configuration/map/entry types.
src/beacon_api/core/beacon_catalog.py	Defines entry-type catalog and builds configuration/map payloads.
src/beacon_api/api/response_utils.py	Centralizes meta/summary/resultset/collections response construction.
src/beacon_api/api/*.py	Refactors endpoints to use `response_utils` and updated response shapes.
scripts/sync_beacon_schemas.sh	Downloads/bundles upstream schemas and runs drift comparison.
scripts/bundle_schemas.js	Bundles/dereferences Beacon schemas into `tmp/bundled_schemas`.
scripts/compare_models.py	Compares bundled schemas vs Pydantic model fields for drift reporting.
pyproject.toml	Adds a dev dependency related to model generation tooling.
README.md	Documents schema synchronization workflow and scripts.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-11T17:09:56Z

src/beacon_api/core/beacon_catalog.py

+from beacon_api.core.config import Settings
+from beacon_api.models.common import SchemaReference
+
+ENTRY_TYPES: dict[str, dict[str, str]] = {


ENTRY_TYPES is annotated as dict[str, dict[str, str]], but single_path is set to None for multiple entries. This will fail static type checking (and can cause downstream assumptions about string operations). Update the annotation to allow None (e.g., str | None) or use a TypedDict/dataclass that correctly models optional keys.

Suggested change

ENTRY_TYPES: dict[str, dict[str, str]] = {

ENTRY_TYPES: dict[str, dict[str, str | None]] = {

Copilot · 2026-02-11T17:09:56Z

src/beacon_api/core/beacon_catalog.py

+    "analysis": {
+        "name": "Analysis",
+        "schema": "tmp/bundled_schemas/analysis.json",
+        "root_path": "/api/analyses",
+        "single_path": None,
+    },


ENTRY_TYPES is annotated as dict[str, dict[str, str]], but single_path is set to None for multiple entries. This will fail static type checking (and can cause downstream assumptions about string operations). Update the annotation to allow None (e.g., str | None) or use a TypedDict/dataclass that correctly models optional keys.

Copilot · 2026-02-11T17:09:57Z

src/beacon_api/models/response.py

    info: dict[str, Any] | None = Field(
-        default=None,
+        default_factory=dict,
        description="Additional information",
    )
+    beacon_handovers: list[BeaconHandover] | None = Field(
+        default_factory=list,
+        alias="beaconHandovers",
+        description="Handovers for accessing data externally",
+    )


info and beacon_handovers are annotated as optional (| None) but use default_factory, which means they will never be None in practice. This makes the generated OpenAPI/schema misleading and creates ambiguity for consumers. Either (a) make them non-optional (dict[str, Any] / list[BeaconHandover]) with default_factory, or (b) keep them optional and use default=None (and optionally exclude empties at serialization time).

@copilot open a new pull request to apply changes based on this feedback can you implement a

Copilot · 2026-02-11T17:09:57Z

src/beacon_api/models/response.py

+        default_factory=list,
+        alias="beaconHandovers",
+        description="Handovers for accessing data externally",
+    )


BeaconCollectionsResponse includes meta, responseSummary, response, info, and beaconHandovers, but appears to omit beaconError (present in the other response models in this file). If this model is used for FastAPI response validation, errors won’t be representable/serializable in a schema-consistent way. Consider adding beacon_error: BeaconError | None = Field(default=None, alias=\"beaconError\", ...) for consistency with BeaconResultsetsResponse / BeaconCountResponse / BeaconBooleanResponse.

Suggested change

)

)

beacon_error: BeaconError | None = Field(

default=None,

alias="beaconError",

description="Error information if query failed",

)

scripts/sync_beacon_schemas.sh

Copilot · 2026-02-11T17:09:57Z

scripts/compare_models.py

+def normalize_field_name(name: str) -> str:
+    """Normalize field name for comparison (camelCase to snake_case)."""
+    # Simple camelCase to snake_case conversion
+    result = []
+    for i, char in enumerate(name):
+        if char.isupper() and i > 0:
+            result.append("_")
+        result.append(char.lower())
+    return "".join(result)


The camelCase→snake_case conversion is very naive and will produce odd results for acronyms (e.g., APIResponse → a_p_i_response) and some mixed cases, which can lead to false-positive drift results. Consider switching to a more robust regex-based conversion (handling consecutive capitals) to reduce noisy reports.

@copilot open a new pull request to apply changes based on this feedback

Copilot · 2026-02-11T19:26:40Z

@iimpulse I've opened a new pull request, #5, to work on those changes. Once the pull request is ready, I'll request review from you.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot · 2026-02-11T19:27:23Z

@iimpulse I've opened a new pull request, #6, to work on those changes. Once the pull request is ready, I'll request review from you.

Co-authored-by: iimpulse <7397665+iimpulse@users.noreply.github.com>

Fix acronym handling in camelCase→snake_case conversion

Remove misleading optional annotations from BeaconBooleanResponse fields

iimpulse added 3 commits February 10, 2026 14:48

sync beacon models, and compare schema to simplified schema

6c5ecd7

using a model sync strategy and implementing

2b64934

abstract response builder methods

4c846d6

iimpulse requested a review from Copilot February 11, 2026 17:07

Copilot AI reviewed Feb 11, 2026

View reviewed changes

Initial plan

58188a2

Copilot AI mentioned this pull request Feb 11, 2026

Remove misleading optional annotations from BeaconBooleanResponse fields #5

Merged

iimpulse and others added 2 commits February 11, 2026 12:27

Update scripts/sync_beacon_schemas.sh

9ed9c56

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Initial plan

3dcebc6

Copilot AI mentioned this pull request Feb 11, 2026

Fix acronym handling in camelCase→snake_case conversion #6

Merged

Copilot AI and others added 6 commits February 11, 2026 19:29

Improve camelCase to snake_case conversion to handle acronyms correctly

d768a33

Co-authored-by: iimpulse <7397665+iimpulse@users.noreply.github.com>

Fix misleading optional annotations on BeaconBooleanResponse fields

c91db36

Co-authored-by: iimpulse <7397665+iimpulse@users.noreply.github.com>

Improve inline comments for clarity based on code review feedback

5cb9ab5

Co-authored-by: iimpulse <7397665+iimpulse@users.noreply.github.com>

Fix regex comments to accurately reflect transformation steps

f77b9d0

Co-authored-by: iimpulse <7397665+iimpulse@users.noreply.github.com>

Merge pull request #6 from P2GX/copilot/sub-pr-4-again

b1f2dc9

Fix acronym handling in camelCase→snake_case conversion

Merge pull request #5 from P2GX/copilot/sub-pr-4

6b5897f

Remove misleading optional annotations from BeaconBooleanResponse fields

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enhancement/model sync#4

Enhancement/model sync#4
iimpulse wants to merge 12 commits intomainfrom
enhancement/model-sync

iimpulse commented Feb 11, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 11, 2026

Uh oh!

Copilot AI Feb 11, 2026

Uh oh!

Copilot AI Feb 11, 2026

Uh oh!

iimpulse Feb 11, 2026

Uh oh!

Copilot AI Feb 11, 2026

Uh oh!

Uh oh!

Copilot AI Feb 11, 2026

Uh oh!

iimpulse Feb 11, 2026

Uh oh!

Copilot AI commented Feb 11, 2026

Uh oh!

Copilot AI commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	ENTRY_TYPES: dict[str, dict[str, str]] = {
	ENTRY_TYPES: dict[str, dict[str, str \| None]] = {

-    )
+    )
+    beacon_error: BeaconError | None = Field(
+        default=None,
+        alias="beaconError",
+        description="Error information if query failed",
+    )

Conversation

iimpulse commented Feb 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

iimpulse Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

iimpulse Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Feb 11, 2026

Uh oh!

Copilot AI commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants