Schemas in the Wild — package.json, tsconfig, OpenAPI

You already use JSON Schema; you might not have noticed

package.json — the npm schema

Open package.json in VS Code. Hover any field. The autocomplete and inline docs come from https://json.schemastore.org/package.json, a community-maintained JSON Schema. Add "$schema": "https://json.schemastore.org/package.json" at the top of your package.json to make the binding explicit (some editors require it, most pick it up by filename alone).

tsconfig.json — TypeScript's contract

Same story: https://json.schemastore.org/tsconfig.json. Read it once and you'll understand every tsconfig field's purpose, default, and constraints. Better than the docs because it's the source of truth for the autocomplete.

OpenAPI — schemas describing API endpoints

OpenAPI 3.x uses JSON Schema (a slight dialect, but mostly compatible) inside components.schemas. Tools like Stoplight, Redoc, Swagger UI render those schemas as documentation pages, generate clients, and validate requests/responses at the gateway. Your API contract lives in JSON Schema; the rest is rendering.

The 'what does this field do' move: when faced with an unfamiliar config (a new linter, a new bundler, a new CI tool), find its schema on Schema Store. The schema's description, enum, and default annotations are usually clearer than the README.

Code

Opt your package.json into autocomplete·json

{
  "$schema": "https://json.schemastore.org/package.json",
  "name": "my-app",
  "version": "1.0.0",
  "description": "A small thing",
  "scripts": {
    "test": "vitest run"
  }
}

OpenAPI schemas (JSON Schema inside)·yaml

openapi: 3.1.0
info:
  title: User API
  version: 1.0.0
components:
  schemas:
    User:                    # ← This is JSON Schema
      type: object
      properties:
        id:    { type: integer }
        name:  { type: string  }
        email: { type: string, format: email }
      required: [id, name, email]
paths:
  /users/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Generate TypeScript types from a schema·bash

# json-schema-to-typescript: schema → .d.ts
npx json-schema-to-typescript user.schema.json > user.d.ts

# OpenAPI → TS client
npx openapi-typescript openapi.yaml -o api-types.ts

Exercise

Add "$schema": "https://json.schemastore.org/package.json" to a real package.json in one of your projects. Notice that VS Code autocomplete became sharper (or stayed the same — some editors infer by filename). Then open the schema URL in a browser and skim it. Find one package.json field you've never used and read what it does. Schema Store doubles as a learning tool.

Schemas in the Wild — package.json, tsconfig, OpenAPI

You already use JSON Schema; you might not have noticed

package.json — the npm schema

tsconfig.json — TypeScript's contract

OpenAPI — schemas describing API endpoints

Code

External links

Exercise

Progress

Comments 0