- From: Irene Polikoff <irene@topquadrant.com>
- Date: Sun, 27 Nov 2016 12:20:23 -0500
- To: kcoyle@kcoyle.net
- Cc: public-data-shapes-wg@w3.org
Personally, I see no problem with any of the passages below. So, I want to pop up this discussion to a higher level. In my experience, given a group of 5 (or even less) people, no wording satisfies everyone. One person may prefer one version of a sentence. Another person prefers a completely different version. They may come to a compromise that satisfies both of them and then a third person will say that they actually made the situation worse and he preferred either one of the previous two versions much better and completely dislikes their compromised version. And so on. This can go on for a very long time and be draining and frustrating for everyone involved. I can’t count the number of times I have experienced this situation in different settings. Yet, progress has to be made and deadlines have to be met. Teams that are committed to delivering recognize that and make compromises - not only in the wording itself, but also in the decisions about when, where and if it is worth to continue to spend time on word smithing and when it is time to stop doing so even if not everyone is satisfied with everything. I believe this approach is used every time a deliverable is produced. Otherwise, no deliverables would ever be delivered. Making the entire specification understandable to all readers can be viewed as an important goal. However, I don’t believe it is ever achieved, especially for a document that is longer than a page or two and discusses fairly complex topics. This is true for pretty much all W3C specs as well. I know from reading other W3C specifications that I often have quite a number of questions about what they actually say. And I know that other people do as well. I also know that the passages I find to be unclear, they find clear and vis versa. Nevertheless, this situation has not prevented these documents from becoming recommendations. Irene > On Nov 27, 2016, at 10:09 AM, Karen Coyle <kcoyle@kcoyle.net> wrote: > > Here are the places where I think "define" is used incorrectly: > > 2.3.3 > A subjects-of target is specified with the predicate sh:targetSubjectsOf, the values of which must be IRIs. For every value p of such a target, the validated nodes are defined as the set of subjects in the data graph that appear in a triple with p as a predicate. > > 3.4 > The validation report is the result of the validation process that reports the conformance and the set of all validation results. The validation report is described with the SHACL Validation Report Vocabulary as defined in this section. This vocabulary defines the RDF properties to represent structural information that may provide guidance on how to identify or fix violations in the data graph. > > 4. > The textual description of each component refers to the concept of value nodes which is defined as follows, including rules for the creation of validation results: > > "The term 'value nodes' used in this section is defined as:" > > ->The part after the comma "including..." ? What does it refer to? What includes this? > > 4.6 Property Pair Constraint Components > > The constraint components in this section restrict the sets of value nodes in relation to other properties. Value nodes of focus node constraints are always defined as a set of size 1 and may produce unexpected results when used with constraint components of this category. > > 4.8.3 > any combination of parameters associated with node validation constraints. A node validation constraint is any constraint defined by a boolean function on nodes. These include the built-in constraints defined by sh:nodeKind, sh:partition, sh:minExclusive, etc. The corresponding subset consists of those remaining nodes for which the boolean function is true. > > ->any combination of parameters associated with node validation constraints. A node validation constraint is any constraint *that is* a boolean function on nodes. These include the built-in constraints sh:nodeKind, sh:partition, sh:minExclusive, etc. The corresponding subset consists of those remaining nodes for which the boolean function is true. > > The following paragraphs define this algorithm more precisely. > > -> drop this, put definition in a box (or some other way that shows that it is not text), and caption it "Algorithm for partition" > > 5.2 > The SHACL vocabulary defines the class sh:PrefixDeclaration for the values of sh:declare although no rdf:type triple is required for them. > > -> defines the class ... as the range/domain? for the values? I don't know what this means > > 6.2.1 Parameter pre-binding > > Every parameter name defines a pre-bound variable for the constraint component the parameter belongs to. > > ->?? how does a name define? What is supposed to be happening here? > > kc > > On 11/26/16 3:19 PM, Holger Knublauch wrote: >> >> >> On 26/11/2016 3:05, Irene Polikoff wrote: >>> How is this different from the following (interchangeable, as far as I >>> can tell) use of the words of ‘define’, ‘describe’ , ‘declare’ and >>> ‘represent’ in https://www.w3.org/TR/owl-ref/? >>> >>> A class description of the "enumeration" kind is defined with >>> the owl:oneOf >>> <http://www.w3.org/TR/2004/REC-owl-semantics-20040210/#owl_oneOf> property. >>> The value of this built-in OWL property must be a list of >>> individuals that are the instances >>> <https://www.w3.org/TR/owl-ref/#Individual> of the class. This >>> enables a class to be described by exhaustively enumerating its >>> instances. The class extension of a class described >>> with |owl:oneOf| contains exactly the enumerated individuals, no >>> more, no less. The list of individuals is typically represented >>> with the help of the RDF construct |rdf:parseType="Collection"|, >>> which provides a convenient shorthand for writing down a set of >>> list elements. For example, the following RDF/XML syntax defines a >>> class of all continents: >>> >>> <owl:Class> >>> >>> <owl:oneOf rdf:parseType="Collection"> >>> >>> <owl:Thing rdf:about="#Eurasia"/> >>> >>> <owl:Thing rdf:about="#Africa"/> >>> >>> <owl:Thing rdf:about="#NorthAmerica"/> >>> >>> <owl:Thing rdf:about="#SouthAmerica"/> >>> >>> <owl:Thing rdf:about="#Australia"/> >>> >>> <owl:Thing rdf:about="#Antarctica"/> >>> >>> </owl:oneOf> >>> >>> </owl:Class> >>> >>> and >>> >>> The following example defines a class of individuals which have at >>> least one parent who is a physician: >>> >>> <owl:Restriction> >>> >>> <owl:onProperty rdf:resource="#hasParent" /> >>> >>> <owl:someValuesFrom rdf:resource="#Physician" /> >>> >>> </owl:Restriction> >>> >>> and >>> >>> The following example describes the class of individuals who have >>> the individual referred to as |Clinton| as their parent: >>> >>> <owl:Restriction> >>> >>> <owl:onProperty rdf:resource="#hasParent" /> >>> >>> <owl:hasValue rdf:resource="#Clinton" /> >>> >>> </owl:Restriction> >>> >>> and >>> >>> if the class description C1 is defined as a subclass of class >>> description C2, then the set of individuals in the class extension >>> of C1 should be a subset of the set of individuals in the class >>> extension of C2. A class is by definition a subclass of itself (as >>> the subset may be the complete set). >>> >>> An example: >>> >>> <owl:Class rdf:ID="Opera"> >>> >>> <rdfs:subClassOf rdf:resource="#MusicalWork" /> >>> >>> </owl:Class> >>> >>> This class axiom declares a subclass relation between two OWL >>> classes that are described through their names >>> (|Opera| and |MusicalWork|). >>> >>> >>> >>> I think we are wasting valuable time on this particular item. >> >> +1 >> >> For the record, I agree with the goal of getting the terminology right, >> and I agree that it's important. At some stage this is becoming rather >> arbitrary though (I mean just look at rdfs:isDefinedBy - shouldn't this >> be rdfs:isDeclaredBy?). This is one of these topics that seem to be only >> relevant in the weird realm of W3C specs, and have almost zero practical >> relevance for end users. >> >> With this clean up of "define" etc I have done what was asked, so let's >> please move on. We have 25 open tickets. >> >> Holger >> >> >>> [A I said previously, I do think that the terms ‘shape description’ or >>> ‘shape definition’ are worth defining] >>> >>> Further, to me, the version of the sentence below that uses “defined >>> using” is much clearer and more intuitive than the version that uses >>> “of”. >>> >>> Irene >>> >>>> On Nov 25, 2016, at 11:34 AM, Karen Coyle <kcoyle@kcoyle.net >>>> <mailto:kcoyle@kcoyle.net>> wrote: >>>> >>>> That's fine if the usage is unambiguous and follows the normal >>>> meaning of "define", and there are many clear uses of define in >>>> document, which I noted previously. If it is used to mean "provides a >>>> definition for" then it's fine. There are other times when it is used >>>> to mean "has as value" or simple "is" - as in >>>> >>>> "Note also that a qualified cardinality constraint defined using >>>> sh:qualifiedValueShape, sh:qualifiedMinCount, and >>>> sh:qualifiedMaxCount is equivalent to a sh:partition constraint that..." >>>> >>>> In those cases, the term "defined" is less precise than: >>>> >>>> Note also that a qualified cardinality constraint of either >>>> sh:qualifiedValueShape, sh:qualifiedMinCount, and >>>> sh:qualifiedMaxCount is equivalent to a sh:partition constraint that..." >>>> >>>> There's no need for define here, and nothing is really being defined. >>>> The use of these properties is not definitional, it simply "is" and >>>> should be stated that way. >>>> >>>> kc >>>> >>>> On 11/24/16 6:14 PM, Irene Polikoff wrote: >>>>> Several W3C specs use the words ‘define’, ‘describe’ and ‘specify’ >>>>> without saying what these words mean. They also, at times, use them >>>>> interchangeably. >>>>> >>>>> For example, I think in the following passage from RDFS spec, ‘define’ >>>>> and ‘describe’ are used interchangeably: >>>>> >>>>> "rdfs:isDefinedBy is an instance of rdf:Property that is used to >>>>> indicate a resource defining the subject resource. This property may >>>>> be used to indicate an RDF vocabulary *in which a resource is >>>>> described.* >>>>> >>>>> A triple of the form: >>>>> >>>>> S rdfs:isDefinedBy O >>>>> >>>>> states that the *resource O defines S*.” >>>>> >>>>> The word ‘declare’ or its derivation such as ‘declaration’ is used more >>>>> rarely, but there is some usage. For example, in the RDFS spec: >>>>> >>>>> >>>>> "Although it is possible to combine use rdfs:domain and rdfs:range >>>>> with sub-property hierarchies, direct support for such declarations >>>>> are provided by richer Web Ontology languages such as OWL.” >>>>> >>>>> >>>>> OWL spec also makes an extensive use of words ‘define’ or ‘describe’ >>>>> without defining them. However, it attempts to define something called >>>>> ‘class description’ and ‘class definition’ e.g., >>>>> in https://www.w3.org/TR/2004/REC-owl-features-20040210/: >>>>> >>>>> "A class description is the term used in this document (and in the >>>>> OWL Semantics and Abstract Syntax) for the basic building blocks of >>>>> class axioms (informally called class definitions in the Overview >>>>> and Guide documents). A class description describes an OWL class, >>>>> either by a class name or by specifying the class extension of an >>>>> unnamed anonymous class.” >>>>> >>>>> >>>>> And in https://www.w3.org/TR/owl-guide/ >>>>> >>>>> Class Definition >>>>> informal term for an owl:Class element >>>>> Class Description >>>>> describes an OWL class, either by a class name or by specifying >>>>> a class extension of an unnamed anonymous class >>>>> >>>>> >>>>> The specification makes an extensive use of the phrase “class >>>>> description”. >>>>> >>>>> With this, I question the need to formally define words such as >>>>> “define”, “describe”, etc. because all other specs seem to rely on the >>>>> common sense interpretation of these words. It may be useful to define >>>>> “shape description” and/or “shape definition'. This could also help to >>>>> resolve Issue-209. >>>>> >>>>> Irene Polikoff >>>>> >>>>> >>>>> >>>>> >>>>> On 11/24/16, 3:22 PM, "Karen Coyle" <kcoyle@kcoyle.net >>>>> <mailto:kcoyle@kcoyle.net> >>>>> <mailto:kcoyle@kcoyle.net>> wrote: >>>>> >>>>> I would advise choosing only one of them, and removing >>>>> "sometimes" from >>>>> the statement, which makes it something you cannot rely on - in other >>>>> words, are they used other times for something else? is something >>>>> else >>>>> sometimes used in their place?: >>>>> >>>>> "(In this document, the verbs <em>specify</em> or >>>>> <em>declare</em> are >>>>> sometimes used to express the fact that a node has property >>>>> values in a >>>>> graph.)" >>>>> >>>>> I haven't read through the uses at this point. >>>>> >>>>> kc >>>>> >>>>> On 11/23/16 9:11 PM, Holger Knublauch wrote: >>>>> >>>>> I have gone through the whole document, replacing most usages of >>>>> "define" with either "specify" or "declare". I have also added >>>>> definitions of these two terms to the beginning of the document: >>>>> >>>>> https://github.com/w3c/data-shapes/commit/92407af35824a7100845b4a84884c86de086b9d7 >>>>> >>>>> Holger >>>>> >>>>> >>>>> On 19/11/2016 2:15, Irene Polikoff wrote: >>>>> >>>>> I would use "specified" for the second meaning of "defined". >>>>> I think >>>>> "declared" would work as well. "Described" - may be, but >>>>> would not be >>>>> my first choice. >>>>> >>>>> On Thu, Nov 17, 2016 at 5:21 PM, RDF Data Shapes Working >>>>> Group Issue >>>>> Tracker <sysbot+tracker@w3.org <mailto:sysbot+tracker@w3.org> >>>>> <mailto:sysbot+tracker@w3.org> >>>>> <mailto:sysbot+tracker@w3.org>> wrote: >>>>> >>>>> shapes-ISSUE-197 (Defined ): "Defined" and "declared" >>>>> used in >>>>> multiple ways, and not defined [SHACL Spec] >>>>> >>>>> http://www.w3.org/2014/data-shapes/track/issues/197 >>>>> <http://www.w3.org/2014/data-shapes/track/issues/197> >>>>> >>>>> Raised by: Karen Coyle >>>>> On product: SHACL Spec >>>>> >>>>> >From Peter's email [1]: >>>>> >>>>> "Constraints are defined within a shape" >>>>> >>>>> "Defined within" is not defined. >>>>> >>>>> "Constraints that declare more than one parameters, >>>>> such as >>>>> sh:pattern, are >>>>> not allowed to be declared more than once in the same >>>>> constraint." >>>>> >>>>> The first two uses of "declare" come from section >>>>> 6.2. A core >>>>> definition is >>>>> needed. >>>>> >>>>> The last use of "declared" is not defined. >>>>> >>>>> "declare" is used for many different purposes, most of >>>>> them undefined. >>>>> >>>>> ******* More analysis ******* >>>>> The use of defined in its normal sense of "having a >>>>> definition" is >>>>> ok. Example: >>>>> >>>>> "The parameter name is defined as the local name of the >>>>> value of >>>>> sh:predicate." >>>>> >>>>> The use of defined to mean something like "takes as a >>>>> value" or >>>>> "is coded as" is less clear: >>>>> >>>>> "Property constraints are defined in a shape with the >>>>> property >>>>> sh:property." >>>>> "Based on the parameter IRIs on the tables, pre-bound >>>>> variables >>>>> are defined using the parameter names." >>>>> >>>>> In some cases, the term "declare" is used in the same >>>>> way as the >>>>> second meaning of define: >>>>> " Constraint components declare one or more parameter >>>>> properties >>>>> and validation instructions (such as those implemented >>>>> as SPARQL >>>>> queries) that can be used to perform the validation for >>>>> the given >>>>> focus node and parameter values." >>>>> >>>>> Suggest: >>>>> - use "defined" for "is given a definition or meaning >>>>> in this or >>>>> other texts >>>>> - do not use "declare" >>>>> - find a more precise term for the second meaning of >>>>> "defined" >>>>> that specifically addresses the creation of properties >>>>> and values, >>>>> regardless of how "definitional" they are. >>>>> >>>>> (Note how this is used in the SKOS document: >>>>> "Therefore, while >>>>> SKOS can be used to describe a concept scheme, SKOS >>>>> does not >>>>> provide any mechanism to completely define a concept >>>>> scheme." >>>>> Could "describe" be used for this second meaning of >>>>> "define"? That >>>>> still seems imprecise for the specific cases in SHACL.) >>>>> >>>>> >>>>> >>>>> >>>>> >>>>> >>>>> >>>>> >>>>> >>>>> >>>>> -- >>>>> Karen Coyle >>>>> kcoyle@kcoyle.net >>>>> <mailto:kcoyle@kcoyle.net> <mailto:kcoyle@kcoyle.net> http://kcoyle.net >>>>> <http://kcoyle.net/> >>>>> m: 1-510-435-8234 >>>>> skype: kcoylenet/+1-510-984-3600 >>>>> >>>>> >>>> >>>> -- >>>> Karen Coyle >>>> kcoyle@kcoyle.net <mailto:kcoyle@kcoyle.net> http://kcoyle.net >>>> <http://kcoyle.net/> >>>> m: 1-510-435-8234 >>>> skype: kcoylenet/+1-510-984-3600 >>> >> > > -- > Karen Coyle > kcoyle@kcoyle.net http://kcoyle.net > m: 1-510-435-8234 > skype: kcoylenet/+1-510-984-3600 >
Received on Sunday, 27 November 2016 17:21:00 UTC