PAYLOADS
What a reader does with the bytes.
A CKey payload is just bytes. These conventions say how a reader should interpret them. A payload that follows none of them is still a valid CKey.
Docs: Overview · Payloads · SDKs · Telemetry · API
Text first
A reader treats a payload as text when it is valid UTF-8 with no control characters other than tab and line feed (CR LF is accepted). Anything else is shown as binary, for example as hexadecimal.
Recognised forms
A text payload whose first :-delimited token is one of these schemes is offered as an action. Schemes match case-insensitively and surrounding whitespace is ignored.
| FORM | EXAMPLE | READER OFFERS |
|---|---|---|
https: / http: | https://openckey.org/docs/ | Open openckey.org (the host is shown first) |
mailto: | mailto:hello@example.org?subject=Hi | Email hello@example.org |
tel: | tel:+15551234567 | Call +15551234567 |
sms: | sms:+15551234567?body=Hi | Message +15551234567 |
geo: | geo:37.33490,-122.00900 | Show 37.33490, -122.00900 on a map |
address: | address:1 Infinite Loop, Cupertino, CA 95014 | Show 1 Infinite Loop, Cupertino, CA 95014 on a map |
BEGIN:VCARD … END:VCARD | a complete vCard | Add contact |
Write phone numbers in E.164 form, with + and the country code.
The address: convention
address: is a CKey convention, not a registered URI scheme. It is followed by a free-text postal address in UTF-8 with no percent-encoding. Line breaks may separate address lines; readers join the non-empty lines with “, ”. It exists because geo: needs coordinates and no standard URI carries a plain street address. Other code readers show it as text, which still works for a person.
Safety rules
- Never act automatically. A decode only shows the payload and the proposed action. The person taps to proceed, and the action names its target, such as “Open example.org” or “Call +1 555…”.
- Allowlist only. Only the forms above get an action.
javascript:,data:,file:,intent:, custom app schemes, and everything else are plain text. - Keep the payload visible. The decoded text, and the raw bytes on request, stay visible next to any action.
- Validate before offering.
mailto:must contain@;tel:andsms:need at least three digits (only+and digits are kept);geo:latitude must be within ±90 and longitude within ±180;address:must not be empty;http(s):must have a host. A form that fails is shown as plain text.
Every SDK ships the same classifier (classifyPayload in the web SDK). The renderer uses it to tell you what readers will offer for your payload.
How /text and /sq relate
openckey.org gives a CKey a short https: payload to carry, so a symbol can stay small:
https://openckey.org/text/idopens hosted text. A reader offers “Open openckey.org”; the page shows only the words.https://openckey.org/sq/idis a short query that redirects to an HTTPS destination after an automated safety scan clears it. A reader still offers “Open openckey.org”, because the redirect happens only after the tap.
Because the reader can only show the openckey.org host for these links, check the destination before you print a short query, and report abuse if one leads somewhere harmful. Each identifier is seven URL-safe Base64 characters and is never reused.
Capacity: the scheme prefix costs bytes like any prefix — tel: is 4, address: 8, https:// 8. Profile 1 carries exactly 16 bytes and is not meant for these forms; use Profile 0.
Source: CKey Payload Conventions (informative, draft 0.1).