JSON Schema Basics

TinySystems uses JSON Schema to define port data structures. The SDK generates schemas automatically from Go structs, but understanding the underlying schema format helps when building complex components.

What is JSON Schema?

JSON Schema is a vocabulary for annotating and validating JSON documents. In TinySystems, schemas serve multiple purposes:

• UI Generation: The visual editor renders forms based on schemas
• Validation: Incoming data is validated against schemas
• Documentation: Schemas describe expected data formats
• Type Safety: Ensures data flows correctly between components

Schema Structure

A typical JSON Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "HTTP Request",
  "description": "An HTTP request configuration",
  "properties": {
    "method": {
      "type": "string",
      "title": "HTTP Method",
      "enum": ["GET", "POST", "PUT", "DELETE"],
      "default": "GET"
    },
    "url": {
      "type": "string",
      "title": "URL",
      "format": "uri"
    },
    "body": {
      "title": "Request Body"
    }
  },
  "required": ["url"]
}

Basic Types

String

{
  "type": "string",
  "title": "Name",
  "description": "Enter your name",
  "minLength": 1,
  "maxLength": 100,
  "default": ""
}

Go equivalent:

Name string `json:"name" title:"Name" description:"Enter your name" minLength:"1" maxLength:"100"`

Number

{
  "type": "number",
  "title": "Amount",
  "minimum": 0,
  "maximum": 1000,
  "default": 100
}

Go equivalent:

Amount float64 `json:"amount" title:"Amount" minimum:"0" maximum:"1000" default:"100"`

Integer

{
  "type": "integer",
  "title": "Count",
  "minimum": 1,
  "maximum": 100
}

Go equivalent:

Count int `json:"count" title:"Count" minimum:"1" maximum:"100"`

Boolean

{
  "type": "boolean",
  "title": "Enabled",
  "default": true
}

Go equivalent:

Enabled bool `json:"enabled" title:"Enabled" default:"true"`

Array

{
  "type": "array",
  "title": "Items",
  "items": {
    "type": "string"
  },
  "minItems": 1,
  "maxItems": 10
}

Go equivalent:

Items []string `json:"items" title:"Items" minItems:"1" maxItems:"10"`

Object

{
  "type": "object",
  "title": "Configuration",
  "properties": {
    "host": {"type": "string"},
    "port": {"type": "integer"}
  }
}

Go equivalent:

type Config struct {
    Host string `json:"host"`
    Port int    `json:"port"`
}

Schema Keywords

Validation Keywords

Keyword	Type	Description
type	All	Data type (string, number, integer, boolean, array, object)
enum	All	List of allowed values
const	All	Single allowed value
default	All	Default value

String Keywords

Keyword	Description
minLength	Minimum string length
maxLength	Maximum string length
pattern	Regex pattern
format	Semantic validation (email, uri, etc.)

Number Keywords

Keyword	Description
minimum	Minimum value (inclusive)
maximum	Maximum value (inclusive)
exclusiveMinimum	Minimum value (exclusive)
exclusiveMaximum	Maximum value (exclusive)
multipleOf	Value must be multiple of

Array Keywords

Keyword	Description
items	Schema for array items
minItems	Minimum array length
maxItems	Maximum array length
uniqueItems	All items must be unique

Object Keywords

Keyword	Description
properties	Property schemas
required	List of required properties
additionalProperties	Schema for extra properties

Format Strings

The format keyword provides semantic validation:

Format	Description	Example
email	Email address	user@example.com
uri	Full URI	https://example.com
uri-reference	URI or relative reference	/path/to/resource
date	ISO 8601 date	2024-01-15
date-time	ISO 8601 datetime	2024-01-15T10:30:00Z
time	ISO 8601 time	10:30:00
duration	ISO 8601 duration	P1D (1 day)
ipv4	IPv4 address	192.168.1.1
ipv6	IPv6 address	::1
uuid	UUID	550e8400-e29b-41d4-a716-446655440000
password	Masked input (UI hint)	*****
button	Button in UI	N/A

Enum Values

Define allowed values:

{
  "type": "string",
  "title": "Log Level",
  "enum": ["debug", "info", "warn", "error"],
  "default": "info"
}

With display titles:

Level string `json:"level" title:"Log Level" enum:"debug,info,warn,error" enumTitles:"Debug,Info,Warning,Error"`

Required Fields

Mark fields as required:

{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "email": {"type": "string"}
  },
  "required": ["name", "email"]
}

Go equivalent:

Name  string `json:"name" required:"true"`
Email string `json:"email" required:"true"`

Nested Objects

{
  "type": "object",
  "properties": {
    "server": {
      "type": "object",
      "title": "Server Settings",
      "properties": {
        "host": {"type": "string"},
        "port": {"type": "integer"}
      }
    },
    "auth": {
      "type": "object",
      "title": "Authentication",
      "properties": {
        "username": {"type": "string"},
        "password": {"type": "string", "format": "password"}
      }
    }
  }
}

Go equivalent:

type Settings struct {
    Server ServerConfig `json:"server" title:"Server Settings"`
    Auth   AuthConfig   `json:"auth" title:"Authentication"`
}

type ServerConfig struct {
    Host string `json:"host"`
    Port int    `json:"port"`
}

type AuthConfig struct {
    Username string `json:"username"`
    Password string `json:"password" format:"password"`
}

Arrays of Objects

{
  "type": "array",
  "title": "Endpoints",
  "items": {
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "url": {"type": "string", "format": "uri"}
    },
    "required": ["name", "url"]
  }
}

Go equivalent:

type Settings struct {
    Endpoints []Endpoint `json:"endpoints" title:"Endpoints"`
}

type Endpoint struct {
    Name string `json:"name" required:"true"`
    URL  string `json:"url" format:"uri" required:"true"`
}

Any Type

For flexible data:

{
  "title": "Data",
  "description": "Any JSON value"
}

Go equivalent:

Data any `json:"data" title:"Data" description:"Any JSON value"`

UI Hints

Additional tags for the visual editor:

Tag	Description
propertyOrder	Field display order
widget	Custom widget (textarea, code, etc.)
readOnly	Field is read-only
hidden	Hide from UI

Example:

type Settings struct {
    Name    string `json:"name" propertyOrder:"1"`
    Code    string `json:"code" propertyOrder:"2" widget:"code"`
    Details string `json:"details" propertyOrder:"3" widget:"textarea"`
}

Next Steps

• Schema from Go - Auto-generate schemas
• ConfigRef Pattern - Reference secrets
• Dynamic Schemas - Runtime schemas