Update 'Home'

2023-11-26 00:32:04 -07:00 · 2023-11-26 00:32:04 -07:00 · fee208e4d9
commit fee208e4d9
parent 8dea46f3fd
1 changed files with 51 additions and 35 deletions
--- a/Home.md
+++ b/Home.md
@ -1,11 +1,20 @@
+# Quick Send Barcode Specification
+
+## Introduction
+
+The Quick Send format is intended as a simple way to encode address and parcel information into a single barcode. This allows users to present a barcode when sending a package, enabling autofilling in shipping software.
+
 ## Basic Rules

 * The barcode shall be in QR Code, DataMatrix, or PDF417 format.
 * Data fields shall be delineated with a pipe character (`|`).
 * Data shall be encoded as ASCII or UTF-8. If the chosen barcode format has a different default/preferred encoding, that encoding may be used instead.
-* Data fields shall not include a newline, or a `|`, `=`, or `+` character.
+* Data fields shall not include a newline or horizontal whitespace characters except normal ASCII spaces. 
+* The vertical pipe character (`|`) must not be used in any data field.
+* The `=` and `+` characters should not be used in data fields, as they are used as subfield separators.
 * The data must not start or end with a pipe character.
 * Most fields are not strictly required and may be left empty when not needed. Implementations may reject a code with insufficient data.
+* Extra fields at the end are ignored.

 ## Data Header

@ -42,6 +51,7 @@ Position | Meaning
 20 | From country (ISO 2-character country code)
 21 | From phone
 22 | From email
+23 | Preferences field. See appendix.


 ### Subtype `p`
@ -50,20 +60,20 @@ Contains address data, plus parcel information and options.

 Position | Meaning
 ---------|--------
-0 - 22 | See `a`
-23 | Weight (U.S. ounces)
-24 | Item type (see appendix)
-25 | Length (inches)
-26 | Width (inches)
-27 | Height (inches)
-28 | Non-machinable: `1` if true, otherwise empty
-29 | Certified Mail: `1` if true, otherwise empty
-30 | Registered Mail: `1` if true, otherwise empty
-31 | Registered Mail declared value, USD
-32 | Return Receipt Requested: `1` if true, otherwise empty
-33 | Special rate eligibility: `M` for Media Mail, `L` for Library Mail, empty if not claiming eligibility
-34 | Insurance amount, USD
-35 | Signature services. 1: Signature required, 2: Adult signature required, 3: Restricted delivery signature, 4: Adult restricted signature, 5: Indirect signature.
+0 - 23 | See `a`
+24 | Weight (U.S. ounces)
+25 | Item type (see appendix)
+26 | Length (inches)
+27 | Width (inches)
+28 | Height (inches)
+29 | Non-machinable: `1` if true, otherwise empty
+30 | Certified Mail: `1` if true, otherwise empty
+31 | Registered Mail: `1` if true, otherwise empty
+32 | Registered Mail declared value, USD
+33 | Return Receipt Requested: `1` if true, otherwise empty
+34 | Special rate eligibility: `M` for Media Mail, `L` for Library Mail, empty if not claiming eligibility
+35 | Insurance amount, USD
+36 | Signature services. 1: Signature required, 2: Adult signature required, 3: Restricted delivery signature, 4: Adult restricted signature, 5: Indirect signature.

 ### Subtype `ac`

@ -71,15 +81,15 @@ Address data plus customs form.

 Position | Meaning
 ---------|--------
-0 - 22 | See `tofrom`
-23 | Customs contents type: "documents", "gift", "merchandise", "returned_goods", "sample", "dangerous_goods", "humanitarian_donation", or "other" (this field always required)
-24 | Customs form signer name (electronically sign the form)
-25 | Non-delivery option: `r` or `a` for return or abandon, respectively. Default if empty is `r`.
-26 | Explanation of contents (required if field 23 is "other")
-27 | Restriction type (empty, "other", "quarantine", or "sanitary_phytosanitary_inspection")
-28 | Restriction comments (required if field 27 is not empty)
-29 | EEL/PFC: Use "NOEEI 30.37(a)" for most shipments under $2,500. Otherwise, use the shipment's Automated Export System (AES) Internal Transaction Number (ITN).
-30 | Customs items. See appendix for format.
+0 - 23 | See `tofrom`
+24 | Customs contents type: "documents", "gift", "merchandise", "returned_goods", "sample", "dangerous_goods", "humanitarian_donation", or "other" (this field always required)
+25 | Customs form signer name (electronically sign the form)
+26 | Non-delivery option: `r` or `a` for return or abandon, respectively. Default if empty is `r`.
+27 | Explanation of contents (required if field 24 is "other")
+28 | Restriction type (empty, "other", "quarantine", or "sanitary_phytosanitary_inspection")
+29 | Restriction comments (required if field 28 is not empty)
+30 | EEL/PFC: Use "NOEEI 30.37(a)" for most shipments under $2,500. Otherwise, use the shipment's Automated Export System (AES) Internal Transaction Number (ITN).
+31 | Customs items. See appendix for format.


 ### Subtype `pc`
@ -88,16 +98,16 @@ Address data, parcel information, and customs form.

 Position | Meaning
 ---------|--------
-0 - 22 | See `a`
-23-35 | See `p`
-36 | Customs contents type: "documents", "gift", "merchandise", "returned_goods", "sample", "dangerous_goods", "humanitarian_donation", or "other" (this field always required)
-37 | Customs form signer name (electronically sign the form)
-38 | Non-delivery option: `r` or `a` for return or abandon, respectively. Default if empty is `r`.
-39 | Explanation of contents (required if field 36 is "other")
-40 | Restriction type (empty, "other", "quarantine", or "sanitary_phytosanitary_inspection")
-41 | Restriction comments (required if field 40 is not empty)
-42 | EEL/PFC: Use "NOEEI 30.37(a)" for most shipments under $2,500. Otherwise, use the shipment's Automated Export System (AES) Internal Transaction Number (ITN).
-43 | Customs items. See appendix for format.
+0 - 23 | See `a`
+24-36 | See `p`
+37 | Customs contents type: "documents", "gift", "merchandise", "returned_goods", "sample", "dangerous_goods", "humanitarian_donation", or "other" (this field always required)
+38 | Customs form signer name (electronically sign the form)
+39 | Non-delivery option: `r` or `a` for return or abandon, respectively. Default if empty is `r`.
+40 | Explanation of contents (required if field 36 is "other")
+41 | Restriction type (empty, "other", "quarantine", or "sanitary_phytosanitary_inspection")
+42 | Restriction comments (required if field 40 is not empty)
+43 | EEL/PFC: Use "NOEEI 30.37(a)" for most shipments under $2,500. Otherwise, use the shipment's Automated Export System (AES) Internal Transaction Number (ITN).
+44 | Customs items. See appendix for format.

 ## Appendix

@ -154,4 +164,10 @@ Position | Meaning
 2 | Value of item in USD (quantity * value of a single item)
 3 | Weight of the item in ounces (quantity * weight of single item)
 4 | Harmonized Tariff Schedule number
-5 | Country of origin as two-character ISO country code
+5 | Country of origin as two-character ISO country code
+
+### Preferences field
+
+This field allows the user's software to communicate preferences to the shipping software.  Data format is implementation-specific. Any format is allowed as long as the data does not include the `|` character.
+
+The one rule for this field is to preface the data with a unique identifer for the implementation, to prevent confusion and incompatibility. The identifier shall be followed by a colon (`:`) to signal the start of the actual data.  Software must read until the colon to determine compatibility with the encoded data. If the software is not compatible, the remainder of this field shall be ignored.