diff --git a/docs/Appendix-URI-Content.md b/docs/Appendix-URI-Content.md new file mode 100644 index 000000000..dfb5d4efa --- /dev/null +++ b/docs/Appendix-URI-Content.md @@ -0,0 +1,257 @@ +# Popular content and URI schemes + +**A brief summary of popular use cases for QR codes.** + + +## URL `https` + +Perhaps the most common use for QR Codes is to share URLs: simply encode the (URL-encoded) string value +and make sure to include the scheme `http(s)://` so that it can be properly identified by the reader application: + +``` +https://en.m.wikipedia.org/wiki/URL +``` + +Some URLs may open a vendor specific application, for example the following URL may open the YouTube app: + +``` +https://www.youtube.com/watch?v=dQw4w9WgXcQ +``` + +**See also:** + + - [What is a URL? (Mozilla MDN)](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL) + - [URL (Wikipedia)](https://en.wikipedia.org/wiki/URL) + + +## E-Mail `mailto` + +E-Mail links are encoded similar to URLs, preceded by the `mailto:` scheme to ensure they are properly identified and the default mail application can be opened. +Parameters may be added as a [URL query string](https://en.wikipedia.org/wiki/Query_string): +``` +mailto:[,...?to=,...&cc=,...&bcc=,...&subject=&body=] +``` + +| Query parameter | Description | +|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `to` | Alternative to add a recipient address: `mailto:?to=` is equivalent to
`mailto:,` and `mailto:?to=,` | +| `subject` | Subject text: `mailto:?subject=Hello%20World%21` would open the e-mail app
and create a messagewith the subject `Hello World!` | +| `body` | Message body: `mailto:?body=This%20is%20the%20message%20body.`
creates a message with the contents `This is the message body.` | +| `cc` | "Carbon copy" to add one or more `cc` recipients | +| `bcc` | "Blind carbon copy" to add one or more `bcc` recipients | + +The fields for recipient adresses (`mailto:`, `to`, `cc`, `bcc`) may contain one or more elements separated by a comma `,`; the values of all fields shall be URL-encoded according to [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). + +**Examples:** + +- `mailto:?to=addr1@example.com` +- `mailto:addr1@example.com,addr2@example.com` +- `mailto:addr1@example.com?cc=addr2@example.com&subject=Hello%21` + +**See also:** + + - [RFC 6068 - The 'mailto' URI Scheme](https://datatracker.ietf.org/doc/html/rfc6068) + - [Email links (Mozilla MDN)](https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Creating_hyperlinks#email_links) + - [Email (Wikipedia)](https://en.wikipedia.org/wiki/Email) + - [mailto (Wikipedia)](https://en.wikipedia.org/wiki/Mailto) + + +## Phone numbers `tel` + +A phone number should be prefixed with the `tel:` scheme so that a device's dialer can be invoked properly: + +``` +tel:+999-123-456-7890 +``` + +Generally, the most complete version of a telephone number possible sould be used, e.g. `+`, spaces or hyphens may be used to separate blocks. +Some devices may also support the `sms` and `fax` schemes, which are deprecated in favor of `tel`. + +**See also:** + + - [RFC 3966 - The 'tel' URI for Telephone Numbers](https://datatracker.ietf.org/doc/html/rfc3966) + - [List of country calling codes (Wikipedia)](https://en.wikipedia.org/wiki/List_of_country_calling_codes) + - [National conventions for writing telephone numbers (Wikipedia)](https://en.wikipedia.org/wiki/National_conventions_for_writing_telephone_numbers) + - [google/libphonenumber (GitHub)](https://github.com/google/libphonenumber) ([PHP port (GitHub)](https://github.com/giggsey/libphonenumber-for-php)) + + +## Geo Coordinates `geo` + +A geographical coordinate, including altitude can be encoded using the `geo:` URI scheme so that it can be opened with a map application. + +``` +geo:,[,;crs=;u=] +``` + +The default coordinate system is WGS-84, for which latitude and longitude should be supplied as decimal degrees, the optional altitude in meters. +Te parameter `u` can be used to specify an *uncertainty* value (in meters), a different *coordinate reference system* may be supplied with `crs`. + +Some applications support an additional query string with values of `z` for *zoom* level and `q` for a local search *query* (URL-encoded): +``` +geo:,?z=&q= +``` + +**Examples:** + +- `geo:47.620521,-122.349293` +- `geo:27.988056,86.925278,8848` +- `geo:11.373333,142.591667,-10920;u=10` +- `geo:37.786971,-122.399677;crs=Moon-2011;u=35` + +**See also:** + +- [RFC 5870 - A Uniform Resource Identifier for Geographic Locations ('geo' URI)](https://datatracker.ietf.org/doc/html/rfc5870) +- [geo URI scheme (Wikipedia)](https://en.wikipedia.org/wiki/Geo_URI_scheme) +- [Coordinate reference system (Wikipedia)](https://en.wikipedia.org/wiki/Coordinate_reference_system) + + +## Mobile Authenticators `otpauth` + +Mobile authenticators can be added with the `otpauth` scheme: + +``` +otpauth:///