jsonschemaprofiles

README

jsonschemaprofiles

A Go library and CLI tool for validating that JSON Schema documents conform to provider-specific structured-output restrictions (for example Gemini and OpenAI).

This project is about schema-profile validation—it validates schemas themselves, not JSON data instances.

Overview

LLM providers that support structured JSON output each accept only a subset of JSON Schema. A schema that works with one provider may be rejected by another. This library:

• Validates schemas against provider profiles using a two-phase model
• Coerces schemas toward compliance with minimal, traceable changes
• Embeds all profile meta-schemas for zero-config usage
• Provides both a Go library API and a CLI

Installation

Go Library

go get github.com/UnitVectorY-Labs/jsonschemaprofiles

CLI

go install github.com/UnitVectorY-Labs/jsonschemaprofiles/cmd/jsonschemaprofiles@latest

Or download a pre-built binary from Releases.

Quick Start

Library

import jsp "github.com/UnitVectorY-Labs/jsonschemaprofiles"

// Validate a schema against a profile
report, err := jsp.ValidateSchema(jsp.OPENAI_202602, schemaBytes, nil)
if !report.Valid {
    fmt.Println(report.Text())
}

// Coerce a schema for compliance
coerced, report, changed, err := jsp.CoerceSchema(jsp.OPENAI_202602, schemaBytes, &jsp.CoerceOptions{
    Mode: jsp.CoerceModeConservative,
})

CLI

# List profiles
jsonschemaprofiles profiles list

# Validate
jsonschemaprofiles validate schema --profile OPENAI_202602 --in schema.json

# Coerce
jsonschemaprofiles coerce schema --profile OPENAI_202602 --in schema.json --out fixed.json

Available Profiles

Profile ID	Description
OPENAI_202602	OpenAI Structured Outputs subset
GEMINI_202602	Gemini baseline structured output
GEMINI_202503	Gemini 2.0 with required propertyOrdering
MINIMAL_202602	Lowest common denominator across providers

License

See LICENSE for details.

Documentation

Index

• func GetProfileSchema(id ProfileID) ([]byte, error)
• type CoerceMode
• type CoerceOptions
• type Finding
• type ProfileID
• type ProfileInfo
  • func GetProfileInfo(id ProfileID) (ProfileInfo, error)
  • func ListProfiles() []ProfileInfo
• type Report
  • func CoerceSchema(profileID ProfileID, schemaBytes []byte, opts *CoerceOptions) ([]byte, *Report, bool, error)
  • func NewReport() *Report
  • func ValidateSchema(profileID ProfileID, schemaBytes []byte, opts *ValidateOptions) (*Report, error)
• type Severity
• type ValidateOptions

Functions

func GetProfileSchema

func GetProfileSchema(id ProfileID) ([]byte, error)

GetProfileSchema returns the raw YAML bytes of the embedded meta-schema for a profile.

Types

type CoerceMode

type CoerceMode = engine.CoerceMode

CoerceMode specifies the coercion aggressiveness.

const (
	CoerceModeConservative CoerceMode = engine.CoerceModeConservative
	CoerceModePermissive   CoerceMode = engine.CoerceModePermissive
	CoerceModeOff          CoerceMode = engine.CoerceModeOff
)

type CoerceOptions

type CoerceOptions = engine.CoerceOptions

CoerceOptions configures coercion behavior.

type Finding

type Finding = engine.Finding

Finding represents a single validation or coercion finding.

type ProfileID

type ProfileID string

ProfileID identifies a provider profile.

const (
	OPENAI_202602  ProfileID = "OPENAI_202602"
	GEMINI_202602  ProfileID = "GEMINI_202602"
	GEMINI_202503  ProfileID = "GEMINI_202503"
	MINIMAL_202602 ProfileID = "MINIMAL_202602"
)

type ProfileInfo

type ProfileInfo struct {
	ID          ProfileID
	Title       string
	Description string
	Baseline    string
	SchemaFile  string // path relative to embed FS root
}

ProfileInfo describes a profile.

func GetProfileInfo

func GetProfileInfo(id ProfileID) (ProfileInfo, error)

GetProfileInfo returns the info for a profile ID.

func ListProfiles

func ListProfiles() []ProfileInfo

ListProfiles returns all registered profile infos.

type Report

type Report = engine.Report

Report is the canonical output of validation or coercion.

func CoerceSchema

func CoerceSchema(profileID ProfileID, schemaBytes []byte, opts *CoerceOptions) ([]byte, *Report, bool, error)

CoerceSchema attempts to make a schema compliant with a profile. Returns the coerced schema bytes, a report of changes, and whether any changes were made.

func NewReport

func NewReport() *Report

NewReport creates a new empty report (valid by default).

func ValidateSchema

func ValidateSchema(profileID ProfileID, schemaBytes []byte, opts *ValidateOptions) (*Report, error)

ValidateSchema validates a candidate JSON Schema against a profile. It runs Phase 1 (meta-schema validation) and Phase 2 (provider-specific code checks).

type Severity

type Severity = engine.Severity

Severity represents the severity of a finding.

const (
	SeverityError   Severity = engine.SeverityError
	SeverityWarning Severity = engine.SeverityWarning
	SeverityInfo    Severity = engine.SeverityInfo
)

type ValidateOptions

type ValidateOptions = engine.ValidateOptions

ValidateOptions configures validation behavior.