JSON Schema — 18 Operations for AI Agents
JSON Schema is the validation contract behind APIs and configs — what's required, what's allowed, what breaks clients. act101 navigates definitions and references structurally, so agents follow a `$ref` chain instead of reconstructing it mentally.
This page is the canonical reference an AI coding agent uses to refactor, query, and analyze JSON Schema code through the act MCP server. 18 operations available: 0 refactor, 18 query, 0 analysis. Each operation is callable from Claude Code, Cursor, Codex, OpenCode, or any MCP-compatible agent host. Click any operation for a stable anchor link suitable for citation.
18Query
Worked JSON Schema examples
act101 walks a JSON Schema document more deeply than plain JSON: every properties entry, every $defs entry, and every array such as required or enum surfaces in the skeleton as its own module declaration, not just the top-level object keys. symbols lists every key in the document as a field, including the schema's own vocabulary — type, pattern, minimum, default — alongside the field names they constrain. The unit of structure in this grammar is still the object key, but because a schema nests a validation keyword under every property it constrains, the declaration count runs higher than an equivalent plain-JSON document of the same size. Each example below is the verbatim output of the command shown, run against the file shown. Query outputs are pretty-printed with the timing block omitted.
Read every property and definition as a skeleton
timesheet.jsonschema constrains a payroll TimesheetEntry: four properties under properties, a required array, and one reusable type, PayCode, under $defs.
$ act query skeleton timesheet.jsonschemaBefore
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "TimesheetEntry",
"type": "object",
"properties": {
"employee_id": { "type": "string", "pattern": "^E[0-9]{5}$" },
"pay_period": { "type": "string", "format": "date" },
"hours_worked": { "type": "number", "minimum": 0, "maximum": 80 },
"overtime_rate": { "type": "number", "default": 1.5 }
},
"required": ["employee_id", "pay_period", "hours_worked"],
"$defs": {
"PayCode": {
"type": "string",
"enum": ["REG", "OT", "PTO", "HOL"]
}
}
}Output
{
"type": "Skeleton",
"declarations": [
{
"kind": "module",
"name": "properties",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 5,
"column": 17,
"byte_offset": 128
},
"end": {
"file": "timesheet.jsonschema",
"line": 10,
"column": 4,
"byte_offset": 387
}
},
"name_range": {
"start": {
"file": "timesheet.jsonschema",
"line": 5,
"column": 4,
"byte_offset": 115
},
"end": {
"file": "timesheet.jsonschema",
"line": 5,
"column": 14,
"byte_offset": 125
}
}
},
{
"kind": "module",
"name": "employee_id",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 6,
"column": 20,
"byte_offset": 149
},
"end": {
"file": "timesheet.jsonschema",
"line": 6,
"column": 66,
"byte_offset": 195
}
},
"name_range": {
"start": {
"file": "timesheet.jsonschema",
"line": 6,
"column": 6,
"byte_offset": 135
},
"end": {
"file": "timesheet.jsonschema",
"line": 6,
"column": 17,
"byte_offset": 146
}
}
},
{
"kind": "module",
"name": "pay_period",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 7,
"column": 19,
"byte_offset": 215
},
"end": {
"file": "timesheet.jsonschema",
"line": 7,
"column": 57,
"byte_offset": 253
}
},
"name_range": {
"start": {
"file": "timesheet.jsonschema",
"line": 7,
"column": 6,
"byte_offset": 202
},
"end": {
"file": "timesheet.jsonschema",
"line": 7,
"column": 16,
"byte_offset": 212
}
}
},
{
"kind": "module",
"name": "hours_worked",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 8,
"column": 21,
"byte_offset": 275
},
"end": {
"file": "timesheet.jsonschema",
"line": 8,
"column": 70,
"byte_offset": 324
}
},
"name_range": {
"start": {
"file": "timesheet.jsonschema",
"line": 8,
"column": 6,
"byte_offset": 260
},
"end": {
"file": "timesheet.jsonschema",
"line": 8,
"column": 18,
"byte_offset": 272
}
}
},
{
"kind": "module",
"name": "overtime_rate",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 9,
"column": 22,
"byte_offset": 347
},
"end": {
"file": "timesheet.jsonschema",
"line": 9,
"column": 58,
"byte_offset": 383
}
},
"name_range": {
"start": {
"file": "timesheet.jsonschema",
"line": 9,
"column": 6,
"byte_offset": 331
},
"end": {
"file": "timesheet.jsonschema",
"line": 9,
"column": 19,
"byte_offset": 344
}
}
},
{
"kind": "module",
"name": "required",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 11,
"column": 15,
"byte_offset": 403
},
"end": {
"file": "timesheet.jsonschema",
"line": 11,
"column": 60,
"byte_offset": 448
}
},
"name_range": {
"start": {
"file": "timesheet.jsonschema",
"line": 11,
"column": 4,
"byte_offset": 392
},
"end": {
"file": "timesheet.jsonschema",
"line": 11,
"column": 12,
"byte_offset": 400
}
}
},
{
"kind": "module",
"name": "$defs",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 12,
"column": 12,
"byte_offset": 461
},
"end": {
"file": "timesheet.jsonschema",
"line": 17,
"column": 4,
"byte_offset": 555
}
},
"name_range": {
"start": {
"file": "timesheet.jsonschema",
"line": 12,
"column": 4,
"byte_offset": 453
},
"end": {
"file": "timesheet.jsonschema",
"line": 12,
"column": 9,
"byte_offset": 458
}
}
},
{
"kind": "module",
"name": "PayCode",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 13,
"column": 16,
"byte_offset": 478
},
"end": {
"file": "timesheet.jsonschema",
"line": 16,
"column": 6,
"byte_offset": 551
}
},
"name_range": {
"start": {
"file": "timesheet.jsonschema",
"line": 13,
"column": 6,
"byte_offset": 468
},
"end": {
"file": "timesheet.jsonschema",
"line": 13,
"column": 13,
"byte_offset": 475
}
}
},
{
"kind": "module",
"name": "enum",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 15,
"column": 15,
"byte_offset": 518
},
"end": {
"file": "timesheet.jsonschema",
"line": 15,
"column": 42,
"byte_offset": 545
}
},
"name_range": {
"start": {
"file": "timesheet.jsonschema",
"line": 15,
"column": 8,
"byte_offset": 511
},
"end": {
"file": "timesheet.jsonschema",
"line": 15,
"column": 12,
"byte_offset": 515
}
}
}
]
}The skeleton reports nine declarations: properties itself, its four fields (employee_id, pay_period, hours_worked, overtime_rate), the required array, $defs, PayCode, and PayCode's own enum array — each nested object or array gets its own module entry.
List every schema key and keyword as symbols
PayCode, nested inside $defs, restricts its value to one of four pay codes via enum.
$ act query symbols timesheet.jsonschemaBefore
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "TimesheetEntry",
"type": "object",
"properties": {
"employee_id": { "type": "string", "pattern": "^E[0-9]{5}$" },
"pay_period": { "type": "string", "format": "date" },
"hours_worked": { "type": "number", "minimum": 0, "maximum": 80 },
"overtime_rate": { "type": "number", "default": 1.5 }
},
"required": ["employee_id", "pay_period", "hours_worked"],
"$defs": {
"PayCode": {
"type": "string",
"enum": ["REG", "OT", "PTO", "HOL"]
}
}
}Output
{
"type": "Symbols",
"symbols": [
{
"name": "\"$schema\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 2,
"column": 3,
"byte_offset": 4
},
"end": {
"file": "timesheet.jsonschema",
"line": 2,
"column": 12,
"byte_offset": 13
}
},
"visibility": "unknown"
},
{
"name": "\"title\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 3,
"column": 3,
"byte_offset": 65
},
"end": {
"file": "timesheet.jsonschema",
"line": 3,
"column": 10,
"byte_offset": 72
}
},
"visibility": "unknown"
},
{
"name": "\"type\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 4,
"column": 3,
"byte_offset": 94
},
"end": {
"file": "timesheet.jsonschema",
"line": 4,
"column": 9,
"byte_offset": 100
}
},
"visibility": "unknown"
},
{
"name": "\"properties\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 5,
"column": 3,
"byte_offset": 114
},
"end": {
"file": "timesheet.jsonschema",
"line": 5,
"column": 15,
"byte_offset": 126
}
},
"visibility": "unknown"
},
{
"name": "\"employee_id\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 6,
"column": 5,
"byte_offset": 134
},
"end": {
"file": "timesheet.jsonschema",
"line": 6,
"column": 18,
"byte_offset": 147
}
},
"visibility": "unknown"
},
{
"name": "\"type\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 6,
"column": 22,
"byte_offset": 151
},
"end": {
"file": "timesheet.jsonschema",
"line": 6,
"column": 28,
"byte_offset": 157
}
},
"visibility": "unknown"
},
{
"name": "\"pattern\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 6,
"column": 40,
"byte_offset": 169
},
"end": {
"file": "timesheet.jsonschema",
"line": 6,
"column": 49,
"byte_offset": 178
}
},
"visibility": "unknown"
},
{
"name": "\"pay_period\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 7,
"column": 5,
"byte_offset": 201
},
"end": {
"file": "timesheet.jsonschema",
"line": 7,
"column": 17,
"byte_offset": 213
}
},
"visibility": "unknown"
},
{
"name": "\"type\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 7,
"column": 21,
"byte_offset": 217
},
"end": {
"file": "timesheet.jsonschema",
"line": 7,
"column": 27,
"byte_offset": 223
}
},
"visibility": "unknown"
},
{
"name": "\"format\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 7,
"column": 39,
"byte_offset": 235
},
"end": {
"file": "timesheet.jsonschema",
"line": 7,
"column": 47,
"byte_offset": 243
}
},
"visibility": "unknown"
},
{
"name": "\"hours_worked\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 8,
"column": 5,
"byte_offset": 259
},
"end": {
"file": "timesheet.jsonschema",
"line": 8,
"column": 19,
"byte_offset": 273
}
},
"visibility": "unknown"
},
{
"name": "\"type\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 8,
"column": 23,
"byte_offset": 277
},
"end": {
"file": "timesheet.jsonschema",
"line": 8,
"column": 29,
"byte_offset": 283
}
},
"visibility": "unknown"
},
{
"name": "\"minimum\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 8,
"column": 41,
"byte_offset": 295
},
"end": {
"file": "timesheet.jsonschema",
"line": 8,
"column": 50,
"byte_offset": 304
}
},
"visibility": "unknown"
},
{
"name": "\"maximum\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 8,
"column": 55,
"byte_offset": 309
},
"end": {
"file": "timesheet.jsonschema",
"line": 8,
"column": 64,
"byte_offset": 318
}
},
"visibility": "unknown"
},
{
"name": "\"overtime_rate\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 9,
"column": 5,
"byte_offset": 330
},
"end": {
"file": "timesheet.jsonschema",
"line": 9,
"column": 20,
"byte_offset": 345
}
},
"visibility": "unknown"
},
{
"name": "\"type\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 9,
"column": 24,
"byte_offset": 349
},
"end": {
"file": "timesheet.jsonschema",
"line": 9,
"column": 30,
"byte_offset": 355
}
},
"visibility": "unknown"
},
{
"name": "\"default\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 9,
"column": 42,
"byte_offset": 367
},
"end": {
"file": "timesheet.jsonschema",
"line": 9,
"column": 51,
"byte_offset": 376
}
},
"visibility": "unknown"
},
{
"name": "\"required\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 11,
"column": 3,
"byte_offset": 391
},
"end": {
"file": "timesheet.jsonschema",
"line": 11,
"column": 13,
"byte_offset": 401
}
},
"visibility": "unknown"
},
{
"name": "\"$defs\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 12,
"column": 3,
"byte_offset": 452
},
"end": {
"file": "timesheet.jsonschema",
"line": 12,
"column": 10,
"byte_offset": 459
}
},
"visibility": "unknown"
},
{
"name": "\"PayCode\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 13,
"column": 5,
"byte_offset": 467
},
"end": {
"file": "timesheet.jsonschema",
"line": 13,
"column": 14,
"byte_offset": 476
}
},
"visibility": "unknown"
},
{
"name": "\"type\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 14,
"column": 7,
"byte_offset": 486
},
"end": {
"file": "timesheet.jsonschema",
"line": 14,
"column": 13,
"byte_offset": 492
}
},
"visibility": "unknown"
},
{
"name": "\"enum\"",
"kind": "field",
"range": {
"start": {
"file": "timesheet.jsonschema",
"line": 15,
"column": 7,
"byte_offset": 510
},
"end": {
"file": "timesheet.jsonschema",
"line": 15,
"column": 13,
"byte_offset": 516
}
},
"visibility": "unknown"
}
]
}symbols lists all 22 keys, including the repeated type keyword that appears once per constrained property and again inside PayCode, each reported as a field.
Query
18 query tools, the same on every supported language. Descriptions live in the shared reference: /docs/query-tools.
callers control_flow data_flow definition diagnostics effect_closure effect_summary fix_auto get_type graph import_organize interface mutations references repo_outline skeleton symbols symbols_batch