Send raw values with standard codes instead of formatted text

How to do it

A field such as "1.234,50 €" breaks every client that reads another locale, and a script that parses it gets 1.2345. Send moments as dates and times says and amounts as money says. Name languages with tags such as sv or zh-Hant, never with names such as "Swedish". Use SE, not "Sweden", for countries. Let each client format with Format dates and numbers for the reader.

Examples

JSON example

{ "language": "sv-SE", "country": "SE", "total": { "amount": 123450, "currency": "EUR" }, "placedAt": "2026-03-05T14:00:00Z" }

JavaScript example

const BCP47 = /^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|\d{3}))?$/;
const isLanguageTag = value => BCP47.test(value) && Intl.getCanonicalLocales(value)[0] === value;

Python example

from babel import Locale, UnknownLocaleError

def is_language_tag(value: str) -> bool:
    try:
        Locale.parse(value, sep="-")
        return True
    except (ValueError, UnknownLocaleError):
        return False

How to check

A contract test validates every response against the schema. Language fields match a BCP 47 pattern, country fields match ^[A-Z]{2}$, and no string field holds a formatted number, date or amount.

Sources

• RFC 5646 (Tags for Identifying Languages)

Related rules

• API-7 Send dates as RFC 3339 with a time zone in API design
• API-8 Send money as an integer with its currency in API design
• LOC-11 Format dates and numbers for the reader in Localization