Re: my proposed introduction to the SHACL document

On 9/4/2015 11:40, Peter F. Patel-Schneider wrote:
> This would replace the entirety of the abstract and Section 1.

I don't see any dedicated abstract in your proposal. All W3C standards 
that I have checked have an abstract. You also seem to suggest we drop 
the Document outline (1.1), the namespaces section (1.4) and the 
Conformance section (1.5)? This sounds like a very bad idea to me.

The purpose of the current draft's introduction was to serve as an 
overview and introduction to the key concepts of SHACL. If people don't 
think this is needed then I'd be more than happy to go with a much 
simpler version similar to what Peter did below. But to be consistent, 
we could just as well delete the whole introduction, because there is 
now so little content in it that it's basically useless.

I had also put a lot of effort into separating Core and Advanced 
sections, because several people in the WG (esp Karen and Arthur) found 
this important. If the opinion of the WG has changed and we no longer 
want this separation, then I'd be more than happy to not highlight this, 
not have a document outline etc.

I suggest we await the discussion about the proposed Primer before doing 
more work on the Introduction. The current Introduction would probably 
be better left to a Primer, and then we can indeed shorten the current 
intro.

An interesting minimalistic approach is taken by the Turtle 1.1 spec 
(http://www.w3.org/TR/turtle/) - they basically just put an example 
snippet into the introduction with hyperlinks to the keywords that are 
used. This might be a compromise with minimal work. Another suggestion 
would be to add an explicit terminology section similar to

     http://www.w3.org/TR/json-ld-api/#general-terminology

as section 2, based on a mix of the current Appendix and the prose of 
the current introduction.

Anyway, all this is for the group to decide; I have no strong opinion.

Holger


>
> peter
>
>
> On 09/03/2015 06:38 PM, Holger Knublauch wrote:
>> Could you clarify which section this is supposed to replace? It looks similar
>> to 1.2 but covers much less material and fewer details.
>>
>> Thanks
>> Holger
>>
>>
>> On 9/4/15 10:43 AM, Peter F. Patel-Schneider wrote:
>>> I put together an introduction to the SHACL document that I think is much
>>> better than the current one.  It presents a short description of the major
>>> aspects of SHACL and then goes into a non-controversial example,.taken from
>>> the SHACL primer and slightly modified.
>>>
>>> There are other parts of the SHACL document that also have bad introductory
>>> material.  This new introduction does not, for example. alleviate the need for
>>> some good introductory material about scopes and filters or about the
>>> relationship between SHACL and SPARQL.
>>>
>>> peter
>>>
>>>
>>>
>>>
>>>
>>>
>>> SHACL (Shapes Constraint Language) is a language for determining whether an
>>> RDF graph (possibly in an RDF dataset) validates against certain shapes.
>>> For example, SHACL can be used to check whether all the nodes in an RDF
>>> graph that have a type link to foaf:Person have a single value for foaf:mbox
>>> and that that value is an IRI.  SHACL can also be used to check whether a
>>> particular node in an RDF graph, say the node ex:bug1, has at least one
>>> value for ex:reportedBy and all such values have an rdf:type link to
>>> foaf:Person.  In doing this checking, SHACL only looks at the triples that
>>> are in the graph.
>>>
>>> The most general interface to SHACL has two arguments.  The first argument
>>> is an RDF graph (in an RDF dataset) that contains the data that is to be
>>> validated, which is called the data graph.  The second argument consists of
>>> the shapes and other information that control what validation is to be done.
>>> This control information can be itself encoded as an RDF graph, which is
>>> called the control graph.
>>>
>>> So in SHACL one might want to determine whether RDF graphs contain
>>> information about issues and users, such as each issue is in either an
>>> unasssigned or an assigned state, and each issue has a reporter and each
>>> such reporter has a precisely one string name and one or more IRI mailboxes.
>>>
>>> A control graph that does this validation has two shapes.  The first,
>>> my:IssueShape contains the two constraints on issues.  The second,
>>> my:UserShape, contains the two constraints on reporters.  The first shape
>>> also contains scope information that here says that its constraints are to
>>> be validated against all nodes that have an rdf:type link to ex:Issue.
>>>
>>> my:IssueShape a sh:Shape ;
>>>       sh:classScope ex:Issue;
>>>       sh:property [
>>>           sh:predicate    ex:state ;
>>>           sh:allowedValue (ex:unassigned ex:assigned) ;
>>>           sh:minCount 1 ; sh:maxCount 1
>>>       ] ;
>>>       sh:property [
>>>           sh:predicate    ex:reportedBy ;
>>>           sh:valueShape   my:UserShape ;
>>>           sh:minCount 1 ; sh:maxCount 1
>>>       ] .
>>>
>>> my:UserShape a sh:Shape ;
>>>       sh:property [
>>>           sh:predicate    foaf:name ;
>>>           sh:valueType    xsd:string ;
>>>           sh:minCount 1 ; sh:maxCount 1
>>>       ] ;
>>>       sh:property [
>>>           sh:predicate    foaf:mbox ;
>>>           sh:nodeKind     sh:IRI ;
>>>           sh:minCount 1
>>>       ] .
>>>
>>> The following data graph might be validated against this control graph
>>>
>>> inst:Issue1 a ex:Issue ;
>>>       ex:state        ex:unassigned ;
>>>       ex:reportedBy   inst:User2 .
>>>
>>> inst:User2 a foaf:Person ;
>>>       foaf:name       "Bob Smith" ;
>>>       foaf:mbox       <mailto:bob@example.org> ;
>>>       foaf:mbox       <mailto:rs@example.org> .
>>>
>>> inst:Issue3 a ex:Issue ;
>>>       ex:state        ex:unsinged ;
>>>       ex:reportedBy   inst:User4 .
>>>
>>> inst:User4 a foaf:Person ;
>>>       foaf:name       "Bob Smith", "Robert Smith" ;
>>>       foaf:mbox       <mailto:bob@example.org> ;
>>>       foaf:mbox       <mailto:rs@example.org> .
>>>
>>> The SHACL validation would validate my:IssueShape against inst:Issue1 and
>>> inst:Issue3.  Validating the first node would determine that inst:Issue1
>>> satisfies the constraints in my:IssueShape, along the way determining that
>>> inst:User2 satisfies the constraints in my:UserShape.  Validating the second
>>> node would determine that inst:Issue3 violates the constraint on values for
>>> ex:state, because ex:unsigned is not in the list of allowed values, and also
>>> violates the constraint on values for ex:reportedBy, because inst:User4
>>> violates the my:UserShape constraint on the maximum number of values for
>>> foaf:name.
>>>
>>

Received on Monday, 7 September 2015 00:13:07 UTC