Skip to content

Schema Reference

Jump to bottom
LoSkroefie edited this page Jan 21, 2025 · 1 revision

Schema Reference for FlexonCLI 📝

This document provides detailed information about the JSON schemas used in FlexonCLI.

Core Schemas

Prompt Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["prompt", "metadata"],
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32768
    },
    "metadata": {
      "type": "object",
      "required": ["model", "timestamp", "version"],
      "properties": {
        "model": {
          "type": "string",
          "minLength": 1
        },
        "timestamp": {
          "type": "string",
          "format": "date-time"
        },
        "version": {
          "type": "string",
          "pattern": "^\\d+\\.\\d+\\.\\d+$"
        }
      }
    }
  }
}

Training Data Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["dataset", "metadata"],
  "properties": {
    "dataset": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["input", "output", "metadata"],
        "properties": {
          "input": {
            "type": "string",
            "minLength": 1
          },
          "output": {
            "type": "string",
            "minLength": 1
          },
          "metadata": {
            "type": "object",
            "required": ["timestamp", "source"],
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time"
              },
              "source": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}

Game State Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["gameState", "metadata"],
  "properties": {
    "gameState": {
      "type": "object",
      "required": ["player", "world", "inventory"],
      "properties": {
        "player": {
          "type": "object",
          "required": ["position", "stats"],
          "properties": {
            "position": {
              "type": "object",
              "required": ["x", "y", "z"],
              "properties": {
                "x": { "type": "number" },
                "y": { "type": "number" },
                "z": { "type": "number" }
              }
            },
            "stats": {
              "type": "object",
              "required": ["health", "level"],
              "properties": {
                "health": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 100
                },
                "level": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    }
  }
}

Schema Usage

Validation

# Validate against schema
flexon-cli validate data.flexon schema.json

# Serialize with schema validation
flexon-cli serialize -i data.json -o output.flexon -s schema.json

Schema Creation

# Generate schema from example
flexon-cli schema-gen -i example.json -o schema.json

# Create schema with defaults
flexon-cli schema-create -t prompt -o prompt_schema.json

Custom Schema Types

Vector Type

{
  "type": "object",
  "properties": {
    "vector": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "minItems": 1
    }
  }
}

Binary Data Type

{
  "type": "object",
  "properties": {
    "binary": {
      "type": "string",
      "contentEncoding": "base64"
    }
  }
}

Schema Best Practices

  1. Version Control

    • Include schema version
    • Document changes
    • Maintain compatibility

  2. Validation

    • Use strict types
    • Set appropriate limits
    • Include required fields

  3. Documentation

    • Comment schemas
    • Provide examples
    • List dependencies

  4. Performance

    • Optimize schema size
    • Use appropriate types
    • Consider validation cost

Common Patterns

Metadata Pattern

{
  "type": "object",
  "properties": {
    "metadata": {
      "type": "object",
      "required": ["version", "timestamp"],
      "properties": {
        "version": {
          "type": "string",
          "pattern": "^\\d+\\.\\d+\\.\\d+$"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}

Security Pattern

{
  "type": "object",
  "properties": {
    "security": {
      "type": "object",
      "required": ["fingerprint", "auditTrail"],
      "properties": {
        "fingerprint": {
          "type": "string"
        },
        "auditTrail": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["timestamp", "action"],
            "properties": {
              "timestamp": {
                "type": "string",
                "format": "date-time"
              },
              "action": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}

Error Messages

Common validation errors and their solutions:

  1. Required Field Missing
{
  "error": "required property missing: metadata",
  "path": "$.metadata",
  "schemaPath": "#/required/1"
}
  1. Type Mismatch
{
  "error": "expected number, got string",
  "path": "$.value",
  "schemaPath": "#/properties/value/type"
}
  1. Pattern Mismatch
{
  "error": "string does not match pattern",
  "path": "$.version",
  "schemaPath": "#/properties/version/pattern"
}

Additional Resources

  1. Documentation

  2. Tools

    • Schema validators
    • Schema generators
    • Documentation tools

  3. Examples

    • Schema patterns
    • Validation cases
    • Error handling

Clone this wiki locally