{"id":35427923,"url":"https://github.com/ioflux-org/studio-json-schema","last_synced_at":"2026-04-02T16:42:46.048Z","repository":{"id":296967148,"uuid":"994086929","full_name":"ioflux-org/studio-json-schema","owner":"ioflux-org","description":"A visual, interactive, graph-based tool to explore, debug, and understand complex JSON Schemas.","archived":false,"fork":false,"pushed_at":"2026-01-25T13:54:57.000Z","size":14577,"stargazers_count":15,"open_issues_count":9,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-26T06:10:58.563Z","etag":null,"topics":["json","json-schmea","jsonschema","studio","visualisation","visualizer"],"latest_commit_sha":null,"homepage":"https://studio.ioflux.org","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/ioflux-org.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":null,"dco":null,"cla":null}},"created_at":"2025-06-01T07:06:20.000Z","updated_at":"2026-01-25T13:54:14.000Z","dependencies_parsed_at":"2026-02-08T12:05:08.576Z","dependency_job_id":null,"html_url":"https://github.com/ioflux-org/studio-json-schema","commit_stats":null,"previous_names":["jagpreetrahi/visualize-json-schema","ioflux-org/studio-json-schema"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/ioflux-org/studio-json-schema","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioflux-org%2Fstudio-json-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioflux-org%2Fstudio-json-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioflux-org%2Fstudio-json-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioflux-org%2Fstudio-json-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ioflux-org","download_url":"https://codeload.github.com/ioflux-org/studio-json-schema/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ioflux-org%2Fstudio-json-schema/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29229419,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-08T12:03:03.049Z","status":"ssl_error","status_checked_at":"2026-02-08T12:02:56.077Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["json","json-schmea","jsonschema","studio","visualisation","visualizer"],"created_at":"2026-01-02T19:29:13.243Z","updated_at":"2026-04-02T16:42:46.029Z","avatar_url":"https://github.com/ioflux-org.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./public/logo-light.svg#gh-light-mode-only\" alt=\"JSON Schema Studio logo\"\u003e\n  \u003cimg src=\"./public/logo-dark.svg#gh-dark-mode-only\" alt=\"JSON Schema Studio logo\"\u003e\n\u003c/p\u003e\n\n# JSON Schema Studio\n\nA visual, interactive, graph-based tool to explore, debug, and understand complex JSON Schemas.\n\n**JSON Schema Studio** is a browser-based tool that converts JSON Schema into an interactive node graph. It helps developers understand deeply nested schemas, `$ref` chains, reusable `$defs`, and circular references\nwithout manually tracing large JSON Schema files.\n\n---\n\n## Table of Contents\n\n- [Why JSON Schema Studio?](#why-json-schema-studio)\n- [Features](#features)\n- [Demo](#demo)\n  - [Example JSON Schema](#example-json-schema)\n- [Understanding the Visualization](#understanding-the-visualization)\n  - [Node colors \u0026 schema types](#node-colors--schema-types)\n  - [Keywords](#keywords)\n  - [Edges](#edges)\n  - [reusable schemas (`$defs`)](#reusable-schemas-defs)\n  - [Boolean schemas](#boolean-schemas)\n  - [Controls](#controls)\n- [How It Works](#how-it-works)\n- [Current Limitations / Known Issues](#current-limitations--known-issues)\n- [Run locally](#run-locally)\n  - [Using Docker (recommended)](#using-docker-recommended)\n  - [Running directly (without Docker)](#running-directly-without-docker)\n- [Tech Stack](#tech-stack)\n- [Future Enhancements / Roadmap](#future-enhancements--roadmap)\n- [Contributing](#contributing)\n  - [Getting started](#getting-started)\n  - [Versioning Rules \u0026 Release Process](#versioning-rules--release-process)\n    - [How to create a changeset](#how-to-create-a-changeset)\n    - [When you do NOT need a changeset](#when-you-do-not-need-a-changeset)\n- [Additional Notes](#additional-notes)\n\n---\n\n## Why JSON Schema Studio?\n\nJSON Schemas become difficult to reason about as they grow:\n\n- Deeply nested objects\n- Heavy usage of [`$ref`](https://www.learnjsonschema.com/2020-12/core/ref)\n- Circular references\n- Unclear relationships between subschemas\n\n**JSON Schema Studio** converts schemas into an interactive graph so you can **see structure, references, and relationships** instantly, instead of mentally parsing large JSON Schema files.\n\n---\n\n## Features\n\n- Interactive graph-based visualization of JSON Schema\n- `$ref` resolution (local \u0026 external)\n- Circular reference handling\n- Clear node \u0026 edge representation for schema entities\n- Light \u0026 dark theme support\n- Runs fully in your browser -- all data stays on your device\n\n---\n\n## Demo\n\n### Example JSON Schema\n\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"https://example.com/schemas/user-profile\",\n  \"description\": \"A JSON Schema describing a person\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": {\n      \"type\": \"string\",\n      \"minLength\": 2,\n      \"maxLength\": 50\n    },\n    \"age\": {\n      \"type\": \"integer\",\n      \"minimum\": 0,\n      \"maximum\": 150\n    },\n    \"address\": {\n      \"$ref\": \"#/$defs/address\"\n    },\n    \"hobbies\": {\n      \"type\": \"array\",\n      \"minItems\": 0,\n      \"maxItems\": 5\n    },\n    \"maritalStatus\": {\n      \"oneOf\": [{ \"const\": \"single\" }, { \"const\": \"married\" }]\n    },\n    \"isEmployed\": {\n      \"type\": \"boolean\"\n    }\n  },\n  \"additionalProperties\": true,\n  \"$defs\": {\n    \"address\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"city\": {\n          \"type\": \"string\"\n        },\n        \"zip\": {\n          \"description\": \"six digit zip code\",\n          \"type\": \"number\"\n        },\n        \"additionalProperties\": false\n      },\n      \"required\": [\"city\", \"zip\"]\n    }\n  }\n}\n```\n\n![Visualization for the above JSON Schema](./public/example-visualization.png)\n_This diagram shows the structure of the \"Example JSON Schema\" above._\n\n---\n\n## Understanding the Visualization\n\n\u003e [!NOTE]\n\u003e The visualization is presented as a graph where **nodes** represent JSON Schemas or subschemas, and **edges** represent the relationships between them.\n\n### Node colors \u0026 schema types\n\n- Each schema/subschema that is rendered as a node is assigned a distinct color based on its `type`.\n- If a schema/subschema explicitly defines a `type`, the node's color directly reflects that type.\n- For schemas/subschemas without an explicit `type` keyword, the tool infers the type from related keywords. The node color is then assigned based on this inference.\n  - In most cases, inference is correct.\n  - If multiple instance types are defined (e.g., `type: [\"string\", \"number\"]`), there is currently no dedicated color. In such cases, the node color is determined based on **type inference**, following this priority order: `object \u003e array \u003e string \u003e number`.\n  - If inference fails entirely, a **soft gray** color is applied to the corresponding node as a fallback.\n- Refer to the image below for node color references:  \n  \u003cimg src=\"./public/node-colors.svg\" alt=\"JSON Schema Studio logo\"\u003e\n\n### Keywords\n\n- Keywords displayed inside a node represent how that schema defines the instance.\n- If a keyword's value is itself a subschema, a new node is created.\n\n### Edges\n\n- Each child node is connected to its parent via a directed edge.\n- Edges originate from the left side of the parent node, vertically aligned with the specific schema keyword they represent (for example: `properties`, `items`, `allOf`, etc.).\n- On hover, the corresponding edge is highlighted and an animated flow is rendered:\n  - the animation starts from the edge's source handle (keyword-aligned origin)\n    and runs toward the connected child node, visually indicating direction.\n- On click, the highlighted state is persisted:\n  - the animation remains active even after hover ends.\n- Multiple edges can be selected and highlighted simultaneously.\n\n⚠️ There is a known issue with precise source-handle positioning (the exact point from which an edge originates) (see _Current Limitations / Known Issues_).\n\n### Reusable schemas (`$defs`)\n\n- If a schema contains `$defs`, a special \"definitions\" container node is created.\n- This node:\n  - Does not represent a schema itself\n  - Groups all reusable subschemas\n  - Connects to the parent schema from the bottom\n- This design intentionally separates regular subschemas from **reusable definitions**.\n\n### Boolean schemas\n\n- Boolean schemas are visually distinct:\n  - `true` --\u003e green node\n  - `false` --\u003e red node\n- Unlike _object schema_ nodes, _boolean schema_ colors are applied to the **entire node**, not just the title.\n- Boolean nodes have more rounded borders to clearly differentiate them.\n\nDesign improvements are welcome :)\n\n### Controls\n\n- Zoom, fit-view, and other graph controls are available in the bottom-left corner of the visualization.\n\n---\n\n## How It Works\n\n- The input JSON Schema is parsed into an **AST** (Abstract Syntax Tree) using [Hyperjump JSON Schema](https://github.com/hyperjump-io/json-schema). This AST represents the full structure of the schema.  \n  _All `$ref` references, both local and external, are automatically resolved by Hyperjump, so the AST includes fully expanded schemas as part of its structure_\n- The resolved AST is transformed into graph **nodes** and **edges**, where each node represents a schema or subschema, and edges represent relationships between parent and child nodes.\n- These nodes and edges are rendered as an interactive graph using [React Flow](https://reactflow.dev), allowing users to explore and understand the schema visually.\n\n---\n\n## Current Limitations / Known Issues\n\n- Currently, it only supports visualization for the latest dialect (2020-12).\n- The **search** feature is visible in the UI but not yet implemented.\n- When editing a schema in real time, the node handles may appear misaligned.  \n  **Workaround**: Refresh the page after editing to restore correct handle positions.\n- If a `$defs` subschema references another `$defs` subschema defined later in the schema, the source/target handles will swap, and the title of the referencing node will be clipped.\n\nThese issues will be addressed as time permits. If you encounter any other problems or have suggestions, please consider opening an issue to start a discussion.\n\n---\n\n### Getting started\n\n- Fork the repository\n\n  ```bash\n  git clone https://github.com/ioflux-org/studio-json-schema.git\n  ```\n\n- Create a new branch\n\n  ```bash\n  git checkout -b feature/my-feature\n  ```\n\n- Make your changes\n- Create a Pull Request\n  - After making changes, don't forget to commit with the sign-off flag (-s)\n\n  ```bash\n  git commit -s -m \"commit message\"\n  ```\n\n  - Once all the changes have been commited, push the changes.\n\n  ```bash\n  git push origin \u003cbranch-name\u003e\n  ```\n\n## Run locally\n\nYou can run the application locally either directly or using Docker (recommended for consistent environment).\n\n### Using Docker (recommended)\n\n- Build the Docker image using the `Dockerfile` at the root of the repository:\n  ```bash\n  docker build --no-cache -t json-schema-studio -f ./Dockerfile .\n  ```\n- Run the Docker container:\n  ```bash\n  docker run -p 8080:80 json-schema-studio\n  ```\n- To run the container in detached mode, use:\n  ```\n  docker run -d -p 8080:80 json-schema-studio\n  ```\n- Access the application in your browser at http://localhost:8080.\n\n### Running directly (without Docker)\n\n- Install dependencies:\n  ```bash\n  npm install\n  ```\n- Start the development server:\n  ```\n  npm run dev\n  ```\n- Open your browser at the URL shown in the terminal (http://localhost:5173).\n\n\u003e [!WARNING]\n\u003e Running directly is fine for development, but using Docker ensures a consistent environment across machines.\n\n---\n\n## Tech Stack\n\n- React + Vite\n- [Hyperjump JSON Schema](https://github.com/hyperjump-io/json-schema) -- validation \u0026 AST generation\n- [React Flow](https://reactflow.dev/) -- graph visualization\n- [Monaco Editor](https://microsoft.github.io/monaco-editor/) -- in-browser schema editor\n- UI inspiration from [JSONCrack](https://github.com/AykutSarac/jsoncrack.com)\n\n---\n\n## Future Enhancements / Roadmap\n\nTo make this tool more accessible, intuitive, and developer-friendly, we are planning several future enhancements aimed at helping users understand and build complex JSON Schemas effortlessly.\n\n- [ ] Export the visualization as an image\n- [ ] Upload JSON Schema files directly for visualization\n- [ ] VS Code extension for in-editor JSON Schema visualization\n- [ ] Inline graph editing with bidirectional updates between the graph and the schema\n- [ ] No-code JSON Schema generator (longer-term goal)\n\nWe'd love to hear from you! If you have ideas, suggestions, or feedback, feel free to open an issue and help shape the future of this project.\n\n---\n\n## Contributing\n\nContributions are welcome and appreciated\n\nWays to contribute:\n\n- Report bugs or request features via Issues\n- Improve documentation\n- Fix bugs or implement new features\n- Suggest better visual or UX improvement\n\n### Versioning Rules \u0026 Release Process\n\nWe use [Changesets](https://github.com/changesets/changesets) to manage versioning, changelogs, and releases.\n\nWhen you make a change that affects the application (new features, bug fixes, UI updates), you must include a changeset.\n\n#### How to create a changeset\n\nRun the following command in your terminal:\n\n```bash\nnpx changeset\n```\n\nThe CLI will prompt you to select the package(s) to bump (select `json-schema-studio` if prompted).\n\nChoose the bump type according to Semantic Versioning (SemVer):\n\n- `major`: Breaking changes\n- `minor`: New features\n- `patch`: Bug fixes\n\nProvide a clear summary of your changes. This will be included in `CHANGELOG.md`.\n\nOnce completed, a new markdown file will be generated in the `.changeset` folder. Commit this file along with your code changes.\n\n#### When you do NOT need a changeset\n\nYou do not need to generate a changeset if your PR only touches:\n\n- `.github/**` (CI/CD workflows)\n- `*.md` files (Documentation)\n- Internal tests or tooling not affecting the shipped application\n\n### Enforcement\n\u003e\n\u003e [!IMPORTANT]\n\u003e Pull requests without a changeset file will be blocked by CI.\n\u003e\n\u003e This policy ensures all changes are properly versioned and that every integration remains clean, predictable, and traceable.\n\n---\n\n## Additional Notes\n\n\u003e [!TIP]\n\u003e The application supports both **light** and **dark** themes. For the best visual experience -- we recommend using the **dark theme**.\n\n\u003e [!IMPORTANT]\n\u003e All data processing occurs **locally on your device.** No data is sent to or processed on external servers.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioflux-org%2Fstudio-json-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fioflux-org%2Fstudio-json-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fioflux-org%2Fstudio-json-schema/lists"}