Internet DRAFT - draft-yee-registration-report-definition

draft-yee-registration-report-definition







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,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", STD 90, RFC 8259,
              DOI 10.17487/RFC8259, December 2017,
              <https://www.rfc-editor.org/info/rfc8259>.

6.2.  Informative References

   [RFC2629]  Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629,
              DOI 10.17487/RFC2629, June 1999,
              <https://www.rfc-editor.org/info/rfc2629>.

   [RFC3552]  Rescorla, E. and B. Korver, "Guidelines for Writing RFC
              Text on Security Considerations", BCP 72, RFC 3552,
              DOI 10.17487/RFC3552, July 2003,
              <https://www.rfc-editor.org/info/rfc3552>.

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]