payto: add rationale in intro, target type examples, grammar fix

1 files changed, 97 insertions, 11 deletions

diff --git a/standards/draft-dold-payto.xml b/standards/draft-dold-payto.xml
index f744578..e6827b1 100644
--- a/standards/draft-dold-payto.xml
+++ b/standards/draft-dold-payto.xml
@@ -13,7 +13,7 @@
 <?rfc subcompact="no" ?>
 
 <rfc category="info"
-     docName="draft-dold-payto-03"
+     docName="draft-dold-payto-04"
      ipr="trust200902">
 
   <front>
@@ -48,7 +48,7 @@
       </address>
     </author>
 
-    <date day="28" month="January" year="2019" />
+    <date day="03" month="March" year="2019" />
 
     <!-- Meta-data Declarations -->
     <area>General</area>
@@ -78,6 +78,14 @@
   The interpretation of the target identifier is defined by the payment target type, and typically
   represents either a bank account or an (unsettled) transaction.
 </t>
+<t>
+  A unified URI scheme for all payment target types
+  allows applications to offer user interactions with URIs that represent payment targets,
+  without delay and churn when new payment systems are introduced.
+</t>
+<t>
+
+</t>
 </section>
 
 <section anchor="syntax"
@@ -92,7 +100,7 @@
   opt = (generic-opt / authority-specific-opt) "=" *( pchar )
   generic-opt = "amount" / "creditor-name" / "debitor-name" /
                 "message" / "instruction"
-  authority = <authority, see [RFC3986], Section 3.2>
+  authority = ALPHA *( ALPHA / DIGIT / "-" / "." )
   path-abempty = <path-abempty, see [RFC3986], Section 3.3>
   pchar = <pchar, see [RFC3986], Appendix A.>
 ]]>
@@ -231,7 +239,9 @@ The "payto" URI scheme is to be registered in the "Permanent URI Schemes" regist
 <t>Status: permanent</t>
 <t>URI scheme syntax: See <xref target="syntax" />.</t>
 <t>URI scheme semantics: See <xref target="semantics" />.</t>
-<t>Applications/protocols that use this scheme name: payto URIs are mainly used by financial software</t>
+<t>Applications/protocols that use this scheme name: payto URIs are mainly used by financial software,
+   as well as by interactive applications (e.g. email clients, chat applications) that detect
+   payto URIs and allow the user to interact with them (e.g. make them clickable)</t>
 <t>Contact: grothoff@gnu.org</t>
 <t>Change controller: grothoff@gnu.org</t>
 <!-- There does not seem to be a way to link to the references section! -->
@@ -249,23 +259,99 @@ is "Payment Target Type Registry".
 </t>
 <t>The registry shall record for each entry:
 <list style="symbols">
-<t>Name:  The name of the payment target type (case insensitive ASCII string)</t>
+<t>Name:  The name of the payment target type (case insensitive ASCII string, restricted to alphanumeric characters,
+dots and dashes)</t>
 <t>Description: A description of the payment target type, including the semantics of the path in the URI if applicable.</t>
+<t>Example: Example URI to illustrate the payment target type.</t>
 <t>Contact: The contact information of a person to contact for further information</t>
 <t>References: Optionally, references describing the payment method (such as an RFC) and method-specific options</t>
 </list>
 The registration policy for this registry is "First Come First Served", as described in <xref target="RFC5226" />.
 </t>
 
+<section anchor="registry-entry-ach" title="ACH Bank Account">
+<t>
+<list style="symbols">
+<t>Name: ach</t>
+<t>Description: Automated Clearing House.  The path consist of two components, the routing number and the account number.</t>
+<t>Example: payto://ach/122000661/1234</t>
+<t>Contact: N/A</t>
+<t>References: <xref target="NACHA" /></t>
+</list>
+</t>
+</section>
+
+<section anchor="registry-entry-iban" title="International Bank Account Number">
+<t>
+<list style="symbols">
+<t>Name: iban</t>
+<t>Description: International Bank Account Number (IBAN).  Generally the IBAN allows to unambiguously derive
+  the the associated BIC (Bank Identifier Code).  However, some legacy applications process payments to the same IBAN differently based on the
+  specified BIC.  Thus the path can either consist of a single component (the IBAN) or two components
+  (BIC and IBAN).
+</t>
+<t>Example:
+  
+  payto://iban/DE75512108001245126199
+  
+  payto://iban/SOGEDEFFXXX/DE75512108001245126199
+</t>
+<t>Contact: N/A</t>
+<t>References: <xref target="ISO20022" /></t>
+</list>
+</t>
+</section>
+
+<section anchor="registry-entry-upi" title="Unified Payments Interface">
+<t>
+<list style="symbols">
+<t>Name: upi</t>
+<t>Description: Unified Payment Interface. The path is an account alias.  The amount and creditor-name
+options are mandatory for this payment target.</t>
+<t>Example: payto://upi/alice@example.com?creditor-name=Alice&amp;amount=INR:200</t>
+<t>Contact: N/A</t>
+<t>References: <xref target="UPILinking" /></t>
+</list>
+</t>
+</section>
+
+<section anchor="registry-entry-bitcoin" title="Bitcoin Address">
+<t>
+<list style="symbols">
+<t>Name: bitcoin</t>
+<t>Description: Bitcoin protocol. The path is a "bitcoinaddress" as per <xref target="BIP0021" />.</t>
+<t>Example: payto://bitcoin/12A1MyfXbW6RhdRAZEqofac5jCQQjwEPBu</t>
+<t>Contact: N/A</t>
+<t>References: <xref target="BIP0021" /></t>
+</list>
+</t>
+</section>
+
+<section anchor="registry-entry-ilp" title="Interledger Protocol Address">
+<t>
+<list style="symbols">
+<t>Name: ilp</t>
+<t>Description: Interledger protocol. The path is an ILP address as per <xref target="ILP-ADDR" />.</t>
+<t>Example: payto://ilp/g.acme.bob</t>
+<t>Contact: N/A</t>
+<t>References: <xref target="ILP-ADDR" /></t>
+</list>
+</t>
+</section>
+
+<!--
+
 <t>The registry is initially populated with the following entries:</t>
 <texttable>
 <ttcol>Name</ttcol><ttcol>Description</ttcol><ttcol>Contact></ttcol><ttcol>References</ttcol>
-<c>ach</c><c>Automated Clearing House.  The path is a bank account number.</c><c>N/A</c><c><xref target="NACHA" /></c>
-<c>sepa</c><c>Single European Payment Area. The path is an IBAN.</c><c>N/A</c><c><xref target="ISO20022" /></c>
-<c>upi</c><c>Unified Payment Interface. The path is an account alias.</c><c>N/A</c><c><xref target="UPILinking" /></c>
-<c>bitcoin</c><c>Bitcoin protocol. The path is a "bitcoinaddress" as per <xref target="BIP0021" />.</c><c>N/A</c><c><xref target="BIP0021" /></c>
-<c>ilp</c><c>Interledger protocol. The path is an ILP address as per <xref target="ILP-ADDR" />.</c><c>N/A</c><c><xref target="ILP-ADDR" /></c>
-</texttable>
+<c>ach</c><c></c><c>N/A</c><c></c>
+<c>sepa</c><c>Single European Payment Area. The path is an IBAN.</c><c>N/A</c><c></c>
+<c>upi</c><c>Unified Payment Interface. The path is an account alias.</c><c>N/A</c><c></c>
+<c>bitcoin</c><c></c><c>N/A</c><c></c>
+<c>ilp</c><c></c><c>N/A</c><c></c>
+  </texttable>
+
+-->
 
 </section><!-- payto-registry -->