JSON Schemas

In Synapse, you can streamline the annotation process and ensure that your metadata meets certain requirements using JSON Schemas. You can define a JSON Schema to require certain fields, restrict annotations to specific values, and even apply conditional logic to validate metadata.

JSON Schemas primarily supplement Annotations; you should understand Annotations in Synapse before using JSON Schemas. This document also assumes you are comfortable with using the Synapse Python Client.

JSON Schemas and Annotations

JSON Schema is a tool used to validate data. In Synapse, JSON Schemas can be used to validate the metadata applied to a project, file, folder, table, or view, including the Annotations applied to it. To learn more about JSON Schemas, check out JSON-Schema.org.

Synapse supports a subset of features from json-schema-draft-07. To see the list of features currently supported, see the JsonSchema object definition from our REST API Documentation.

When a JSON Schema is bound to an object in Synapse, a couple of things happen:

• When the metadata or schema changes, the metadata is automatically validated against the applied JSON schema.

• (Experimental Mode only) In the web UI, a custom form is shown when editing Annotations to help write Annotations that match the bound schema.

Organizations

JSON Schemas are managed by Organizations. At this time, Organizations must be created via a programmatic client or REST API call.

Create an Organization

To create an Organization, all you need is a name, which must meet certain requirements.

In Python, after logging in, you can create an organization. Note that you’ll have to change the organization name to something unique.

organizationName = "SynapseDocs"

organizationRequestBody = f"{{ \"organizationName\": \"{organizationName}\"}}"

organization = syn.restPOST("/schema/organization", organizationRequestBody)

Create a JSON Schema

Once you’ve created an Organization, you can create a JSON Schema. We’ll create a simple schema that specifies an annotation called “color”. Note that you will have to modify the organization name in the schema $id to successfully create your own schema.

schemaRequestBody = """
{
	"schema": {
		"$schema": "http://json-schema.org/draft-07/schema#",
		"$id": "https://repo-prod.prod.sagebase.org/repo/v1/schema/type/registered/SynapseDocs-Color",
		"properties": {
			"color": {
				"type": "string",
				"title": "Color",
				"description": "The color of the object",
				"enum": [
					"Red",
					"Green",
					"Blue",
					"Yellow",
					"Orange",
					"Purple",
					"Brown",
					"Black",
					"White"
				]
			}
		},
		"required": [
			"color"
		]
	},
	"dryRun": false
}
"""

# Issue a request to create the schema
schemaJobResponse = syn.restPOST("/schema/type/create/async/start", schemaRequestBody)

# Check on the job until it completes.
asyncJobStatus = syn.restGET(f"/asynchronous/job/{schemaJobResponse['token']}")

while asyncJobStatus["jobState"] == "PROCESSING":
    time.sleep(1) 
    asyncJobStatus = syn.restGET(f"/asynchronous/job/{schemaJobResponse['token']}")

Schema Versioning

You can create new versions of the schema by issuing a new request to the same endpoint, POST /schema/type/create/async/start.

When you bind a JSON schema to an object, you can choose to bind a particular version of the schema to prevent updates to the schema from applying to the object.

Bind a JSON Schema to an Object

You can bind a JSON Schema to any project, folder, file, table, or view. When you bind a JSON Schema to a project or folder, then all items inside of the project or folder will inherit the schema binding, unless the item has a schema bound to itself. Only one schema can be bound to an item at a time.

If you have edit access on a Synapse object, you can bind a schema to the entity in Python:

objectId = 'syn########' # Replace the ID with your own

bindSchemaRequest = f"""{{ "entityId": "{objectId}", "schema$id": "SynapseDocs-Color"}}"""

syn.restPUT(f"/entity/{entityId}/schema/binding", bindSchemaRequest)

Annotate an Object with a Schema

At the bottom of the page, ensure that Experimental Mode is toggled on. This may cause issues with other Synapse features that you use in your workflow.

Once you have enabled Experimental Mode, navigate to the file or folder for which you’ve bound a schema. As you edit the annotations on the file, you will see a form that corresponds to the schema that you have bound.

In Experimental Mode, you’ll also be able to see if a file’s metadata or annotations are invalid because of missing or invalid data.