[SYNPY-1726] Add bind-jsonschema CLI command by aditigopalan · Pull Request #1317 · Sage-Bionetworks/synapsePythonClient

aditigopalan · 2026-02-09T20:54:00Z

Problem:

The CLI didn't have a workflow for registering and binding JSON Schemas.

Specifically:

There was no register-json-schema CLI command
There was no bind-json-schema CLI command

Highlighted in SYNPY-1762

Solution:

Introduced a new schema_management.py module that provides thin wrapper functions (register_jsonschema() and bind_jsonschema()), keeping CLI logic minimal and consistent with previous work
Added a new register-json-schema CLI command that registers schemas using JSONSchema.store().
Added a new bind-json-schema CLI command that binds schemas to entities via Entity.bind_schema().
Updated CLI and Python tutorial documentation to reflect the new commands and recommended usage.

Testing:

Added unit tests covering both register-json-schema and bind-json-schema CLI commands.
Verified that schema registration and binding routes through JSONSchema.store() and Entity.bind_schema() respectively.
Manually tested the CLI commands to confirm expected behavior and alignment with the updated docs.

- Create schema_management.py with register_jsonschema and bind_jsonschema - Export functions from curator extension __init__.py

- Update register_json_schema to use register_jsonschema wrapper - Update bind_json_schema to use bind_jsonschema wrapper - Add register-json-schema CLI command with argparse configuration

- Add register-json-schema to table of contents - Add complete command documentation with usage and parameters - Document schema registration workflow

- Update tutorial to cover complete JSON Schema workflow - Add section 9: Register JSON Schema to Synapse - Add section 10: Bind JSON Schema to entities - Update tutorial script with register_jsonschema and bind_jsonschema examples - Update imports and line references

- Add test for argument parsing - Add test for --enable-derived-annotations flag - Add test for API call invocation

Update test to mock bind_jsonschema wrapper instead of asyncio.run, and verify correct arguments are passed to the wrapper function.

andrewelamb · 2026-02-09T22:07:36Z

Thanks for doing this @aditigopalan ! Could you add an integration test as well as the unit testing you did?

synapseclient/extensions/curator/schema_management.py

- Update register_jsonschema to log message and return only schema_uri - Update CLI function to match new signature - Update docstring and examples

- Update return type from str to JSONSchema - Update docstring and examples to show accessing json_schema.uri - Update tutorial script accordingly

Add comprehensive integration tests for register_jsonschema and bind_jsonschema wrapper functions. Tests cover: - Registering schemas with and without version - Binding schemas to folders - Enabling derived annotations - Complete register + bind workflow

synapseclient/extensions/curator/schema_management.py

tests/integration/synapseclient/test_schema_management.py

Add integration tests for register-json-schema and bind-json-schema CLI commands in test_command_line_client.py. Tests cover: - Registering a schema via CLI - Binding a schema to an entity via CLI - Complete workflow of register and bind operations

linglp

Thanks for your hard work @aditigopalan ! I left some comments about documentation and code style changes.

synapseclient/extensions/curator/schema_management.py

linglp · 2026-02-10T22:00:17Z

synapseclient/extensions/curator/schema_management.py

+    Arguments:
+        schema_path: Path to the JSON schema file to register
+        organization_name: Name of the organization to register the schema under
+        schema_name: The name of the JSON schema


Nit: Name of the JSON Schema
This is to be consistent with organization_name

What do you mean by this?

I just meant that you have:
organization_name: Name of the organization to register the schema under
And similarly, we can do:
schema_name: Name of the JSON schema

synapseclient/__main__.py

docs/tutorials/python/schema_operations.md

thomasyu888

Thanks for your contribution @aditigopalan !

@andrewelamb or @linglp once all the changes are made, can one of you make sure the all the tests contributed here runs, since contributions via forks don't have CI tests.

Thanks all!

returning result

aditigopalan · 2026-02-12T18:55:27Z

@linglp @andrewelamb thank you both for reviewing! Please let me know if I understood the documentation changes correctly.

Regarding the organizations section, I’m not entirely sure what would make sense to include in the documentation. Since new organizations can be created, I’m not sure what it means for the JSON schemas to be “consistent with organization name.”

For example, for HTAN2Organization, we generate schemas like these:
https://github.com/ncihtan/htan2-data-model/tree/main/JSON_Schemas/v1.2.0

I’m also not sure what other DCCs are doing in this space, so I’ll defer to you both (and @thomasyu888) on what makes sense to describe in the documentation.

tests/integration/synapseclient/test_schema_management.py

synapseclient/extensions/curator/schema_management.py

tests/integration/synapseclient/test_schema_management.py

andrewelamb · 2026-02-12T20:37:02Z

@aditigopalan Thank you for adding the integration tests! However, they are not passing. These all need to be resolved:

ERROR tests/integration/synapseclient/test_command_line_client.py::TestSchemaManagementCommands::test_register_json_schema - ValueError: Name may be separated by periods, but each part must start with a letter and contain only letters and numbers: test.org.1e893b7b
ERROR tests/integration/synapseclient/test_command_line_client.py::TestSchemaManagementCommands::test_bind_json_schema - ValueError: Name may be separated by periods, but each part must start with a letter and contain only letters and numbers: test.org.3b8d5232
ERROR tests/integration/synapseclient/test_command_line_client.py::TestSchemaManagementCommands::test_register_and_bind_workflow - ValueError: Name may be separated by periods, but each part must start with a letter and contain only letters and numbers: test.org.193d052a

FAILED tests/integration/synapseclient/test_schema_management.py::TestRegisterJsonSchema::test_register_jsonschema_with_version - AttributeError: 'JSONSchema' object has no attribute 'version'
FAILED tests/integration/synapseclient/test_schema_management.py::TestRegisterJsonSchema::test_register_jsonschema_without_version - AttributeError: 'JSONSchema' object has no attribute 'version'
FAILED tests/integration/synapseclient/test_schema_management.py::TestBindJsonSchema::test_bind_jsonschema_to_folder - TypeError: argument of type 'JSONSchemaBinding' is not iterable
FAILED tests/integration/synapseclient/test_schema_management.py::TestBindJsonSchema::test_bind_jsonschema_with_derived_annotations - TypeError: argument of type 'JSONSchemaBinding' is not iterable
FAILED tests/integration/synapseclient/test_schema_management.py::TestRegisterAndBindWorkflow::test_complete_workflow - AttributeError: get_schema
ERROR tests/integration/synapseclient/test_schema_management.py::TestRegisterAndBindWorkflow::test_complete_workflow - synapseclient.core.exceptions.SynapseHTTPError: 400 Client Error: Cannot delete a schema that is bound to an object

- previously tried to test if that the binding result contains entity information (like entityId or entity_id) - result is a JSONSchemaBinding object (a Python class instance), not a dictionary - just checking that the result is not none should be sufficient

Resolved conflicts in schema_operations documentation: - Kept display_label example from upstream - Added register_jsonschema and bind_jsonschema documentation - Updated line number references in markdown

tests/integration/synapseclient/test_schema_management.py

andrewelamb · 2026-02-17T16:56:10Z

tests/integration/synapseclient/test_command_line_client.py

+        """Set up test state with organization and schema file"""
+        from synapseclient.models import SchemaOrganization
+
+        class SchemaState:


I'm confused by this class. Could you add documentation describing what it's for?

This was originally just meant to be a container class to bundle everything, but on second thought I just decided to reuse test_state + separate fixtures for organization and schema_file. Let me know if this makes sense!

Now if cleanup fails, the test will fail

Add explicit schema unbinding before folder deletion to ensure schemas can be deleted (schemas cannot be deleted while bound - errors out)

- Remove SchemaState container class in favor of separate fixtures for schema_organization and schema_file. - aligns with the existing test pattern where test_state provides the core Synapse client, project, and parser, while additional fixtures provide test-specific resources.

docs/tutorials/python/tutorial_scripts/schema_operations.py

synapseclient/extensions/curator/schema_management.py

tests/integration/synapseclient/test_schema_management.py

BryanFauble

There are some items to fix, but this is great progress!

use class-scoped fixture, fix UUID naming, use addfinalizer

…ions - Add register_jsonschema_async and bind_jsonschema_async functions - Refactor sync functions to use wrap_async_to_sync pattern - Export async functions from curator __init__.py

andrewelamb · 2026-02-18T16:44:25Z

Thanks for all the work @aditigopalan !

BryanFauble

Thanks for the updates!

synapseclient/extensions/curator/schema_management.py

docs/tutorials/python/tutorial_scripts/schema_operations.py

aditigopalan added 6 commits February 9, 2026 15:34

Add schema management wrapper functions using OOP models

e0fdb91

- Create schema_management.py with register_jsonschema and bind_jsonschema - Export functions from curator extension __init__.py

Update CLI commands to use OOP model wrapper functions

c8fb80f

- Update register_json_schema to use register_jsonschema wrapper - Update bind_json_schema to use bind_jsonschema wrapper - Add register-json-schema CLI command with argparse configuration

Add register-json-schema command to CLI documentation

0c5bbd2

- Add register-json-schema to table of contents - Add complete command documentation with usage and parameters - Document schema registration workflow

[test] Add unit tests for bind-json-schema CLI command

42d5b8f

- Add test for argument parsing - Add test for --enable-derived-annotations flag - Add test for API call invocation

[test] Fix bind-json-schema test to match new wrapper implementation

ae634da

Update test to mock bind_jsonschema wrapper instead of asyncio.run, and verify correct arguments are passed to the wrapper function.

aditigopalan requested a review from a team as a code owner February 9, 2026 20:54

andrewelamb requested changes Feb 9, 2026

View reviewed changes

aditigopalan added 5 commits February 10, 2026 09:20

Use JSONSchema.uri instead of manually building URI

a8245ef

Log success message in register_jsonschema instead of returning it

208eaa6

- Update register_jsonschema to log message and return only schema_uri - Update CLI function to match new signature - Update docstring and examples

Return JSONSchema object instead of just URI string

6cefe2e

- Update return type from str to JSONSchema - Update docstring and examples to show accessing json_schema.uri - Update tutorial script accordingly

Remove unnecessary fallback logic in bind_jsonschema

51814d6

aditigopalan requested a review from andrewelamb February 10, 2026 14:35

andrewelamb reviewed Feb 10, 2026

View reviewed changes

synapseclient/extensions/curator/schema_management.py Outdated Show resolved Hide resolved

andrewelamb reviewed Feb 10, 2026

View reviewed changes

synapseclient/extensions/curator/schema_management.py Outdated Show resolved Hide resolved

andrewelamb reviewed Feb 10, 2026

View reviewed changes

tests/integration/synapseclient/test_schema_management.py Show resolved Hide resolved

aditigopalan added 3 commits February 10, 2026 16:35

Use new operations API instead of deprecated syn.get()

23c8362

Simplify return statement in bind_jsonschema

9c4eac8

[test]

5f1f4ae

Add integration tests for register-json-schema and bind-json-schema CLI commands in test_command_line_client.py. Tests cover: - Registering a schema via CLI - Binding a schema to an entity via CLI - Complete workflow of register and bind operations

aditigopalan requested a review from andrewelamb February 10, 2026 21:41

linglp reviewed Feb 10, 2026

View reviewed changes

thomasyu888 reviewed Feb 11, 2026

View reviewed changes

aditigopalan added 5 commits February 12, 2026 13:04

Fix return type annotation for bind_jsonschema

6abca43

Remove comments from schema_manahement.py

dab5d9c

Remove verbose binding details from CLI output

47ef105

Simplify initial setup section in schema operations tutorial

babfe4c

Update main.py

64759e1

returning result

aditigopalan requested a review from linglp February 12, 2026 18:55

andrewelamb requested changes Feb 12, 2026

View reviewed changes

aditigopalan added 3 commits February 12, 2026 16:50

[test] fixing import

8a5b5de

[test] removing assert fix

7152d77

- previously tried to test if that the binding result contains entity information (like entityId or entity_id) - result is a JSONSchemaBinding object (a Python class instance), not a dictionary - just checking that the result is not none should be sufficient

Merge upstream/develop into develop

9ec6e39

Resolved conflicts in schema_operations documentation: - Kept display_label example from upstream - Added register_jsonschema and bind_jsonschema documentation - Updated line number references in markdown

aditigopalan requested a review from andrewelamb February 17, 2026 15:26

andrewelamb requested changes Feb 17, 2026

View reviewed changes

aditigopalan added 4 commits February 17, 2026 12:29

[test] changing clean up to finalizer

12542c5

[test] removing try/ except blocks

49bd3d2

Now if cleanup fails, the test will fail

[test] add schema unbinding before folder deletion

12a920e

Add explicit schema unbinding before folder deletion to ensure schemas can be deleted (schemas cannot be deleted while bound - errors out)

aditigopalan requested a review from andrewelamb February 17, 2026 18:26

BryanFauble reviewed Feb 17, 2026

View reviewed changes

docs/tutorials/python/tutorial_scripts/schema_operations.py Show resolved Hide resolved

BryanFauble reviewed Feb 17, 2026

View reviewed changes

synapseclient/extensions/curator/schema_management.py Show resolved Hide resolved

BryanFauble reviewed Feb 17, 2026

View reviewed changes

tests/integration/synapseclient/test_schema_management.py Outdated Show resolved Hide resolved

BryanFauble requested changes Feb 17, 2026

View reviewed changes

aditigopalan added 4 commits February 17, 2026 14:14

[test] refactor

9bf8e8b

use class-scoped fixture, fix UUID naming, use addfinalizer

[docs] moving hardcoded file paths to the top

94efc1d

[test] syn.delete > project.delete

101e60d

Add Python 3.14 compatible async versions for schema management funct…

a5bb249

…ions - Add register_jsonschema_async and bind_jsonschema_async functions - Refactor sync functions to use wrap_async_to_sync pattern - Export async functions from curator __init__.py

aditigopalan requested a review from BryanFauble February 17, 2026 20:25

andrewelamb approved these changes Feb 18, 2026

View reviewed changes

BryanFauble approved these changes Feb 18, 2026

View reviewed changes

thomasyu888 reviewed Feb 18, 2026

View reviewed changes

synapseclient/extensions/curator/schema_management.py Outdated Show resolved Hide resolved

Apply suggestion from @thomasyu888

c90a7cb

thomasyu888 reviewed Feb 18, 2026

View reviewed changes

docs/tutorials/python/tutorial_scripts/schema_operations.py Show resolved Hide resolved

Apply suggestions from code review

aa1ada4

thomasyu888 merged commit 184718b into Sage-Bionetworks:develop Feb 18, 2026
4 checks passed

Comments

Conversation

aditigopalan commented Feb 9, 2026 • edited by atlassian bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem:

Solution:

Testing:

Uh oh!

andrewelamb commented Feb 9, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

linglp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

linglp Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

aditigopalan Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

linglp Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thomasyu888 left a comment

Choose a reason for hiding this comment

Uh oh!

aditigopalan commented Feb 12, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

andrewelamb commented Feb 12, 2026

Uh oh!

Uh oh!

Uh oh!

andrewelamb Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

aditigopalan Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BryanFauble left a comment

Choose a reason for hiding this comment

Uh oh!

andrewelamb commented Feb 18, 2026

Uh oh!

BryanFauble left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

aditigopalan commented Feb 9, 2026 •

edited by atlassian bot

Loading