｢‍｣ Lingenic

HSV Schema beta

Type definitions in HSV format

Two Modes

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.5 [RS] hsv.typed [US] true [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]

With Constraints

For richer type definitions, use nested values:

[SOH] hsv [US] 1.5 [RS] hsv.typed [US] true [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.

Activating Typed Mode

Typed mode is activated by an explicit declaration in the header—never by sniffing values for type-like names. Two ways to activate:

• hsv.typed [US] true — inline schema: non-hsv.-prefixed header keys are field type definitions
• hsv.schema [US] <url> — external schema reference (implies typed mode)

When typed mode is not declared, no header value is ever interpreted as a type—metadata like encoding [US] binary is never misread as a field-type declaration.

The hsv. key prefix is reserved for control and metadata. All keys starting with hsv. are protocol-level; all other keys in a typed header are field type definitions.

Schema Reference

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

[SOH] hsv [US] 1.5 [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.

Trade-off. External schema reference is the single construct where an HSV document is no longer self-contained—validation depends on a network fetch and inherits an availability and trust surface. Implementations should cache referenced schemas and consider pinning with an integrity hash (e.g., hsv.schema.hash [US] sha256:abc...). This is the one exception to the "debug with grep" guarantee.

Type System

Fields can be absent or empty by default. Use required [US] true to mandate presence.

Encoding canonicality. In typed mode, each type maps to one normative construct: array ≡ GS-separated values, object ≡ SSA/ESA nesting. In open mode, the same structures are permissive—the consumer assigns meaning.

Type Constraints

Standard Formats

Nested Object Schema

An object field's type definition can carry a nested schema using SSA/ESA, recursively:

profile [US] [SSA] type [US] object [RS] fields [US] [SSA]
  bio [US] string [RS]
  location [US] [SSA] type [US] object [RS] fields [US] [SSA]
    city [US] string [RS]
    country [US] string
  [ESA] [ESA]
[ESA] [ESA]

The fields constraint on an object type contains a nested set of field definitions using the same syntax as the top-level schema. This closes typed mode under nesting—the schema is fully self-hosting.

If fields is omitted from an object type, the nested content is accepted without validation (open sub-structure).

Notes

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.5 [RS] hsv.typed [US] true [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:

1. Parse the header to extract field types
2. Parse each record
3. Validate each field against its type definition
4. 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.5 [RS] hsv.typed [US] true [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.5 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.