Core Conventions

Patterns that apply across all WorldAPI standards.

Object Identity

Every WorldAPI object identifies itself with two fields:

Property Purpose
$type The WorldAPI standard: contact, platform, feed, location, filesystem, message, event
$kind The subtype within that standard: point, area, route for location, etc.
$version Standard version number

Property Prefixes

Prefix Meaning
$property Defined by a WorldAPI standard
property Custom property (your own data)
_property Private property (not shared publicly)

The Value Pattern

Any property that holds a value about something (email, phone, address, etc.) follows the same pattern. It can be a simple value, an object with metadata, or an array of either.

Single simple value

$phone: '+43664123456'

Single value with metadata

$phone: {
	$value: '+43664123456',
	$kind: 'mobile'
}

Multiple simple values

$phone: ['+43664123456', '+4311234567']

Multiple values with metadata

$phone: [
	{ $value: '+43664123456', $kind: 'mobile' },
	{ $value: '+4311234567', $kind: 'landline' },
	{ $value: '+4315554321', $kind: 'work', $primary: true }
]

Structured values

Some properties have their own structure instead of a flat $value. The same pattern applies -- single, with metadata, or array.

// simple string
$address: 'Stephansplatz 3, 1010 Vienna, AT'

// structured object
$address: {
	$street: 'Stephansplatz 3',
	$city: 'Vienna',
	$postal: '1010',
	$country: 'AT',
	$kind: 'home'
}

// multiple
$address: [
	{
		$street: 'Stephansplatz 3',
		$city: 'Vienna',
		$postal: '1010',
		$country: 'AT',
		$kind: 'home'
	},
	{
		$street: 'Kärntner Ring 1',
		$city: 'Vienna',
		$postal: '1010',
		$country: 'AT',
		$kind: 'work'
	}
]

Value Metadata

These properties can appear on any value object:

Property Type Description
$value string The value itself (for flat values like email, phone)
$kind string Category: private, work, home, mobile, landline, etc.
$primary boolean Marks the preferred value when multiple exist

Dates

All dates and times are ISO 8601 strings. Pick the form by meaning:

Meaning Format Example
Instant (when something happened) UTC with Z '2026-09-25T18:00:00Z'
Local wall-clock time No offset, plus $timezone (IANA) $start: '2026-10-02T18:00:00', $timezone: 'Europe/Vienna'
Date without time YYYY-MM-DD '2026-11-03'
Duration ISO 8601 duration 'PT1H', 'PT15M', 'P1D'
  • Timestamps like $created, $updated, $expires are instants and always UTC.
  • Use local time + $timezone only where the meaning is local, e.g. events that stay at 18:00 across DST changes.
  • A local time without $timezone is floating: the same clock time in every zone.
  • Seconds may be omitted ('2026-09-25T18:00Z'). Fractions are allowed.

Changes

  • 2026-09-25 -- Date rule changed from "UTC only, YYYY-MM-DD HH:MM:SS" to ISO 8601 with instants in UTC (Z), local wall-clock times with $timezone, date-only values and ISO 8601 durations. UTC-only cannot express calendar events: "every Monday 09:30 in Vienna" moves by an hour in UTC across DST, and all-day events have no time at all. The T/Z form is also what JavaScript Date, databases and iCalendar tools parse directly. Location route $duration changed from seconds to an ISO 8601 duration for the same reason. Added the Event standard.