PortableContacts schema XML namespace

[Martin Atkins]

Hi folks,

I'm considering the use of the PortableContacts schema to represent
people in Atom.

In order to do this, the PortableContacts elements need to be in an XML
namespace.

Can we pick a URL on portablecontacts.net that is used when
PortableContacts elements appear in other XML formats?

This would also make the portable contacts schema usable in RDF, though
admittedly it would then duplicate much of what FOAF does. (one might
argue that it already does, though currently with a different syntax as
well as a different schema.)

[Joseph Smarr]

Sounds reasonable. Can you and/or someone else more familiar with xml
customs make a proposal for what namespace to use and how to reflect
that in the draft spec? Thanks, js

[Martin Atkins]

Joseph Smarr wrote:
> Sounds reasonable. Can you and/or someone else more familiar with xml
> customs make a proposal for what namespace to use and how to reflect
> that in the draft spec? Thanks, js
>

I don't think this really needs to be anything massively complicated.
The namespace URI could just be http://portablecontacts.net/ for the
sake of keeping it memorable.

In Atom I'd then expect it to look something like this:

<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:pc="http://portablecontacts.net/">

<title>Martin Atkins</title>
... (other Atom elements) ...

<pc:displayName>Martin Atkins</pc:displayName>
<pc:gender>Male</pc:gender>
... (other PortableContacts elements) ...

</entry>

It's a little unfortunate that Atom has some required elements that
overlap with the PortableContacts schema, but that's for the
hypothetical "using PoCo in Atom" spec to worry about.

As I see it, all the PortableContacts spec needs to say is:

---------------------------------

If the elements defined in this specification are used within another
XML format that makes use of XML namespaces, or are used in RDF, the
elements from this specification SHOULD be in the XML namespace
"http://portablecontacts.net/". The elements retain the same meanings,
content models and processing expectations as defined in this specification.

---------------------------------

I'm not really sure where this paragraph would go in the current draft,
since there isn't actually any particular section describing in detail
the XML serialization; it's just stuck on the end of the description of
the "format" argument. It might be good to describe the two
serializations in more detail in sections of their own, which would then
give my paragraph above somewhere to live.

An open question is whether the XML serialization of the
PortableContacts *protocol* should also use this namespace. This has the
advantage that -- in theory at least -- the same parsing code can be
used regardless of where the elements are used. However, since the
primary motivation of the XML serialization is to make it easier to
process in Java and .NET, this decision ought to be driven by what
impact that has on Java and .NET developers. I don't know the answer to
that question, and I don't feel strongly either way on this issue.

[N. Jones]

I agree with Martin, it can be simple. However I would put some versioning data in the URL even if it's just the year. This will allow for locking in to a version to avoid compatibility issues if/when they come up.

This also has the side-effect of making it a browse-able page specific to this namespace, if we choose to throw something up there...

I would suggest: http://portablecontacts.net/2008

Where 2008 is the year PoCo was started.

Nika

[Dan Brickley]

On 2/1/09 16:48, Joseph Smarr wrote:
> Sounds reasonable. Can you and/or someone else more familiar with xml
> customs make a proposal for what namespace to use and how to reflect
> that in the draft spec? Thanks, js

This would be really great - good suggestion Martin. I asked for it
before too, since it makes a huge difference for our ability to map
between the PC formats and the RDF/FOAF world. While PC isn't itself
directly an RDF vocabulary (yet?), having an XML namespace URI for it
would allow a mapping to be made using GRDDL technology.

http://www.w3.org/TR/grddl/ (a fairly modest spec) defines some
mechanisms by which transforms, typically XSLT, can be discovered from
such a URI. You could use this to make an RDF view of your work (eg. to
exploit the SPARQL query language, the RDFa HTML notation, etc), or to
map to similar constructs in FOAF. Or both. I'd be happy to help with
any of this. As Martin mentions there are definite overlaps with FOAF,
as well as areas that each spec covers but the other doesn't attempt.
All the more reason to define some basic interop in a machine-friendly way.

For the namespace name, I recommend something short and memorable.
Having a version in the URI is a mixed blessing. I got stuck with '0.1'
in FOAF and migrations can be painful. But breaking things up by
publication year (eg. '2009' as suggested) is a common design.

cheers,

Dan

--
http://danbri.org/

[Joseph Smarr]

For xrds we use http://portablecontacts.net/spec/1.0 -- would that
also be a good choice for a versioned xml namespace? Thanks, js

[Martin Atkins]

N. Jones wrote:
> I agree with Martin, it can be simple. However I would put some versioning
> data in the URL even if it's just the year. This will allow for locking in
> to a version to avoid compatibility issues if/when they come up.
>
> This also has the side-effect of making it a browse-able page specific to
> this namespace, if we choose to throw something up there...
>
> I would suggest: http://portablecontacts.net/2008
>
> Where 2008 is the year PoCo was started.
>

I did consider this, but figured that there's no versioning on the
serializations used by the core protocol, so if versioning is necessary
that would be the correct place to add it rather than at the XML
namespace level.

Would you agree?

[Martin Atkins]

Joseph Smarr wrote:
> For xrds we use http://portablecontacts.net/spec/1.0 -- would that
> also be a good choice for a versioned xml namespace? Thanks, js
>

Ahh yes, I didn't see that when I was scanning the spec.

That could be a reasonable choice, if we want to tie the version number
of the schema and the version number of the protocol together. (I can't
think of any reason not to, but I just wanted to make it clear that this
is what we're doing. :) )

[Dan Brickley]

On 2/1/09 22:23, Joseph Smarr wrote:
> For xrds we use http://portablecontacts.net/spec/1.0 -- would that
> also be a good choice for a versioned xml namespace? Thanks, js

Seems reasonable, although as Martin mentions it could bite if you find
the protocol versus the vocabulary/schema aspects of PC evolving on
different schedules.

Are you happy making /spec/1.0 dereference to an XML or XHTML document?

If I draft an XSLT doc expressing mappings to FOAF (and possibly other
schemas) could it be linked with GRDDL declarations from there?

If so I'll knock up a demo of PC data being mixed with other stuff
(FOAF+DOAP might be nice) and queried with SPARQL...

[Martin Atkins]

I also meant to point out the disadvantage of putting an explicit
version number on an XML namespace:

If you ever increment the version, you're instantly incompatible with
the previous version in all respects, since your elements now
effectively have different names.

Of course, this remains a hot issue within the XML community, so I'm
speaking only to my viewpoint here, but it seems to me that keeping
schemas backwards-compatible is much easier than keeping protocols
backwards-compatible, so my usual inclination is to keep versioning out
of the schema and instead just define all new versions to be a superset
of the previous version, with the possibility of deprecating
now-redundant elements.

[Joseph Smarr]

Right now it dereferences to the spec doc, which is generated from
xml2rfc, and not sure if it's valid xhtml or not. Does that work, or
does it need to be a different doc with special metadata? Thanks, js

On 1/2/09, Dan Brickley <dan...@danbri.org> wrote:
>

[Scott Seely]

The XMLNS should also have a version number of some sort embedded so
that one can differentiate between different iterations of the spec.
When building the schema, please reference the XSD used by OpenSocial.
If the XSD is wrong in some form, OpenSocial needs to know since we are
trying hard to keep the info in sync.

Alternatively, PoCo could link the XSD to a single version of the
OpenSocial schema, specifying that PoCo uses an established subset of
the XSD.

A third alternative: PoCo gets to define the base XSD and OpenSocial has
their XSD reference PoCo.

Regardless, please look at using the OpenSocial 0.9 Draft XSD
(http://sites.google.com/site/opensocialdraft/Home/restful-protocol-spec
ification#TOC-XML-format-XSD) as a starting point.

[N. Jones]

The XMLNS version doesn't need to increment every time the PoCo spec gets a new version number or adds new parameters, however if a breaking point such as all returned XML is nested to look like an array even if its the only one element or something.

Then the thought was we should be able to at least separate out that schema, because it will be consumed differently and has a high chance of breaking in existing implementations. So the XMLNS could be a big clue to breaking changes.

Nika

[Martin Atkins]

N. Jones wrote:
> The XMLNS version doesn't need to increment every time the PoCo spec gets a
> new version number or adds new parameters, however if a breaking point such
> as all returned XML is nested to look like an array even if its the only one
> element or something.
>
> Then the thought was we should be able to at least separate out that schema,
> because it will be consumed differently and has a high chance of breaking in
> existing implementations. So the XMLNS could be a big clue to breaking
> changes.
>

Fair enough, but having a hypothetical version 2.0 of the
PortableContacts spec still using a namespace with 1.0 in it has the
potential to be confusing.

However, I would say that changing the namespace just to fiddle with
things like how plural fields are encoded would be irresponsible. We
should just pick one approach and stick with it; implementation
experience while creating this iteration of the spec should tell us
which is the right choice.

(And with that in mind, is anyone actually consuming the XML output of
PortableContacts right now? I'd be interested to see a Java or .NET
implementation using these amazing XML APIs I keep hearing so much about!)

[Dan Brickley]

On 3/1/09 00:25, Martin Atkins wrote:
> N. Jones wrote:
>> The XMLNS version doesn't need to increment every time the PoCo spec gets a
>> new version number or adds new parameters, however if a breaking point such
>> as all returned XML is nested to look like an array even if its the only one
>> element or something.
>>
>> Then the thought was we should be able to at least separate out that schema,
>> because it will be consumed differently and has a high chance of breaking in
>> existing implementations. So the XMLNS could be a big clue to breaking
>> changes.
>>
>
> Fair enough, but having a hypothetical version 2.0 of the
> PortableContacts spec still using a namespace with 1.0 in it has the
> potential to be confusing.

Yup. We may be overthinking this :)

How about http://ns.portablecontacts.net/pc or
http://ns.portablecontacts.net/pc

This could be succeeded or augmented by numbered (or dated) versions in
the future should the need arise. And it could for now redirect to the
HTML (HTML4 currently) spec, without being directly shackled to it forever.

Putting it on a separate subdomain allows it to be managed separately
from whatever choices are made for the main site. Eg. the latter could
be made into a Drupal, Wordpress or Wiki installation without messing up
the integrity of the namespace documents. But then a simple Apache
directive could do the same.

> However, I would say that changing the namespace just to fiddle with
> things like how plural fields are encoded would be irresponsible. We
> should just pick one approach and stick with it; implementation
> experience while creating this iteration of the spec should tell us
> which is the right choice.
>
> (And with that in mind, is anyone actually consuming the XML output of
> PortableContacts right now? I'd be interested to see a Java or .NET
> implementation using these amazing XML APIs I keep hearing so much about!)

I started on an import-to-SPARQL tool that consumes the XML flavour.

http://svn.foaf-project.org/foaftown/foafablecontacts/

The XSLT barely exists, but it gets some data from Joseph's old
vcard-to-pc tool into an RDF database and queries it with SPARQL.

[N. Jones]

I like the idea of the subdomain http://ns.portablecontacts.net/pc looks good to me.

and we're using the XML output but it's consumed by PHP :)

Nika

[Dan Brickley]

On 2/1/09 23:03, Joseph Smarr wrote:
> Right now it dereferences to the spec doc, which is generated from
> xml2rfc, and not sure if it's valid xhtml or not. Does that work, or
> does it need to be a different doc with special metadata? Thanks, js

I think it'd need to be real XML. As I understand it (see
http://www.w3.org/TR/grddl/#ns-bind and
http://en.wikipedia.org/wiki/GRDDL#XML_.26_Transformations ) various XML
formats, or XHTML, would be fine. I guess you could probably even
content-negotiate non-XML HTML and an XHTML flavour if needed, though
that'd probably be overkill.

Actually I'm finding the GRDDL documentation focusses more on HTML-based
markups, like microformats. But the XML schema support is there, just a
little confusingly documented. One example is:

[[
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http:.../Order-1.0"
targetNamespace="http:.../Order-1.0"
version="1.0"
...
xmlns:data-view="http://www.w3.org/2003/g/data-view#"

data-view:transformation="http://www.w3.org/2003/g/embeddedRDF.xsl" >
<xsd:element name="Order" type="OrderType">
<xsd:annotation
<xsd:documentation>This element is the root
element.</xsd:documentation>
</xsd:annotation>
...
<xsd:annotation>
<xsd:appinfo>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<rdf:Description rdf:about="http://www.w3.org/2003/g/po-ex">
<data-view:namespaceTransformation
rdf:resource="grokPO.xsl" />
</rdf:Description>
</rdf:RDF>
</xsd:appinfo>
</xsd:annotation>
...
]]

...which is an example of XSD that can live at a namespace URI, and
which when parsed using GRDDL, reveals an RDF statement saying:

<http://www.w3.org/2003/g/po-ex> stands in a <namespaceTransformation>
relationship to the XSLT document <grokPO.xsl>. Meaning that anyone
encountering XML instance data using <http://www.w3.org/2003/g/po-ex>
can run that XSLT against the instance to extract RDF statements
compatible with SPARQL, RDFa, and merge-able with other RDF data.

It looks from
http://validator.w3.org/check?uri=http%3A%2F%2Fportablecontacts.net%2Fdraft-spec.html&charset=%28detect+automatically%29&doctype=Inline&group=0

...as if the current format is valid HTML rather than XHTML, and with
106 warnings. The HTML validator doesn't like <br /> and <hr />, since
these are XHTMLisms.

Probably easiest is to put a tiny little XHTML document at the ns URI,
which points to the appropriate spec page, to the project homepage, and
doesn't do a lot else.

Here is what the XHTML folk do, for example: http://www.w3.org/1999/xhtml/

[Edward Vielmetti]

this, i suspect, is one reason people use JSON - to
avoid layers upon layers of layers.

--
Edward Vielmetti
Ann Arbor, MI

+1 734 330 2465

[Dan Brickley]

On 3/1/09 01:53, Edward Vielmetti wrote:
> this, i suspect, is one reason people use JSON - to
> avoid layers upon layers of layers.

Doubtless. It's also the reason others use HTML, or XHTML, or plain XML,
or even raw SQL. The art is finding a way to defragment data that's
split across these different (and all quite reasonable) environments. I
quite like CSV files, is it ok to admit that? :)

[Joseph Smarr]

Ok, how's this for a proposal:

 

1) Use http://portablecontacts.net/schema/1.0 for the namespace, and have it dereference to the XSD file or whatever else you need for GRDDL etc. to work well with PoCo XML.

 

2) Start with the OpenSocial XSD that Scott pointed you to. Make any changes you think are necessary to make the XSD perfectly compliant with the spec, and tell Scott about any changes you had to make along the way.

 

3) I'm torn between asking OpenSocial to then adopt the Portable Contacts schema vs. keeping their own copy that is nevertheless identical. The latter is more in keeping with how we've handled the alignment thus far (intended to remain the same, but not forcibly joined), but wouldn't the former really be necessary so that a client could treat any OpenSocial RESTful provider transparently as a Portable Contacts provider? I guess the same is true for XRDS, except there it's fine to list multiple Service Types (i.e. OS REST and PoCo) whereas you only get one namespace. The clear spirit of the alignment was "If you are a compliant OpenSocial RESTful provider, then you are automatically a compliant Portable Contacts provider too". So please suggest a resolution to how we share/duplicate schemas that makes that statement true.

 

Thanks! js

[Justin du coeur]

On Fri, Jan 2, 2009 at 6:25 PM, Martin Atkins <ma...@degeneration.co.uk> wrote:

(And with that in mind, is anyone actually consuming the XML output of
PortableContacts right now? I'd be interested to see a Java or .NET
implementation using these amazing XML APIs I keep hearing so much about!)

Not yet, but only because I'm currently distracted over onto other priorities.  As soon as I have the available cycles, I expect to get my system (CommYou, which is Java-based) consuming PoCo, probably through the XML API...

[Scott Seely]

#3 gets into what we put as the targetNamespace in the XSD. To make these equivalent, we can also go to the step of creating an XSLT that allows one to simply transform between the XMLNS. This particular XSLT would be trivial to create, but violates the equivalence spirit. Perhaps we should relax the statement to articulate that the two are wire compatible with respect to JSON, simple transformation compatible with respect to XML/Atom? I think this is an appropriate compromise as it recognizes that the two groups evolve at a different pace and have related but separate concerns.

 

From: portable...@googlegroups.com [mailto:portable...@googlegroups.com] On Behalf Of Joseph Smarr
Sent: Saturday, January 03, 2009 7:42 AM
To: portable...@googlegroups.com
Subject: Re: PortableContacts schema XML namespace

 

Ok, how's this for a proposal:

[Joseph Smarr]

I think we *should* have them compatible in XML too; some developers just find XML easier to work with than JSON, and I don't think that should impact whether an OpenSocial container "just works" for them as a Portable Contacts consumer.

So if I understand you correctly, are you saying the XMLNS associated with the PoCo XML tags is a (potentially) different URI than the targetNamespace in the XSD? And given that the specs are currently aligned, if we can break out the PoCo schema into a separate XSD, say http://portablecontacts.net/schema/1.0 then wouldn't it be reasonable for OpenSocial to use that for now? And if/when we decide we can't keep compatibility going forward (which hopefully won't happen in the first place), then you could just switch to a new namespace, which would be appropriate anyway, no?

Thanks, js

[Scott Seely]

Again—it depends on how compatible they need to be. Do they need to be XML Infoset compatible or do they simply need to be structurally similar with identical Local Names on all common representations? When this was brought up earlier on the OpenSocial list, we chose to take the latter approach (http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/27a2f9d86d55b33b).  

 

Does Infoset compatibility help things or is structure/node name compatibility sufficient? In JavaScript, node name compatibility is good enough. The same is roughly true for .NET, Java, and other parsers. This only becomes an issue when validating the structure, and most work I’ve done with XML outside of automated serializers avoids validation when possible, treating the XSD as documentation instead of a hard requirement.

[Martin Atkins]

Scott Seely wrote:
> Again—it depends on how compatible they need to be. Do they need to be
> XML Infoset compatible or do they simply need to be structurally similar
> with identical Local Names on all common representations? When this was
> brought up earlier on the OpenSocial list, we chose to take the latter
> approach
> (http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/27a2f9d86d55b33b).
>
> Does Infoset compatibility help things or is structure/node name
> compatibility sufficient? In JavaScript, node name compatibility is good
> enough. The same is roughly true for .NET, Java, and other parsers. This
> only becomes an issue when validating the structure, and most work I’ve
> done with XML outside of automated serializers avoids validation when
> possible, treating the XSD as documentation instead of a hard requirement.
>

I'm not sure what this impacts from an implementation standpoint -- most
XML libraries I've dealt with have been namespace-sensitive, but I only
really deal in languages where folks would use JSON anyway -- but having
two namespaces for the same schema just seems needlessly confusing.

If OpenSocial already has the elements in a different namespace, then we
should just adopt that namespace for PortableContacts. The URI used for
the namespace is not important.

[Scott Seely]

Most libraries understand the XML Infoset but also support working with
the local name of the node instead of the qualified name. I'm not aware
of any parsers that only use QNames.

Anyhow-- looping in the OpenSocial community to see if anyone has a
strong opinion on which way to proceed. I think that we'll want to stick
with the status quo of separate, similar until one or both of the groups
is willing to commit to keeping the schema/structure of the common
elements stable.

> -----Original Message-----
> From: portable...@googlegroups.com
> [mailto:portable...@googlegroups.com] On Behalf Of Martin Atkins
> Sent: Monday, January 05, 2009 11:22 AM
> To: portable...@googlegroups.com
> Subject: Re: PortableContacts schema XML namespace
>
>

> Scott Seely wrote:
> > Again-it depends on how compatible they need to be. Do they need to

[Simon Perreault]

On Monday 05 January 2009 14:22:14 Martin Atkins wrote:
> I'm not sure what this impacts from an implementation standpoint -- most
> XML libraries I've dealt with have been namespace-sensitive

From an implementation standpoint, elements in different namespaces that
happen to have the same local name are *not* the same. Using e.g. libxml, it
is as easy to search for a fully-qualified element name as it is to search for
a given local name. I would expect new applications to be namespace-aware.

For example, there are many extensions to WebDAV and each has its own
namespace. Tags from different namespaces are frequently mixed in WebDAV
queries and responses. It is important for WebDAV applications to be
namespace-aware. (Mine are!)

Therefore, I would argue for the two schemas to describe elements in a single
standard namespace.

Furthermore, why would it be wrong if two completely separate schemas
described the same set of elements? It is common to do so with e.g. an XML
Schema schema and a Relax NG schema, one language patching the holes in the
other. Even adding Schematron in the mix is common. You end up with multiple
documents describing the same thing, which is far from being a bug.

Cheers,
Simon

--
Please try Numb, a STUN/TURN server implementation.
Free access at http://numb.viagenie.ca/.

[Dan Brickley]

On 3/1/09 16:41, Joseph Smarr wrote:
> Ok, how's this for a proposal:
> 1) Use http://portablecontacts.net/schema/1.0 for the namespace, and
> have it dereference to the XSD file or whatever else you need for GRDDL
> etc. to work well with PoCo XML.

+1

> 2) Start with the OpenSocial XSD that Scott pointed you to. Make any
> changes you think are necessary to make the XSD perfectly compliant with
> the spec, and tell Scott about any changes you had to make along the way.

I'll have a go. May end up using indirection as the ultimate solve-all
and pointing to whatever XSDs there are around.

> 3) I'm torn between asking OpenSocial to then adopt the Portable
> Contacts schema vs. keeping their own copy that is nevertheless
> identical. The latter is more in keeping with how we've handled the
> alignment thus far (intended to remain the same, but not forcibly
> joined), but wouldn't the former really be necessary so that a client
> could treat any OpenSocial RESTful provider transparently as a Portable
> Contacts provider? I guess the same is true for XRDS, except there it's
> fine to list multiple Service Types (i.e. OS REST and PoCo) whereas you
> only get one namespace. The clear spirit of the alignment was "If you
> are a compliant OpenSocial RESTful provider, then you are automatically
> a compliant Portable Contacts provider too". So please suggest a
> resolution to how we share/duplicate schemas that makes that statement true.
> Thanks! js

Good to have that high level goal written down. Extensible schema
evolution design is hairy stuff. I'll try to have you a GRDDL-compatible
proposal that fits whatever the latest W3C advice is
(http://www.w3.org/2001/tag/doc/nsDocuments-2008-06-25/ seems relevant,
RDDL also). I'm offline much of next week but will see what I can get done.

Are there plans to extend the OpenSocial formats in ways that go beyond
what you'll want to directly include in PC?

cheers,

Dan

[Kevin Marks]

No, we can indulge your RDF fetishes, but CSV is a mess. JSON codifies well what CSV gets hideously wrong:

The Microsoft version of CSV is a textbook example of how not to design a textual file format. Its problems begin with the case in which the separator character (in this case, a comma) is found inside a field. The Unix way would be to simply escape the separator with a backslash, and have a double escape represent a literal backslash. This design gives us a single special case (the escape character) to check for when parsing the file, and only a single action when the escape is found (treat the following character as a literal). The latter conveniently not only handles the separator character, but gives us a way to handle the escape character and newlines for free. CSV, on the other hand, encloses the entire field in double quotes if it contains the separator. If the field contains double quotes, it must also be enclosed in double quotes, and the individual double quotes in the field must themselves be repeated twice to indicate that they don't end the field.

The bad results of proliferating special cases are twofold. First, the complexity of the parser (and its vulnerability to bugs) is increased. Second, because the format rules are complex and underspecified, different implementations diverge in their handling of edge cases. Sometimes continuation lines are supported, by starting the last field of the line with an unterminated double quote — but only in some products! Microsoft has incompatible versions of CSV files between its own applications, and in some cases between different versions of the same application (Excel being the obvious example here).

http://www.faqs.org/docs/artu/ch05s02.html