Wire formats · JSON Schema 2020-12 · v0.1

Schemas

Six JSON Schemas define every document Kindling puts on the wire. Each table below is generated from the schema file itself, so it cannot drift from it.

Pool manifestpool_manifest.schema.json
Parsed profileparsed_profile.schema.json
Handshake messagehandshake_message.schema.json
Kindling messagekindling_message.schema.json
Well-known Pool filewell_known_pool.schema.json
Block listblock_list.schema.json

01Schema

pool_manifest.schema.json

Pool manifest

Raw file: pool_manifest.schema.json Spec: §3JSON Schema 2020-12 · PoolManifest

A Kindling Pool: a curated list of profile entries plus the metadata that defines its purpose, governance, and consent rules.

No fields beyond those listed are allowed at the top level.

Pool manifest · every field
Field	Required	Type or values	About
schema_version	Yes	`"0.1"`, fixed	No description in the schema.
id	No	string	Stable identifier for this Pool, typically a slug. Optional; generated from name if omitted.
name	Yes	string	Human-readable Pool name. At least 1 character.
curator	Yes	array of objects	One or more verified Kindling identities curating this Pool. At least 1 item.
curator[].identity	Yes	string	Curator's Kindling identity (email, OAuth-bound identifier, or fingerprint).
curator[].display_name	No	string	No description in the schema.
curator[].verification_level	Yes	`email` · `oauth` · `cryptographic`	No description in the schema.
curator[].primary	No	boolean	True for the primary curator. At most one primary. Default: `false`.
intent_tags	Yes	array of strings	What the Pool is for. Free-form tags; common values: friendship, dating, professional, hiking, polyamorous-dating-la, neurodivergent-friendships. At least 1 item.
visibility	Yes	`public` · `unlisted` · `invite-only`	No description in the schema.
consent_model	Yes	`universal-opt-in` · `vouching-required` · `curator-only-adds`	Default: `"universal-opt-in"`.
curator_contact	Yes	string	How a profile owner can reach the curator about removal, complaints, disputes. Typically email or a contact-form URL.
charter	Yes	string	Free-text description of what the Pool is for and what it isn't. Required, plain text in v0.1. At least 20 characters.
geographic_scope	No	object	Optional. Used when a Pool is location-specific. No other fields.
geographic_scope.city	No	string	No description in the schema.
geographic_scope.region	No	string	No description in the schema.
geographic_scope.country	No	string	No description in the schema.
geographic_scope.online	No	boolean	No description in the schema.
governance_rules	No	string	Optional. How co-curators are added, how disputes are handled. Defaults to the protocol-level boilerplate when not specified.
messaging_preferences	No	object	Pool-level defaults that apply to all members unless their profile overrides. No other fields.
messaging_preferences.block_list_subscriptions	No	array of strings (uri)	No description in the schema.
messaging_preferences.minimum_sender_verification	No	`unverified` · `email` · `oauth`	No description in the schema.
status	No	`active` · `dormant` · `archived`	Pool lifecycle state. Dormant = curator inactive 90+ days; Archived = read-only after failed curator transition. Default: `"active"`.
created_at	No	string (date-time)	No description in the schema.
updated_at	No	string (date-time)	No description in the schema.
entries	Yes	array of objects	The list of profile entries in this Pool.
entries[].profile_url	Yes	string (uri)	No description in the schema.
entries[].parsed_profile	No	a `parsed_profile` (see Parsed profile)	No description in the schema.
entries[].parsed_at	No	string (date-time)	No description in the schema.
entries[].consent_proof	Yes	object	No other fields.
entries[].consent_proof.handshake_id	Yes	string	No description in the schema.
entries[].consent_proof.accepted_at	Yes	string (date-time)	No description in the schema.
entries[].consent_proof.method	No	`email-link` · `oauth` · `curator-vouching` · `auto-accept`	No description in the schema.
entries[].verification_level	Yes	`email` · `oauth` · `curator-vouched` · `cryptographic`	No description in the schema.
entries[].added_at	Yes	string (date-time)	No description in the schema.
entries[].added_by	No	string	Curator identity of who added this entry.

Required means required within its parent object. Field names in gray are the path to the parent.

02Schema

parsed_profile.schema.json

Parsed profile

Raw file: parsed_profile.schema.json Spec: §2JSON Schema 2020-12 · ParsedProfile

The structured representation of a Kindling profile, produced by parsing a freeform profile URL (with h-card baseline plus AI extraction).

No fields beyond those listed are allowed at the top level.

Parsed profile · every field
Field	Required	Type or values	About
schema_version	Yes	`"0.1"`, fixed	The version of the parsed_profile schema this document conforms to.
profile_url	Yes	string (uri)	Canonical source URL the profile was parsed from.
display_name	Yes	string	Human-readable name as the owner presents themselves. At least 1 character.
pronouns	No	string	Pronouns the owner uses, free-form (e.g., 'she/her', 'they/them').
location	No	object	Where the owner lives or operates from. All fields optional. No other fields.
location.city	No	string	No description in the schema.
location.region	No	string	No description in the schema.
location.country	No	string	No description in the schema.
location.remote	No	boolean	True if the owner explicitly identifies as remote / location-independent.
location.lat	No	number	From -90 to 90.
location.lon	No	number	From -180 to 180.
photo_hints	No	array of strings (uri)	URLs to images on the source page. Kindling does not cache; implementations decide whether to cache locally.
intent_tags	No	array of strings	What the owner is open to (friendship, dating, networking, hiking buddies, co-founders, etc.).
about	No	string	Free-text 'about me' compressed from the source page. Plain text only at v0.1.
contact_methods	No	array of objects	Declared external contact methods.
contact_methods[].type	Yes	`email` · `twitter` · `bluesky` · `mastodon` · `instagram` · `linkedin` · `calendly` · `url` · `other`	No description in the schema.
contact_methods[].value	Yes	string	No description in the schema.
contact_methods[].label	No	string	No description in the schema.
verification	No	object	Identity verification level for this profile. No other fields.
verification.level	No	`unverified` · `email` · `oauth` · `curator-vouched` · `cryptographic`	The strongest verification this profile holds. 'cryptographic' is reserved for v0.2.
verification.verified_at	No	string (date-time)	No description in the schema.
verification.verifier	No	string	For OAuth: the provider (google, apple, etc.). For curator-vouched: the curator's identity.
messaging_preferences	No	object	Per-profile rules for incoming messages and handshakes. No other fields.
messaging_preferences.accept_from	No	`anyone` · `verified` · `shared-pool` · `vouched` · `none`	Default: `"verified"`.
messaging_preferences.minimum_curator_verification	No	`unverified` · `email` · `oauth`	No description in the schema.
messaging_preferences.no_cold_messages	No	boolean	Default: `false`.
messaging_preferences.auto_accept_rules	No	array of objects	At most 5 items.
messaging_preferences.auto_accept_rules[].intent_tags	Yes	array of strings	At least 1 item.
messaging_preferences.auto_accept_rules[].minimum_curator_verification	No	`email` · `oauth`	No description in the schema.
messaging_preferences.auto_accept_rules[].allowed_visibility	No	array of: `public` · `unlisted`	No description in the schema.
kindling_noindex	No	boolean	If true, this profile asks not to be included in any Pool. Compliant Pools and crawlers respect this. Default: `false`.
parsed_at	Yes	string (date-time)	ISO-8601 timestamp of when this parsed_profile was produced.
parser	No	string	Identifier of the parser implementation that produced this profile (e.g., 'kindling-parser/0.1.0').

Required means required within its parent object. Field names in gray are the path to the parent.

03Schema

handshake_message.schema.json

Handshake message

Raw file: handshake_message.schema.json Spec: §5.2JSON Schema 2020-12 · HandshakeMessage

A consent handshake exchange between a Pool and a profile owner.

A handshake message is exactly one of two shapes: a request or a response. Neither allows fields beyond those listed.

HandshakeRequest · every field
Field	Required	Type or values	About
schema_version	Yes	`"0.1"`, fixed	No description in the schema.
type	Yes	`"handshake-request"`, fixed	No description in the schema.
handshake_id	Yes	string	Unique identifier for this handshake exchange.
pool	Yes	object	No other fields.
pool.url	Yes	string (uri)	No description in the schema.
pool.name	Yes	string	No description in the schema.
pool.charter	Yes	string	No description in the schema.
pool.curator_identity	Yes	string	No description in the schema.
pool.curator_verification	Yes	`email` · `oauth` · `cryptographic`	No description in the schema.
pool.intent_tags	Yes	array of strings	No description in the schema.
pool.visibility	Yes	`public` · `unlisted` · `invite-only`	No description in the schema.
profile_url	Yes	string (uri)	No description in the schema.
sent_at	Yes	string (date-time)	No description in the schema.
expires_at	Yes	string (date-time)	No description in the schema.
accept_url	Yes	string (uri)	No description in the schema.
decline_url	Yes	string (uri)	No description in the schema.

HandshakeResponse · every field
Field	Required	Type or values	About
schema_version	Yes	`"0.1"`, fixed	No description in the schema.
type	Yes	`"handshake-response"`, fixed	No description in the schema.
handshake_id	Yes	string	No description in the schema.
decision	Yes	`accept` · `decline`	No description in the schema.
responded_at	Yes	string (date-time)	No description in the schema.
responder_identity	No	string	Verified identity of the profile owner responding.

Required means required within its parent object. Field names in gray are the path to the parent.

04Schema

kindling_message.schema.json

Kindling message

Raw file: kindling_message.schema.json Spec: §6JSON Schema 2020-12 · KindlingMessage

A native Kindling message envelope. v0.1 transport is structured email under the hood.

No fields beyond those listed are allowed at the top level.

Kindling message · every field
Field	Required	Type or values	About
schema_version	Yes	`"0.1"`, fixed	No description in the schema.
message_id	Yes	string	Globally unique message identifier.
type	Yes	`handshake-request` · `handshake-response` · `intro` · `reply` · `withdrawal` · `system`	No description in the schema.
in_reply_to	No	string	If this message is a reply, the message_id it replies to.
sender	Yes	object	No other fields.
sender.identity	Yes	string	No description in the schema.
sender.display_name	No	string	No description in the schema.
sender.verification_level	Yes	`unverified` · `email` · `oauth` · `curator-vouched` · `cryptographic`	No description in the schema.
sender.profile_url	No	string (uri)	No description in the schema.
recipient	Yes	object	No other fields.
recipient.identity	Yes	string	No description in the schema.
recipient.profile_url	No	string (uri)	No description in the schema.
via_pool	No	object	If the message was triggered through a Pool, the Pool's reference. No other fields.
via_pool.url	No	string (uri)	No description in the schema.
via_pool.id	No	string	No description in the schema.
via_pool.name	No	string	No description in the schema.
sent_at	Yes	string (date-time)	No description in the schema.
subject	No	string	Optional human-facing subject line.
body	Yes	object	No other fields.
body.content_type	Yes	`text/plain` · `text/markdown`	No description in the schema.
body.content	Yes	string	No description in the schema.
transport	No	object	Transport-layer metadata. v0.1: email. No other fields.
transport.type	No	`email`	No description in the schema.
transport.message_headers	No	object of strings	No description in the schema.

Required means required within its parent object. Field names in gray are the path to the parent.

05Schema

well_known_pool.schema.json

Well-known Pool file

Raw file: well_known_pool.schema.json Spec: §10JSON Schema 2020-12 · WellKnownKindlingPool

The discovery file published at /.well-known/kindling-pool by any domain hosting a Pool. Crawlers and registries fetch this to find Pools without a central authority.

No fields beyond those listed are allowed at the top level.

Well-known Pool file · every field
Field	Required	Type or values	About
schema_version	Yes	`"0.1"`, fixed	No description in the schema.
pools	Yes	array of objects	All Pools hosted on this domain that are discoverable.
pools[].manifest_url	Yes	string (uri)	No description in the schema.
pools[].name	No	string	No description in the schema.
pools[].intent_tags	No	array of strings	No description in the schema.
pools[].visibility	Yes	`public` · `unlisted` · `invite-only`	No description in the schema.
pools[].status	Yes	`active` · `dormant` · `archived`	No description in the schema.
pools[].geographic_scope	No	object	No other fields.
pools[].geographic_scope.city	No	string	No description in the schema.
pools[].geographic_scope.region	No	string	No description in the schema.
pools[].geographic_scope.country	No	string	No description in the schema.
pools[].geographic_scope.online	No	boolean	No description in the schema.
pools[].last_updated	No	string (date-time)	No description in the schema.
operator	No	object	Optional metadata about the entity operating this discovery file. No other fields.
operator.name	No	string	No description in the schema.
operator.contact	No	string	No description in the schema.
operator.url	No	string (uri)	No description in the schema.

Required means required within its parent object. Field names in gray are the path to the parent.

06Schema

block_list.schema.json

Block list

Raw file: block_list.schema.json Spec: §7.3JSON Schema 2020-12 · KindlingBlockList

A signed shared block list. Implementations subscribe to one or more lists and filter senders / curators / Pools accordingly.

No fields beyond those listed are allowed at the top level.

Block list · every field
Field	Required	Type or values	About
schema_version	Yes	`"0.1"`, fixed	No description in the schema.
list_id	Yes	string	Globally unique identifier for this list, typically a URL-safe slug.
name	Yes	string	No description in the schema.
description	No	string	No description in the schema.
publisher	Yes	object	No other fields.
publisher.identity	Yes	string	No description in the schema.
publisher.name	No	string	No description in the schema.
publisher.url	Yes	string (uri)	No description in the schema.
version	Yes	integer	Monotonically increasing version. Implementations should pull updates. At least 1.
published_at	Yes	string (date-time)	No description in the schema.
entries	Yes	array of objects	No description in the schema.
entries[].target_type	Yes	`identity` · `profile_url` · `pool_url` · `curator_identity` · `implementation`	No description in the schema.
entries[].target_identifier	Yes	string	No description in the schema.
entries[].reason_category	Yes	`spam` · `harassment` · `impersonation` · `consent_violation` · `scraping` · `other`	No description in the schema.
entries[].reason_detail	No	string	Optional human-readable explanation. Avoid PII; this list is public.
entries[].added_at	Yes	string (date-time)	No description in the schema.
entries[].expires_at	No	string (date-time)	Optional. If present, the entry should be ignored after this date.
signature	No	object	Optional cryptographic signature attesting to the list's integrity. Recommended for v0.2 onward. No other fields.
signature.algorithm	No	string	No description in the schema.
signature.value	No	string	No description in the schema.
signature.key_url	No	string (uri)	No description in the schema.

Required means required within its parent object. Field names in gray are the path to the parent.

07Open

Open questions

Where the text and the schemas differ

The specification text and the six schemas were written together, and in a few places they say different things. They are listed here as open questions for the maintainers, not as rulings. Nothing on this page changes either one.

Verification level names
The text. §4.5 names four levels: email-verified, oauth-verified, curator-vouched and unverified.
The schema. The schemas use email, oauth, curator-vouched, unverified and cryptographic. A curator’s level may only be email, oauth or cryptographic, and a Pool entry’s level has no unverified.
Open question: Which names are the wire values, and should the text list cryptographic?
Read §4.5
Extraction provenance
The text. §2.3 says a parsed profile’s extraction_source field carries which fields were h-card-derived and which were inferred.
The schema. parsed_profile.schema.json has no such field, and it allows no fields beyond the ones it lists.
Open question: Where does per-field provenance live in a v0.1 document?
Read §2.3
The handshake window
The text. §5.2 sets a default window of 14 days, “configurable per Pool”.
The schema. The Pool manifest has no field for the window. A handshake request carries its own expires_at, which is the only place a window appears in the schemas.
Open question: Should the manifest name its window, or is each request’s expires_at the whole of it?
Read §5.2
Message types
The text. §6.3 lists four message types: handshake-request, handshake-response, intro and reply.
The schema. kindling_message.schema.json allows six, adding withdrawal and system.
Open question: Should §6.3 list the other two, and what is a system message for?
Read §6.3
Noindex and privacy
The text. §2.7 says a Profile with a kindling-noindex directive is included in no Pool, registry or discovery surface.
The schema. The schema’s kindling_noindex means “do not include me in any Pool”, and it can be set on a parsed profile, which a Pool entry may hold. Privacy inside a Pool comes from the Pool’s visibility; noindex is not a visibility setting.
Open question: Can a parsed profile with kindling_noindex: true appear in a Pool entry at all?
Read §2.7
Auto-accept and invite-only Pools
The text. §5.5 says a rule can be limited by a visibility constraint.
The schema. In the schema, allowed_visibility may hold only public or unlisted, so no rule can ever auto-accept into an invite-only Pool. The text does not say so.
Open question: Is that limit intended as part of §5.5?
Read §5.5

Also noticed while generating the tables above

These smaller differences came up while this page was built from the schema files. They have not been reviewed yet.

The version field
The text. §12.1 says every document MUST carry a kindling_version field.
The schema. All six schemas name it schema_version, fixed at "0.1".
Read §12.1
The well-known file
The text. §10.2 lists name, pool_url, visibility, intent_tags, status and curator_contact for each Pool.
The schema. The schema calls the address manifest_url, requires only manifest_url, visibility and status, and has no curator_contact. It adds an optional operator.
Read §10.2
The Pool reference in a message
The text. §6.2 names it pool_ref.
The schema. The message schema calls it via_pool.
Read §6.2
What a Pool entry must hold
The text. §3.4 says each entry MUST contain parsed_profile and parsed_at.
The schema. The schema requires profile_url, consent_proof, verification_level and added_at, and leaves parsed_profile and parsed_at optional.
Read §3.4
Where a profile’s level sits
The text. §2.4 lists verification_level on a parsed profile.
The schema. The schema nests it as verification.level.
Read §2.4
Messaging rule names
The text. §7.2 names open-to-all, pool-mates-only, vouched-only, no-cold-messages and minimum-sender-verification.
The schema. The profile schema has accept_from (anyone, verified, shared-pool, vouched, none) and no_cold_messages. minimum_sender_verification appears only in the Pool manifest.
Read §7.2
A signature on consent proofs
The text. RFC 0004 says the v0.1 schema includes a signature field for consent proofs.
The schema. A manifest entry’s consent_proof holds handshake_id, accepted_at and method, and nothing else. Only the block list has a signature.
Read §5.2

Schemas

Pool manifest

Parsed profile

Handshake message

Kindling message

Well-known Pool file

Block list

Where the text and the schemas differ

Verification level names

Extraction provenance

The handshake window

Message types

Noindex and privacy

Auto-accept and invite-only Pools

Also noticed while generating the tables above

The version field

The well-known file

The Pool reference in a message

What a Pool entry must hold

Where a profile’s level sits

Messaging rule names

A signature on consent proofs