json

JSON

JSON Schema

This package provides functionality to generate JSON schemas from Go types.

Functions

GenerateSchema

The GenerateSchema function takes a reflect.Type and generates a JSON schema as a map[string]any. It supports the following Go types:

• struct: Generates an "object" type schema with properties.
• slice and array: Generates an "array" type schema with items.
• map: Generates an "object" type schema with additional properties.
• int, int8, int16, int32, int64: Generates an "integer" type schema.
• float32, float64: Generates a "number" type schema.
• bool: Generates a "boolean" type schema.
• string: Generates a "string" type schema.
• Other types default to a "string" type schema.

func GenerateSchema(t reflect.Type) map[string]any

Example usage:

package main

import (
    "fmt"
    "reflect"
    "jsonschema"
)

type Example struct {
    Name        string `json:"name" title:"Name" description:"The name of the person" minLength:"1" maxLength:"100"`
    Age         int    `json:"age" minimum:"0" maximum:"150"`
    Email       string `json:"email" format:"email"`
    Tags        []string `json:"tags" minItems:"1" uniqueItems:"true"`
    Preferences map[string]any `json:"preferences" additionalProperties:"true"`
    Password    string `json:"password" required:"true" pattern:"^[a-zA-Z0-9]{8,}$"`
}

func main() {
    schema := jsonschema.GenerateSchema(reflect.TypeOf(Example{}))
    fmt.Println(schema)
}

Supported Tags

• Numeric constraints:

  • minimum: Specifies the minimum value.
  • maximum: Specifies the maximum value.
  • multipleOf: Specifies that the value must be a multiple of this number.

• String constraints:

  • minLength: Specifies the minimum length of the string.
  • maxLength: Specifies the maximum length of the string.
  • pattern: Specifies a regular expression that the string must match.
  • format: Specifies the format of the string (e.g., email, date).

• Array constraints:

  • minItems: Specifies the minimum number of items in the array.
  • maxItems: Specifies the maximum number of items in the array.
  • uniqueItems: Specifies whether all items in the array must be unique.

• Enum support:

  • enum: Specifies a comma-separated list of valid values.

• Metadata:

  • title: Specifies the title of the schema.
  • description: Specifies the description of the schema.
  • default: Specifies the default value.
  • dataSource : Specifies a keyword to indicate options
  • componentId : Specifies a UI component ID

define the data source as an API

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "dataSource": {
        "url": "https://api.example.com/categories",
        "method": "GET",
        "valueField": "id",
        "labelField": "name"
      }
    }
  }
}

define the data source as a token

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "dataSource": "categories"
    }
  }
}

• Composition keywords:

  • oneOf: Specifies a comma-separated list of schemas, one of which must be valid.
  • anyOf: Specifies a comma-separated list of schemas, any of which must be valid.
  • allOf: Specifies a comma-separated list of schemas, all of which must be valid.
  • not: Specifies a schema that must not be valid.

• Required field:

  • required: Specifies whether the field is required.

• Additional properties:

  • additionalProperties: Specifies whether additional properties are allowed (e.g., true, false, or a schema reference).

JSON Patch

The jsonpatch package provides utilities to generate and apply JSON Patch operations. JSON Patch is a format for describing changes to a JSON document. It can be used to update a JSON document by sending the changes rather than the entire document.

Features

• Generate JSON Patch operations by comparing two JSON documents.
• Apply JSON Patch operations to a JSON document.
• Supports add, remove, replace, and move operations.

Usage

To generate a patch:

import "github.com/fgrzl/json/jsonpatch"

before := map[string]any{"foo": "bar"}
after := map[string]any{"foo": "baz"}

patches, err := jsonpatch.GeneratePatch(before, after, "")
if err != nil {
    // handle error
}

To apply a patch:

import "github.com/fgrzl/json/jsonpatch"

original := map[string]any{"foo": "bar"}
patches := []jsonpatch.Patch{
    {Op: "replace", Path: "/foo", Value: "baz"},
}

updated, err := jsonpatch.ApplyPatch(original, patches)
if err != nil {
    // handle error
}

Polymorphic JSON

The polymorphic package provides utilities to handle polymorphic JSON serialization and deserialization. It allows you to register types with a discriminator and serialize/deserialize JSON data with type information.

Features

• Register types with a discriminator.
• Serialize objects with type information.
• Deserialize JSON data into the correct type based on the discriminator.

Usage

To register a type:

import "github.com/fgrzl/json/polymorphic"

type Animal struct {
    Name string `json:"name"`
}

type Dog struct {
    Animal
    Breed string `json:"breed"`
}

func init() {
    polymorphic.Register("dog", func() any { return &Dog{} })
}

To serialize an object:

import "github.com/fgrzl/json/polymorphic"

dog := &Dog{
    Animal: Animal{Name: "Buddy"},
    Breed:  "Golden Retriever",
}

data, err := polymorphic.MarshalPolymorphicJSON("dog", dog)
if err != nil {
    // handle error
}
fmt.Println(string(data))

To deserialize JSON data:

import "github.com/fgrzl/json/polymorphic"

var envelope polymorphic.Envelope
err := json.Unmarshal(data, &envelope)
if err != nil {
    // handle error
}

dog, ok := envelope.Content.(*Dog)
if !ok {
    // handle error
}
fmt.Printf("Deserialized dog: %+v\n", dog)