{"id":50832085,"url":"https://github.com/varavelio/vdl-plugin-json-schema","last_synced_at":"2026-06-14T00:05:24.882Z","repository":{"id":347489011,"uuid":"1191764171","full_name":"varavelio/vdl-plugin-json-schema","owner":"varavelio","description":"VDL plugin for generating JSON Schema files","archived":false,"fork":false,"pushed_at":"2026-04-21T18:36:55.000Z","size":87,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T20:40:54.648Z","etag":null,"topics":["codegen","json","json-schema","varavel","vdl","vdl-plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/varavelio.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":"2026-03-25T15:06:27.000Z","updated_at":"2026-04-21T18:36:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/varavelio/vdl-plugin-json-schema","commit_stats":null,"previous_names":["varavelio/vdl-plugin-json-schema"],"tags_count":1,"template":false,"template_full_name":"varavelio/vdl-plugin-template","purl":"pkg:github/varavelio/vdl-plugin-json-schema","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varavelio%2Fvdl-plugin-json-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varavelio%2Fvdl-plugin-json-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varavelio%2Fvdl-plugin-json-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varavelio%2Fvdl-plugin-json-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/varavelio","download_url":"https://codeload.github.com/varavelio/vdl-plugin-json-schema/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varavelio%2Fvdl-plugin-json-schema/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34304633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"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":["codegen","json","json-schema","varavel","vdl","vdl-plugin"],"created_at":"2026-06-14T00:05:24.108Z","updated_at":"2026-06-14T00:05:24.874Z","avatar_url":"https://github.com/varavelio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg\n    src=\"https://raw.githubusercontent.com/varavelio/vdl/9cb8432f972f986ba91ffa1e4fe82220a8aa373f/assets/png/vdl.png\"\n    alt=\"VDL logo\"\n    width=\"130\"\n  /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eVDL JSON Schema Plugin\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Generate JSON Schema Draft 2020-12 from VDL \u003cstrong\u003etypes\u003c/strong\u003e and \u003cstrong\u003eenums\u003c/strong\u003e.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://varavel.com\"\u003e\n    \u003cimg src=\"https://cdn.jsdelivr.net/gh/varavelio/brand@1.0.0/dist/badges/project.svg\" alt=\"A Varavel project\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://varavel.com/vdl\"\u003e\n    \u003cimg src=\"https://cdn.jsdelivr.net/gh/varavelio/brand@1.0.0/dist/badges/vdl-plugin.svg\" alt=\"VDL Plugin\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nThis plugin converts your VDL schema into a standard `schema.json` file that can be consumed by validators, documentation tools, form builders, API gateways, and any platform that understands JSON Schema.\n\nIt is focused on data models only.\n\nUse it when you want to:\n\n- validate JSON payloads outside generated SDKs\n- share a machine-readable contract with external systems\n- drive forms, docs, or internal tooling from your schema\n- publish a standard JSON Schema representation of your VDL model\n\n## Quick Start\n\n1. Add the plugin to your `vdl.config.vdl`:\n\n```vdl\nconst config = {\n  version 1\n  plugins [\n    {\n      src \"varavelio/vdl-plugin-json-schema@v0.1.0\"\n      schema \"./schema.vdl\"\n      outDir \"./gen\"\n    }\n  ]\n}\n```\n\n2. Run your normal VDL generation command:\n\n```bash\nvdl generate\n```\n\n3. Check the generated file in `./gen`:\n\n- `schema.json`\n\nBy default, the plugin writes a single file named `schema.json` inside your `outDir`.\n\n## Plugin Options\n\nAll options are optional.\n\n| Option    | Type     | Default         | What it changes                                                                                                                                                                                              |\n| --------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `outFile` | `string` | `\"schema.json\"` | Sets the filename written inside `outDir`. Use it when you want a custom output name such as `my-schema.json` or `product.schema.json`.                                                                      |\n| `id`      | `string` | `\"\"`            | Sets the top-level `$id` of the generated JSON Schema document. Use it when your schema should have a canonical URI.                                                                                         |\n| `root`    | `string` | `\"\"`            | Sets the top-level `$ref` to a named definition inside `$defs`. Use it when you want one main entry point such as `Config` or `Product`. If the name does not exist, generation fails with a friendly error. |\n\nExample with all options:\n\n```vdl\nconst config = {\n  version 1\n  plugins [\n    {\n      src \"varavelio/vdl-plugin-json-schema@v0.1.0\"\n      schema \"./schema.vdl\"\n      outDir \"./gen\"\n      options {\n        outFile \"product.schema.json\"\n        id \"https://example.com/schemas/product.schema.json\"\n        root \"Product\"\n      }\n    }\n  ]\n}\n```\n\n## What You Get\n\n- A JSON Schema document using Draft 2020-12.\n- All top-level VDL types and enums emitted inside `$defs`.\n- Stable `$ref` links between named types, aliases, and enums.\n- Object `required` fields generated only for non-optional VDL fields.\n- Support for nested objects, arrays, multidimensional arrays, and maps.\n- Documentation and deprecation metadata carried into the generated schema.\n\n## Type Mapping\n\n| VDL                 | JSON Schema output                              |\n| ------------------- | ----------------------------------------------- |\n| `string`            | `\"type\": \"string\"`                              |\n| `int`               | `\"type\": \"integer\"`                             |\n| `float`             | `\"type\": \"number\"`                              |\n| `bool`              | `\"type\": \"boolean\"`                             |\n| `datetime`          | `\"type\": \"string\", \"format\": \"date-time\"`       |\n| `T[]`               | `\"type\": \"array\"` with `items`                  |\n| `map[T]`            | `\"type\": \"object\"` with `additionalProperties`  |\n| named type or alias | `$ref` to `#/$defs/...`                         |\n| enum                | `\"enum\": [...]` with the correct primitive type |\n\n## Root Behavior\n\n- If `root` is not set, the document contains reusable definitions in `$defs` and no top-level `$ref`.\n- If `root \"Config\"` is set, the document also includes `\"$ref\": \"#/$defs/Config\"`.\n- `root` can point to any generated top-level definition.\n- If the selected name does not exist, the plugin returns a clear error and, when possible, suggests a similar definition name.\n\n## Example\n\nGiven this `schema.vdl`:\n\n```vdl\n\"\"\" Status of an order. \"\"\"\nenum OrderStatus {\n  Pending = \"pending\"\n  Shipped = \"shipped\"\n}\n\ntype Product {\n  id string\n  status OrderStatus\n  releasedAt datetime\n  tags? string[]\n}\n```\n\nAnd this plugin configuration:\n\n```vdl\nconst config = {\n  version 1\n  plugins [\n    {\n      src \"varavelio/vdl-plugin-json-schema@v0.1.0\"\n      schema \"./schema.vdl\"\n      outDir \"./gen\"\n      options {\n        id \"https://example.com/schemas/product.schema.json\"\n        root \"Product\"\n      }\n    }\n  ]\n}\n```\n\nRunning `vdl generate` produces `./gen/product.schema.json` similar to:\n\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"https://example.com/schemas/product.schema.json\",\n  \"$ref\": \"#/$defs/Product\",\n  \"$defs\": {\n    \"OrderStatus\": {\n      \"type\": \"string\",\n      \"enum\": [\"pending\", \"shipped\"],\n      \"description\": \"Status of an order.\"\n    },\n    \"Product\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"id\": {\n          \"type\": \"string\"\n        },\n        \"releasedAt\": {\n          \"type\": \"string\",\n          \"format\": \"date-time\"\n        },\n        \"status\": {\n          \"$ref\": \"#/$defs/OrderStatus\"\n        },\n        \"tags\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"type\": \"string\"\n          }\n        }\n      },\n      \"required\": [\"id\", \"releasedAt\", \"status\"]\n    }\n  }\n}\n```\n\n## Documentation and Deprecation\n\n- VDL doc blocks are emitted as JSON Schema `description`.\n- `@deprecated` sets `\"deprecated\": true` on the generated schema fragment.\n- `@deprecated(\"message\")` also appends the deprecation reason to `description`.\n- If `@deprecated` has no explicit message, the plugin adds a default deprecation note.\n\n## License\n\nThis plugin is released under the MIT License. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaravelio%2Fvdl-plugin-json-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaravelio%2Fvdl-plugin-json-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaravelio%2Fvdl-plugin-json-schema/lists"}