Subject: [weirds] Entity postal address information in draft-ietf-weirds-json-response-01

From: Gavin Brown <[email-masked]>
Date: Wed, 19 Dec 2012 13:55:09 +0000

Postal address information for entities is returned in a flat array format:

         "postalAddress" :
         [
           "123 Maple Ave",
           "Suite 90001",
           "Vancouver",
           "BC",
           "12393"
         ],

For any registry whose database design was developed to support EPP,
this is quite lossy, since the specific meaning of each field is lost.

I suggest that in addition to the above format, the standard should also
permit a full object, like so:

         "postalAddress" :
         {
           street: [ "123 Maple Ave", "Suite 90001", ],
           city: "Vancouver",
           sp: "BC",
           pc: "12393",
           cc: "CA"
         },

It would be pretty easy for clients to work out which model was being
used, and handle it accordingly. Servers should use one model or the
other, but not both.

G.

-- 
Gavin Brown
Chief Technology Officer
CentralNic Ltd
Innovative, Reliable and Flexible Registry Services
for ccTLD, gTLD and private domain name registries
https://www.centralnic.com/

CentralNic Ltd is a company registered in England and Wales with company
number 4985780. Registered Offices: 35-39 Moorgate, London, EC2R 6AR.

---

From: Andy Newton <[email-masked]>
Date: Wed, 19 Dec 2012 14:59:41 +0000

>used, and handle it accordingly. Servers should use one model or the

That's an interesting compromise. I would suggest

"postalAddress" :
{
  "structured" :
  {
    ...
  },
  "flat" :
  [
    ...
  ]
}

And if we have to figure out which structured format to use, EPP seems the
most reasonable to me.

I do think we need to ask the question of why we need structured postal
addresses though. Is it for automated sending of postal mail? I would
think that from a law enforcement point of view, a human is ALWAYS gonna
interpret the address so a flat structure is fine.

-andy

---

From: Gavin Brown <[email-masked]>
Date: Thu, 20 Dec 2012 10:59:24 +0000

> That's an interesting compromise. I would suggest

Agreed - although I think there should be some wording to encourage
implementers to pick and use one type only, rather than duplicating the
data in both types of structure (which the extract above seems to do).

> interpret the address so a flat structure is fine.

Even if a human is responsible for parsing the address, there are
situations where there is ambiguity. If you have an address like this:

	"postalAddress": [
	  "123 Example Street",
	  "Exampletown",
	  "NL",
	],

"NL" could be "Netherlands" or "Newfoundland" - you'd have to find out
the meaning and order of the fields via an out-of-band process. With a
structured address, the client and end-user know instantly whether the
postage for their letter is domestic or international.

For example of where having structured data is useful, consider:

1. law enforcement and anti-abuse people who may need to
programmatically determine the jurisdiction in which the registrants of
a large number of resources reside, where the number of records is large
enough that manual inspection is impractical, or

2. Maintainers of "Geo IP" and "ASN to Country" databases, or other
aggregations of registration data.

G.

---

From: Jaap Akkerhuis <[email-masked]>
Date: Thu, 20 Dec 2012 15:38:50 +0100

[I think I'm reacting on Andy's mail here but I might attribute this
to the wrong person. Apologies in that case].
    
  > That's an interesting compromise. I would suggest

I find it a bit odd to have twice the same data. The way the data is
presented to the user is to my taste more a presentation issue then a
protocol issue. It is also way easier to remove structure then going
the reverse, therefore I would prefer to go for a structured approach.

    And if we have to figure out which structured format to use, EPP
    seems the most reasonable to me.

Given that a lot provisioning is done using EPP, that is an obvious
choice. I don't remember where the format which EPP comes from, but it
might be useful to look at other formats as well.

As an example, the UPU has an addressing standard (S42. see
<http://www.upu.int/uploads/tx_sbdownloader/sheetAddressingS42InternationalAddressingStandardsFactSheetEn.pdf>).
They also have an expert group which collects the various templates
<http://www.upu.int/en/activities/addressing/s42-templates.html> using
the terminology of this standard.

This standard is under currently revision in cooperation with ISO/TC
211 as well as the ISO 19160 addressing project (see
<http://www.isotc211.org/address/iso19160.htm>).

    I do think we need to ask the question of why we need structured
    postal addresses though. Is it for automated sending of postal
    mail? I would think that from a law enforcement point of view, a
    human is ALWAYS gonna interpret the address so a flat structure is
    fine.

For machine readable exchange of address information there is the UPU
standard S53. This standards uses elements as defined in the S42 and
uses XML. Still, it will be advisable use at minimum as inspiration.

It might be that only humans look at the data which comes of "the word
protocol" but understanding by humans is often aided by a structural
presentation.

	jaap

---

From: Arturo Servin <[email-masked]>
Date: Thu, 20 Dec 2012 12:50:35 -0200

> the reverse, therefore I would prefer to go for a structured approach.

	I think it is only one of the two.

	If you have structured data, you serve that. Otherwise you serve the flat.

<snip>

Regards
/as

---

From: Simon Perreault <[email-masked]>
Date: Fri, 21 Dec 2012 15:13:53 +0100

Please allow me to remind everyone that the IETF has a standard for such 
information: vCard. Let's use it and focus on WEIRDS, not on postal 
address formats.

And there is a draft about a JSON representation for vCard:
http://tools.ietf.org/html/draft-bhat-vcarddav-json-00

It's really straightforward IMHO...

Simon

-- 
DTN made easy, lean, and smart --> http://postellation.viagenie.ca
NAT64/DNS64 open-source        --> http://ecdysis.viagenie.ca
STUN/TURN server               --> http://numb.viagenie.ca

---

From: Andy Newton <[email-masked]>
Date: Fri, 21 Dec 2012 14:42:25 +0000

>It's really straightforward IMHO...

Simon,

I think the issue here is if registries have the data store in a way that
they can fill out a vCard structure. The EPP structure is likely the most
common for this community. Perhaps we should see if the EPP structure maps
into vCard. Of course, none of this gets us away from needing a flat
structure. Can vCard accommodate that?

-andy

---

From: Alex Sergeyev <[email-masked]>
Date: Fri, 21 Dec 2012 10:19:53 -0500

> information: vCard. Let's use it and focus on WEIRDS, not on postal address
> formats.
Earlier this year many people mentioned that they just don't have
ability to present structured data.  vCard is even more structured
than EPP, it would be hard to get there.

Now back to having both "flat" and "structured" in postalAddress....

I like structured data but I think that having many ways to present
the info makes it harder for clients to parse and adds more ability
for server software engineers to get creative. Also:
* there is nothing good from additional nesting, adds complexity and
points for potential exception handling
* extensions will randomly use hashes and "structured/flat" approach
following the example (I truly assume that weirds might be universal
"object info" protocol, not just for replacing whois)

I would offer this:

* keep presentation as plain ordered string list
* make server able to provide postalAddressFields list that describes
positions that were used

e.g

"postalAddress" :  [ "123 Maple Ave", "Suite 90001", "Vancouver",
"BC",   "12393", "CA"  ],
"postalAddressFields": [ "street", "street", "city", "sp", "postal", "cc" ]

with list of appropriate strings in appendix (mine are from attempts
to recall EPP)

I also think such approach could be used elsewhere - phones, emails,
entityNames.... (wording for "*Fields" is tricky... essentially I wish
it would be "must if it has ability to reveal data structure")

Still feel it's not ideal but at least it gives schema that everyone
should follow when extending things.

--
Alex.

On Fri, Dec 21, 2012 at 9:13 AM, Simon Perreault
<[email-masked]> wrote:
> _______________________________________________
> weirds mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/weirds

---

From: Simon Perreault <[email-masked]>
Date: Fri, 21 Dec 2012 16:32:28 +0100

> structure. Can vCard accommodate that?

Let's see what RFC 5733 contains... I'm looking for correspondence with 
vCard elements from RFC 6350.

>       2.3. Individual and Organizational Names ........................5

Correspond to vCard properties FN and ORG.

>       2.4. Address ....................................................6
>            2.4.1. Street, City, and State or Province .................6
>            2.4.2. Postal Code .........................................6
>            2.4.3. Country .............................................6

Corresponds to vCard property ADR.

>       2.5. Telephone Numbers ..........................................6

Corresponds to vCard property TEL.

>       2.6. Email Addresses ............................................6

Corresponds to vCard property EMAIL.

>       2.7. Dates and Times ............................................6

Corresponds to the various and usual vCard date/time data types.

Did I miss anything?

Based on this overview I think vCard can easily represent EPP contact 
information.

Simon

---

From: Simon Perreault <[email-masked]>
Date: Fri, 21 Dec 2012 16:33:06 +0100

> Now back to having both "flat" and "structured" in postalAddress....

vCard has both a structured postal address property (ADR) and an 
unstructured one (LABEL), precisely because structured does not work for 
everyone and every situation.

Look, vCard has been around for a long time. It has been used a lot, and 
it has evolved with practice. What you want is probably in it.

> points for potential exception handling

Who said anything about nesting?

vCard is a flat list of properties. That's it.

> "object info" protocol, not just for replacing whois)

WEIRDS could specify a restricted "profile" of vCard. It has been done 
before:

http://tools.ietf.org/html/rfc6493

Simon

---

From: Andy Newton <[email-masked]>
Date: Fri, 21 Dec 2012 15:53:15 +0000

>everyone and every situation.

I think that solves our requirement.

I assume we would be embedding these vCards. Is that correct?

Are there other opinions regarding switching to vCard?

-andy

---

From: Alex Sergeyev <[email-masked]>
Date: Fri, 21 Dec 2012 10:56:18 -0500

> Are there other opinions regarding switching to vCard?

 whole "entities" concept gets replaced to "vcards" or it's only for
postalAddress?

-- 
Alex

---

From: Simon Perreault <[email-masked]>
Date: Fri, 21 Dec 2012 17:07:29 +0100

>   whole "entities" concept gets replaced to "vcards" or it's only for

Looking at this:

http://tools.ietf.org/html/draft-ietf-weirds-json-response-01#section-7.1

I think some elements would be replaced by a vCard, some others would 
remain WEIRDS' business.

Replaced by a vCard:
entityNames
postalAddress
emails
phones

In WEIRDS:
remarks (although vCard has a NOTE property... not sure)
links (although vCard has a URL property... not sure)
handle
roles
registrationDate
lastChangedDate (vCard has a REV property with a timestamp value)
lastChangedBy

Simon

---

From: Peter Koch <[email-masked]>
Date: Sun, 23 Dec 2012 00:00:09 +0100

> it has evolved with practice. What you want is probably in it.

so has WHOIS.  My understanding was that structured data was one of the
many drivers behind a whois replacement.  Has this "requirement" now gone?

-Peter

---

From: "John Levine" <[email-masked]>
Date: 23 Dec 2012 00:24:53 -0000

>many drivers behind a whois replacement.  Has this "requirement" now gone?

The data providers can only return what they have.  If the underlying
data doesn't have any structure, no quantity of MUST in a spec will
change that.

---

From: Marc Blanchet <[email-masked]>
Date: Sun, 23 Dec 2012 11:02:38 -0500

> data doesn't have any structure, no quantity of MUST in a spec will

ok. but postal addresses have been in that state for a lot of apps. That does not prevent to structure the format.
Every registry will then try to fit the best they can the data they have in the structure of the format.
For example, some may have the postal code, some may have but embedded in the street address. So the structure format having a postal code, then those who can put the postal code in the right field, some who can't just continue as they were doing. 

In other words, the protocol format should be the "best possible" (not the perfect one) and then each organization maps its current dataset into that format.  And overtime, things will improve as new registries come, as old registries are redoing their apps/database, as ...

Given that vcard is not only used a lot into the field for all kind of apps, and that vcard is an IETF format, I would suggest to closely look at it to reuse as much as possible, instead of reinventing the wheel.  Moreover, vcard includes the i18n requirements.

Marc.

---

From: "John R Levine" <[email-masked]>
Date: 23 Dec 2012 12:17:28 -0500

> Given that vcard is not only used a lot into the field for all kind of apps, and that vcard is an IETF format, I would suggest to closely look at it to reuse as much as possible, instead of reinven…

I wouldn't object to using the vcard address format, so long as there's 
also some way to return address info when the provider isn't able to 
shoehorn it into the vcard fields.

Regards,
John Levine, [email-masked], Taughannock Networks, Trumansburg NY
"I dropped the toothpaste", said Tom, crestfallenly.

---

From: Gavin Brown <[email-masked]>
Date: Mon, 24 Dec 2012 10:50:58 +0000

> http://tools.ietf.org/html/draft-bhat-vcarddav-json-00

Reusing an existing representation makes a lot of sense to me, as long as:

1. the profile is restricted to pretty much the same data as the current
spec supports.

2. both flat and structured address data is supported.

3. data which are common to all the object types (registration/update
times, sponsoring registrar, etc) have the same names across all objects.

4. the formatting of dates, telephone numbers, etc are the same across
all objects.

Otherwise, implementations are going to have to introduce special
object-specific handlers for the same data, which will be a pain.

Here's how I see an entity representation working, with a vCard
representation merged with the format in draft-ietf-weirds-json-response-01:

    {
        "handle" : "SH8013-REP",
        "fn" : "John Doe",
        "status" : [ "validated", "locked" ],
        "org" : { "text" : "Example Inc" },
        "adr" : {

            /* used by servers with flat address data */
            "label" : "123 Example Dr., Suite 100, Dulles, VA,
20166-6503, US",

            /* used by servers with structured address data */
            "street" : "123 Example Dr., Suite 100",
            "locality" : "Dulles",
            "region" : "VA",
            "code" : "20166-6503",
            "country" : "US"
        },
        "tel" : [
            {
                "type" : "voice",
                "uri" : "tel : +1.7035555555x1234"
            },
            {
                "type" : "fax",
                "uri" : "tel : +1.7035555556"
            }
        ],
        "email" : { "text" : "[email-masked]" },
        "remarks" : [
            "she sells seas shells",
            "down by the seashore"
        ],
        "links" : [
            {
                "value" : "http : //example.com/entity/XXXX",
                "rel" : "self",
                "href" : "http : //example.com/entity/XXXX"
            }
        ],
        "port43" : "whois.example.net",
        "registrationDate" : "1990-12-31T23 : 59 : 60Z",
        "registrationBy" : "ABC123",
        "lastChangedDate" : "1990-12-31T23 : 59 : 60Z",
        "lastChangedBy" : "ABC123",
        "sponsoredBy" : "SponsorXYZ",
        "resoldBy" : "ResellerPDQ"
    }

---

From: Alessandro Vesely <[email-masked]>
Date: Mon, 24 Dec 2012 18:01:53 +0100

> I think some elements would be replaced by a vCard, some others would

vCard defines an email type, such as "work", which can be extended so as
to match, for example, automated and non-automated mailboxes of the
abuse role.

> links (although vCard has a URL property... not sure)

What changes, beside the field's name?

---

From: Simon Perreault <[email-masked]>
Date: Tue, 25 Dec 2012 09:19:56 +0100

> to match, for example, automated and non-automated mailboxes of the

Yes, IMHO that would be good protocol design.

> What changes, beside the field's name?

I'm not sure exactly what is the extent of your question, but I was 
thinking that the vCard would be embedded into the WEIRDS JSON 
structure, not merged. For example you would have a "vCard" item whose 
value would be a vCard JSON structure.

The reason for that is that WEIRDS should not care (too much) about 
contact information. I can imagine a ton of use cases where programs 
would not care about this information and would treat it as a blob.

So, taking "links" as an example, would those links be about the contact 
(e.g. "this person has a website at this address"), or do they have 
WEIRDS-specific semantics? I guess it's the latter, which is why I did 
not move it to the vCard.

Simon

---

From: Alessandro Vesely <[email-masked]>
Date: Wed, 26 Dec 2012 12:42:52 +0100

> Yes, IMHO that would be good protocol design.

For merge-vs-embed considerations, a reliable way to determine a
complaint reporting email address /is/ WEIRDS-specific.  At least, I
came to this WG after learning that

   Deciding where to send an unsolicited report will typically
   rely on heuristics.
                http://tools.ietf.org/html/rfc6650#section-5.3
                                                     June 2012
> value would be a vCard JSON structure.

WHOIS data is traditionally flattened, irrespective of the depth of the
underlying database.  It eases both parsing and presentation.

> would not care about this information and would treat it as a blob.

As long as the same data is not repeated at top level too, that makes
sense.  It may ease comprehension and aid the design of visual layouts.

> not move it to the vCard.

Hm... We have some fields, like "remarks" which are quite popular (7
TLDs, according to Linlin's analysis.)  "Links" seems to be less used
than that.  In cases where semantics corresponds, by using the same
field names WEIRDS and vCard can reinforce one another.  Whether WEIRDS
data could then be considered an extended vCard is a minor issue, IMHO.

---

From: "Linlin Zhou" <[email-masked]>
Date: Thu, 27 Dec 2012 09:58:03 +0800

Dear Marc,
> In other words, the protocol format should be the "best possible" (not the
> perfect one) and then each organization maps its current dataset into that
format.
> And overtime, things will improve as new registries come, as old
registries are
> redoing their apps/database, as ...
> 
> Given that vcard is not only used a lot into the field for all kind of
apps, and that
> vcard is an IETF format, I would suggest to closely look at it to reuse as
much as
> possible, instead of reinventing the wheel.  Moreover, vcard includes the
i18n
> requirements.
As seeing you mentioned the i18n requirements included in the vcard, I'd
like to know more details about it. Could you please give any reference?
Thanks.

Linlin

---

From: Marc Blanchet <[email-masked]>
Date: Thu, 27 Dec 2012 09:28:04 -0500

> like to know more details about it. Could you please give any reference?

sure. first, I'm not claiming that vcard i18n "features" are in match with weirds requirements (maybe, maybe not).
But:
- previous vcard version (RFC2425,…) was not "clean" for i18n. multiple charsets, etc…
- current version of vcard (RFC6350): the group went to make sure any i18n requirement was met. so, more precisely:
 + mandating UTF-8 (section 3.1, RFC6350)
 + escaping (section 3.4)
 + dates/time in iso format (section 4.3)
 + language (section 5.1)
 + geo 
 + tz
 + tel: based on x.520

Please see RFC6350.

Marc.