{"id":33295185,"url":"https://github.com/nyxstack/schema","last_synced_at":"2026-05-17T03:02:08.921Z","repository":{"id":324449728,"uuid":"1097270179","full_name":"nyxstack/schema","owner":"nyxstack","description":"Fluent, type-safe schema validation and JSON Schema generation for Go. Supports strings, numbers, arrays, objects, unions, conditionals, nullable/optional fields, custom errors, formats, and full i18n error messaging. Build complex validation logic with a clean, chainable API and export standard JSON Schema.","archived":false,"fork":false,"pushed_at":"2025-11-15T21:31:58.000Z","size":122,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-15T23:23:54.510Z","etag":null,"topics":["data-validation","go","golang","i18n","json-schema","library","nyx","nyxstack","schema","validation"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nyxstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-15T21:15:09.000Z","updated_at":"2025-11-15T21:33:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nyxstack/schema","commit_stats":null,"previous_names":["nyxstack/schema"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/nyxstack/schema","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyxstack%2Fschema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyxstack%2Fschema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyxstack%2Fschema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyxstack%2Fschema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nyxstack","download_url":"https://codeload.github.com/nyxstack/schema/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyxstack%2Fschema/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284988465,"owners_count":27095952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-18T02:00:05.759Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-validation","go","golang","i18n","json-schema","library","nyx","nyxstack","schema","validation"],"created_at":"2025-11-18T02:01:18.856Z","updated_at":"2025-11-18T02:03:10.438Z","avatar_url":"https://github.com/nyxstack.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NYX Schema\n\nA powerful, fluent Go library for schema validation and JSON Schema generation with internationalization support.\n\n[![Go Version](https://img.shields.io/badge/Go-%3E%3D%201.24.2-blue.svg)](https://golang.org/)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n## Features\n\n- **Fluent API**: Chainable method calls for intuitive schema construction\n- **Type Safety**: Strong typing with validation for primitives, objects, arrays, and unions\n- **JSON Schema Generation**: Export schemas as standard JSON Schema format\n- **Internationalization**: Built-in i18n support for error messages\n- **Comprehensive Validation**: Support for all common validation constraints\n- **Advanced Schema Types**: AllOf, AnyOf, OneOf, Not, and conditional schemas\n- **Format Validation**: Built-in support for email, URI, UUID, date-time, and more\n- **Custom Error Messages**: Override default validation messages with custom ones\n- **Nullable \u0026 Optional**: Fine-grained control over required fields and null values\n\n## Installation\n\n```bash\ngo get github.com/nyxstack/schema\n```\n\n## Documentation\n\nFor comprehensive documentation on all schema types, including detailed examples and API references:\n\n**[📚 View Full Documentation →](docs/README.md)**\n\nQuick links to specific schema types:\n- [String Schema](docs/string.md) - Text validation with formats and patterns\n- [Int/Number Schema](docs/int.md) - Integer and floating-point validation\n- [Object Schema](docs/object.md) - Structured data validation\n- [Array Schema](docs/array.md) - Collection validation\n- [Union Schema](docs/union.md) - Multiple schema options (OneOf/AnyOf/AllOf)\n- [Conditional Schema](docs/conditional.md) - If/then/else validation logic\n- [UUID Schema](docs/uuid.md) - UUID validation with versions\n- [Date Schema](docs/date.md) - Date, DateTime, Time validation\n- [Transform Schema](docs/transform.md) - Input transformation and validation\n- [Ref Schema](docs/ref.md) - Schema references and reuse\n\n[View all schema types →](docs/README.md)\n\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/nyxstack/schema\"\n)\n\nfunc main() {\n    // Create a string schema with validation\n    nameSchema := schema.String().\n        Title(\"Full Name\").\n        Description(\"User's full name\").\n        MinLength(2).\n        MaxLength(50).\n        Pattern(\"^[a-zA-Z\\\\s]+$\").\n        Required()\n\n    // Validate data\n    ctx := schema.DefaultValidationContext()\n    result := nameSchema.Parse(\"John Doe\", ctx)\n    \n    if result.Valid {\n        fmt.Printf(\"Valid name: %v\\n\", result.Value)\n    } else {\n        for _, err := range result.Errors {\n            fmt.Printf(\"Error: %s\\n\", err.Message)\n        }\n    }\n}\n```\n\n## Core Schema Types\n\n### String Schema\n\n```go\n// Basic string validation\nemailSchema := schema.String().\n    Email().\n    Required(\"Email is required\").\n    MinLength(5, \"Email too short\")\n\n// Pattern validation\nusernameSchema := schema.String().\n    Pattern(\"^[a-zA-Z0-9_]+$\").\n    MinLength(3).\n    MaxLength(20)\n\n// Enum validation\nstatusSchema := schema.String().\n    Enum([]string{\"active\", \"inactive\", \"pending\"})\n```\n\n### Number Schema\n\n```go\n// Integer validation\nageSchema := schema.Int().\n    Min(0).\n    Max(120).\n    Required()\n\n// Float validation\npriceSchema := schema.Float().\n    Min(0.01).\n    Max(9999.99).\n    MultipleOf(0.01)\n```\n\n### Array Schema\n\n```go\n// Array of strings\ntagsSchema := schema.Array(schema.String().MinLength(1)).\n    MinItems(1).\n    MaxItems(10).\n    UniqueItems()\n\n// Complex array validation\nusersSchema := schema.Array(\n    schema.Object().\n        Property(\"name\", schema.String().Required()).\n        Property(\"email\", schema.String().Email().Required()),\n).MinItems(1)\n```\n\n### Object Schema\n\n```go\n// Structured object validation\nuserSchema := schema.Object().\n    Property(\"id\", schema.Int().Min(1).Required()).\n    Property(\"name\", schema.String().MinLength(2).Required()).\n    Property(\"email\", schema.String().Email().Required()).\n    Property(\"age\", schema.Int().Min(13).Max(120).Optional()).\n    Property(\"tags\", schema.Array(schema.String()).Optional()).\n    AdditionalProperties(false)\n\n// Using Shape for concise object creation\nuser := schema.Shape{\n    \"name\":  schema.String().Required(),\n    \"email\": schema.String().Email().Required(),\n    \"age\":   schema.Int().Min(0).Optional(),\n}.AsObject()\n```\n\n### Record Schema\n\n```go\n// Record schema for key-value maps with dynamic keys\nmetadataSchema := schema.Record(\n    schema.String().MinLength(1), // Key schema\n    schema.String().MinLength(1), // Value schema\n).MinProperties(1).MaxProperties(10)\n\n// Example: validate a map of string labels\nlabelsSchema := schema.Record(\n    schema.String().Pattern(\"^[a-z0-9-]+$\"), // Keys must be lowercase with dashes\n    schema.String().MaxLength(100),           // Values max 100 chars\n)\n```\n\n### Union Types\n\n```go\n// AnyOf - value matches at least one schema\nstringOrNumber := schema.AnyOf(\n    schema.String().MinLength(1),\n    schema.Int().Min(0),\n)\n\n// OneOf - value matches exactly one schema\nidSchema := schema.OneOf(\n    schema.String().Pattern(\"^[a-zA-Z0-9_]+$\"),\n    schema.Int().Min(1),\n)\n\n// AllOf - value matches all schemas\nrestrictiveString := schema.AllOf(\n    schema.String().MinLength(8),\n    schema.String().Pattern(\".*[A-Z].*\"),\n    schema.String().Pattern(\".*[0-9].*\"),\n)\n```\n\n## Advanced Features\n\n### Conditional Validation\n\n```go\nconditionalSchema := schema.Conditional().\n    If(schema.Object().Property(\"type\", schema.String().Const(\"premium\"))).\n    Then(schema.Object().Property(\"features\", schema.Array(schema.String()).MinItems(3))).\n    Else(schema.Object().Property(\"features\", schema.Array(schema.String()).MaxItems(1)))\n```\n\n### Custom Error Messages\n\n```go\nschema := schema.String().\n    MinLength(8, \"Password must be at least 8 characters\").\n    Pattern(\".*[A-Z].*\", \"Password must contain uppercase letter\").\n    Required(\"Password is mandatory\")\n```\n\n### Nullable and Optional\n\n```go\n// Optional field (can be omitted)\noptionalField := schema.String().Optional()\n\n// Nullable field (can be null)\nnullableField := schema.String().Nullable()\n\n// Both optional and nullable\nflexibleField := schema.String().Optional().Nullable()\n```\n\n### Format Validation\n\n```go\n// Built-in formats\nemailSchema := schema.String().Email()\nurlSchema := schema.String().URL()\nuuidSchema := schema.String().UUID()\ndateSchema := schema.String().DateTime()\n\n// Custom format with pattern\nphoneSchema := schema.String().\n    Format(schema.StringFormat(\"phone\")).\n    Pattern(\"^\\\\+?[1-9]\\\\d{1,14}$\")\n```\n\n## Validation Context\n\n```go\n// Default English context\nctx := schema.DefaultValidationContext()\n\n// Custom locale for internationalization\nctx := schema.NewValidationContext(\"es\") // Spanish\n\n// With Go context\nctx := schema.DefaultValidationContext().\n    WithContext(context.Background())\n```\n\n## JSON Schema Generation\n\n```go\nuserSchema := schema.Object().\n    Property(\"name\", schema.String().Required()).\n    Property(\"email\", schema.String().Email().Required())\n\n// Generate JSON Schema\njsonSchema := userSchema.JSON()\n\n// Convert to JSON\njsonBytes, _ := json.Marshal(jsonSchema)\nfmt.Println(string(jsonBytes))\n```\n\nOutput:\n```json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\"\n    },\n    \"email\": {\n      \"type\": \"string\",\n      \"format\": \"email\"\n    }\n  },\n  \"required\": [\"name\", \"email\"],\n  \"additionalProperties\": false\n}\n```\n\n## Error Handling\n\n```go\nresult := schema.Parse(data, ctx)\n\nif !result.Valid {\n    for _, err := range result.Errors {\n        fmt.Printf(\"Field: %v\\n\", err.Path)\n        fmt.Printf(\"Value: %s\\n\", err.Value)\n        fmt.Printf(\"Error: %s\\n\", err.Message)\n        fmt.Printf(\"Code: %s\\n\", err.Code)\n    }\n}\n```\n\n## Real-World Example\n\n```go\n// User registration schema with i18n support\nregistrationSchema := schema.Object().\n    Property(\"username\", schema.String().\n        Pattern(\"^[a-zA-Z0-9_]+$\").\n        MinLength(3).\n        MaxLength(20).\n        Required(i18n.S(\"username is required\"))).\n    Property(\"email\", schema.String().\n        Email().\n        Required(i18n.S(\"email address is required\"))).\n    Property(\"password\", schema.String().\n        MinLength(8, i18n.F(\"password must be at least %d characters\", 8)).\n        Pattern(\".*[A-Z].*\", i18n.S(\"password must contain uppercase\")).\n        Pattern(\".*[0-9].*\", i18n.S(\"password must contain number\")).\n        Required(i18n.S(\"password is required\"))).\n    Property(\"age\", schema.Int().\n        Min(13, i18n.F(\"must be at least %d years old\", 13)).\n        Max(120).\n        Optional()).\n    Property(\"terms\", schema.Bool().\n        Const(true, i18n.S(\"must accept terms and conditions\")).\n        Required()).\n    AdditionalProperties(false)\n\n// Validate registration data\ndata := map[string]interface{}{\n    \"username\": \"johndoe\",\n    \"email\": \"john@example.com\",\n    \"password\": \"SecurePass123\",\n    \"age\": 25,\n    \"terms\": true,\n}\n\nresult := registrationSchema.Parse(data, schema.DefaultValidationContext())\nif result.Valid {\n    fmt.Println(\"Registration data is valid!\")\n} else {\n    for _, err := range result.Errors {\n        fmt.Printf(\"Validation error: %s\\n\", err.Message)\n    }\n}\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Write tests for your changes\n4. Ensure all tests pass (`go test ./...`)\n5. Commit your changes (`git commit -am 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## Testing\n\nRun the test suite:\n\n```bash\ngo test ./...\n```\n\nRun tests with coverage:\n\n```bash\ngo test -cover ./...\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Related Projects\n\n- [nyxstack/i18n](https://github.com/nyxstack/i18n) - Internationalization support used by this library\n- [nyxstack/validator](https://github.com/nyxstack/validator) - Struct tag based validation using this schema library. Enables validation through struct tags for seamless integration with Go structs.\n\n## Support\n\n- Create an issue for bug reports or feature requests\n- Check existing issues before creating new ones\n- Provide minimal reproducible examples for bugs\n\n---\n\nMade with ❤️ by the Nyx team","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyxstack%2Fschema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnyxstack%2Fschema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyxstack%2Fschema/lists"}