Repository navigation
feat(config): JSON Schemas for config.json and the devcontainer block - #522
Merged
Merged
Conversation
The configuration is not stable, so #268 maps one explicitly provisional, named version: v0-provisional. The schema is hand-written in schemas/config.v0-provisional.schema.json and checks structure only (keys, types, enums, ranges); ownership, permissions and runtime policy stay in Validate and whr doctor. config.Parse keeps DisallowUnknownFields. Only an optional string key $schema is added, as Config.Schema, so a file that names its schema for editors still loads while typos and secret-field rejection are unchanged. Nothing reads or resolves the value, so no network request can happen and a missing, wrong or unreachable URL never affects loading; a test pins that by structure, since a call cannot be proven absent otherwise. Two $schema meanings stay apart: the schema document names the JSON Schema dialect, an instance names the published schema URL (a test checks both). internal/schematest holds a small validator and a recursive comparison of a schema with a Go struct (keys both ways, nested, types, optionality). I wrote a walker instead of adding a validator dependency: it supports only the keywords the schemas use and panics on any other, so nothing in a schema goes unchecked. The one deliberate exception is clone_depth, which the loader reads as 0 when missing. Refs: #268 Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
D51's check and the other hint keys live in a free-form customizations block, so an editor cannot complete or check them. Add the hand-written schemas/devcontainer-workharbor.v0-provisional.schema.json (same provisional name as the config schema: v0-provisional). It is structural only; the supervisor's configuration still decides and the reader still ignores bad values with a note. It flags unknown keys so an editor shows a typo although the reader would ignore them. The reader's anonymous struct becomes the named workharborBlock so a test can compare it recursively with the schema, as it does for config.json (keys both ways, types, optionality). previewPorts stays a RawMessage because the reader accepts numbers and numeric strings; the schema allows both and the test only requires its entry. Good and wrong blocks (typo, wrong type, bad port) are validated with the same small walker. Refs: #268 Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
#268 asks for the schemas next to openapi.json. Mount the repository's schemas/ directory into the site at /schemas/, as #267 does for openapi.json: one canonical source, copied during the docs build, with no second copy. The pages workflow now also runs when schemas/ changes. Each file name carries its surface and version (<surface>.v0-provisional.schema.json), so a later version gets a new URL and older files stay where they are. A docs test checks that every file of schemas/ is published byte for byte and that its name has that shape; that a published file is never edited stays a review rule, not a test. The new manual page JSON Schemas explains the provisional marking, the $schema line (ignored by the loader, never fetched) and one editor association for the devcontainer block (a VS Code json.schemas wrapper). Whether VS Code resolves that remote $ref is marked unverified. The docs test helper builds the site once for all tests of the package. Refs: #268 Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Owner
Author
|
Opus review CLEAR on 8c2d39c. Full go test ./... exit 0 and make check-ci exit 0 on that head (author and reviewer). No High/Medium findings. Lows (batched on #399): schematest unsupported-keyword walk only covers reached subschemas; scripts/docs_schema_test.go leaves a built site in TMPDIR; schema stricter than the loader for explicit zero percents/preview ports and uppercase URL scheme. Unverified: VS Code handling of the remote $ref, hosted Pages deployment. |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Adds hand-written, provisionally versioned (v0-provisional) JSON Schemas for config.json and customizations.workharbor, a recursive schema-versus-struct comparison test, an optional $schema key that the loader ignores (no runtime loading), and publication on the docs site.
Closes #268
Review: Opus CLEAR on 8c2d39c; Lows (schematest keyword walk, docs-site temp dir cleanup, schema stricter than loader for explicit zero values and scheme case) are batched on #399. Unverified: VS Code handling of the remote $ref; hosted Pages deployment.
🤖 Generated with Claude Code