Use standard formats

Add format to a string when your application expects a standard representation. Struct enforces supported formats during generation, including calendar rules for dates and timezone requirements for times.

Choose a format

Value	format	Example
Date	date	2026-11-14
Time	time	09:30:00Z
Timestamp	date-time	2026-11-14T09:30:00Z
Duration	duration	PT45M

UUIDs, IPv4 addresses and JSON pointers also have supported formats. See the format reference for the full list. Use a pattern for a custom shape instead.

Example: normalize a scheduled time

The request below converts a human-readable date and time to an RFC 3339 timestamp.

Save event-time.schema.json beside your client:

event-time.schema.json

Download event-time.schema.json

{
  "type": "object",
  "properties": {
    "starts_at": {
      "type": "string",
      "format": "date-time",
      "description": "Convert the stated start date and time to an RFC 3339 timestamp, preserving the timezone specified in the input."
    }
  },
  "required": ["starts_at"],
  "additionalProperties": false
}

Before you run this example

Call https://api.blatent.ai from your server. Set your API key in the same terminal where you run the example:

export BLATENT_API_KEY='YOUR_SERVICE_KEY'

Python requires Python 3.10+ and HTTPX:

python -m pip install "httpx>=0.28,<1"

TypeScript requires Node.js 24+ and uses its built-in fetch. The cURL examples require curl and jq.

Save the displayed files and the selected client in one directory. Run the client there with python example.py, node example.ts or bash example.sh. Downloads use the example's name in place of example.

Download Python

Python

import json
import os
from pathlib import Path
import httpx

request = {
    "input": "Maintenance starts at 09:30 UTC on 14 November 2026.",
    "schema": json.loads(Path("event-time.schema.json").read_text(encoding="utf-8")),
}
with httpx.Client(
    base_url="https://api.blatent.ai",
    headers={"Authorization": f"Bearer {os.environ['BLATENT_API_KEY']}"},
    timeout=195,
) as client:
    response = client.post("/v1/resolve", json=request)
    response.raise_for_status()
    print(json.dumps(response.json()["output"]))

TypeScript

import { readFileSync } from "node:fs";

const request = {
    "input": "Maintenance starts at 09:30 UTC on 14 November 2026.",
    "schema": JSON.parse(readFileSync("event-time.schema.json", "utf8")),
};
const response = await fetch(
  "https://api.blatent.ai" + "/v1/resolve",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BLATENT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(request),
    signal: AbortSignal.timeout(195_000),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(JSON.stringify((await response.json()).output));

cURL

set -eu

body=$(jq -n --argjson body '{"input":"Maintenance starts at 09:30 UTC on 14 November 2026."}' \
  --slurpfile f0 'event-time.schema.json' \
  '$body | setpath(["schema"]; $f0[0])')
curl --fail-with-body --silent --show-error \
  "https://api.blatent.ai/v1/resolve" \
  -H "Authorization: Bearer $BLATENT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary "$body"

Illustrative output:

{"starts_at":"2026-11-14T09:30:00Z"}

What a format checks

A date must be a real calendar date, including leap-year rules. A time or timestamp must include a timezone. The Z in this example means UTC.

A valid representation can still describe the wrong event or instant. Supply enough context to resolve ambiguous dates and timezones, and describe which value to normalize.

Formats check individual values. For a rule such as an end time following its start, see date relationships.