The Open API specification for Synapse is now available for download!

Download Open API Spec

POST /schema/type/create/async/start

Start an asynchronous job to create a new JSON schema.

A JSON schema must include an $id that is a relative URL of that schema. The pseudo-BNF syntax for a valid $id is as follows:

 < $id > ::= < organization name > "-" < schema name > [ "-"  < semantic version > ]
 
 < organization name > ::= < dot separated alpha numeric > 
 
 < schema name > ::= < dot separated alpha numeric >
 
 < semantic version > ::= See: https://semver.org/
 
 < dot separated alpha numeric >  :: = < alpha numeric > ( "." < alpha numeric > )*
 
 < alpha numeric > ::= < letter > ( < identifier > )*
 
 < letter > ::= [a-zA-Z]
 
 < identifier > ::= < letter > | < digit >
 
 < digit > :: = [0-9]
 

Take the following example, if organizationName="my.organization", schemaName="foo.Bar.json", and semanticVersion="0.1.2", then $id="my.organization-foo.Bar.json-0.1.2". Note: The semantic version is optional. When provide the semantic version is a label for a specific version that allows other schemas to reference it by its version. When a semantic version is include, that version of the schema is immutable. This means if a semantic version is included in a registered schema's $id, all $refs within the schema must also include a semantic version.

All $ref within a JSON schema must either be references to "definitions" within the schema or references other registered JSON schemas. References to non-registered schemas is not currently supported. To reference a registered schema $ref should equal the $id of the referenced schema. To reference the example schema from above use $ref="my.organization-foo.Bar.json-0.1.2".

Note: The semantic version of a referenced schema is optional. When the semantic version is excluded in a $ref the reference is assumed to reference the latest version of the schema. So $ref="my.organization-foo.Bar.json" would be a reference to the latest version of that schema. While $ref="my.organization-foo.Bar.json-0.1.2" would be a reference to the version 0.1.2

To monitor the progress of the job and to get the final results use: GET schema/type/create/async/get/{asyncToken}"

Note: The caller must be granted the ACCESS_TYPE.CREATE permission on the Organization in the schema's $id.

Resource URL

https://repo-prod.prod.sagebase.org/repo/v1/schema/type/create/async/start

Resource Information
Authentication Required
Required OAuth Scopes modify
HTTP Method POST
Request Object CreateSchemaRequest
(application/json)
Response Object AsyncJobId
(application/json)