W3C home > Mailing lists > Public > w3c-rdfcore-wg@w3.org > November 2002

Primer draft review - syntax section

From: Dave Beckett <dave.beckett@bristol.ac.uk>
Date: Wed, 06 Nov 2002 14:42:47 +0000
To: w3c-rdfcore-wg@w3.org
Message-ID: <28467.1036593767@hoth.ilrt.bris.ac.uk>


Primer draft
http://www.w3.org/2001/09/rdfprimer/rdf-primer-20021031.html

(also reading Brian's comments at
http://lists.w3.org/Archives/Public/w3c-rdfcore-wg/2002Nov/att-0120/01-rdf-primer-20021031.html
)

Sec 1

+1 to Brian's suggestion of an RDF graph here.

Sec 2

+1 on Brian's comments to de-emphasising N-Triples a little.  Just
describe it as a simple triples syntax.

s/untyped literals/plain literals/ since that's what Concepts and
Syntax WD use now.

Add some links to the Concepts sections/definitions for RDF URI
References, Literals, Typed Literals, RDF Graphs, Nodes, Triples,
... maybe?


Sec 3 An XML Syntax for RDF

Maybe stick the example in an attached RDF/XML file, link to it, so
it can be machine checked?

"rdf:RDF start-tag" => more correctly, this is called the XML
document element or root element.  So the sentence could be changed
to:

  [[Following the rdf:RDF on this same line is an XML namespace
  declaration, represented as an xmlns attribute on the rdf:RDF
  document element.]]

"... prefixed with rdf: are part of the namespace identified by ..."

maybe refer to the RDF Namespace and point to it:
"... prefixed with rdf: are part of the [RDF Namespace] identified by ..."
linking to http://www.w3.org/TR/rdf-syntax-grammar/#section-Namespace


Consistency;  the exterms:creation-date in the triple representation
turns into ex:creation-date.  I'd suggest using the same prefix.


Line 3 para
  More s/start-tag/document element/

Line 4-6 para
  "is to say it's a" => "is to say its a" ?
    (I'm rubbish at apostrophies, check this)

  "This is exactly the RDF/XML represents the statement. "
   =>
  "This is how RDF/XML represents the statement. "

  "that we're starting a description, "
  =>
  "that we're starting a description of a resource", 

 " to hold the value "
 =>
 " to hold the string literal value "

 "It is nested within the preceding rdf:Description element,
 indicating that this property applies to the resource specified in
 the containing rdf:Description element."
 =>
 "It is nested within the containing rdf:Description element,
 indicating that this property applies to the resource specified in
 the rdf:about attribute of the rdf:Description element."

 "The complete URIref of the creation-date property corresponding to
 the QName <ex:creation-date> would be obtained by replacing the ex:
 prefix by the namespace URI defined for it in Line 3"
 =>
 "The URIref of the creation-date property corresponding to
 the QName <ex:creation-date> is obtained by appending the
 name creation-date to the URI of the ex: prefix
 http://www.example.org/terms/ giving
 http://www.example.org/terms/creation-date"


para "In this case, in Line 8 ..."

 "Because the URIref is being used as an attribute value, we cannot
 abbreviate it as a QName, as we've done in writing element and
 attribute names (this is due to the need to conform to XML
 syntax). Instead, we must write it out as a full URIref."

not quite right; since XML doesn't require that.  It is up to
individual XML formats to decide if attribute values take qnames
or URIs.

I'd either delete this sentence or say RDF/XML requires it.

para 
  It is important to understand that the RDF/XML in the above two
  examples are abbreviations. The RDF/XML below, in which all
  resources are represented with separate rdf:Description elements,
  and each statement is written separately, describes exactly the
  same RDF graph: 

is crying out for links!  "above two examples", "rdf/xml below" and
"same graph"

I'm wondering if you need to introduce the idea of abbreviations or
alternate ways to write RDF/XML earlier on?


  "All blank nodes are assigned arbitrary URIs or blank node identifiers."

No.

  "All blank nodes are given blank node identifiers."

They are not given arbitrary URI(refs)

  "Each resource is listed in turn as the subject of an un-nested
  rdf:Description element, using an rdf:about attribute.

unless they are blank, in which case rdf:nodeID must be used.

  " For each triple with this resource as subject, an appropriate
  property element is created, with either literal content (possibly
  empty) or an rdf:resource attribute specifying the object of the
  triple."

unless the object node is blank in which case rdf:nodeID is used on
the property element.

I don't define such a basic serialization syntax in the current
syntax WD, I should think about doing this.

sec 3.2

I'd avoid the defining word in the title

This is always description, the rdf:ID stuff is shorthand for
URI-refs that are close to the document URI (or base URI, xml:base
and so on)

You might want to introduce base URI explicitly rather than after
describing the example.  (I note that relative, base URIs stuff is
hard to explain clearly.)

...

  "The example also illustrates the fact that the RDF describing a
  particular resource does not need to be located all in one place;
  instead, it may be distributed throughout the web."

I'd avoid "the fact" in my personal style.  Just s/the fact that the/that/

sec 3.3

  "One of the abbreviations allowed by RDF/XML is that when properties
  are not repeated within an rdf:Description element,"
   ... property elements are not ...

PLUS the values must be literal strings with the same language (xml:lang)

And that ignores rdf:type which can be also be moved, only if it
points at a node with URI-ref.


The example of parseType="Literal" has typos, bad XML. Plus I changed
the internal content to use a:Box so as not to confuse with the
parseType "Collection".  Correct to:

----------------------------------------------------------------------
1.  <?xml version="1.0"?>
2.  <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
3.              xmlns:ex="http://example.org/stuff/1.0/">

5.     <rdf:Description rdf:about="http://example.org/item01">
6.       <ex:prop rdf:parseType="Literal"
7.             xmlns:a="http://example.org/a#><a:Box required="true">
8.             <a:widget size="10" />
9.             <a:grommit id="23" />
10.          </a:Box></ex:prop>
11.    </rdf:Description>

12. </rdf:RDF>
----------------------------------------------------------------------
(or check with syntax wd example when it appears)


I'm wondering if this example needs to be here at all.  Maybe this
stuff is something we shouldn't include.

--

skipping to 4.3.3

Is this something we are keeping?

A bit of duplication with (current draft)
http://ilrt.org/discovery/2001/07/rdf-syntax-grammar/#section-rdf-in-HTML
although this section covers motivations.

6.4

There is a lot of text here, who owns this?

6.5

the RDF/XML here could do with a bit of indenting for readability


END OF REVIEW


General:

Add figure numbers for the examples you are using with line numbers
so that way you can say when you add stuff, you can compare to
previous versions.  Such as when you do things in the example after
fig 11 (see, I can't point at it with a link!) you can compare with
the example, a few paragraphs back.
  "Compared with the previous two examples, " <= links :)

Link to various things defined in RDF concepts:
  Node, Triple, RDF Graph, RDF URI Reference, Literal,
  Plain Literal, Typed Literal, Blank Node, Blank Node Identifier

Rename the WDs:
  RDF Schema => RDF Vocabulary ... 1.0: RDF Schema (shorthand, RDF Vocabulary)
  RDF Model Theory => RDF Semantics ...
  RDF Concepts and Abstract Data Model => RDF Concepts and Abstract Syntax
etc. and remember to update the references.

You might want to cite the exact abbreviations used pointing to the
newest syntax WD, there should be sections for them all.

Some of these values like "very" and "easier" are pretty subjective;
you might want to just place them as alternatives or say "may be easier"
etc.

I'm wondering also if we'd rather omit some of these abbreviations in
the Primer to discourage their use.  I'd vote for ignoring 1)
property attributes and 2) property attributes on an empty property
element.


I see no show stoppers not already covered by Brian.

Dave
Received on Wednesday, 6 November 2002 09:42:53 EST

This archive was generated by hypermail pre-2.1.9 : Wednesday, 3 September 2003 09:53:59 EDT