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]