Struct Tags Complete Reference

Complete reference for struct tags used in TinySystems component schemas.

Overview

Struct tags control how Go structs are converted to JSON Schema and rendered in the UI.

type Example struct {
    Field string `json:"field" required:"true" title:"Field Name" description:"Help text"`
}

JSON Tags

json

Maps Go field to JSON property name.

Syntax: json:"name" or json:"name,omitempty"

Examples:

UserName string `json:"userName"`       // camelCase
user_id  string `json:"user_id"`        // snake_case
Data     string `json:"data,omitempty"` // omit if empty

Notes:

Required for all exported fields
Use json:"-" to exclude from schema

Validation Tags

required

Marks field as required.

Syntax: required:"true"

Example:

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

Effect: Field must be provided; UI shows required indicator.

minimum / maximum

Sets numeric range constraints.

Syntax: minimum:"value" maximum:"value"

Examples:

Age       int     `json:"age" minimum:"0" maximum:"150"`
Percentage float64 `json:"percentage" minimum:"0" maximum:"100"`
Port      int     `json:"port" minimum:"1" maximum:"65535"`

minLength / maxLength

Sets string length constraints.

Syntax: minLength:"value" maxLength:"value"

Examples:

Username string `json:"username" minLength:"3" maxLength:"50"`
Code     string `json:"code" minLength:"6" maxLength:"6"`

minItems / maxItems

Sets array size constraints.

Syntax: minItems:"value" maxItems:"value"

Examples:

Tags    []string `json:"tags" minItems:"1" maxItems:"10"`
Choices []string `json:"choices" minItems:"2"`

pattern

Sets regex pattern constraint.

Syntax: pattern:"regex"

Examples:

Email  string `json:"email" pattern:"^[^@]+@[^@]+\\.[^@]+$"`
Phone  string `json:"phone" pattern:"^\\+?[0-9]{10,14}$"`
Slug   string `json:"slug" pattern:"^[a-z0-9-]+$"`

enum

Restricts to specific values.

Syntax: enum:"value1,value2,value3"

Examples:

Status   string `json:"status" enum:"pending,active,completed"`
Priority string `json:"priority" enum:"low,medium,high"`

Display Tags

title

Sets display label.

Syntax: title:"Label"

Examples:

UserID    string `json:"userId" title:"User ID"`
MaxRetries int   `json:"maxRetries" title:"Maximum Retries"`

description

Sets help text / tooltip.

Syntax: description:"Help text"

Examples:

Timeout string `json:"timeout" description:"Duration to wait before timing out (e.g., 30s, 1m)"`
APIKey  string `json:"apiKey" description:"Your API key from the dashboard"`

default

Sets default value.

Syntax: default:"value"

Examples:

Timeout    string `json:"timeout" default:"30s"`
MaxRetries int    `json:"maxRetries" default:"3"`
Enabled    bool   `json:"enabled" default:"true"`

Notes:

Value is string; converted to appropriate type
Used as initial value in UI

readonly

Makes field read-only in UI.

Syntax: readonly:"true"

Examples:

ID        string `json:"id" readonly:"true"`
CreatedAt string `json:"createdAt" readonly:"true"`

UI Layout Tags

format

Specifies special rendering format.

Syntax: format:"formatName"

Formats:

Format	Description
`textarea`	Multi-line text input
`password`	Masked input
`email`	Email input with validation
`uri`	URL input
`date`	Date picker
`time`	Time picker
`date-time`	Date and time picker
`button`	Render as clickable button
`code`	Code editor

Examples:

Bio       string `json:"bio" format:"textarea"`
Password  string `json:"password" format:"password"`
Email     string `json:"email" format:"email"`
Endpoint  string `json:"endpoint" format:"uri"`
BirthDate string `json:"birthDate" format:"date"`
Start     bool   `json:"start" format:"button" title:"Start"`
Config    string `json:"config" format:"code"`

tab

Groups fields into tabs.

Syntax: tab:"Tab Name"

Examples:

type Settings struct {
    // Basic tab
    Name    string `json:"name" tab:"Basic" title:"Name"`
    Email   string `json:"email" tab:"Basic" title:"Email"`

    // Advanced tab
    Timeout string `json:"timeout" tab:"Advanced" title:"Timeout"`
    Debug   bool   `json:"debug" tab:"Advanced" title:"Debug Mode"`
}

colSpan

Controls column width in grid layout.

Syntax: colSpan:"col-span-N" where N is 1-12

Examples:

Title       string `json:"title" colSpan:"col-span-12"`     // Full width
FirstName   string `json:"firstName" colSpan:"col-span-6"`  // Half width
LastName    string `json:"lastName" colSpan:"col-span-6"`   // Half width
Description string `json:"description" colSpan:"col-span-8"` // Two-thirds

propertyOrder

Controls field display order.

Syntax: propertyOrder:"N"

Examples:

type Form struct {
    Email    string `json:"email" propertyOrder:"2"`
    Name     string `json:"name" propertyOrder:"1"`
    Comments string `json:"comments" propertyOrder:"3"`
}
// Displayed: Name, Email, Comments

Special Tags

configurable

Marks field as user-configurable.

Syntax: configurable:"true"

Example:

type Input struct {
    Data   string `json:"data" configurable:"true"`    // User can set
    Source string `json:"source" configurable:"false"` // Set by system
}

shared

Makes field available for referencing by other components.

Syntax: shared:"true"

Example:

type Output struct {
    Result string `json:"result" shared:"true"` // Can be referenced
}

configRef

Enables secret/configmap reference.

Syntax: Use the ConfigRef type

Example:

type Settings struct {
    APIKey ConfigRef `json:"apiKey" title:"API Key"`
}

type ConfigRef struct {
    Value     string `json:"value,omitempty"`
    ConfigRef *struct {
        Name string `json:"name"`
        Key  string `json:"key"`
    } `json:"configRef,omitempty"`
}

Type-Specific Tags

For Strings

Tag	Purpose	Example
`minLength`	Min characters	`minLength:"1"`
`maxLength`	Max characters	`maxLength:"255"`
`pattern`	Regex validation	`pattern:"^[a-z]+$"`
`format`	Input type	`format:"email"`
`enum`	Allowed values	`enum:"a,b,c"`

For Numbers

Tag	Purpose	Example
`minimum`	Min value	`minimum:"0"`
`maximum`	Max value	`maximum:"100"`
`default`	Default value	`default:"10"`

For Arrays

Tag	Purpose	Example
`minItems`	Min elements	`minItems:"1"`
`maxItems`	Max elements	`maxItems:"10"`

For Booleans

Tag	Purpose	Example
`default`	Default value	`default:"true"`
`format`	Render as button	`format:"button"`

Complete Example

type ServerSettings struct {
    // Basic Settings Tab
    Name string `json:"name" required:"true" title:"Server Name"
        description:"Unique identifier for this server"
        minLength:"1" maxLength:"64"
        tab:"Basic" propertyOrder:"1"`

    Host string `json:"host" required:"true" title:"Host"
        description:"Hostname or IP address"
        default:"0.0.0.0"
        tab:"Basic" propertyOrder:"2"
        colSpan:"col-span-8"`

    Port int `json:"port" required:"true" title:"Port"
        description:"Port number (1-65535)"
        minimum:"1" maximum:"65535" default:"8080"
        tab:"Basic" propertyOrder:"3"
        colSpan:"col-span-4"`

    // Security Tab
    TLSEnabled bool `json:"tlsEnabled" title:"Enable TLS"
        description:"Use HTTPS instead of HTTP"
        default:"false"
        tab:"Security"`

    APIKey ConfigRef `json:"apiKey" title:"API Key"
        description:"Secret API key for authentication"
        tab:"Security"`

    // Advanced Tab
    Timeout string `json:"timeout" title:"Request Timeout"
        description:"Maximum time to wait for requests"
        default:"30s"
        tab:"Advanced"`

    MaxConnections int `json:"maxConnections" title:"Max Connections"
        description:"Maximum concurrent connections"
        minimum:"1" maximum:"10000" default:"100"
        tab:"Advanced"`

    Debug bool `json:"debug" title:"Debug Mode"
        description:"Enable verbose logging"
        default:"false"
        tab:"Advanced"`

    // Control (Button)
    Start bool `json:"start" format:"button" title:"Start Server"
        description:"Click to start the server"`
}

Quick Reference Table

Tag	Purpose	Example
`json`	JSON field name	`json:"fieldName"`
`required`	Mark required	`required:"true"`
`title`	Display label	`title:"Field Label"`
`description`	Help text	`description:"Help"`
`default`	Default value	`default:"value"`
`readonly`	Read-only	`readonly:"true"`
`minimum`	Min number	`minimum:"0"`
`maximum`	Max number	`maximum:"100"`
`minLength`	Min string length	`minLength:"1"`
`maxLength`	Max string length	`maxLength:"255"`
`minItems`	Min array items	`minItems:"1"`
`maxItems`	Max array items	`maxItems:"10"`
`pattern`	Regex pattern	`pattern:"^[a-z]+$"`
`enum`	Allowed values	`enum:"a,b,c"`
`format`	Special format	`format:"textarea"`
`tab`	Group in tab	`tab:"Advanced"`
`colSpan`	Column width	`colSpan:"col-span-6"`
`propertyOrder`	Display order	`propertyOrder:"1"`
`configurable`	User editable	`configurable:"true"`
`shared`	Share for reference	`shared:"true"`

Struct Tags Complete Reference ​

Overview ​

JSON Tags ​

json ​

Validation Tags ​

required ​

minimum / maximum ​

minLength / maxLength ​

minItems / maxItems ​

pattern ​

enum ​

Display Tags ​

title ​

description ​

default ​

readonly ​

UI Layout Tags ​

format ​

tab ​

colSpan ​

propertyOrder ​

Special Tags ​

configurable ​

shared ​

configRef ​

Type-Specific Tags ​

For Strings ​

For Numbers ​

For Arrays ​

For Booleans ​

Complete Example ​

Quick Reference Table ​

Struct Tags Complete Reference

Overview

JSON Tags

json

Validation Tags

required

minimum / maximum

minLength / maxLength

minItems / maxItems

pattern

enum

Display Tags

title

description

default

readonly

UI Layout Tags

format

tab

colSpan

propertyOrder

Special Tags

configurable

shared

configRef

Type-Specific Tags

For Strings

For Numbers

For Arrays

For Booleans

Complete Example

Quick Reference Table