JSON Schema Manual

JSON Schema Manual

What it is: a draft 2020-12 schema over a field list someone already confirmed - validating structure, never inventing business rules.

Overview

Produces JSON Schema from a confirmed canonical field list, for validation, API contracts, import and export structures, form generation, and schema documentation.

JSON Schema validates structure. It does not compute, decide or imply. This is a helper: it defines no table of its own and renders whatever field list the active module already confirmed, so the property names here are the names that module uses in its CSV, SQL, spreadsheet and Notion mapping.

Layer: n/a. Fits: every stage. Table code: n/a - it renders the active module's table.

When to Use This Skill

• I need a JSON Schema
• validate this payload before it goes in
• make an API contract for this table
• document the shape of this import file
• generate a form from this schema
• turn the agreed fields into a schema

Also use it when a module has confirmed a field list and the user wants the contract for the system that will read it, rather than the table itself.

Do not use it to add validation the business has not asked for. A schema is a promise about what a payload may contain, and every restriction in it rejects real data.

How It Works

Follow the shared execution contract. The module-specific rules below define only domain fields, decisions, calculations, and safety constraints.

Step 1 - Identify intent

Read the request and pick the intent before asking anything.

• "I need a schema" -> a strict or permissive schema, per Step 5.
• "something rejected my payload" -> review or fix: only the rule that caused it.
• "which fields are required" -> advice: answer from the confirmed field list, and offer the schema rather than emitting one.

Build only what was requested. A fix does not become a rewrite, and advice does not become a file.

Step 2 - Ask only what is missing

Reuse everything already confirmed, including by the module that owns the field list: the property names and types, the select options, the date and currency fields, the calculated fields, the statuses and the IDs. Never ask again for information the user has already supplied.

Ask one short question per message, and only when the answer changes the schema:

Q: Should the schema reject unknown fields, or allow them?

Nothing else is worth a question. Requiredness, options and formats come from the confirmed field list, not from a new round of asking.

Step 3 - Hold the internal context

Hold the answers in this shape. It stays internal - it is not shown to the user unless they ask, and it never carries a value the user did not give.

module: json-schema-manual
intent: null            # set in Step 1, one of: schema, review, fix, advice
source_module: null     # the module whose field list this renders
draft: "https://json-schema.org/draft/2020-12/schema"
additional_properties: null   # false | true - asked once, then held
example_instances: false
confirmed_facts: []     # only what the user actually said
open_questions: []      # the unanswered ones, in the order worth asking

source_module is the one field this skill needs that a module skill does not have. If it is unknown, ask which table the contract is for, because a schema built from a guess rejects the real data.

Step 4 - Recommend the smallest workflow

Build an already requested artifact without asking again. For advice-only requests, give a short recommendation and offer the relevant artifact.

Recommended approach: one object schema, one property per confirmed field, no required entry the field list does not mark as required, and no enum the field list does not define. Strictness only where the contract is closed.

Why this one: a schema's damage is asymmetric. A property it omits passes data nobody reviewed; a property it marks required, or an enum it invents, rejects data that was perfectly valid. Confirm the closed rules and stay silent on the rest.

Workflow: Field list confirmed -> Properties typed -> Requiredness applied from the source -> (validated) -> Published as the contract

Step 5 - Build only on request

Once the user asks, emit the schema as data only. Keep prose outside machine-readable data; provide file links and material limitations separately. Property names come from the confirmed field list, identical to the CSV, SQL, spreadsheet and Notion names, in the same order. Never rename a property independently.

Default draft:

https://json-schema.org/draft/2020-12/schema

Type mapping

Required

A property goes in required only when the parent skill marks it required, or the user explicitly confirms it. Unknown requiredness means optional, and requiredness is never inferred from what a business obviously needs - a calculated value is never required when its source may legitimately be missing.

Select options

enum only for confirmed options:

{
  "Status": {
    "type": "string",
    "enum": ["Draft", "Filed", "Paid"]
  }
}

Never invent an enum value. Where options are a starting set rather than a confirmed taxonomy, leave the property a plain string and say the options are not yet fixed.

Additional properties

"additionalProperties": false only when the contract is meant to be strict:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "...",
  "type": "object",
  "properties": {},
  "required": []
}

If strictness is unknown and it matters, ask the one question in Step 2. Otherwise follow the parent skill's convention.