edit tutorial; add example for updating schema

Author: linglp

docs/tutorials/python/json_schema.md

@@ -35,15 +35,16 @@ By the end of this tutorial, you will:
 
 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).
 
-Note: If you make an update to your schema, you can re-register your schema with the organization and give it a new version number:
-```python
-test_org.create_json_schema(new_schema_body, your_schema_name, "0.0.2")
-```
 
 ## 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-64}
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=52-65}
+```
+
+Note: If you make an update to your schema, you can re-register your schema with the organization and give it a new version number:
+```python
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=68-90}
 ```
 
 ## 4. Bind the JSON Schema to the Folder
@@ -52,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_annos` to have Synapse automatically calculate derived annotations based on the schema:
 
 ```python
-{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=67-73}
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=94-100}
 ```
 
 <details class="example">
@@ -75,7 +76,7 @@ JSON schema was bound successfully. Please see details below:
 ## 5. Retrieve the Bound Schema
 Next, we can retrieve the bound schema:
 ```python
-{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=76-78}
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=103-105}
 ```
 
 <details class="example">
@@ -104,12 +105,12 @@ JSON Schema was retrieved successfully. Please see details below:
 ## 6. Add Invalid Annotations to the Folder and Store, and Validate the Folder against the Schema
 Try adding invalid annotations to your folder: This step and the step below demonstrate how the system handles invalid annotations and how the schema validation process works.
 ```python
-{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=70-76}
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=108-112}
 ```
 
 Try validating the folder. You should be able to see messages related to invalid annotations.
 ```python
-{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=81-91}
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=116-118}
 ```
 
 
@@ -145,12 +146,12 @@ This step is only relevant for container entities, such as a folder or a project
 
 Try creating a test file locally and store the file in the folder that we created earlier. Then, try adding invalid annotations to a file. This step demonstrates how the files inside a folder also inherit the schema from the parent entity.
 ```python
-{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=95-121}
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=122-148}
 ```
 
 You could then use `get_schema_validation_statistics` to get information such as the number of children with invalid annotations inside a container.
 ```python
-{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=123-125}
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=150-152}
 ```
 
 
@@ -169,7 +170,7 @@ Validation statistics were retrieved successfully. Please see details below:
 
 You could also use `get_invalid_validation` to see more detailed results of all the children inside a container, which includes all validation messages and validation exception details.
 ```python
-{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=127-130}
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=154-159}
 ```
 
 <details class="example">

docs/tutorials/python/tutorial_scripts/json_schema.py

@@ -22,6 +22,7 @@
 # 2. Take a look at the constants and structure of the JSON schema
 ORG_NAME = "myUniqueAlzheimersResearchOrgTurtorial"
 VERSION = "0.0.1"
+NEW_VERSION = "0.0.2"
 SCHEMA_NAME = "clinicalObservations"
 
 title = "Alzheimer's Clinical Observation Schema"
@@ -49,17 +50,45 @@
 
 # 3. Try create test organization and json schema if they do not exist
 js = syn.service("json_schema")
-try:
-    my_test_org = js.JsonSchemaOrganization(ORG_NAME)
-except SynapseHTTPError as e:
-    if e.response.status_code == 404:
-        my_test_org = js.create_organization(ORG_NAME)
-
-try:
-    my_test_schema = my_test_org.get_json_schema(SCHEMA_NAME)
-except SynapseHTTPError as e:
-    if e.response.status_code == 404:
-        my_test_schema = my_test_org.create_json_schema(schema, SCHEMA_NAME, VERSION)
+all_orgs = js.list_organizations()
+for org in all_orgs:
+    if org["name"] == ORG_NAME:
+        print(f"Organization {ORG_NAME} already exists.")
+        break
+else:
+    print(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)
+
+# If you want to make an update, you can re-register your schema with the organization:
+updated_schema = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://example.com/schema/alzheimers_observation.json",
+    "title": "my new title",
+    "type": "object",
+    "properties": {
+        "patient_id": {
+            "type": "string",
+            "description": "A unique identifier for the patient",
+        },
+        "cognitive_score": {
+            "type": "integer",
+            "description": "Quantitative cognitive function score",
+        },
+        "updated_field": {
+            "type": "string",
+            "description": "Updated description for the field",
+        },
+    },
+}
+new_test_schema = my_test_org.create_json_schema(
+    updated_schema, SCHEMA_NAME, NEW_VERSION
+)
+
 
 # 4. Bind the JSON schema to the folder
 schema_uri = ORG_NAME + "-" + SCHEMA_NAME + "-" + VERSION
@@ -122,7 +151,9 @@ def create_random_file(
 print("Validation statistics were retrieved successfully. Please see details below:")
 pprint(vars(validation_statistics))
 
-invalid_validation = test_folder.get_invalid_validation()
+invalid_validation = invalid_results = test_folder.get_invalid_validation(
+    synapse_client=syn
+)
 for child in invalid_validation:
     print("See details of validation results: ")
     pprint(vars(child))