schema

package module
v0.0.0-...-b0bab05 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 28, 2026 License: MPL-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package schema validates Runway template files against the v1alpha1 JSON Schema. The schema itself is embedded, so callers do not need to ship v1alpha1.json alongside their binary.

Index

Constants

View Source 
const ID = "https://raw.githubusercontent.com/runway-templates/schema/refs/heads/main/v1alpha1.json"

ID is the canonical $id of the v1alpha1 schema. It matches the URL referenced by the yaml-language-server header in template files.

Variables

This section is empty.

Functions

func Schema 

func Schema() (*jsonschema.Schema, error)

Schema returns the compiled v1alpha1 schema. The schema is compiled lazily on first call and cached for the lifetime of the process.

func Validate 

func Validate(raw []byte) error

Validate parses raw as YAML or JSON (JSON is a subset of YAML, so either works) and validates the decoded document against the v1alpha1 schema.

func ValidateFile 

func ValidateFile(path string) error

ValidateFile reads a YAML or JSON template from path and validates it against the v1alpha1 schema.

Types

type EnvValue 

type EnvValue struct {
	Value       string `json:"value"`
	Description string `json:"description,omitempty"`
	Warning     string `json:"warning,omitempty"`
}

EnvValue accepts either a bare string ("PORT": "8080") or the full object form ({"value": "8080", "description": "..."}). The shorthand is decoded as if it were {"value": "<string>"}.

func (EnvValue) MarshalJSON 

func (e EnvValue) MarshalJSON() ([]byte, error)

MarshalJSON emits the string shorthand when only Value is set.

func (*EnvValue) UnmarshalJSON 

func (e *EnvValue) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes both the string shorthand and the object form.

type Expr 

type Expr struct {
	Kind ExprKind
	// Name holds the input name (ExprInput), env key (ExprEnv), or
	// runway field (ExprRunway).
	Name string
	// Service and Output are set for ExprOutput.
	Service string
	Output  string
	// N is the requested secret length for ExprSecret.
	N int
}

Expr is one interpolation expression found in a template string. The grammar is defined in docs/interpolation/interpolation.md.

func Expressions 

func Expressions(s string) ([]Expr, error)

Expressions extracts every ${{ ... }} expression from s, in order of appearance. "$${{" escapes a literal "${{" and yields no expression; anything that is not a ${{ ... }} expression is literal text. It returns an error for an unterminated "${{" or a body that does not match the grammar.

func (Expr) String 

func (e Expr) String() string

type ExprKind 

type ExprKind int

ExprKind identifies the namespace of a parsed ${{ ... }} expression. 

const (
	// ExprInput is ${{ inputs.<name> }}.
	ExprInput ExprKind = iota
	// ExprOutput is ${{ services.<service>.outputs.<KEY> }}.
	ExprOutput
	// ExprEnv is ${{ env.<KEY> }}.
	ExprEnv
	// ExprRunway is ${{ runway.<field> }}.
	ExprRunway
	// ExprSecret is ${{ runway.secret(<n>) }}.
	ExprSecret
)

type Healthcheck 

type Healthcheck struct {
	Type                string   `json:"type,omitempty"`
	Path                string   `json:"path,omitempty"`
	Command             []string `json:"command,omitempty"`
	InitialDelaySeconds *int     `json:"initialDelaySeconds,omitempty"`
	PeriodSeconds       *int     `json:"periodSeconds,omitempty"`
	TimeoutSeconds      *int     `json:"timeoutSeconds,omitempty"`
}

Healthcheck configures the probe that decides when the service is healthy.

type InitContainer 

type InitContainer struct {
	Name    string              `json:"name"`
	Image   string              `json:"image,omitempty"`
	Command []string            `json:"command,omitempty"`
	Args    []string            `json:"args,omitempty"`
	Env     map[string]EnvValue `json:"env,omitempty"`
}

InitContainer runs to completion before the main container starts.

type Input 

type Input struct {
	Type        string `json:"type"`
	Description string `json:"description,omitempty"`
	Default     any    `json:"default,omitempty"`
	Required    bool   `json:"required,omitempty"`
	Secret      bool   `json:"secret,omitempty"`
	Enum        []any  `json:"enum,omitempty"`
	Min         *int   `json:"min,omitempty"`
	Max         *int   `json:"max,omitempty"`
	MinLength   *int   `json:"minLength,omitempty"`
	MaxLength   *int   `json:"maxLength,omitempty"`
	Pattern     string `json:"pattern,omitempty"`
	Category    string `json:"category,omitempty"`
}

Input describes a single user-supplied input. Default and Enum are typed as any because the value type depends on Type (string, integer, boolean).

type Issue 

type Issue struct {
	Path     string
	Message  string
	Severity Severity
}

Issue is one finding from Lint. Path uses dotted notation with array indices, e.g. "services[0].image" or "metadata.license".

func Lint 

func Lint(t *Template) []Issue

Lint runs semantic checks against a decoded Template that the JSON Schema cannot express: interpolation reference checks (errors, see docs/interpolation/interpolation.md) plus SPDX license and minPlan checks (warnings). It returns all issues found; an empty slice means clean. Callers decide whether to treat warnings as fatal — errors always are.

func LintFile 

func LintFile(path string) ([]Issue, error)

LintFile decodes the template at path and returns its lint issues. It does not run schema validation; pair it with ValidateFile when both passes are needed.

func ValidateInputs 

func ValidateInputs(t *Template, values map[string]any) (map[string]any, []Issue)

ValidateInputs checks user-supplied values against the inputs declared in t. It returns the normalized value set — defaults filled in, string values as string, integer values as int64, boolean values as bool — and the issues found. All issues are errors; a non-empty list means the values must not be deployed.

The returned map contains only declared inputs. An input that is optional, has no default, and was not provided is left out.

func (Issue) String 

func (i Issue) String() string

type Metadata 

type Metadata struct {
	Name          string   `json:"name"`
	Version       string   `json:"version"`
	DisplayName   string   `json:"displayName"`
	Description   string   `json:"description"`
	Category      string   `json:"category"`
	Tags          []string `json:"tags,omitempty"`
	Documentation string   `json:"documentation,omitempty"`
	Website       string   `json:"website,omitempty"`
	Source        string   `json:"source,omitempty"`
	License       string   `json:"license,omitempty"`
	Maintainer    string   `json:"maintainer,omitempty"`
}

Metadata describes a template for the marketplace: identity, version, and upstream links.

type Service 

type Service struct {
	Name        string              `json:"name"`
	Image       string              `json:"image"`
	Command     []string            `json:"command,omitempty"`
	Args        []string            `json:"args,omitempty"`
	Env         map[string]EnvValue `json:"env,omitempty"`
	Volume      *Volume             `json:"volume,omitempty"`
	Init        []InitContainer     `json:"init,omitempty"`
	Workers     []WorkerContainer   `json:"workers,omitempty"`
	Outputs     map[string]string   `json:"outputs,omitempty"`
	Healthcheck *Healthcheck        `json:"healthcheck,omitempty"`
	Settings    *Settings           `json:"settings,omitempty"`
	MinPlan     string              `json:"minPlan,omitempty"`
}

Service is one deployable unit of a template. Each service becomes its own app on Runway.

type Settings 

type Settings struct {
	// Route controls whether the service gets a public route. Defaults to
	// true when nil.
	Route *bool `json:"route,omitempty"`
	// Lockdown runs the service with a read-only filesystem. Defaults to
	// false when nil. Independent of Route.
	Lockdown *bool `json:"lockdown,omitempty"`
}

Settings holds per-service platform settings. Pointer fields distinguish "not set" (platform default) from an explicit false/true.

type Severity 

type Severity int

Severity classifies a lint Issue. The lint pass currently emits only warnings — none of the checks are universally required by the schema — but the type is exposed so callers can filter or upgrade severities. 

const (
	SeverityWarning Severity = iota
	SeverityError
)

Severity levels for lint issues.

func (Severity) String 

func (s Severity) String() string

type Template 

type Template struct {
	APIVersion string           `json:"apiVersion"`
	Kind       string           `json:"kind"`
	Metadata   Metadata         `json:"metadata"`
	Inputs     map[string]Input `json:"inputs,omitempty"`
	Services   []Service        `json:"services"`
}

Template is the typed representation of a v1alpha1 template document. It mirrors the JSON Schema in v1alpha1.json. Field-level rules (pattern, enum, etc.) are not enforced here — run Validate for that.

func Decode 

func Decode(raw []byte) (*Template, error)

Decode parses raw as YAML or JSON into a Template. It does not run schema validation; pair it with Validate when both a typed model and structural checks are needed.

func DecodeFile 

func DecodeFile(path string) (*Template, error)

DecodeFile reads a YAML or JSON template from path and returns the typed Template. It does not run schema validation — call Validate or ValidateFile separately if you need the structural checks.

type Volume 

type Volume struct {
	MountPath string `json:"mountPath"`
}

Volume declares persistent storage for a service.

type WorkerContainer 

type WorkerContainer struct {
	Name    string              `json:"name"`
	Image   string              `json:"image,omitempty"`
	Command []string            `json:"command,omitempty"`
	Args    []string            `json:"args,omitempty"`
	Env     map[string]EnvValue `json:"env,omitempty"`
}

WorkerContainer is a long-running sidecar in the service's pod.

Source Files

View all Source files

Directories

Path Synopsis
cmd
tool command
Command tool lints and validates Runway template files.
 Command tool lints and validates Runway template files.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.