Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

JSON-scheman och beskrivningar

Lektion 2 av 14 Uppdaterad 29 juli 2026 Utvecklare
På denna sida
  1. Verktygens språk: JSON-schema
  2. Anatomin av en verktygsdefinition
  3. Parameterbeskrivningar
  4. Avancerade parametrar
  5. Bästa praxis för beskrivningar
  6. Viktiga punkter

Verktygens språk: JSON-schema

För att Grok ska kunna anropa dina funktioner måste det veta vad de gör och vilka parametrar de förväntar sig. Det är JSON-schemans roll. Varje verktyg beskrivs av ett strukturerat objekt som innehåller tre väsentliga delar: ett namn, en beskrivning och ett parameterschema.

Anatomin av en verktygsdefinition

Här är den kompletta strukturen för ett verktyg så som Grok API förväntar sig det:

{
  "type": "function",
  "name": "get_weather",
  "description": "Get the current weather for a given city",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "The city name (e.g., Paris, Lyon)"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "default": "celsius"
      }
    },
    "required": ["city"]
  }
}

Låt oss bryta ner varje fält:

Fältet type

Alltid "function" för anpassade funktioner. Andra typer finns för inbyggda verktyg (web_search, code_interpreter), men för dina egna funktioner är det alltid "function".

Fältet name

Det tekniska namnet på din funktion. Det måste vara:

  • Unikt bland alla verktyg i begäran
  • Beskrivande: get_weather snarare än fn1
  • I snake_case enligt konvention: search_products, create_ticket
  • Kort men tydligt: modellen använder detta namn för att avgöra vilket verktyg som ska anropas

Fältet description

Detta är det viktigaste fältet för anropskvaliteten. Modellen förlitar sig främst på beskrivningen för att avgöra när och hur ett verktyg ska användas. En bra beskrivning:

  • Förklarar vad funktionen gör i en mening
  • Specificerar när den ska användas (om det inte är uppenbart)
  • Nämner kantfall om det behövs

Jämför dessa två beskrivningar:

❌ "Väder"
✅ "Hämtar aktuellt väder för en stad. Returnerar temperatur, luftfuktighet och väderförhållanden."

Den andra ger modellen tillräcklig kontext för att veta exakt när denna funktion ska anropas och vad den får tillbaka.

Blocket parameters

Parametrar följer formatet JSON Schema. Typer som stöds inkluderar:

  • string — teckensträngar
  • number / integer — tal
  • boolean — sant/falskt
  • array — listor
  • object — nästlade objekt
  • enum — lista över tillåtna värden

Arrayen required listar obligatoriska parametrar. Andra är valfria – modellen kan välja att utelämna dem.

Parameterbeskrivningar

Varje parameter bör ha sin egen description. Det är detta som låter modellen förstå vilket värde som ska skickas:

{
  "date": {
    "type": "string",
    "description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
  }
}

Utan en beskrivning måste modellen gissa det förväntade formatet – vilket leder till fel.

Avancerade parametrar

Enums för att begränsa värden

{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "critical"],
    "description": "Ticket priority level"
  }
}

Enums är särskilt användbara: de talar om för modellen exakt vilka värden den kan använda, vilket eliminerar formatfel.

Standardvärden

{
  "limit": {
    "type": "integer",
    "default": 10,
    "description": "Maximum number of results to return"
  }
}

Modellen förstår att den kan utelämna denna parameter om standardvärdet fungerar.

Nästlade objekt

{
  "address": {
    "type": "object",
    "properties": {
      "street": { "type": "string" },
      "city": { "type": "string" },
      "zip": { "type": "string" }
    },
    "required": ["city"]
  }
}

Bästa praxis för beskrivningar

Beskrivningen är den enda kanal genom vilken modellen förstår ditt verktyg – varje ord räknas. Specificitet först: “Sök efter produkter efter namn eller kategori i katalogen” talar om för modellen exakt när detta verktyg gäller, medan “Sök efter produkter” lämnar den att gissa. Format därefter: att specificera “Datum i ISO 8601-format (ÅÅÅÅ-MM-DD)” i en parameterbeskrivning eliminerar hälften av argumentfelen, eftersom modellen replikerar formatet du visar den. Gränser är en del av kontraktet: “Maximalt 50 resultat per anrop” hindrar modellen från att lova användaren fullständighet som verktyget inte kan leverera. Och att beskriva returvärdet – “Returnerar ett objekt med pris, tillgänglighet och beskrivning” – hjälper modellen att planera framåt: den vet vad den kommer att ha till hands innan den ens anropar.

Viktiga punkter

  • Varje verktyg definieras av ett name, en description och parameters
  • Beskrivningen är faktor nummer ett för anropskvaliteten – lägg tid på den
  • Namn måste vara unika och i snake_case
  • Använd enum för att begränsa möjliga värden
  • Varje parameter bör ha sin egen beskrivning med det förväntade formatet
  • Arrayen required skiljer obligatoriska parametrar från valfria