XTP Schema
The XTP Schema Document is a custom IDL (Interface Description Language) that acts as the source of truth for an Extension Point and all the plug-ins that run on it. It's up to host to define this schema and keep it up to date. From this document, we will be able to automate a lot of valuable features such as:
- Plugin Validation: We can ensure that plugins that are uploaded properly match the interface defined in the schema.
- Documentation: We can generate documentation that can be used by your plug-in developers.
- PDKs / Bindings: We can generate bindings for your plug-in developers to give them a well typed, language idiomatic experience.
Versioning
Stable Versions
All schema documents should have a root level property called version
. Our
versions will be a consecutive increasing sequence of the format: v0
, v1
,
v2
, ... v{n}
. A new number will be minted when we declare a format as
stable. To be stable means that we will not break the format, however we may add
features to a stable version.
Unstable Versions
As we experiment and develop new features and tools, we need a way to express unstable versions. These versions may be used with the understanding that they may break. We will be publishing a changelog of changes to versions and do our best to alert you when they will break. However we do not recommend using draft versions in production.
Unstable versions are published with the suffix -draft
(e.g. v1-draft
). We
will remove the suffix when we declare the version stable, but we will keep the
draft versions around for stability. The draft version will effectively become
an alias for the stable version.
For example, suppose we have versions [v0
, v1-draft
]. When v1 is stable we
will have versions [v0
, v1-draft
, v1
] where v1-draft
is just an alias to
v1
.
JSON Schema
The specification for the XTP Schema is written and stored as a JSON Schema specification. You can currently find a reference to the spec in production here: https://xtp.dylibso.com/assets/wasm/schema.json.
This document can be used to validate or develop your schema documents.
OpenAPI Support
The XTP Schema is inspired by and meant to be as compatible as possible with OpenAPI. We built our own IDL based on OpenAPI because many applications already have APIs and types that are defined with OpenAPI and it's a well understood technology with good tooling support.
OpenAPI is a useful standard for defining types and interfaces across a boundary, however it was not designed for Wasm or having bi-directional calling semantics. Because of this, there are a few key differences. There are also some features that we have yet to support but will be adding support for in the near future.
- Instead of
paths
, XTP Schema definesexports
andimports
- Our interface is no longer an HTTP API, it's a Wasm / code module
- So we must define our types for our export functions and our import functions
- We only support
schemas
under thecomponents
key $ref
can only currently point to a schema type- Non-primitive types cannot be defined inline, you must define a named type and
$ref
to it - All enums must have a named type
Refer to the Definitions below to learn more about these various elements of the XTP Schema
Reference
v0
v0 is our first stable version. It's meant to be minimal and provide just enough information to check that the plugin conforms to the interface that your host expects. Exports are only described by name.
version: v0
exports:
- myExport
- processUser
v1
v1 is still unstable. We're using this version to build out code and documentation generation, along with some other automation features. Exports can be a simple string, or a more complex type. The more information you give us, the more we can generate and validate.
version: v1-draft
exports:
reflectJsonObject:
description: |
This function takes a KitchenSinkObject and returns a KitchenSinkObject.
It should come out the same way it came in.
codeSamples:
- lang: typescript
source: |
// pass this through the host function and return it back
return reflectJsonObjectHost(input)
input:
contentType: application/json
$ref: "#/components/schemas/KitchenSinkObject"
output:
contentType: application/json
$ref: "#/components/schemas/KitchenSinkObject"
reflectUtf8String:
description: |
This function takes a string and returns it.
Should come out the same way it came in.
codeSamples:
- lang: typescript
source: |
return reflectUtf8StringHost(input)
input:
type: string
description: The input string
contentType: text/plain; charset=utf-8
output:
type: string
description: The output string
contentType: text/plain; charset=utf-8
reflectByteBuffer:
description: |
This function takes a byte buffer and returns it.
Should come out the same way it came in.
codeSamples:
- lang: typescript
source: |
return reflectByteBufferHost(input)
input:
contentType: application/x-binary
type: buffer
description: The input byte buffer
output:
contentType: application/x-binary
type: buffer
description: The output byte buffer
imports:
reflectJsonObjectHost:
description: |
This function takes a KitchenSinkObject and returns a KitchenSinkObject.
It should come out the same way it came in. It's the same as the export.
But the export should call this.
input:
contentType: application/json
$ref: "#/components/schemas/KitchenSinkObject"
output:
contentType: application/json
$ref: "#/components/schemas/KitchenSinkObject"
reflectUtf8StringHost:
description: |
This function takes a string and returns it.
Should come out the same way it came in. Same as export.
input:
type: string
description: The input string
contentType: text/plain; charset=utf-8
output:
type: string
description: The output string
contentType: text/plain; charset=utf-8
reflectByteBufferHost:
description: |
This function takes a bugger and returns it.
Should come out the same way it came in. Same as export.
input:
contentType: application/x-binary
type: buffer
description: The input byte buffer
output:
contentType: application/x-binary
type: buffer
description: The output byte buffer
components:
schemas:
EmbeddedObject:
description: An embedded object, has some arrays too
properties:
aBoolArray:
description: an array of bools
type: array
items:
type: boolean
aStringArray:
description: an array of strings
type: array
items:
type: string
anEnumArray:
description: an array of enums
type: array
items:
$ref: "#/components/schemas/AStringEnum"
anIntArray:
description: an array of enums
type: array
items:
type: integer
aDate:
description: a date
type: string
format: date-time
AStringEnum:
description: A string enum
type: string
enum:
- option1
- option2
- option3
KitchenSinkObject:
description: A json object with every type of property
properties:
anOptionalString:
type: string
description: A string but not required
nullable: true
aString:
type: string
description: A String
anInt:
type: integer
description: An Integer
aFloat:
type: number
format: float
description: A Float
aDouble:
type: number
format: double
description: A Double
aBool:
type: boolean
description: A Boolean
anUntypedObject:
type: object
description: An untyped object
anEnum:
description: A string enum (prop comment)
$ref: "#/components/schemas/AStringEnum"
anEmbeddedObject:
description: A embedded object array(prop comment)
$ref: "#/components/schemas/EmbeddedObject"
anEmbeddedObjectArray:
description: A embedded object array (prop comment)
type: array
items:
$ref: "#/components/schemas/EmbeddedObject"
aDate:
description: a date
type: string
format: date-time
JSON Schema
Properties
version
: Refer to #/$defs/XtpVersion.
Definitions
-
XtpVersion
(string): Must be one of:["v0", "v1-draft"]
. -
Export
(object): Cannot contain additional properties.description
(string)codeSamples
(array)- Items: Refer to #/$defs/CodeSample.
input
: Refer to #/$defs/Parameter.output
: Refer to #/$defs/Parameter.
-
CodeSample
(object): Cannot contain additional properties.lang
(string, required): Must be one of:["typescript"]
.source
(string, required)label
(string)
-
Import
(object): Cannot contain additional properties.description
(string)input
: Refer to #/$defs/Parameter.output
: Refer to #/$defs/Parameter.
-
Schema
- One of
- : Refer to #/$defs/ObjectSchema.
- : Refer to #/$defs/EnumSchema.
- One of
-
ObjectSchema
(object): Cannot contain additional properties.description
(string, required)properties
^[a-zA-Z_$][a-zA-Z0-9_$]*$
: Refer to #/$defs/Property.
-
EnumSchema
(object): Cannot contain additional properties.type
(string): Must be one of:["string"]
.description
(string)enum
(array, required)- Items (string)
-
Parameter
- One of
- : Refer to #/$defs/ValueParameter.
- : Refer to #/$defs/RefParameter.
- One of
-
RefParameter
(object): Cannot contain additional properties.$ref
: Refer to #/$defs/SchemaReference.description
(string)nullable
(boolean): Default:false
.contentType
: Refer to #/$defs/ContentType.
-
ValueParameter
(object): Cannot contain additional properties.contentType
: Refer to #/$defs/ContentType.type
: Refer to #/$defs/XtpType.format
: Refer to #/$defs/XtpFormat.nullable
(boolean): Default:false
.description
(string)items
(object): Refer to #/$defs/ArrayItem.
-
Property
- One of
- : Refer to #/$defs/ValueProperty.
- : Refer to #/$defs/RefProperty.
- One of
-
ValueProperty
(object): Cannot contain additional properties.type
: Refer to #/$defs/XtpType.format
: Refer to #/$defs/XtpFormat.nullable
(boolean): Default:false
.description
(string)items
(object): Refer to #/$defs/ArrayItem.
-
RefProperty
(object): Cannot contain additional properties.$ref
: Refer to #/$defs/SchemaReference.description
(string)nullable
(boolean): Default:false
.
-
ContentType
(string): Must be one of:["application/json", "application/x-binary", "text/plain; charset=utf-8"]
. -
XtpType
(string): Must be one of:["integer", "string", "number", "boolean", "object", "array", "buffer"]
. -
XtpFormat
(string): Must be one of:["int32", "int64", "float", "double", "date-time", "byte"]
. -
SchemaReference
(string) -
ArrayItem
(object)- One of
- : Refer to #/$defs/ValueArrayItem.
- : Refer to #/$defs/RefArrayItem.
- One of
-
ValueArrayItem
(object): Cannot contain additional properties.type
: Refer to #/$defs/XtpType.format
: Refer to #/$defs/XtpFormat.
-
RefArrayItem
(object): Cannot contain additional properties.$ref
: Refer to #/$defs/SchemaReference.