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
$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 are UTC, formatted as YYYY-MM-DD HH:MM:SS.