json-schema-manual – skill Lập trình cho agent AI

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?

Reuse confirmed requiredness, options and formats. If missing information materially changes the contract (including source, null semantics, numeric precision or intended validator), clarify it rather than guessing.

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

| Canonical type | JSON Schema |

|---|---|

| id | integer or string, matching the confirmed source |

| title | string |

| text | string |

| long_text | string |

| number | number |

| currency | number |

| percentage | number |

| date | string, format: date |

| datetime | string, format: date-time |

| checkbox | boolean |

| select | string |

| multi_select | array of string |

| url | string, format: uri |

| email | string, format: email |

| phone | string |

| relation | string or integer, matching the confirmed reference key |

| files | array or string, only when the source structure defines it |

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.

Null handling

Do not add null to a type automatically. Allow it only where the parent schema

explicitly distinguishes null from missing. For unknown or optional data, prefer omission

over invented null semantics - a validator that accepts null where the data model has no

such value is a rule nobody agreed to.

Examples and descriptions

No examples, no instance data, and no description beyond what the source field

definition supports. Examples only when the user asks for them, and then obviously fake.

A description that invents meaning becomes the spec, and the spec then rejects real data.

Calculated fields

A calculated output field is represented by its data type and nothing else. The schema

does not carry the calculation, and a consumer that reads the field gets the value the

producing system computed - never one this schema invents.

Before you hand it over

Property names exactly match the canonical fields?
Types aligned with the source?
Every `required` entry supported by the source?
Every `enum` confirmed?
No invented formats?
No fake examples?
No schema drift against the other artifacts?

Field Reference

This skill has no Field Reference of its own, and it must not grow one. The active

module's Field Reference is the single source: its property names here, its CSV columns,

its SQL columns and its Notion properties are the same field list, but a passing schema does not prove the consuming importer, SQL or Notion mapping can read the payload.

If the field list is not in front of you, read skills/<slug>/SKILL.md for the module in

play. If it is missing or ambiguous, ask which table the contract is for and stop.

See the [Input Modules](references/input-modules.md) reference for the full guidance.

Select Options

enum values are the confirmed taxonomy, never a starting set presented as final. Where

the business has not settled its options, the property stays a string and the mapping

notes that the options are open - a schema is a contract, and an unconfirmed list becomes

a rejection waiting for a real record.

Relations

A relation is a reference key: string or integer, matching whatever the source uses

as the key. The schema does not describe the target table, does not check that the target

exists, and cannot enforce database referential integrity. JSON Schema $ref refers to a schema, not a database record. Do not add a property for the target's

fields; that is a second schema, and the user has not asked for one.

Examples

Prompt

Give me a JSON Schema for the invoices table so 

… (nội dung đầy đủ có trong gói tải về)