[Bug 5104] sml 4.2.1 uri scheme

http://www.w3.org/Bugs/Public/show_bug.cgi?id=5104

           Summary: sml 4.2.1 uri scheme
           Product: SML
           Version: unspecified
          Platform: PC
        OS/Version: Windows XP
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Core
        AssignedTo: cmsmcq@w3.org
        ReportedBy: johnarwe@us.ibm.com
         QAContact: public-sml@w3.org


Probably all editorial from the get-go, but change to final bullet some might
feel is non-editorial so I did not mark it editorial.

Original text:
The URI Scheme is based on the anyURI type defined in the XML schema
specification [XML Schema Datatypes]. References that are represented using the
URI scheme MUST be implemented by using the sml:uri global element as a child
of reference elements, i.e., elements for which sml:ref="true".  More
precisely, if a model author chooses to represent references using the URI
scheme,
    *      It MUST represent each reference using an instance of the sml:uri
global element declaration as a child of the reference element.  
    *      It MUST treat each instance of  the sml:uri global element
declaration, whose parent element is a reference element, as a reference
represented in the URI scheme.

Problems:
(1) There is a danger that some readers will see
"More precisely, if a model author chooses to represent references using the
URI scheme,
    *     It MUST represent each reference using..."
and conclude that (in an example document containing 9 sml refs) the choice is
between all 9 using the URI scheme and 0 using it.

(2) This text also mixes concerns of the "model author" (what one might call a
producer) with those of a validator (more generally, consumer).

(3) This text re-states the definition of an SML reference, and then does so
incompletely.  This could be read to mean that sml:ref="1" should not be
recognized as an instance of the URI scheme (which I think is NOT our intent).

Proposal to clarify:
(1) no change:
The URI Scheme is based on the anyURI type defined in the XML schema
specification [XML Schema Datatypes]. 

(2) from:
References that are represented using the URI scheme MUST be implemented by
using the sml:uri global element as a child of reference elements, i.e.,
elements for which sml:ref="true".  

to: i.e., remove final clause and insert SML before ref, plural to singular

Each reference represented using the URI scheme MUST be implemented by using
the sml:uri global element as a child of an SML reference element.  

(3)
from "if                     the model author chooses to represent 
      references using the URI scheme,..."
to   "for each SML reference the model author chooses to represent 
                 using the URI scheme,..."

(4)
from "* It MUST represent each reference  ..."
to   "* The reference MUST be represented ..."

(5) Get rid of the bulleting to separate the concerns of producing a model
document containing instances of the URI scheme from consuming such a document

(6) Rename "URI scheme" to "SML URI Scheme" to be crystal clear.  It is not
difficult to imagine the possibility that other URI ref schemes might be spec'd
later, this is just pre-emptive disambiguation.

(7) Reword the old second bullet, getting rid of It (which de-ref'd back to
"model author" and would be redundant w/ first bullet)
from
* It MUST treat each instance of  the sml:uri global element declaration, whose
parent element is a reference element, as a reference represented in the URI
scheme.
to
SML processors that recognize the SML URI Scheme MUST treat each instance of 
the sml:uri global element declaration whose parent element is a reference
element as a reference represented in the URI scheme.

New consolidated text:
The SML URI Scheme is based on the anyURI type defined in the XML schema
specification [XML Schema Datatypes]. Each reference represented using the URI
scheme MUST be implemented by using the sml:uri global element as a child of an
SML reference element.  More precisely, for each SML reference the model author
chooses to represent using the URI scheme, the reference MUST be represented
using an instance of the sml:uri global element declaration as a child of the
reference element.  

SML processors that recognize the SML URI Scheme MUST treat each instance of 
the sml:uri global element declaration whose parent element is a reference
element as a reference represented in the URI scheme.

Received on Sunday, 30 September 2007 18:35:46 UTC