JSON Schema

Vad det är

JSON Schema är ett språk för att beskriva hur ett stycke JSON ska se ut, och det är självt skrivet i JSON. En beskrivning i språket, ett schema, ställer upp reglerna: det här värdet är ett objekt, det ska ha de här egenskaperna, den här är ett heltal på minst ett, den andra en textsträng på högst 200 tecken. Ett program som kallas validator tar ett schema och en instans, alltså de data som ska kontrolleras, och svarar på om instansen följer schemat och, om inte, var och varför. Projektet skriver namnet med stort S, JSON Schema, medan ett enskilt dokument skrivet i språket bara kallas ett schema, med litet s, på svenska lika väl som på engelska.

Specifikationen underhålls av JSON Schema-projektet på json-schema.org. Den gällande versionen är 2020-12 och den förra 2019-09; tidigare versioner var numrerade utkast, som draft-04 och draft-07, och äldre verktyg och artiklar kallar dem fortfarande vid de namnen. Texten består av två delar. Kärndokumentet definierar hur ett schema behandlas, hur ett schema hänvisar till ett annat och medietypen application/schema+json, och ett annat dokument, om validering, definierar de nyckelord som kontrollerar värden. De gällande dokumenten för 2020-12 är båda daterade den 16 juni 2022.

Varje nyckelord lägger till ett villkor. type anger en av sex primitiva typer, null, boolean, object, array, number eller string, eller integer, som matchar varje tal vars decimaldel är noll. För tal finns minimum, maximum och multipleOf; för textsträngar minLength, maxLength och pattern, ett reguljärt uttryck; för arrayer minItems, maxItems och uniqueItems; för objekt properties, required och additionalProperties. Nyckelord som allOf, anyOf, oneOf och not kombinerar scheman, och $ref pekar på ett schema som är definierat någon annanstans, ofta under $defs i samma dokument, så att en form som skrivs en gång kan användas på många ställen. Allt som ett schema inte nämner är tillåtet. Det tomma schemat, {}, godtar varje instans.

Ett schema kan också ange vilken version av språket det är skrivet i. Nyckelordet $schema innehåller adressen till ett metaschema, ett schema som beskriver giltiga scheman i den versionen, och specifikationssidan påpekar att metaschemat validerar sig självt. För 2020-12 är adressen https://json-schema.org/draft/2020-12/schema.

Varför det spelar roll

JSON säger ingenting om betydelse. Varje välformat dokument går att parsa, oavsett om programmet som läser det kan använda det till något. Utan en nedskriven beskrivning har varje program som läser ett dokument sin egen uppfattning om vad som är giltigt, utspridd i villkor i koden, och uppfattningarna glider isär tills en begäran misslyckas i produktion. Ett schema samlar reglerna på ett ställe i en form som både människor och program kan läsa, och det kan sparas, versioneras, granskas och publiceras som vilken annan fil som helst.

Specifikationen beskriver sitt syfte brett: JSON Schema är tänkt för validering, dokumentation, navigering via hyperlänkar och styrning av interaktionen med JSON-data, och valideringsvokabulären ska också ge användargränssnitt som arbetar med datan ledtrådar om den. I praktiken betyder det att en enda beskrivning kan avvisa felaktiga indata i kanten av en tjänst, dokumentera ett API, styra fälten på en sida där folk fyller i uppgifter och kontrollera att den JSON som en språkmodell returnerar har de fält som nästa steg väntar sig.

Det har också blivit den gemensamma grund som andra specifikationer bygger på. OpenAPI 3.1 definierar sitt Schema Object som en övermängd av JSON Schema 2020-12, så innehållet i begäranden och svar i en API-beskrivning beskrivs i JSON Schema med några få tillägg. MCP, protokollet som AI-agenter hittar och anropar verktyg genom, beskriver varje verktygs parametrar med ett inputSchema, som är ett JSON Schema, och kan beskriva resultatet med ett outputSchema, som klienter bör validera strukturerade resultat mot. En beskrivning som skrivs en gång kan alltså betjäna en validator, ett API-dokument och en agent, och de tre kan inte bli oense.

Så ser det ut i praktiken

Schemat nedan beskriver indata till ett verktyg som bokar ett leveransfönster. Det anger versionen det är skrivet i, räknar upp fyra egenskaper med deras regler, säger vilka tre som måste finnas med och avvisar varje egenskap som det inte räknar upp:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/tools/book-slot.json",
  "title": "Boka ett leveransfönster",
  "type": "object",
  "properties": {
    "order": { "type": "string", "pattern": "^[0-9]{4,8}$" },
    "date": { "type": "string", "format": "date" },
    "pallets": { "type": "integer", "minimum": 1, "maximum": 30 },
    "note": { "type": ["string", "null"], "maxLength": 200 }
  },
  "required": ["order", "date", "pallets"],
  "additionalProperties": false
}

En instans som bryter mot reglerna:

{ "order": "4471", "date": "27/10/2026", "pallets": 0, "pallet": 2 }

Instansen fallerar på två punkter. pallets ligger under minimivärdet 1, och pallet, ett stavfel för pallets, är en egenskap som schemat inte räknar upp. Att note saknas är inget fel, eftersom note inte står i required; hade den skickats som null hade det också gått igenom, eftersom typen tillåter null. Datumet är det lärorika. Formatet date kräver året först, och 27/10/2026 är inte skrivet så, men en validator som körs med sina standardinställningar godtar det, eftersom specifikationen gör format till en annotering som bara kontrolleras när den kontrollen är påslagen. Slå på kontrollen i en validator som kan kontrollera datum, så fallerar samma instans på tre punkter.

Ett verktyg som beskrivs på det sättet är just ämnet för sidan om din programvara som verktyg för AI-agenter här på webbplatsen. Den beskriver hur varje operation som en agent ska ha erbjuds som ett verktyg namngivet efter arbetet, som att boka en tid eller släppa en order, med typade indata, fel som en agent kan agera på och idempotenta anrop, så att ett nytt försök aldrig bokar två gånger. Beskrivningen är ett OpenAPI-dokument som genereras ur koden, och en MCP-server erbjuder samma operationer. Sidans poäng är att en agent litar på ett verktygs beskrivning även när den har blivit inaktuell, och en som skrivits för hand är inaktuell redan veckan efter att den har släppts. Därför genereras beskrivningarna från koden och utåt, genom databasen, API:et, beskrivningen och klienten, med en kontroll i varje steg som stoppar bygget när två av dem är oense.

Var det går fel

En egenskap som räknas upp men aldrig krävs. properties kontrollerar bara de egenskaper som finns med, så ett objekt som utelämnar dem allihop går igenom. Att en egenskap måste finnas med styrs av ett eget nyckelord, och utelämnas required krävs ingenting. Skriv required bredvid properties varje gång, och ha ett testfall för varje obligatorisk egenskap där just den egenskapen har tagits bort.

Stavfel som slinker igenom som extra egenskaper. Utan additionalProperties är varje egenskap som schemat inte räknar upp tillåten, så pallet går igenom, och den riktiga pallets saknas utan att någon märker det. Sätts nyckelordet till false stängs objektet, men nyckelordet ser bara properties och patternProperties i sitt eget schemaobjekt. Ett schema som bygger på ett annat genom allOf eller $ref och sedan stänger sig självt på det sättet avvisar just de egenskaper som det har ärvt. Version 2020-12 har unevaluatedProperties för det fallet, eftersom det också räknar med de egenskaper som har kontrollerats genom allOf, $ref och de andra nyckelord som tillämpar scheman på plats. Använd additionalProperties: false på ett schema som står för sig självt och unevaluatedProperties: false på ett som är sammansatt.

format som inte kontrollerar något. Som standard är format en annotering som bara beskriver, inte ett påstående som avvisar: specifikationen kräver att en validator som kan kontrollera format håller den kontrollen avslagen om ingen ber om den, och även när den är påslagen får en validator låta vilket format som helst passera okontrollerat. OpenAPI 3.1 följer samma regel och tillägger att hur väl format kontrolleras varierar mellan implementationer. Slå på formatkontroll i den validator du använder, bevisa det med ett testfall som ska fallera, och där ett format spelar roll men inte kan kontrolleras, lägg till ett pattern eller en kontroll i koden.

Mönster som matchar en del av ett värde. Ett pattern är inte förankrat, så [0-9]{4} godtar order 4471b, eftersom fyra siffror förekommer någonstans i värdet; specifikationens eget exempel är att es matchar expression. Börja mönstret med ^ och avsluta det med $ när hela värdet ska matcha. Mönster följer ECMA-262-dialekten, och specifikationen rekommenderar en liten uppsättning konstruktioner för mönster som ska bete sig likadant överallt, så håll dig till enkla teckenklasser, kvantifierare och ankare.

Saknad, null och tom behandlade som samma sak. En egenskap som inte finns med, en egenskap satt till null och en tom textsträng är tre olika instanser. "type": "string" avvisar null, och en egenskap som inte står i required får saknas. En klient som skickar null för att säga ”inget värde” till ett schema som är skrivet med tanke på att fältet saknas fallerar på varje sådan begäran. Bestäm för varje egenskap vad var och en av de tre betyder, och skriv ner det: ["string", "null"] när null har en betydelse, utelämnande ur required när egenskapen är valfri och minLength: 1 när en tom textsträng inte är ett värde.

Inget $schema, eller två versioner blandade. När roten i ett schema saknar $schema överlåter specifikationen beteendet åt implementationen, och varje validator använder den version som den har som standard. Versionerna skiljer sig åt där det spelar roll. I 2019-09 beskrev en array som gavs till items en tupel; i 2020-12 har den uppgiften flyttats till prefixItems, och items har tagit över rollen från additionalItems. Sätt $schema i varje rot, läs versionsanteckningarna när du byter version och validera varje schema mot sitt metaschema i CI.

Läs mer

• JSON Schema Specification — projektets översikt över den gällande versionen, metascheman och versionsanteckningarna för varje tidigare utkast.
• JSON Schema: A Media Type for Describing JSON Documents — Core 2020-12: hur scheman behandlas, $schema, $ref och $defs, och de nyckelord som kombinerar scheman.
• JSON Schema Validation: A Vocabulary for Structural Validation of JSON — nyckelorden för varje typ av värde, required och reglerna för format.
• JSON Schema 2020-12 Release Notes — vad som har ändrats sedan 2019-09, med prefixItems och $dynamicRef sida vid sida med det de ersatte.
• OpenAPI Specification v3.1.1 — Schema Object som en övermängd av JSON Schema 2020-12, och format som annotering som standard.
• Model Context Protocol: Tools — hur ett verktyg anger sina parametrar och sitt strukturerade resultat i JSON Schema.