Create Definitions - Versori User Documentation

POST

{organisation_id}

connections

{connection_id}

versions

{version}

definitions

object

Required

object

DefinitionsCreate is the payload used to create new Definitions. Each definition can reference another definition in the same request using the following syntax:

{
  "$ref": "#/$defs/{definition_name}"
}

New definitions may also reference existing definitions, however they use the proper URL syntax:

{
  "$ref": "https://platform.versori.com/api/schemas/v1/o/{organisation_id}/{connection_id}/{connection_version}/{definition_id}.{media_type_ext}"
}

Note, the $refs stored in GCS are the gs:// URLs. The API must transform the URLs to the correct public URL. Ideally, the Definition's name would be in the URL, but this would cause issues if a user wanted to rename a Definition, which is something I think we should support. For now using id is fine, but if we changed to in the future, we'd need a way to iterate over all Definitions referencing the one being renamed and update the $ref URLs.

For referencing existing definitions, the definition name must already exist within the scope of the current Connection and Version.

Each definition must have matching dataMediaTypes and schema.mediaType values.

definitions

array

Authorizations

string

cookierequired

Cookie authentication used by the Versori Platform.

Path Parameters

organisation_id

string

required

connection_id

string

required

ID is the unique identifier of the Connection.

version

string

required

Version is the version name of the Connection to retrieve. The reserved names "latest" and "default" may be used to retrieve the latest version or the default version respectively.

Body

application/json

definitions

object[]

required

Response

201 - application/json

definitions

object[]

required

definitions.id

string

required

ID is the unique identifier of the Definition.

definitions.name

string

required

Name is a unique identifier for the Definition within the scope of the Connection. It is expected to both human and machine-readable, i.e. "Product" or "product_variant".

definitions.accept

string[]

required

Accept indicates which content types, expressed as MIME types, that this definition can accept. This value is analogous to the Accept HTTP header, as defined in RFC 7231, section 5.3.2, except each type is defined in a separate array element, rather than as a comma-separated list.

This does not represent the content type of the schema body itself, but the data which conforms to this definition. For example, an API may respond in JSON or YAML, but the schema may be a YAML-formatted JSON Schema. In this case, the Definition's accept field could be ["application/json", "text/yaml"] and schema.contentType will be application/schema+yaml.

definitions.description

string

Description is a human-friendly description of the Definition. This is typically used to describe the purpose of the Definition and how it should be used.

definitions.url

string

required

URL is the location of the actual Schema definition for this Definition entity.

The structure of this URL will be consistent across all media types for each environment, for example:

https://platform.versori.com/api/schemas/v1/o/{organisation_id}/{connection_id}/{connection_version}/{definition_slug}.{media_type_ext}

definitions.referencedBy

object[]

ReferencedBy is a list of DefinitionReference objects which defines what other entities are referencing the this Definition.

Get Definitions Delete Definitions

API Reference

Authorizations

Path Parameters

Body

Response