Registry Fee Extension for the Extensible Provisioning Protocol (EPP)
Summary: Has 2 DISCUSSes. Has enough positions to pass once DISCUSS positions are resolved.
Roman Danyliw Discuss
** There a few easy clarifications that need to be regarding the cardinality of attributes: -- Section 3.1. Is the use of command@name optional? The schema suggests that it is and the text in this section doesn’t making any claims. If blank, how should such a command be processed? -- Section 3.1. If command@name=”custom”, MUST command@customName be present? If not, what are the processing instructions to a recipient? -- Section 3.1 and 3.8. Can a client send a command@subphase attribute without a command@phase? The schema suggests this is possible and clarifying text provide no guidance. It seems like this should be an error. -- Section 3.4. Can a fee@lang be present without fee@description? The schema suggests it can but the text provides no direction. If this is possible, what should implementers do with a @lang without a @description? ** Section 6.1. This section needs a normative reference to W3C Schema as the format of the blob between the BEGIN and END tags.
** Section 3.4 and 3.9 Per fee@lang and reason@lang, the text don’t explicitly describe how to specify a language. It must be inferred from the schema. ** Section 3.4.2. The format of the grace period is not described in the text. It must be inferred from the schema. ** Section 4. Mixing the schema Boolean notation between false being “0” or “false” is confusing. In one paragraph, “The server MUST return avail=’0’” but in another “the server MUST set the ‘avail’ attribute … to false”
Benjamin Kaduk Discuss
I think (at least with the present formulation) we need greater clarity on when the "it's up to server policy whether to include, but that policy must be the same for all transactions" elements (<fee:balance> and <fee:creditLimit>) are returned, as at present there seems to be an internal inconsistency in the text. Section 3.5 and 3.6 just talk about including them "in responses to all 'transform' or billable commands", but then we have more qualified text such as (but not limited to) in Section 5.2.5 that only has <fee:updData> (and its children) included when the <update> has been processed successfully. So, are <fee:balance> and <fee:creditLimit> supposed to be included in error responses or not?
It might be helpful to note somewhere that <fee:cd> stands for "check data", as per stock EPP, since we use the term a few times before we get to the <fee:chkData> context and its definition. Section 1 Given the expansion of the DNS namespace, and the proliferation of novel business models, it is desirable to provide a method for EPP It's not clear to me whether all readers (whether now or in ten years) will have the context to appreciate what is meant by these background clauses. Section 3.3 When querying for fee information using the <check> command, the <fee:period> element is used to indicate the units to be added to the registration period of objects by the <create>, <renew> and <transfer> commands. This element is derived from the <domain:period> element described in [RFC5731]. The word "units" here is really confusing me. Even after reading the rest of the document (and 5731's definition of periodType) it still feels like there's some words missing here. Section 3.4 A server MAY respond with multiple <fee:fee> and <fee:credit> elements in the same response. In such cases, the net fee or credit applicable to the transaction is the arithmetic sum of the values of each of the <fee:fee> and/or <fee:credit> elements. This amount applies to the total additional validity period applied to the object (where applicable) rather than to any incremental unit. "unit" here is also confusing to me, though less so. I think what's going on here is just the common-sense "the sum of all fees/credits applies for the conceptual 'sum' of all the indicated registry operations taken together", in which case I might suggest to s/incremental unit/individual component of the transaction/. description: an OPTIONAL attribute which provides a human-readable description of the fee. Servers should provide documentation on the possible values of this attribute, and their meanings. An OPTIONAL "lang" attribute MAY be present to identify the language of the returned text and has a default value of "en" (English). I assume we're reusing the "lang" semantics from 5730 (which in turn relies on 4646), but it's probably worth being explicit about it. Section 3.4.3 If a <fee:fee> element has a "grace-period" attribute then it MUST also be refundable and the "refundable" attribute MUST be true. If the "refundable" attribute of a <fee:fee> element is false then it MUST NOT have a "grace-period" attribute. If a client receives a response that contravenes these requirements, what should it do? Section 3.5, 3.6 For these elements that the server MUST include in all responses if it chooses to include them in (any) responses, do we expect that to be global server policy, or potentially tailored to individual clients? (Also, I'm vaguely curious how much it could increase the response footprint, not that XML is a terribly concise representation to start with.) Section 3.7 If a server makes use of this element, it should provide clients with a list of all the values that the element may take via an out-of-band channel. Servers MUST NOT use values which do not appear on this list. I think we generally dislike to rely on out-of-band channels to quite this extent, though it's not clearly wrong for this case. I'm somewhat curious (not necessarily to include in the document) what existing out-of-band channels for this look like, though. Section 4 The server MUST return avail="0" in its response to a <check> command for any object in the <check> command that does not include the <fee:check> extension for which the server would likewise fail a domain <create> command when no <fee> extension is provided for that same object. nit: this wording makes it sound like avail="0" is scoped to the object, as opposed to the check data. So maybe s/for any object/if any object/? If a server receives a <check> command from a client, which results in no possible fee combination but where a fee is required, the server MUST set the "avail" attribute of the <fee:cd> element to false and provide a <fee:reason>. nit: I'm not sure how to interpret "where a fee is required" just given what's in this document. If the currency or total fee provided by the client is less than the server's own calculation of the fee for that command, then the server MUST reject the command with a 2004 "Parameter value range" error. How can a currency be "less than the server's own calculation"? (I assume this is supposed to be "currency is different".) Section 5.1.1 When the server receives a <check> command that includes the extension elements described above, its response MUST contain an <extension> element, which MUST contain a child <fee:chkData> element. The <fee:chkData> element MUST contain a <fee:currency> element and a <fee:cd> for each element referenced in the client <check> command. Can we be more precise about "for each element referenced in the client <check> command"? ("No" is a valid answer.) Specifically, does this apply to the <domain:check> child elements in the <check>, or to the <fee:check> extension elements, or something else? (My guess from the examples is the former.) o A <fee:command> element matching each <fee:command> (unless the "avail" attribute of the <fee:cd> if false) that appeared in the corresponding <fee:check> of the client command. This element MAY have the OPTIONAL "standard" attribute, with a default value of "0" (or "false"), which indicates whether the fee matches the fee of the "standard" classification (see section 3.7). This element MAY have the OPTIONAL "phase" and "subphase" attributes, which SHOULD match the same attributes in the corresponding <fee:command> element of the client command if sent by the client. I don't think I see how the SHOULD could be applicable -- doesn't Section 3.8 place tight requirements on server behavior and errors regarding phase/subphase in requests? That is, I think the descriptive "will match" would be appropriate here. The <fee:command> element(s) MAY have the following child elements: o An OPTIONAL <fee:period> element (as described in Section 3.3), which contains the same unit that appeared in the <fee:period> element of the command. If the value of the preceding <fee:command> element is "restore", this element MUST NOT be included, otherwise it MUST be included. If no <fee:period> appeared in the client command (and the command is not "restore") then the server MUST return its default period value. I think we need some caveat language ("if present"?) for "the same unit that appeared in the <fee:period> element of the command", since that element is OPTIONAL in the command in question. nit: is this the "preceding <fee:command> element" or "parent <fee:command> element"? Also, the rhetorical value of the "OPTIONAL" is unclear, as there's no server choice in the matter -- its presence/absence is fully determined by the <fee:command> value. If the "avail" attribute of the <fee:cd> element is true and if no <fee:fee> elements are present in a <fee:command> element, this indicates that no fee will be assessed by the server for this command. If the "avail" attribute is true, then the <fee:command> element MUST NOT contain a <fee:reason> element. In this second quoted paragraph, is this the "avail" attribute only of <fee:command> or does it apply to <fee:cd> as well? Section 5.2.1 The server MUST fail the <create> command if the <fee:fee> provided by the client is less than the server fee. I think we are more specific about this ("Parameter value range" error) in Section 4, which is also a MUST-level requirement. It's perhaps a bit anachronous to have a domain-creation example from 1999 when the -00 of this document's precedessor wasn't until 2013. Section 5.2.3 [The examples here are only from 2005; progress!] Section 7 Thank you for addressing the points discussed in the secdir review. That said, the text of this section still feels a bit sparse, with it mostly being bare statements without much discussion of the motivation for or consequences of many of the requirements at hand. For example, we could say something about why it's important to provide confidentiality/integrity protection for financial data, say more about what the "needed level of [...] protection" is, and reiterate that the transport protocol has to do so because there are no in-band EPP mechanisms to do so. It would also be fine to reiterate any key considerations from 5730/5731, if there are any that seem particularly relevant (but it's also fine to not do so). Also, I think that it's important to add "peer authentication" to the list of protections provided by the transport -- it's important to know who you're talking to when sending financial information! (Though, the client is just sending its estimate of the server's fee schedule, which is a lot less sensitive than sending its current balance.)
Barry Leiba Yes
Ignas Bagdonas No Objection
Deborah Brungard No Objection
Alissa Cooper No Objection
Suresh Krishnan No Objection
Warren Kumari No Objection
Firstly, thank you for working with Carlos to address the OpsDir comments -- he raised some good points (and is nicer than me), so I'm going to be a bit more of a stickeler than he was. "A <fee:fee> element MUST have a non-negative value." -- Yes, zero is a non-negative value (Hi Barry!), but not listing it explicitly seems like it's just asking for someone to do something like: ## Estimate how many transactions like this we can do: total_balance / fee or something similar. Simply mentioning the word should help lazy coders take this corner case into account. How would: A <fee:fee> element MUST must have a zero or greater value work for you? Also, I must admit I found this bit surprising: "A <fee:credit> element MUST have a negative value." If I go to Payless and return a pair of shoes, they give me a **credit** of $20, not of -$20. I really think that the credit element should either be treated in the same way, or you could do away with the credit elemans and just have negative "fees" (if I open my credit-card bill and see a charge of -$20 I know what it means), or if you don't want to do that, provide some clear warning text around this section. If I were implementing this, and not paying sufficient attention I'd calculate "new_balance = old_balance - fees + credits" -- a simple phrase or two should help prevent stupid errors.
Mirja Kühlewind No Objection
Alexey Melnikov No Objection
Alvaro Retana No Objection
Adam Roach No Objection
Éric Vyncke No Objection
Thank you for the work put into this document. I have only one COMMENT and one NITS see below. Regards, -éric == COMMENT == -- Section 3.4 -- C.1) Any reason to have a negative value for <fee:credit> ? This seems counter-intuitive to me. == NITS == Introducing <fee:cd> earlier in the text would improve the readability of the document.