HSV Schema beta

Type definitions in HSV format

Two Modes

Mode	Header Contains	Behavior	Status
Open	No type definitions	Application defines meaning freely	✓ v1.0 standard
Typed	Type definitions	Types MUST be enforced	beta

Open mode is the default HSV behavior defined in the core spec. This page defines the beta Typed extension: if a header contains type definitions, conforming applications must validate data against them.

What Typed Mode Enables

Type safety: Validation at parse time. Code generation for typed languages. Type coercion ("30" → integer 30).

Rich types: rational for exact fractions (1/2, 22/7)—no floating point errors. binary for raw bytes. Standard formats: email, uri, date, datetime, uuid.

Constraints: required, min, max, minlen, maxlen, pattern, enum, items.

Self-describing data: Schema travels with the data in the header. External schema references via URL. No separate schema file needed.

Structured content: HTML/XML-like content via namespace prefixes. No escaping for quotes, angles, ampersands.

Header is the Schema

Header defines structure, body contains data.

HSV uses HSV to describe HSV. Keys are field names, values are types:

[SOH] hsv [US] 1.0 [RS] name [US] string [RS] age [US] int [RS] email [US] string [STX] name [US] Alice [RS] age [US] 30 [RS] email [US] a@b.com [ETX]

Header Key	Header Value	Data Key	Data Value
`name`	`string`	`name`	`Alice`
`age`	`int`	`age`	`30`
`email`	`string`	`email`	`a@b.com`

With Constraints

For richer type definitions, use nested values:

[SOH] hsv [US] 1.0 [RS] name [US] [SSA] type [US] string [RS] required [US] true [ESA] [RS] age [US] [SSA] type [US] int [RS] min [US] 0 [ESA] [RS] email [US] [SSA] type [US] string [RS] format [US] email [ESA] [STX] name [US] Alice [RS] age [US] 30 [RS] email [US] a@b.com [ETX]

Simple types use plain values (string, int). Constrained types use nested structures.

Detecting Schema Mode

A header is a schema if any value is a recognized type name (string, int, float, rational, bool, array, object, binary) or a nested structure (SSA...ESA) containing type [US] .

Reserved header keys (not type definitions):

hsv — version identifier
hsv.schema — external schema reference

Schema Reference

Reference an external schema with the reserved hsv.schema key:

[SOH] hsv [US] 1.0 [RS] hsv.schema [US] https://example.com/user.hsv [STX] name [US] Alice [RS] age [US] 30 [ETX]

The URL returns an HSV document whose header defines the schema.

Type System

Type	Description	Example Values
`string`	UTF-8 text (default)	`Alice`, `hello world`
`int`	Integer	`42`, `-7`
`float`	Floating point (IEEE 754)	`3.14`, `-0.5`, `1.5e-10`
`rational`	Exact fraction	`1/2`, `-3/4`, `22/7`
`bool`	Boolean	`true`, `false`
`array`	GS-separated list	`a [GS] b [GS] c`
`object`	Nested structure	`SSA...ESA`
`binary`	DLE-transparent bytes	`[DLE] [STX] ... [DLE] [ETX]`

Fields can be absent or empty by default. Use required [US] true to mandate a non-empty value.

Type Constraints

Constraint	Applies To	Meaning
`required [US] true`	Any	Must have non-empty value
`min [US] N`	int, float, rational	Minimum value
`max [US] N`	int, float, rational	Maximum value
`minlen [US] N`	string, array	Minimum length
`maxlen [US] N`	string, array	Maximum length
`pattern [US] regex`	string	Must match regex
`format [US] name`	string	Semantic format (see below)
`enum [US] a [GS] b [GS] c`	Any	Value must be one of listed
`items [US] type`	array	Type of array elements
`default [US] value`	Any	Default if absent

Standard Formats

Format	Description	Example
`email`	Email address	`user@example.com`
`uri`	URI/URL	`https://example.com`
`date`	ISO 8601 date	`2026-01-27`
`time`	ISO 8601 time	`14:30:00`
`datetime`	ISO 8601 datetime	`2026-01-27T14:30:00Z`
`uuid`	UUID	`550e8400-e29b-41d4-a716-446655440000`
`base64`	Base64 encoded	`SGVsbG8=`

Notes

object: Nested object schema (defining properties of nested structures) is not yet specified. Use object type to indicate nesting; validation of nested content is application-defined.

binary: Only required constraint applies. Content validation is application-defined.

Full Example

A user record with typed schema in the header:

[SOH] hsv [US] 1.0 [RS]
  id [US] [SSA] type [US] int [RS] required [US] true [RS] min [US] 1 [ESA] [RS]
  name [US] [SSA] type [US] string [RS] required [US] true [RS] maxlen [US] 100 [ESA] [RS]
  email [US] [SSA] type [US] string [RS] format [US] email [ESA] [RS]
  role [US] [SSA] type [US] string [RS] enum [US] admin [GS] user [GS] guest [RS] default [US] user [ESA] [RS]
  tags [US] [SSA] type [US] array [RS] items [US] string [ESA] [RS]
  profile [US] object
[STX] id [US] 1 [RS] name [US] Alice [RS] email [US] alice@example.com [RS] role [US] admin [RS] tags [US] staff [GS] engineering [RS] profile [US] [SSA] bio [US] Engineer [RS] location [US] NYC [ESA] [ETX]

The header maps field names to their types. Simple fields use plain type names (object), constrained fields use nested definitions.

Validation

When a header contains type definitions, conforming applications must:

Parse the header to extract field types
Parse each record
Validate each field against its type definition
Reject invalid data or report errors with field path and constraint violated

Data without typed headers is schema-free HSV—no validation required.

Schema-Only Documents

Standalone schema files (referenced via hsv.schema) contain only a header:

[SOH] hsv [US] 1.0 [RS]
  id [US] [SSA] type [US] int [RS] required [US] true [ESA] [RS]
  name [US] [SSA] type [US] string [RS] required [US] true [ESA] [RS]
  email [US] [SSA] type [US] string [RS] format [US] email [ESA]
[STX] [ETX]

Empty body, schema in header. The file extension .hsv is sufficient.

Summary

Two modes, one format:

Open: No types in header → application defines meaning (v1.0 standard)
Typed: Types in header → validation is mandatory (beta)

Schema syntax:

Simple types: name [US] string
Constrained types: age [US] [SSA] type [US] int [RS] min [US] 0 [ESA]
External schema: hsv.schema [US] https://...

HSV Schema uses HSV format. Same parser, same benefits.