Back to Details

json-views

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

JSON Views

JSON Views

1. About the product

1. 产品介绍

JSON Views is an open-source editor that presents JSON as editable tables, record pages, Kanban boards, and custom HTML layouts. People and agents work on the same JSON; views are saved presentations of that data, not separate copies.
Objects and arrays are navigable as table-like pages, including nested properties. The built-in Table tab browses structured data; Source shows the raw JSON. Named views give direct access to useful paths, columns, filters, sorting, and layouts. Users can edit both data and view settings through the UI.
Ordinary JSON works without annotations: the viewer infers field editors and useful views without changing the source. Optional 
$jsonviews
metadata makes schema and views explicit and portable with the file. Schema describes field types, editors, and validation independently of any view; it does not convert the underlying data types.
JSON Views 是一款开源编辑器，可将 JSON 呈现为可编辑的表格、记录页面、Kanban 看板和自定义 HTML 布局。人员与 Agent 处理同一份 JSON；视图是保存下来的数据呈现形式，而不是单独的副本。
对象和数组可像页面化表格一样浏览和导航，包括嵌套属性。内置的 Table 标签页用于浏览结构化数据；Source 显示原始 JSON。命名视图可直接访问有用的路径、列、筛选、排序和布局。用户可以通过 UI 同时编辑数据和视图设置。
普通 JSON 无需注释即可使用：查看器会在不改变源文件的情况下推断字段编辑器和有用的视图。可选的 
$jsonviews
元数据可随文件一起显式定义 Schema 和视图，并使其可移植。Schema 独立于任何视图描述字段类型、编辑器和验证规则；它不会转换底层数据类型。

2. Set up and use the viewer

2. 设置并使用查看器

The public website runs entirely in the browser. The local CLI connects the same viewer to files on disk. Use the interface that fits where the user's data should live.
公共网站完全在浏览器中运行。本地 CLI 可将同一查看器连接到磁盘上的文件。请选择与用户数据存放位置相匹配的界面。

Open the viewer

打开查看器

  • Website: open json-views.com and upload or paste JSON. Documents persist in this browser profile across reloads and restarts. Download a document for a copy outside the browser; edits do not overwrite imported files.
  • Local file: run the command below to connect the editor to a disk file. Accepted edits save back to that file. Add 
    --no-open
    to print the URL and open it in the desired browser yourself.
bash
npx @script-it/json-views <file.json>
  • 网站： 打开 json-views.com 并上传或粘贴 JSON。文档会跨页面重新加载和浏览器重启保留在此浏览器配置文件中。如需在浏览器之外保留副本，请下载文档；编辑操作不会覆盖导入的文件。
  • 本地文件： 运行以下命令，将编辑器连接到磁盘文件。接受的编辑会保存回该文件。添加 
    --no-open
    可打印 URL，然后自行在所需浏览器中打开。
bash
npx @script-it/json-views <file.json>

Work through the agent API

通过 Agent API 操作

In the page's JavaScript context, use 
window.jsonViews
(version 1), or discover the browser's registered WebMCP tools. 
jsonViews.help()
and 
json_views_help
return this guide plus its references, bundled for offline use. Discover the operations available in the current viewer before using them.
Prefix calls with 
jsonViews.
. 
id
accepts a stable document ID, unique filename, or relative folder path; prefer IDs. Document info includes 
id
, 
filename
, optional 
relativePath
, 
active
, 
storage
, and 
valid
.
CallResult
list({ includeDiagnosticCount: true })
Document info; options and diagnostic counts are optional.
get(id)
Parsed JSON; changing this object does not save it.
source(id)
Exact source, preserving formatting and numeric spelling.
diagnostics(id)
Document info plus validation diagnostics.
await create(filename, value)
Create and select a browser document.
await patch(id, operations)
Apply atomic RFC 6902 JSON Patch.
await setSource(id, source)
Replace complete source after syntax validation.
select(id)
Show a document; return its info.
link(id, viewName?)
Return a URL for the file and exact view name without navigating; omit the view for the file root. WebMCP: 
json_views_get_link
.
remove(id)
Remove from workspace/cache; returns nothing, leaves local files on disk.
Writes return document info plus diagnostics. For CSV, read/write exact text with 
source()
/
setSource()
; 
get()
/
patch()
require JSON.
Use 
jsonViews.link(id, "Board")
to direct the user to an exact named view in the current workspace. This navigational link is not a shared copy; use snapshot sharing for another browser. Keep local-file URLs private because they contain an access token.
在页面的 JavaScript 上下文中，使用 
window.jsonViews
（版本 1），或发现浏览器已注册的 WebMCP 工具。
jsonViews.help()
和 
json_views_help
返回本指南及其参考资料，并捆绑提供以便离线使用。使用前请先发现当前查看器中可用的操作。
调用时添加 
jsonViews.
前缀。
id
接受稳定的文档 ID、唯一文件名或相对文件夹路径；建议优先使用 ID。文档信息包括 
id
、
filename
、可选的 
relativePath
、
active
、
storage
和 
valid
。
调用结果
list({ includeDiagnosticCount: true })
文档信息；选项和诊断计数均为可选项。
get(id)
已解析的 JSON；修改此对象不会保存更改。
source(id)
精确的源内容，保留格式和数字拼写方式。
diagnostics(id)
文档信息及验证诊断。
await create(filename, value)
创建并选中一个浏览器文档。
await patch(id, operations)
应用原子化的 RFC 6902 JSON Patch。
await setSource(id, source)
语法验证后替换完整源内容。
select(id)
显示文档并返回其信息。
link(id, viewName?)
返回指向文件和精确视图名称的 URL，但不进行导航；省略视图名称时指向文件根目录。WebMCP：
json_views_get_link
。
remove(id)
从工作区/缓存中移除；不返回内容，磁盘上的本地文件会保留。
写入操作会返回文档信息和诊断信息。对于 CSV，使用 
source()
/
setSource()
精确读写文本；
get()
/
patch()
需要 JSON。
使用 
jsonViews.link(id, "Board")
可将用户直接导航到当前工作区中的指定命名视图。此导航链接不是共享副本；如需在另一个浏览器中访问，请使用快照分享。由于本地文件 URL 包含访问令牌，请务必保密。

Make and verify edits

进行并验证编辑

Use atomic RFC 6902 patches for targeted changes. Supported operations are 
add
, 
remove
, 
replace
, 
move
, 
copy
, and 
test
. These paths are JSON Pointers: 
/tasks/0/status
, 
/$jsonviews
, 
/tasks/-
to append, or 
""
for the root. Escape 
~
and 
/
in property names as 
~0
and 
~1
.
js
const result = await jsonViews.patch(id, [
  { op: "test", path: "/tasks/0/status", value: "Todo" },
  { op: "replace", path: "/tasks/0/status", value: "Doing" }
]);
Patches preserve unrelated source. Avoid whole-document rewrites that can lose numeric precision. Use 
test
to guard expected values; after a persistence conflict, reread the current document before retrying.
Inspect diagnostics returned by every write. 
valid
means syntax only: saved documents can still have schema/value errors, and invalid views may be excluded. Fix diagnostic causes, reinspect, and open each affected view to confirm its path and settings work. Invalid source or failed patches change nothing.
For storage timing, error response shapes, CSV operations, and link edge cases, consult viewer and authoring nuances.
对于定向更改，使用原子化的 RFC 6902 Patch。支持的操作包括 
add
、
remove
、
replace
、
move
、
copy
和 
test
。这些路径是 JSON Pointers，例如 
/tasks/0/status
、
/$jsonviews
、
/tasks/-
（用于追加），或 
""
（用于根节点）。属性名中的 
~
和 
/
应分别转义为 
~0
和 
~1
。
js
const result = await jsonViews.patch(id, [
  { op: "test", path: "/tasks/0/status", value: "Todo" },
  { op: "replace", path: "/tasks/0/status", value: "Doing" }
]);
Patch 会保留无关的源内容。避免重写整个文档，以免丢失数值精度。使用 
test
保护预期值；发生持久化冲突后，重试前应重新读取当前文档。
检查每次写入返回的诊断信息。
valid
仅表示语法有效：已保存的文档仍可能存在 Schema/值错误，无效视图也可能被排除。修复诊断原因，重新检查，并打开每个受影响的视图，以确认其路径和设置正常工作。无效源内容或失败的 Patch 不会产生任何更改。
有关存储时序、错误响应结构、CSV 操作和链接边界情况，请参阅查看器和创作细节。

3. Author JSON documents

3. 编写 JSON 文档

Document structure and paths

文档结构和路径

Keep ordinary data outside 
$jsonviews
. Output strict JSON and preserve unrelated values, unknown metadata fields, existing view IDs, and original JSON types. Do not stringify numbers, booleans, or arrays for display. Choose views that expose the parts of the data the user needs to work with.
$jsonviews: { "version": 1, "schema": {...}, "views": [...] }
sits beside data on an object root. Schema defines field editors and validation; views present the same data in different ways. This schema is a descriptor map, not JSON Schema.
Explicit 
$jsonviews
metadata replaces inference; include every field and view you need. Wrapping an existing array root under 
data
changes its paths: confirm that conversion with the user.
Metadata paths support 
$
, 
.property
, 
['quoted key']
, 
[0]
, and 
[*]
(array/dictionary members), without recursive descent or filter expressions. View roots are concrete (
$.tasks
); collection field paths add 
[*]
and a field (
$.tasks[*].owner.email
). These differ from patch pointers.
将普通数据放在 
$jsonviews
之外。输出严格 JSON，并保留无关值、未知元数据字段、现有视图 ID 和原始 JSON 类型。不要为了显示而将数字、布尔值或数组转换为字符串。选择能够展示用户需要处理的数据部分的视图。
$jsonviews: { "version": 1, "schema": {...}, "views": [...] }
位于对象根节点中，与数据并列。Schema 定义字段编辑器和验证规则；视图则以不同方式呈现同一份数据。此 Schema 是描述符映射，而不是 JSON Schema。
显式的 
$jsonviews
元数据会替代推断机制；请包含所需的每个字段和视图。将现有数组根节点包装到 
data
下会改变其路径：转换前应与用户确认。
元数据路径支持 
$
、
.property
、
['quoted key']
、
[0]
和 
[*]
（数组/字典成员），不支持递归下降或筛选表达式。视图根路径必须是具体路径（
$.tasks
）；集合字段路径会添加 
[*]
和一个字段（
$.tasks[*].owner.email
）。这些路径不同于 Patch 指针。

Field schema

字段 Schema

Every descriptor requires 
type
; common properties are 
title
, 
description
, 
required
. Optional fields allow null/missing values.
TypeValueProperties
text
string
multiline
, 
placeholder
, 
pattern
number
finite number
minimum
, 
maximum
, 
step
checkbox
boolean—
select
/ 
multi-select
string / string array
options
, 
optionColors
date
date string
minimum
, 
maximum
, 
defaultIncludeTime
, 
placeholder
url
/ 
email
HTTP(S) URL / email string—
markdown
string rendered as Markdown with supported HTML fragments; edits preserve the source
placeholder
, 
pattern
html
complete HTML page or styled fragment rendered in an isolated preview; edits preserve the source
placeholder
, 
pattern
Choice options are suggestions, accepting new strings. Colors: 
gray
, 
blue
, 
green
, 
yellow
, 
orange
, 
red
, 
purple
, 
pink
. Dates: 
YYYY-MM-DD
, RFC 3339 with offset, or floating 
YYYY-MM-DDTHH:mm:ss
(seconds required in timestamps); no empty strings, locale dates, or numeric timestamps. Patterns use RE2; 
^…$
matches the whole string.
每个描述符都必须包含 
type
；常用属性包括 
title
、
description
和 
required
。可选字段允许使用 null 或缺失值。
类型值属性
text
字符串
multiline
、
placeholder
、
pattern
number
有限数值
minimum
、
maximum
、
step
checkbox
布尔值—
select
/ 
multi-select
字符串/字符串数组
options
、
optionColors
date
日期字符串
minimum
、
maximum
、
defaultIncludeTime
、
placeholder
url
/ 
email
HTTP(S) URL/电子邮件字符串—
markdown
使用支持的 HTML 片段渲染为 Markdown 的字符串；编辑会保留源内容
placeholder
、
pattern
html
在隔离预览中渲染的完整 HTML 页面或带样式片段；编辑会保留源内容
placeholder
、
pattern
选项仅作为建议，并接受新字符串。颜色包括 
gray
、
blue
、
green
、
yellow
、
orange
、
red
、
purple
和 
pink
。日期格式包括 
YYYY-MM-DD
、带偏移量的 RFC 3339，或浮动的 
YYYY-MM-DDTHH:mm:ss
（时间戳中必须包含秒）；不支持空字符串、区域格式日期或数字时间戳。Pattern 使用 RE2；
^…$
会匹配整个字符串。

Named views

命名视图

Required: 
name
, concrete 
path
. Use stable 
id
values; omitted IDs are generated. Table and Source are built-in tabs. Table browses the document structure; Source shows the raw JSON. Their icons are a table and 
{ }
, respectively. Collections are arrays/dictionaries of records, including empty arrays/objects.
SettingMeaning
display
Omit for automatic layout: a record page for one record, a table for record collections; 
"kanban"
for board; 
"html"
for a custom HTML/CSS layout. Primitive arrays/scalars use their natural layout.
html
/ 
css
HTML views only: required non-empty HTML template and optional CSS string.
columns
Ordered 
{ "label": "Task", "path": "$.tasks[*].title" }
entries; omitted/empty means infer.
groupBy
Existing scalar field path; required for Kanban.
groupOrder
Array of scalar lane values defining Kanban column order.
orderPath
Existing finite numeric field on every record, distinct from 
groupBy
; persists Kanban ordering.
filter
{ "match": "all", "rules": [{ "path": "$.tasks[*].status", "operator": "neq", "value": "Done" }] }
; match also accepts 
"any"
.
sort
Ordered 
{ "path": "$.tasks[*].due", "direction": "asc" }
entries; direction also accepts 
"desc"
.
Columns, grouping, ordering, filters, and sorting use collection field paths and require collections. Filters support type-specific subsets of 
eq
, 
neq
, 
in
, 
notIn
, 
gt
, 
gte
, 
lt
, 
lte
, 
contains
, 
notContains
, 
isEmpty
, 
isNotEmpty
. Membership takes array values; presence omits 
value
. Dates support equality, ordering, presence; date-only comparisons use the written calendar day. Diagnostics supply allowed operators.
Choose the first column deliberately: put the field that best identifies each record (for example, task name or customer name) first in 
columns
. It supplies the table's record link, Kanban card heading, and heading when that record is opened. Reordering or hiding it changes the record label. Without configured columns, the viewer infers a label such as 
name
or 
title
; standalone records also infer their headings. Schema 
title
labels a field and does not select record identity.
必需属性：
name
、具体的 
path
。使用稳定的 
id
值；省略 ID 时会自动生成。Table 和 Source 是内置标签页。Table 用于浏览文档结构；Source 显示原始 JSON。它们的图标分别是表格和 
{ }
。集合是由记录组成的数组/字典，包括空数组和空对象。
设置含义
display
省略时自动选择布局：单条记录使用记录页面，记录集合使用表格；
"kanban"
表示看板，
"html"
表示自定义 HTML/CSS 布局。基元数组/标量使用其自然布局。
html
/ 
css
仅用于 HTML 视图：必须提供非空 HTML 模板，CSS 字符串为可选项。
columns
按顺序排列的 
{ "label": "Task", "path": "$.tasks[*].title" }
条目；省略或留空表示自动推断。
groupBy
已存在的标量字段路径；Kanban 视图必须提供此属性。
groupOrder
定义 Kanban 列顺序的标量泳道值数组。
orderPath
每条记录中都存在的有限数值字段，必须与 
groupBy
不同；用于持久化 Kanban 排序。
filter
{ "match": "all", "rules": [{ "path": "$.tasks[*].status", "operator": "neq", "value": "Done" }] }
；
match
也可设为 
"any"
。
sort
按顺序排列的 
{ "path": "$.tasks[*].due", "direction": "asc" }
条目；
direction
也可设为 
"desc"
。
列、分组、排序、筛选和过滤使用集合字段路径，并要求目标是集合。筛选器支持按类型限定的操作符子集：
eq
、
neq
、
in
、
notIn
、
gt
、
gte
、
lt
、
lte
、
contains
、
notContains
、
isEmpty
、
isNotEmpty
。成员关系操作符接受数组值；存在性操作符省略 
value
。日期支持相等、排序和存在性比较；仅日期的比较使用所填写的日历日期。诊断信息会提供允许使用的操作符。
请谨慎选择第一列：把最能标识每条记录的字段（例如任务名称或客户名称）放在 
columns
的首位。它会用作表格中的记录链接、Kanban 卡片标题，以及打开该记录时显示的标题。重新排序或隐藏该列会改变记录标签。未配置 
columns
时，查看器会推断 
name
或 
title
等标签；独立记录也会推断其标题。Schema 的 
title
用于标注字段，不用于选择记录标识。

Example

示例

json
{
  "$jsonviews": {
    "version": 1,
    "schema": {
      "$.tasks[*].title": { "type": "text", "required": true },
      "$.tasks[*].status": { "type": "select", "options": ["Todo", "Doing", "Done"] },
      "$.tasks[*].due": { "type": "date" }
    },
    "views": [
      {
        "id": "open-tasks", "name": "Open tasks", "path": "$.tasks",
        "columns": [
          { "label": "Task", "path": "$.tasks[*].title" },
          { "label": "Status", "path": "$.tasks[*].status" },
          { "label": "Due", "path": "$.tasks[*].due" }
        ],
        "filter": { "match": "all", "rules": [{ "path": "$.tasks[*].status", "operator": "neq", "value": "Done" }] },
        "sort": [{ "path": "$.tasks[*].due", "direction": "asc" }]
      },
      {
        "id": "task-board", "name": "Board", "path": "$.tasks",
        "display": "kanban", "groupBy": "$.tasks[*].status",
        "columns": [{ "label": "Task", "path": "$.tasks[*].title" }]
      },
      { "id": "first-task", "name": "First task", "path": "$.tasks[0]" },
      {
        "id": "task-layout", "name": "Task layout", "path": "$.tasks", "display": "html",
        "html": "<jv-repeat source=\"$.tasks\" as=\"task\"><h2><jv-field bind=\"task.title\"></jv-field></h2><p><jv-value bind=\"task.status\"></jv-value></p></jv-repeat>",
        "css": "h2 { font: 24px Georgia, serif; }"
      }
    ]
  },
  "tasks": [
    { "title": "Draft the guide", "status": "Doing", "due": "2026-09-15" },
    { "title": "Review the example", "status": "Todo", "due": "2026-09-16" }
  ]
}
For HTML bindings, restrictions, and interaction details, read HTML views.
json
{
  "$jsonviews": {
    "version": 1,
    "schema": {
      "$.tasks[*].title": { "type": "text", "required": true },
      "$.tasks[*].status": { "type": "select", "options": ["Todo", "Doing", "Done"] },
      "$.tasks[*].due": { "type": "date" }
    },
    "views": [
      {
        "id": "open-tasks", "name": "Open tasks", "path": "$.tasks",
        "columns": [
          { "label": "Task", "path": "$.tasks[*].title" },
          { "label": "Status", "path": "$.tasks[*].status" },
          { "label": "Due", "path": "$.tasks[*].due" }
        ],
        "filter": { "match": "all", "rules": [{ "path": "$.tasks[*].status", "operator": "neq", "value": "Done" }] },
        "sort": [{ "path": "$.tasks[*].due", "direction": "asc" }]
      },
      {
        "id": "task-board", "name": "Board", "path": "$.tasks",
        "display": "kanban", "groupBy": "$.tasks[*].status",
        "columns": [{ "label": "Task", "path": "$.tasks[*].title" }]
      },
      { "id": "first-task", "name": "First task", "path": "$.tasks[0]" },
      {
        "id": "task-layout", "name": "Task layout", "path": "$.tasks", "display": "html",
        "html": "<jv-repeat source=\"$.tasks\" as=\"task\"><h2><jv-field bind=\"task.title\"></jv-field></h2><p><jv-value bind=\"task.status\"></jv-value></p></jv-repeat>",
        "css": "h2 { font: 24px Georgia, serif; }"
      }
    ]
  },
  "tasks": [
    { "title": "Draft the guide", "status": "Doing", "due": "2026-09-15" },
    { "title": "Review the example", "status": "Todo", "due": "2026-09-16" }
  ]
}
有关 HTML 绑定、限制和交互详情，请阅读 HTML 视图。