Skip to content

[SYNPY-1673] Update jsonschema tutorial #1260

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Parent: [SYNPY-1673] Add JSONSchema documentation, deprecate old classes
merged 4 commits into from
Oct 23, 2025
Merged

[SYNPY-1673] Update jsonschema tutorial #1260

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6240444
Update jsonschema tutorial
thomasyu888 Oct 22, 2025
dc40bd5
Update script
thomasyu888 Oct 22, 2025
91ce7ed
update script locations
thomasyu888 Oct 22, 2025
991b17a
Add a line
thomasyu888 Oct 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions docs/tutorials/python/json_schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,16 @@ By the end of this tutorial, you will:
* You are familiar with [adding annotations](./annotation.md) to synapse entity.


## 1. Set Up Synapse Python Client and Retrieve Project
## 1. Set Up Synapse Python Client

```python
{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=1-19}
{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=1-10}
```

## 2. Take a Look at the Constants and Structure of the JSON Schema

```python
{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=21-49}
{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=13-40}
```

Derived annotations allow you to define default values for annotations based on schema rules, ensuring consistency and reducing manual input errors. As you can see here, you could use derived annotations to prescribe default annotation values. Please read more about derived annotations [here](https://help.synapse.org/docs/JSON-Schemas.3107291536.html#JSONSchemas-DerivedAnnotations).
Expand All @@ -39,12 +39,12 @@ Derived annotations allow you to define default values for annotations based on
## 3. Try Create Test Organization and JSON Schema if They Do Not Exist
Next, try creating a test organization and register a schema if they do not already exist:
```python
{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=51-65}
{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=43-59}
```

Note: If you update your schema, you can re-register it with the organization by assigning a new version number to reflect the changes. Synapse does not allow re-creating a schema with the same version number, so please ensure that each schema version within an organization is unique:
```python
{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=67-99}
{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=61-94}
```

## 4. Bind the JSON Schema to the Folder
Expand All @@ -53,7 +53,7 @@ After creating the organization, you can now bind your json schema to a test fol
When you bind the schema, you may also include the boolean property `enable_derived_annotations` to have Synapse automatically calculate derived annotations based on the schema:

```python
{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=101-108}
{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=96-108}
```

<details class="example">
Expand Down
62 changes: 31 additions & 31 deletions docs/tutorials/python/tutorial_scripts/json_schema.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,29 +3,21 @@

import synapseclient
from synapseclient.core.utils import make_bogus_data_file
from synapseclient.models import File, Folder
from synapseclient.models import File, Folder, JSONSchema, Project, SchemaOrganization

# 1. Set up Synapse Python client and retrieve project
# 1. Set up Synapse Python client
syn = synapseclient.Synapse()
syn.login()

# Retrieve test project
PROJECT_ID = syn.findEntityId(
name="My uniquely named project about Alzheimer's Disease"
)

# Create a test folder for JSON schema experiments
test_folder = Folder(name="clinical_data_folder", parent_id=PROJECT_ID).store()

# 2. Take a look at the constants and structure of the JSON schema
ORG_NAME = "myUniqueAlzheimersResearchOrgTutorial"
ORG_NAME = "myUniqueAlzheimersResearchOrgTutorialTest"
VERSION = "0.0.1"
NEW_VERSION = "0.0.2"

SCHEMA_NAME = "clinicalObservations"

title = "Alzheimer's Clinical Observation Schema"
schema = {
schema_body = {
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://example.com/schema/alzheimers_observation.json",
"title": title,
Expand All @@ -48,20 +40,23 @@
}

# 3. Try create test organization and json schema if they do not exist
js = syn.service("json_schema")
all_orgs = js.list_organizations()
for org in all_orgs:
if org["name"] == ORG_NAME:
syn.logger.info(f"Organization {ORG_NAME} already exists.")
break
else:
syn.logger.info(f"Creating organization {ORG_NAME}.")
js.create_organization(ORG_NAME)

my_test_org = js.JsonSchemaOrganization(ORG_NAME)
test_schema = my_test_org.get_json_schema(SCHEMA_NAME)
if not test_schema:
test_schema = my_test_org.create_json_schema(schema, SCHEMA_NAME, VERSION)
organization = SchemaOrganization(name=ORG_NAME)
try:
organization.store()
except Exception as e:
organization.get()

schemas = list(organization.get_json_schemas())
for schema in schemas:
print(schema)

schema = JSONSchema(name=SCHEMA_NAME, organization_name=ORG_NAME)
try:
schema.get()
except Exception as e:
schema.store(schema_body=schema_body, version=VERSION)

schema.get_body()

# If you want to make an update, you can re-register your schema with the organization:
updated_schema = {
Expand All @@ -86,9 +81,7 @@
}

try:
new_test_schema = my_test_org.create_json_schema(
updated_schema, SCHEMA_NAME, VERSION
)
schema.store(schema_body=updated_schema, version=VERSION)
except synapseclient.core.exceptions.SynapseHTTPError as e:
if e.response.status_code == 400 and "already exists" in e.response.text:
syn.logger.warning(
Expand All @@ -97,10 +90,17 @@
else:
raise e

schema.store(schema_body=updated_schema, version=NEW_VERSION)
schema.get_body(version=VERSION)
# 4. Bind the JSON schema to the folder
schema_uri = ORG_NAME + "-" + SCHEMA_NAME + "-" + VERSION
# Retrieve test project
PROJECT_ENT = Project(name="My uniquely named project about Alzheimer's Disease").get()

# Create a test folder for JSON schema experiments
test_folder = Folder(name="test_folder", parent_id=PROJECT_ENT.id).store()

bound_schema = test_folder.bind_schema(
json_schema_uri=schema_uri, enable_derived_annotations=True
json_schema_uri=schema.id, enable_derived_annotations=True
)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be schema.uri? schema.id will be a string of an integer like '6164'

json_schema_version_info = bound_schema.json_schema_version_info
syn.logger.info("JSON schema was bound successfully. Please see details below:")
Expand Down
Loading