[SYNPY-1673] Add JSONSchema documentation, deprecate old classes

docs/reference/experimental/async/json_schema.md

@@ -0,0 +1,19 @@
+# JSONSchema
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+::: synapseclient.models.JSONSchema
+    options:
+        inherited_members: true
+        members:
+        - get_async
+        - store_async
+        - delete_async
+        - get_versions_async
+        - get_body_async
+        - fill_from_dict
+        - from_uri

docs/reference/experimental/async/schema_organization.md

@@ -0,0 +1,19 @@
+# SchemaOrganization
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+::: synapseclient.models.SchemaOrganization
+    options:
+        inherited_members: true
+        members:
+        - get_async
+        - store_async
+        - delete_async
+        - get_json_schemas_async
+        - get_acl_async
+        - update_acl_async
+        - fill_from_dict

docs/reference/experimental/sync/json_schema.md

@@ -0,0 +1,17 @@
+# JSONSchema
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+::: synapseclient.models.JSONSchema
+    options:
+        inherited_members: true
+        members:
+        - get
+        - store
+        - delete
+        - get_versions
+        - get_body

docs/reference/experimental/sync/schema_organization.md

@@ -0,0 +1,18 @@
+# SchemaOrganization
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+::: synapseclient.models.SchemaOrganization
+    options:
+        inherited_members: true
+        members:
+        - get
+        - store
+        - delete
+        - get_json_schemas
+        - get_acl
+        - update_acl

docs/tutorials/python/json_schema.md

@@ -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).
@@ -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
@@ -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">

docs/tutorials/python/tutorial_scripts/json_schema.py

@@ -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,
@@ -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 = {
@@ -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(
@@ -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.uri, enable_derived_annotations=True
 )
 json_schema_version_info = bound_schema.json_schema_version_info
 syn.logger.info("JSON schema was bound successfully. Please see details below:")

mkdocs.yml

@@ -98,6 +98,8 @@ nav:
           - Curator: reference/experimental/sync/curator.md
           - Link: reference/experimental/sync/link_entity.md
           - Functional Interfaces: reference/experimental/functional_interfaces.md
+          - SchemaOrganization: reference/experimental/sync/schema_organization.md
+          - JSONSchema: reference/experimental/sync/json_schema.md
           - Asynchronous:
               - Factory Operations: reference/experimental/async/factory_operations.md
               - Agent: reference/experimental/async/agent.md
@@ -116,6 +118,8 @@ nav:
               - UserProfile: reference/experimental/async/user_profile.md
               - Curator: reference/experimental/async/curator.md
               - Link: reference/experimental/async/link_entity.md
+              - SchemaOrganization: reference/experimental/async/schema_organization.md
+              - JSONSchema: reference/experimental/async/json_schema.md
           - Mixins:
               - AccessControllable: reference/experimental/mixins/access_controllable.md
               - StorableContainer: reference/experimental/mixins/storable_container.md

synapseclient/client.py

@@ -1627,7 +1627,10 @@ def _print_transfer_progress(self, *args, **kwargs) -> None:
         "json_schema": "JsonSchemaService",
     }
 
-    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1583
+    @deprecated(
+        version="4.11.0",
+        reason="To be removed in 5.0.0.",
+    )
     def get_available_services(self) -> typing.List[str]:
         """Get available Synapse services
         This is a beta feature and is subject to change
@@ -1638,7 +1641,10 @@ def get_available_services(self) -> typing.List[str]:
         services = self._services.keys()
         return list(services)
 
-    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1583
+    @deprecated(
+        version="4.11.0",
+        reason="To be removed in 5.0.0.",
+    )
     def service(self, service_name: str):
         """Get available Synapse services
         This is a beta feature and is subject to change

synapseclient/models/schema_organization.py

@@ -949,7 +949,6 @@ async def store_schema():
         )
         new_version_info = completed_request.new_version_info
         self.organization_id = new_version_info.organization_id
-        self.id = new_version_info.id
         self.created_by = new_version_info.created_by
         self.created_on = new_version_info.created_on
         return self

synapseclient/services/json_schema.py

@@ -4,7 +4,8 @@
 ***********
 
 !!! warning
-    This is a beta implementation and is subject to change.  Use at your own risk.
+    Everything in this module has been deprecated.
+    Use synapseclient.models.SchemaOrganization and synapseclient.models.JSONSchema instead.
 """
 
 from __future__ import annotations
@@ -13,6 +14,8 @@
 from functools import wraps
 from typing import Mapping, Optional, Sequence, Union
 
+from deprecated import deprecated
+
 from synapseclient.client import Synapse
 from synapseclient.core.exceptions import SynapseAuthenticationError, SynapseHTTPError
 from synapseclient.core.utils import id_of
@@ -21,6 +24,10 @@
 DEFAULT_ACCESS = ("CHANGE_PERMISSIONS", "DELETE", "READ", "CREATE", "UPDATE")
 
 
+@deprecated(
+    version="4.11.0",
+    reason="To be removed in 5.0.0. Use synapseclient.models.JSONSchema instead.",
+)
 class JsonSchemaVersion:
     """Json schema version response object
 
@@ -149,6 +156,10 @@ def bind_to_object(self, synapse_id: str):
         return response
 
 
+@deprecated(
+    version="4.11.0",
+    reason="To be removed in 5.0.0. Use synapseclient.models.JSONSchema instead.",
+)
 class JsonSchema:
     """Json schema response object
 
@@ -272,6 +283,10 @@ def create(
         return version
 
 
+@deprecated(
+    version="4.11.0",
+    reason="To be removed in 5.0.0. Use synapseclient.models.SchemaOrganization instead.",
+)
 class JsonSchemaOrganization:
     """Json Schema Organization
 
@@ -484,6 +499,10 @@ def create_json_schema(
         return json_schema
 
 
+@deprecated(
+    version="4.11.0",
+    reason="To be removed in 5.0.0.",
+)
 class JsonSchemaService:
     """Json Schema Service
 

tests/integration/synapseclient/models/async/test_schema_organization.py

@@ -219,15 +219,15 @@ async def test_store_and_get(self, json_schema: JSONSchema) -> None:
         assert not json_schema.created_by
         assert not json_schema.created_on
         # WHEN the object is stored
-        # THEN the Synapse metadata is filled out
+        # THEN the Synapse metadata is filled out, minus id (which is not part of the response)
         await json_schema.store_async({}, synapse_client=self.syn)
         assert json_schema.name
         assert json_schema.organization_name
         assert json_schema.uri
         assert json_schema.organization_id
-        assert json_schema.id
         assert json_schema.created_by
         assert json_schema.created_on
+        assert not json_schema.id
         # AND it should be getable by future instances using the same name
         js2 = JSONSchema(json_schema.name, json_schema.organization_name)
         await js2.get_async(synapse_client=self.syn)