Re: Target audience of the Direct Mapping document?

On 11 Jul 2011, at 14:04, Juan Sequeda wrote:
>> [[
>> The ROW GRAPH for a row is an RDF graph containing the following triples:
>> * one FOREIGN KEY TRIPLE for each foreign key of the table, if the row's fields corresponding to the foreign key's columns are all non-null
>> * one DATA TRIPLE for each non-null field of the row, except for fields of a column that has a single-column foreign key defined over it
>> * a ROW TYPE TRIPLE for the row
>> ]]
>> 
>> Where the all-caps terms expand again to definitions like:
>> 
>> [[
>> The ROW TYPE TRIPLE for a row is an RDF triple with the following components:
>> * subject: the ROW NODE for the row
>> * predicate: rdf:type
>> * object: the TABLE CLASS IRI for the row's table
>> ]]
>> 
>> And so on. That's easy to read without having to learn or decipher any special notation, and it's precise (or can be made so). Admittedly it's more verbose by a factor of two or three.
>> 
> 
> But we have that in http://www.w3.org/2001/sw/rdb2rdf/directMapping/#rules
> 
> As you can see, in section 2 we introduce Table Triple, Literal Triple and Reference Triple. In Section 4, we make reference to these same names

A normative section can't reference an informative section, because the direct mapping should still be unchanged if all the informative stuff (notes, examples etc) was deleted.

I didn't look at Section 2 in a while because it's only marked as informative. You are right, it follows the style I'm advocating to a certain degree.

Problems with Section 2 include:

The definitions are interspersed with very large examples, making it hard to find the actual definitions. Examples don't need to be exhaustive or overwhelming -- we have the test cases document for that.

The definitions itself are also more verbose than they have to be. For example, you have:

“Table IRI: The IRI that identifies a table is created by concatenating the base IRI with the table name. Specifically, if base_IRI is the base IRI and table_name is the table name, then base_IRI/table_name is the Table IRI for the table.”

This contradicts itself ('/' between base IRI and table name or not?). It forgets the percent-encoding. And it can be stated so much shorter:

“The Table IRI of a table is the concatenation of the base IRI and the percent-encoded table name.”

Or look at the definition for Column IRI -- the single-column case doesn't need its own case at all, because it can be handled by the multi-column case.

Or this:

“Literal Triples: Each column with a non-null value, including the column(s) that constitute the primary key, and that either is not the only constituent of a foreign key or is the only constituent of a foreign key that references a candidate key, generates a triple with the following:”

I gave a definition of ROW GRAPH above, it contains all of this (except the candidate key bit, which I think we decided should not be done (?)) in half as many words.

Best,
Richard

Received on Monday, 11 July 2011 18:43:41 UTC