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 defines exports and imports
  • 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 the components 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.
• 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.
• 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.
• 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.
• 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.