JSON Schema

A V library for working with JSON Schema - providing model definitions, bidirectional code generation, and utility functions.

Overview

This module provides comprehensive tools for working with JSON Schema, which is "a declarative language that allows you to annotate and validate JSON documents." The module offers:

1. JSON Schema Model: Complete V struct definitions that map to the JSON Schema specification
2. V Code ↔ JSON Schema Conversion: Bidirectional conversion between V code and JSON Schema
3. Code Generation: Generate V structs from JSON Schema and vice versa

Module Structure

• model.v: Core JSON Schema model definitions
• decode.v: Functions to decode JSON Schema strings into Schema structures
• consts_numeric.v: Numeric constants for JSON Schema
• codegen/: Code generation functionality
• generate.v: Generate JSON Schema from V code models
• codegen.v: Generate V code from JSON Schema
• templates/: Templates for code generation

JSON Schema Model

The module provides a comprehensive V struct representation of JSON Schema (based on draft-07), including:

pub struct Schema {
pub mut:
    schema string                // The $schema keyword identifies which version of JSON Schema
    id string                    // The $id keyword defines a URI for the schema
    title string                 // Human-readable title
    description string           // Human-readable description
    typ string                   // Data type (string, number, object, array, boolean, null)
    properties map[string]SchemaRef // Object properties when type is "object"
    additional_properties ?SchemaRef // Controls additional properties
    required []string            // List of required property names
    items ?Items                 // Schema for array items when type is "array"
    // ... and many more validation properties
}

The properties of a JSON Schema is a list of key value pairs, where keys represent the subschema's name and the value is the schema (or the reference to the schema which is defined elsewhere) of the property. This is analogous to the fields of a struct, which is represented by a field name and a type.

It's good practice to define object type schemas separately and reference them in properties, especially if the same schema is used in multiple places. However, object type schemas can also be defined in property definitions. This may make sense if the schema is exclusively used as a property of a schema, similar to using an anonymous struct for the type definition of a field of a struct.

Json Schema Decode & Validation

import freeflowuniverse.herolib.schemas.jsonschema
mut myschema:=jsonschema.decode('the spec...')!

#
#
The module can generate JSON Schema from V code models, making it easy to create schemas from your existing V structs:

```v
// Example: Generate JSON Schema from a V struct import freeflowuniverse.herolib.core.code import freeflowuniverse.herolib.schemas.jsonschema.codegen

// Create a struct model struct_ := code.Struct{ name: 'Person' description: 'A person record' fields: [ code.StructField{ name: 'name' typ: 'string' description: 'Full name' }, code.StructField{ name: 'age' typ: 'int' description: 'Age in years' } ] }

// Generate JSON Schema from the struct schema := codegen.struct_to_schema(struct_)

// The resulting schema will represent: // { //   "title": "Person", //   "description": "A person record", //   "type": "object", //   "properties": { //     "name": { //       "type": "string", //       "description": "Full name" //     }, //     "age": { //       "type": "integer", //       "description": "Age in years" //     } //   } // }
`

JSON Schema to V Code

The module can also generate V code from JSON Schema:

import freeflowuniverse.herolib.schemas.jsonschema import freeflowuniverse.herolib.schemas.jsonschema.codegen

// Create or load a JSON Schema schema := jsonschema.Schema{ title: 'Person' description: 'A person record' typ: 'object' properties: { 'name': jsonschema.Schema{ typ: 'string' description: 'Full name' } 'age': jsonschema.Schema{ typ: 'integer' description: 'Age in years' } } }

// Generate V structs from the schema v_code := codegen.schema_to_v(schema)

// The resulting V code will be: // module schema.title. // // // A person record // struct Person { //     name string // Full name //     age int // Age in years // }

Advanced Features

Handling References

The module supports JSON Schema references ($ref), allowing for modular schema definitions:

// Example of a schema with references schema := jsonschema.Schema{ // ... properties: { 'address': jsonschema.Reference{ ref: '#/components/schemas/Address' } } }

Anonymous Structs

When generating schemas from V structs with anonymous struct fields, the module creates inline schema definitions in the property field, similar to how anonymous structs work in V.

Notes

Due to this issue, a JSON Schema cannot be directly decoded into the JSON Schema structure defined in this module. To decode a JSON Schema string into a structure, use the pub fn decode(data str) !Schema function defined in decode.v.

fn decode(data string) !Schema

fn decode_items(data Any) !Items

fn decode_schemaref(data_map map[string]Any) !SchemaRef

fn decode_schemaref_map(data_map map[string]Any) !map[string]SchemaRef

type Items = SchemaRef | []SchemaRef

Items represents either a single schema reference or an array of schema references. This type is used for the 'items' field in JSON Schema which can be either a schema or an array of schemas.

type Number = int

Number is a type alias for numeric values in JSON Schema.

type SchemaRef = Reference | Schema

SchemaRef represents either a direct Schema object or a Reference to a schema. This allows for both inline schema definitions and references to external schemas.

struct Reference {
pub:
	// The reference path, e.g., "#/definitions/Person" or "http://example.com/schema.json#"
	ref string @[json: '\$ref'; omitempty]
}

Reference represents a JSON Schema reference using the $ref keyword. References point to definitions in the same document or external documents.

struct Schema {
pub mut:
	// The $schema keyword identifies which version of JSON Schema the schema was written for
	schema string @[json: 'schema'; omitempty]

	// The $id keyword defines a URI for the schema
	id string @[json: 'id'; omitempty]

	// Human-readable title for the schema
	title string @[omitempty]

	// Human-readable description of the schema
	description string @[omitempty]

	// The data type for the schema (string, number, object, array, boolean, null)
	typ string @[json: 'type'; omitempty]

	// Object properties when type is "object"
	properties map[string]SchemaRef @[omitempty]

	// Controls additional properties not defined in the properties map
	additional_properties ?SchemaRef @[json: 'additionalProperties'; omitempty]

	// List of required property names
	required []string @[omitempty]

	// Schema for array items when type is "array"
	items ?Items @[omitempty]

	// Definitions of reusable schemas
	defs map[string]SchemaRef @[omitempty]

	// List of schemas, where data must validate against exactly one schema
	one_of []SchemaRef @[json: 'oneOf'; omitempty]

	// Semantic format of the data (e.g., "date-time", "email", "uri")
	format string @[omitempty]

	// === Validation for numbers ===
	// The value must be a multiple of this number
	multiple_of int @[json: 'multipleOf'; omitempty]

	// The maximum allowed value
	maximum int @[omitempty]

	// The exclusive maximum allowed value (value must be less than, not equal to)
	exclusive_maximum int @[json: 'exclusiveMaximum'; omitempty]

	// The minimum allowed value
	minimum int @[omitempty]

	// The exclusive minimum allowed value (value must be greater than, not equal to)
	exclusive_minimum int @[json: 'exclusiveMinimum'; omitempty]

	// Enumerated list of allowed values
	enum_ []string @[json: 'enum'; omitempty]

	// Example value that would validate against this schema (not used for validation)
	example json.Any @[json: '-']
}

Schema represents a JSON Schema document according to the JSON Schema specification. This implementation is based on JSON Schema draft-07. See: https://json-schema.org/draft-07/json-schema-release-notes.html