Review of RDFa Core 1.1 (Dec. 15th 2011)

This is a review of the RDFa Core 1.1 specification dated December 15th
2011. I reviewed the document checking for grammar, spelling and
technical concerns. It took 5 hours to read the entire document and
comment on it... I would expect it to take longer for someone reading
the document for the first time. I don't think that's a good thing, but
don't think we should remove anything from the document either.

Thanks again to the editors of this document (as well as the rest of the
documents), and especially to Shane, for sticking with it for so long,
always being on top of things, and for being an all around great guy...
the entire WG owes you a beer (or five hundred). I only found one thing
that could be a non-editorial issue and it's really not that big of an
issue.

Abstract
--------

The Abstract is still not succinct. I vaguely remember promising to
provide an alternate and I have yet to do so. :(

> already available in the markup language (e.g., XHTML)

I think we should just use "HTML" here instead of "XHTML" because it is
our largest target market. (yes a little bit of me just died suggesting
that)

> please consult the RDFa Primer.

RDFa Primer link is wrong, use this one instead:

http://www.w3.org/TR/rdfa-primer/

How to Read this Document
-------------------------

> then you may find the RDFa Primer [RDFA-PRIMER]

Link is wrong, reference is wrong in bibliography, point to the new RDFa
Primer. This is the case throughout the document, I'm sure once you
clean up the bibliography that all references will take care of themselves.

2. Syntax Overview
------------------

The note at the end needs to be updated to Jeni's new text.

2.1 The RDFa Attributes
-----------------------

In hindsight, I think we should've named "CURIEs" - "SIRIs", for "Short
IRI". I hesitate to say that we should do this now because of everyone
that knows what a CURIE is at this point... and all the other specs that
it's gone into. I'm on the fence... I think SIRI would be best
long-term... maybe.

2.2 Examples
------------

> it's possible with RDFa to indicate the type of that item using
> @typeof:

Hmm, this example is a bit mis-leading as it creates a new bnode and the
data isn't associated with the page anymore. Maybe we should use the
book example w/o @typeof and the book example with @typeof to
demonstrate @typeof. So, the example below this one is moved up and
@typeof is removed, the next example should also be the book example,
but with @typeof added.

3.2 Triples
-----------

> The second part of a triple is the property

Should 'property' be italicized to match the style for 'subject' above?

> These are more usually called predicates in RDF.

The sentence is a bit strange... maybe:

"These properties are typically called /predicates/ in RDF."

3.3 IRI references
------------------

Should "references" be capitalized?

> the predicate

Terminology issue - I think we should be using "property" here and in
the rest of the document when referring to "predicate"s. I think it's
easier for people to grasp what a property is without having to learn
about RDF's strange language.

> 'Friend of a Friend' taxonomy.

We should use "vocabulary" instead of "taxonomy" here.

3.9 Markup Fragments and RDFa
-----------------------------

> (A good example of the latter is the licensing fragment provided by
> Creative Commons.)

Does this entire sentence need to be parenthetical? Probably not.

3.10 A description of RDFa in RDF terms
---------------------------------------

Does the title need to be capitalized?

> The aim of RDFa is to allow a single RDF graph to be carried in
> various types of document markup. An RDF graph comprises nodes linked
> by relationships.

May want to switch the second sentence the first sentence - we use the
definition before it is defined.

> the predicate is always

Change to "the property is always"?

4.1 RDFa Processor Conformance
------------------------------

The start of the section is slightly confusing. It says an RDFa
processor MUST make a single output graph available, but then describes
this thing called the processor graph - does an RDFa processor need to
make that available too? Is that a MAY? I'm pretty sure we intended it
to be a MAY. So, you might want to reword this to say an RDFa processor
MUST make at least the output graph available and MAY make the processor
graph available.

4.3 XML+RDFa Document Conformance
---------------------------------

This is non-editorial. I don't think people will do this:

> The document must use the attributes defined in this specification
> through references to the XHTML namespace
> (http://www.w3.org/1999/xhtml).

I think they'll use the RDFa attributes in the 'no namespace' context...
and I think the spec should say that doing that is fine. If people don't
want to do that, then they can use the XHTML namespace.

5. Attributes and Syntax
------------------------

> a traditionally navigable URI for expressing

This should be IRI, no? There are other mentions of URI in this section
that we'd want to change to IRI.

> property ... used for expressing relationships between a subject and
>  some literal text

This is no longer true as @property can be used for resources as well.

> An attribute (value ignored)

Move the parenthetical out into another sentence to make it more clear
about what "value ignored" means.

> Causes a list to be created if it does not already exist

Missing a period at the end of the sentence.

7.1 Overview
------------

2nd Note - we may want to mention something about the processor graph here?

7.4 CURIE and IRI Processing
----------------------------

> In RDFa these mappings are expressed using the XML namespace syntax:

Not anymore, they're not! :)

> The author is free to split the IRI at any point, as long as it
> begins at the left end.

I don't know what "begins at the left end" means. Do we need that? Why
isn't "The author is free to split the IRI at any point." good enough?

7.5 Sequence - Step 2
---------------------

> In such a case, setting @vocab to the empty value has the effect of
> clearing the local default vocabulary.

I don't think this is clear enough. If the @vocab is set via the default
vocabulary, it is cleared? Or if it is set to something, it is cleared?
My assumption is that if you do vocab='' it is cleared in all cases,
even if a default vocabulary is specified.

7.5 Sequence - Step 2
---------------------

> Note that a IRI mapping will simply overwrite

/an/ IRI mapping

7.5 Sequence - Step 5.1
-----------------------

> but does not contains neither the @content nor @datatype attributes

but does not /contain either/ the @content /or the/ @datatype /attribute/

> is set the IRI from the first value

is set /to/ the IRI ?

7.5 Sequence - Step 5.2
-----------------------

> otherwise:

No need to italicize this.

> contains a @about

contains /an/ @about

7.5 Sequence - Step 11
----------------------

This step made my brain hurt... the new algorithm feels twice as
complicated as the old one due to the RDFa Lite 1.1 changes. I don't
think there is any way we can simplify it without getting folks upset
about dropped features.

7.5 Sequence - Step 12
----------------------

> This list is iterated and is and each of the predicates is used

This list is iterated and /DELETE/ each of the predicates is used

7.5 Sequence - Step 12
----------------------

> For each IRI in the local list mapping, if the equivalent list does
> not exist in the evaluation context, indicating that the list was
> originally defined on the current element, use the list as follows

Awkward sentence is awkward.

> For each pair of bnode and IRI from the list the following triple

For each /bnode-IRI pair/ in the list/,/ the following triple

7.6 Processor Status
--------------------

> The processor graph is designed as a possible mechanism

The processor graph is designed as the mechanism

> generation of a processor graph,

Missing <tref>

> host language

Host Language should be capitalized like it is in the rest of the
document, no?

> rdfa:Info, rdfa:Warning, or rdfa:Error triples may

We should have <code> elements around rdfa:Info / rdfa:Warning / etc.

7.6.2 Processor Graph Terms
---------------------------

> Other, implementation-specific subclasses

Unnecessary comma

7.7 Vocabulary Expansion
------------------------

> Processors may perform limited RDFS entailment rules to perform
> vocabulary expansion

rephrase:

Processors MAY perform vocabulary expansion by utilizing limited RDFS
entailment rules,

8.1 Changing the evaluation context
-----------------------------------

capitalization issue

8.1.1.1 The current document
----------------------------

In section 8, we say "The examples are all written using XHTML+RDFa.",
but then we use plain 'ol HTML5 in the examples. We may just want to say
that the examples are written in "HTML+RDFa".

> In (X)HTML the value of base may change the initial value of current
>  subject:

This isn't an XHTML document, is it? No xmlns declaration?

> <http://www.example.org/jo/blog> foaf:primaryTopic <#bbq> .

This triple is wrong, no? #bbq should be
http://www.example.org/jo/blog#bbq ?

8.1.1.3 Typing resources with @typeof
-------------------------------------

> <div  about=

In space, no one can hear you scream.

8.3.1 Object resolution for the @property attribute
---------------------------------------------------

The image is too small to make out what it says.

8.3.2.2 Using @href or @src
---------------------------

May want to make this "Using @href or @src to set the subject"?

8.4 List generation
-------------------

capitalization issue "List Generation"

We use "dc:creator" in this section and use text strings and IRIs for
the object. The range of dc:creator in dcterms is supposed to be an IRI,
specifically a http://purl.org/dc/terms/Agent

I suggest we use IRIs for all three authors.

> elements are resources and not literal.

elements are resources and not literal/s/.

10.1 Details of the RDFa Vocabulary Expansion
---------------------------------------------

> Applications usually do not require those additional information.

s/those/any of this/

10.1.1 RDFa Vocabulary Entailment
---------------------------------

> and is based on the RDF-Based Semantics of OWL[

missing space between OWL and [

> and it considers

Sentence starts with "and", rephrase.

> In particular, the relevant rules are (using the rule identifications
> in section 4.3 of [OWL2-PROFILES]):

rephrase:

The relevant rules are, using the rule identifications in section 4.3 of
[OWL2-PROFILES]:

10.2 Vocabulary Expansion Control of RDFa Processors
----------------------------------------------------

> Conforming RDFa processors are NOT required to provide vocabulary
> expansion.

NOT doesn't need to be capitalized, does it?

A. CURIE Datatypes
------------------

> A single curie

CURIE should be capitalized here?

> A white space separated list of CURIEs

No <tref> for CURIE?

> A CURIE or a IRI

External definition link doesn't go anywhere or do anything or say
anything helpful by hovering.

> A single safe_curie

underscores are weird in this context, also shouldn't CURIE be capitalized?

A.1 XML Schema Definition
-------------------------

> <xs:simpleType name="CURIEorIRI"> <xs:union memberTypes="xh11d:CURIE
> xs:anyURI" />

xs:anyURI isn't the exact same lexical space as IRI, is it?

B.2 Processor Graph Reporting
-----------------------------

> "is the

We start a number of these dc:descriptions with the phrase "is the" when
we should just be using "The".

> error condition; warning;

We should be using complete sentences here as well. "A warning to be
used...", "An error condition to be used...", etc. Shane, could you
please make a full pass for grammar on this section?

> B.3 Term for vocabulary expansion

> "provides a

Capitalize the first letter in the sentence, add a period to the end of
the sentence.

C. Acknowledgments
------------------

This list needs to be updated, probably to this:

Stéphane Corlosquet, Massachusetts General Hospital
Ivan Herman, W3C
Gregg Kellogg (Invited Expert)
Niklas Lindström (Invited Expert)
Shane McCarron, Applied Testing and Technology, Inc. (Invited Expert)
Steven Pemberton, Centre for Mathematics and Computer Science (CWI)
Manu Sporny, Digital Bazaar (Chair, Invited Expert)

THE END.

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny)
President/CEO - Digital Bazaar, Inc.
blog: Web Payments - PaySwarm vs. OpenTransact Shootout
http://manu.sporny.org/2011/web-payments-comparison/

Received on Thursday, 19 January 2012 04:49:52 UTC