home / skills / sammcj / agentic-coding / json-schema-lookup

json-schema-lookup skill

safe

This skill helps you discover and validate configuration schemas from schemastore.org to ensure correct structure and supported options.

npx playbooks add skill sammcj/agentic-coding --skill json-schema-lookup

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.4 KB

---
name: json-schema-lookup
description: >-
  Guidelines for querying schemastore.org. Use when you need to validate or discover
  options for config files relating to popular open source projects.
allowed-tools: WebFetch Bash(curl *) Bash(jq *) Bash(yq *) Bash(grep *) Bash(head *) Bash(less *)
---

# JSON Schema Lookup via SchemaStore

Query schemastore.org's catalog of public configuration file schemas to validate structure, discover options, and check allowed values.

## API

- **Catalog**: `https://www.schemastore.org/api/json/catalog.json`
  - Structure: `{ "schemas": [{ "name", "description", "fileMatch", "url", "versions"? }] }`
- **Individual schemas**: Fetch the `url` from the matching catalog entry

## Workflow

### 1. Find the schema

Search the catalog by name or filename pattern:

```bash
# Search by name (case-insensitive)
curl -s https://www.schemastore.org/api/json/catalog.json | jq '.schemas[] | select(.name | test("tsconfig"; "i")) | {name, url, fileMatch}'

# Search by filename match
curl -s https://www.schemastore.org/api/json/catalog.json | jq '.schemas[] | select(.fileMatch[]? | test("package\\.json")) | {name, url}'
```

Alternatively, use WebFetch on the catalog URL and ask for the relevant entry.

### 2. Fetch and inspect the schema

```bash
# List top-level properties
curl -s SCHEMA_URL | jq '.properties | keys'

# Inspect a specific field (type, enum values, description)
curl -s SCHEMA_URL | jq '.properties.FIELD_NAME'

# Check definitions/shared types (schemas use $ref to these)
curl -s SCHEMA_URL | jq '.definitions.DEF_NAME.properties'

# Get the full schema (warning - might be large!)
curl -s SCHEMA_URL | jq .
```

### 3. Common queries

```bash
# Find enum values for a field
curl -s SCHEMA_URL | jq '.properties.FIELD.enum'

# List nested properties (e.g. compilerOptions in tsconfig)
curl -s SCHEMA_URL | jq '.definitions.compilerOptionsDefinition.properties.compilerOptions.properties | keys'

# Find all required fields
curl -s SCHEMA_URL | jq '.required'
```

## Tips

- Some schemas use `allOf`/`anyOf` composition -- check those arrays for the full property set
- The `versions` field on catalog entries provides version-specific schema URLs when available
- Schema URLs vary: some point to `json.schemastore.org`, others to `raw.githubusercontent.com`
- For large schemas, query specific paths rather than dumping the entire document
- Cache the catalog response locally if making multiple lookups in one session

Overview

This skill provides practical guidelines for querying SchemaStore (schemastore.org) to find, fetch, and inspect public JSON schemas for popular open source configuration files. It helps you validate structure, discover allowed values, and locate versioned schema URLs for tools and frameworks. Use it to speed up config validation, editor tooling, and automated checks.

How this skill works

The skill shows how to search the SchemaStore catalog (catalog.json) by schema name or filename pattern, identify the matching catalog entry, and fetch the schema document at the entry's URL. It explains targeted queries against the schema JSON (properties, enums, definitions, required fields) and highlights composition patterns like allOf/anyOf. It also recommends efficient retrieval patterns (query specific paths, cache the catalog).

When to use it

Validating a config file against a known public schema (e.g., package.json, tsconfig.json).
Discovering allowed enum values or available configuration keys for an editor or linter.
Implementing automated CI checks that enforce config structure or required fields.
Building tooling that needs to adapt to versioned schemas for specific tools.
Inspecting nested or referenced definitions used across schema files.

Best practices

Search the catalog by name and by fileMatch patterns to reliably find the right schema.
Fetch only the schema paths you need (properties, definitions) to avoid downloading huge documents.
Check catalog entry versions for version-specific URLs when working with multiple releases.
Handle composition (allOf/anyOf/oneOf) by examining each item in those arrays for merged properties.
Cache the catalog.json locally within a session to minimize repeated network requests.

Example use cases

List top-level keys of a schema to generate editor autocompletion hints.
Extract enum values for a field to validate user input in a CLI or web form.
Find compilerOptions properties in a tsconfig schema when writing a transpiler integration.
Identify required fields before running a CI validation step on config files.
Resolve $ref definitions to produce a flattened view of nested schema types.

FAQ

How do I find a schema for a specific filename?

Search catalog.json for entries whose fileMatch array contains a pattern matching the filename, or filter by schema name with a case-insensitive match.

What if a schema uses $ref or composition?

Follow the referenced definition URLs or inspect the definitions and allOf/anyOf arrays to gather the full set of properties and types.