diff --git a/docs/tutorials/python/schema_operations.md b/docs/tutorials/python/schema_operations.md new file mode 100644 index 000000000..03c49209f --- /dev/null +++ b/docs/tutorials/python/schema_operations.md @@ -0,0 +1,59 @@ +JSON Schema is a tool used to validate data. In Synapse, JSON Schemas can be used to validate the metadata applied to an entity such as project, file, folder, table, or view, including the [annotations](https://help.synapse.org/docs/Annotating-Data-With-Metadata.2667708522.html) applied to it. To learn more about JSON Schemas, check out [JSON-Schema.org](https://json-schema.org/). + +Synapse supports a subset of features from [json-schema-draft-07](https://json-schema.org/draft-07). To see the list of features currently supported, see the [JSON Schema object definition](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/schema/JsonSchema.html) from Synapse's REST API Documentation. + +In this tutorial, you will learn how to create these JSON Schema using an existing data-model. + +## Tutorial Purpose +You will create a JSON schema using your data model. + +## Prerequisites +* You have a working [installation](../installation.md) of the Synapse Python Client. +* You have a data-model, see [here](https://sagebionetworks.jira.com/wiki/spaces/SCHEM/pages/2473623559/The+Data+Model+Schema) + +## 1. Imports + +```python +{!docs/tutorials/python/tutorial_scripts/schema_operations.py!lines=1-2} +``` + +## 2. Set up your variables + +```python +{!docs/tutorials/python/tutorial_scripts/schema_operations.py!lines=4-10} +``` + +To create a JSON Schema you need a data-model, and the data-types you want to create. +The data-model must be in either CSV or JSON-LD form. The data model may be a local path or a URL. + +The data-types must exist in your data-model. This cna be a list of data-types, or `None` to create all datatatypes in the data-model. + +## 3. Log into Synapse +```python +{!docs/tutorials/python/tutorial_scripts/schema_operations.py!lines=12-13} +``` + + +## 4. Create the JSON Schema +Create the JSON Schema(s) +```python +{!docs/tutorials/python/tutorial_scripts/schema_operations.py!lines=15-23} +``` +You should see the first JSON Schema for the datatype(s) you selected printed. + + +## Source Code for this Tutorial + +
+ Click to show me + +```python +{!docs/tutorials/python/tutorial_scripts/schema_operations.py!} +``` +
+ + +## Reference +- [JSON Schema Object Definition](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/schema/JsonSchema.html) +- [JSON Schema Draft 7](https://json-schema.org/draft-07) +- [JSON-Schema.org](https://json-schema.org./) diff --git a/docs/tutorials/python/tutorial_scripts/schema_operations.py b/docs/tutorials/python/tutorial_scripts/schema_operations.py new file mode 100644 index 000000000..c24ae077b --- /dev/null +++ b/docs/tutorials/python/tutorial_scripts/schema_operations.py @@ -0,0 +1,23 @@ +from synapseclient import Synapse +from synapseclient.extensions.curator import generate_jsonschema + +# Put the path/url of your data model here, either CSV or JSONLD format +DATA_MODEL_SOURCE = "tests/unit/synapseclient/extensions/schema_files/example.model.csv" +# Put the names of the datatypes in your data-model you want to create here +# or None to create them all +DATA_TYPE = ["Patient"] +# Put the directory where you want the JSONSchema to generated at here +OUTPUT_DIRECTORY = "./" + +syn = Synapse() +syn.login() + +schemas, file_paths = generate_jsonschema( + data_model_source=DATA_MODEL_SOURCE, + output_directory=OUTPUT_DIRECTORY, + data_type=DATA_TYPE, + data_model_labels="class_label", + synapse_client=syn, +) + +print(schemas[0]) diff --git a/mkdocs.yml b/mkdocs.yml index cca09f73a..63b4d27db 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,6 +44,7 @@ nav: # - Team: tutorials/python/team.md - Upload data in bulk: tutorials/python/upload_data_in_bulk.md - Download data in bulk: tutorials/python/download_data_in_bulk.md + - Creating JSON Schema: tutorials/python/schema_operations.md - Working with JSON Schema: tutorials/python/json_schema.md # - Move Files and Folders: tutorials/python/move_files_and_folders.md # - Migrate data to other storage locations: tutorials/python/migrate_data_to_other_storage_locations.md