Registration Protocol Extensions J. Yee, Ed. Internet-Draft Afilias Intended status: Standards Track July 21, 2019 Expires: January 21, 2020 Registration Report Definition draft-yee-registration-report-definition-00 Abstract This document specifies the domain registration report definition format in JavaScript Object Notation (JSON) that could be communicated between client and server in various mechanisms such SFTP and HTTP. If there is a preference to send registration report definition over EPP , the format could change from JSON to XML. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on January 21, 2020. Copyright Notice Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Yee Expires January 11, 2020 [Page 1] Internet-Draft Registration Report Definition July 2019 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 2 2. Specification of Registration Report Definition . . . . . . . 2 2.1. Information about the report definition file . . . . . . 2 2.2. Information about the report file name . . . . . . . . . 3 2.3. Information about the report content . . . . . . . . . . 3 2.4. Information about the report content specification . . . 3 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 5. Security Considerations . . . . . . . . . . . . . . . . . . . 4 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 5 6.1. Normative References . . . . . . . . . . . . . . . . . . 5 6.2. Informative References . . . . . . . . . . . . . . . . . 5 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction This document defines the registration report definition format for registry operator to share with registrars of the content in a particular report. The report definition will include not only field names, but could also include meta information such as file name convention, and detailed information of the field like data type and whether field allow empty value. JSON [RFC8259] is the chosen format for the definition file due to its simplicity and a robust choice under various delivery mechanism such as HTTP REST or SFTP. If HTTP REST is the preferred method, JSON is the most popular, well known choice for data format. JSON can also convert to XML easily if there is desire to deliver the same information through EPP. The XML definition and namespace for EPP communication is out of scope in this document. 1.1. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. 2. Specification of Registration Report Definition 2.1. Information about the report definition file 1. "version" : For author who wants to use version to track defition file. This field is optional. 2. "lastUpdate" : For author who wants to provide the definition's last updated time. This field is option. Yee Expires January 11, 2020 [Page 2] Internet-Draft Registration Report Definition July 2019 2.2. Information about the report file name 1. "fileNameFormat" : To inform reader what the report file name may look like. This field is optional. 2. "fileNameConvention" : To inform reader if any pattern applied in the file name. As there may have more than one pattern, all info shoudl be stored in JSON array format. This field is optional. " 3. "fileExtension" : list of file extension that the report file name uses. This field is optional. 2.3. Information about the report content 1. "fields" : List all fields' value in JSON array, one field name per value. This field is mandatory. 2. "tokenizer" : List the character used in report as separator. This field is mandatory. 2.4. Information about the report content specification The field name starts with "definition", and follows by nested array, with each one specifies one field's definition. Field specification is optional For each defition: 1. "name" : the value for each name is the field name in the report. 2. "type" : tells what kind of data the field holds. The usual value is either text or number. 3. "allowEmpty" : the value is either true or false, a boolean type in JSON. This tells reader if the field allows empty value or not. 3. Examples Yee Expires January 11, 2020 [Page 3] Internet-Draft Registration Report Definition July 2019 Simple example with fields only. File: transactions-def.json { "fields" : ["tld","domain","transaction-type","time","term","charge"], "tokenizer" : "|" } Example with defintion information, report name information, report information, and report content definition. File: transaction-def.json { "version" : "1.0", "lastUpdate" : "2019-07-04T00:00:00Z", "filenNameFormat" : "RO_transaction_${TLD}_${frequency-date}", "fileNameConvention" : [ { "TLD" : [ "ALL", "registry-portfolio-name", "tld-string" ] }, { "frequency-date" : [ "daily_YYYY-MM-DD", "monthly_YYYY-MM" ] } ], "fileExtension" : "csv", "fields" : ["tld","domain","transaction-type","time","term","charge"], "tokenizer" : "|", "defintion" : [ { "name" : "tld", "type" : "text", "allowEmpty" : false }, { "name" : "domain", "type": "text", "allowEmpty" : false }, { "name" : "transaction-type", "type": "text", "allowEmpty" : false }, { "name" : "time", "type": "text", "allowEmpty" : false }, { "name" : "term", "type": "number", "allowEmpty" : true }, { "name" : "charge", "type": "number", "allowEmpty" : true } ] } 4. IANA Considerations This documemnt may ask IANA to create a repository to hold reports defintion submitted by registry operator. TBD 5. Security Considerations All drafts are required to have a security considerations section. See RFC 3552 [RFC3552] for a guide. Yee Expires January 11, 2020 [Page 4] Internet-Draft Registration Report Definition July 2019 6. References 6.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . 6.2. Informative References [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, DOI 10.17487/RFC2629, June 1999, . [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, DOI 10.17487/RFC3552, July 2003, . Author's Address Joseph Yee (editor) Afilias Suite 204, 4141 Yonge Street Toronto, Ontario M2P 2A8 Canada Email: jyee@afilias.info Yee Expires January 11, 2020 [Page 5]