Add validation tools for server.json schemas and examples #176
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Created validate-schemas tool to verify JSON schema validity - Created validate-examples tool to validate examples against both schemas - Fixed validation errors in examples.md (missing repository ID, wrong source type) - Added validation count tracking to prevent silent failures - Integrated tools into main go.mod for consistent dependency management - Added documentation to docs/server-json/README.md 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Replace fmt.Print with log for output (linter forbids fmt.Print) - Fix unused parameters by using _ - Add error checking for compiler.AddResource - Convert if-else chain to switch statement - Remove timestamps from log output for cleaner CLI experience
- Remove validate-examples and validate-schemas binaries - Add them to .gitignore to prevent future commits
4 tasks
- Resolved conflict in examples.md by keeping repository ID from main - Updated expectedExampleCount to 8 (main branch added a new example)
Keep the more descriptive ID format (example-nuget-id-...) that clearly indicates this is an example ID
chlowell
reviewed
Jul 15, 2025
Co-authored-by: Charles Lowell <10964656+chlowell@users.noreply.github.com>
Co-authored-by: Charles Lowell <10964656+chlowell@users.noreply.github.com>
- Replaced interface{} with any throughout the codebase (Go 1.18+ best practice)
- Added revive linter's use-any rule to enforce this going forward
- Prevents future usage of interface{} in favor of the cleaner 'any' alias
This change improves code readability and ensures consistency with modern Go conventions.
- Replace Cobra with simple main functions
- Tools don't need CLI framework since they take no arguments
- Reduces dependencies and complexity
- Also switched from interface{} to any (Go 1.18+ style)
- In both tools, we already count successful validations - No need for separate boolean when validatedCount tells us everything - Simplifies logic: validation passes if validatedCount == expectedCount
- Use regex pattern to find JSON code blocks in markdown - Cleaner and more maintainable than switch/case string parsing - Handles edge cases better (e.g., won't break on malformed markdown) - Regex pattern: (?s)```json\n(.*?)\n``` captures content between markers
- Better encapsulation: compiler is only used within validateSchema - Cleaner separation of concerns - Each validation gets its own fresh compiler instance - Simplifies the runValidation function
- gocritic offBy1 warning: Index() can return -1 - Add proper bounds checking before slicing string - Prevents potential runtime panic
Member
Author
|
Thanks for the review @chlowell ! This is my first-ever Go PR (coming from a TypeScript/Ruby and some Python career), so all the feedback is very welcome :) |
chlowell
previously approved these changes
Jul 15, 2025
Co-authored-by: Charles Lowell <10964656+chlowell@users.noreply.github.com>
Member
Author
|
Thanks @chlowell - one more 👍 when you have a sec |
chlowell
approved these changes
Jul 15, 2025
domdomegg
pushed a commit
that referenced
this pull request
Aug 7, 2025
This is a first PR for #159 - adding some validation scripts. I want to get to a place where we are confident that making schema changes is in sync with the rest of our code. Step one is making sure the schemas are in sync with our examples. Step two will be making sure the schemas are in sync with our actual Registry implementation code. This is just for the JSON right now; if we're feeling good about this approach I'll do an analogous change for the OpenAPI schemas as well. I'll also follow with adding usage of these scripts to our CI pipeline so we have automated checks on them with every change. ## Summary - Added CLI validation tools for JSON schemas and examples in `docs/server-json/` - Fixed some minor validation errors found in `examples.md` - Ensures schema consistency and example validity in CI/CD pipelines ## Changes ### New Validation Tools 1. **`tools/validate-schemas`** - Validates that `schema.json` and `registry-schema.json` are valid JSON Schema documents 2. **`tools/validate-examples`** - Validates all JSON examples in `examples.md` against both schemas ### Key Features - ✅ Validates JSON schema syntax and structure - ✅ Validates all examples against both base and registry schemas - ✅ Tracks validation counts to prevent silent failures - ✅ Proper exit codes for CI integration - ✅ Clear error messages for debugging ### Fixes to examples.md - Added missing `repository.id` field in NuGet example - Changed `repository.source` from "gitlab" to "github" in Docker example ### Usage ```bash # From repository root ./tools/validate-schemas.sh ./tools/validate-examples.sh ``` ## Testing I ran these scripts locally with minor (breaking) changes, which they each correctly reported. As submitted, they are both passing. 🤖 Co-authored with [Claude Code](https://claude.ai/code) --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Charles Lowell <10964656+chlowell@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is a first PR for #159 - adding some validation scripts. I want to get to a place where we are confident that making schema changes is in sync with the rest of our code. Step one is making sure the schemas are in sync with our examples. Step two will be making sure the schemas are in sync with our actual Registry implementation code.
This is just for the JSON right now; if we're feeling good about this approach I'll do an analogous change for the OpenAPI schemas as well.
I'll also follow with adding usage of these scripts to our CI pipeline so we have automated checks on them with every change.
Summary
docs/server-json/examples.mdChanges
New Validation Tools
tools/validate-schemas- Validates thatschema.jsonandregistry-schema.jsonare valid JSON Schema documentstools/validate-examples- Validates all JSON examples inexamples.mdagainst both schemasKey Features
Fixes to examples.md
repository.idfield in NuGet examplerepository.sourcefrom "gitlab" to "github" in Docker exampleUsage
# From repository root ./tools/validate-schemas.sh ./tools/validate-examples.shTesting
I ran these scripts locally with minor (breaking) changes, which they each correctly reported. As submitted, they are both passing.
🤖 Co-authored with Claude Code