Re: ADMS review

Thanks again for this James. I've just posted an updated version of ADMS 
and so I'll go through your comments in turn below.

Comments inline

On 07/04/2013 22:18, James McKinney wrote:
> Here's my domain model review.
>
> 1. Small fixes
>
> * its contains > it contains
> * user terms -> use terms
> * Usage note> -> Usage note:
> * Seamntic > Semantic

I can't find these typos now - but I wonder whether we're looking at the 
same document. The one I'm concerned with is 
https://dvcs.w3.org/hg/gld/raw-file/default/adms/index.html. I fear you 
may have been looking at the currently published namespace doc which is 
generated by an XSLT from the original RDF/XML schema - that's due to be 
retired. But let me continue...

> * In the tables in the Properties and Relationships section, ensure all left-hand cells end with a colon

I don't think this is necessary as the table cell is the divider. All 
tables are consistent in not having a colon.

>
> 2. I am unable to parse "A level as defined in a list such the European Interoperability Framework [[EIF2]] for which an Asset is relevant." Similarly, "The interoperability level for which the Semantic Asset is relevant."

The EIF document defines a set of interoperability levels - Legal, 
Organisational, Political etc. - and the idea is that you can declare 
which of those levels an asset is at. See 
https://joinup.ec.europa.eu/svn/adms/ADMS_v1.00/ADMS_SKOS_v1.00.rdf for 
a bunch of SKOS concepts that include these.

If you can suggest better wording I'm happy to use it.


>
> 3. Why do we not include classes in the "Properties and Relationships" section (which should be renamed "Vocabulary Reference" if we add classes)?

I don't think it's unusual to list classes separately from properties 
(FOAF and DC both do it). We need to give slightly different info about 
classes than properties. But I have added to the text for each one 
indicating the property that links to it.

>
> 3. I'd appreciate an index at the beginning of the Properties and Relationships section. It's also hard to determine what properties go with which classes. Could we group properties under the class they are related to for easier reading, as is done in DCAT? For properties that can be used on many classes, like dcterms:description, we can add those in a catch-all subsection, or repeat them in each subsection.

As well as the above, I've slightly changed the markup so that classes 
are listed in the ToC. All properties are listed there (in alphabetical 
order). I hope that's sufficient listing?

>
> 5. Why do some tables have the header "Object Type Property:" and others "Datatype Property:"? Why not just "Property:"?

Because the difference between the two is important to some people. For 
non RDF folks, properties are what we call datatype properties and what 
we call object type properties are relationships. The schema declares 
which type they are too as Dave has done in his schemas.

>
> 6. Should the range of "adms:contactPoint" not be specified for the same reasons as in http://www.w3.org/2011/gld/track/issues/45 ?

Not quite the same issue. In Org/RegOrg we needed to be able to provide 
an address in formats other than vCard and it was specifically an 
address. Here we just want to say "here's how you contact the owner of 
this thing" and not limit ourselves specifically to addresses. A phone 
number or e-mail address is the most likely piece of data here rather 
than a postal address. I admit this could come back to bite us at some 
point but I think it's very unlikely.

>
> 7. Do we need adms:distribution? Isn't dcat:distribution sufficient?

No. It's gone by resolution at the f2f.

>
> 8. Do we need adms:relatedWebPage? Why not foaf:page?

The original creators of ADMS are denizens of PDF land where documents 
and Web pages are disjoint, hence relatedWebPage and 
relatedDocumentation. I have, however, now defined both as sub 
properties of foaf:page.

>
> 9. Is there a reason the domain is missing from nearly every property in the vocabulary?

Yes - for greater portability. I find domains rarely help and often 
simply prevent the re-use of terms I'd like to use. Where the property 
can sensibly only be applied within ADMS, I've specified the domain. 
Otherwise I've left it open. For example, adms:status - I've hearda few 
cases in the last week where I was glad that we haven't restricted the 
domain of that to adms:SemanticAsset - there are other cases where 
pointing to the status of something in a SKOS concept scheme could be 
useful.

The most widely known property that I've ever minted is popular 
precisely because it places no constraints on domain or range 
(wdrs:describedby).


>
> 10. representationTechnique seems to be an unusual term to describe "The machine-readable language in which a Distribution is expressed. This is more fine-grained than file format, for example 'Word 2003'". I don't have a better suggestion, though.

I agree it is a little odd but that's the term that was minted and that 
is now in use (@Makx - correct me if I;m wrong but joinup uses it?)

Have I answered your points satisfactorily?

Phil.



>
> On 2013-04-07, at 4:43 PM, James McKinney wrote:
>
>> Here's a first review that doesn't go into the domain model.
>>
>> 1. Small fixes:
>>
>> * xml -> XML
>> * data set -> dataset
>> * anad -> and
>> * 'a document' -> a document (without quotes)
>> * Semantic Interoperability -> Semantic interoperability (lowercase "i")
>> * consuption -> consumption
>> * a few missing periods at the ends of paragraphs
>>
>> 2. I find the document's first sentence to be a much clearer description of semantic assets than the introduction's first sentence. Can we simply re-use the clearer sentence?
>>
>> 3. Most of the introduction is actually about explaining why we have ADMS when we already have DCAT. Perhaps this can be moved to a new "Rationale" section, maybe as a subsection of "Vocabulary Overview"?
>>
>> 4. Add an "Acknowledgements" header for the three "The original development of ADMS ...", "ADMS was first developed by PwC EU Services ...", and "This version of ADMS ..." paragraphs, and perhaps move it to the end of the document, like in ORG.
>>
>> 5. Add a "Conformance" header before "A data interchange, however that interchange occurs, ..." and move this section before Namespaces.
>>
>> 6. It's unusual that the terms described in the Terminology section are never used elsewhere, i.e. "Semantic interoperability" and "Semantic interoperability asset". We use "semantic asset" everywhere, which is defined in the introduction, but it is never said whether it is a synonym of "semantic interoperability asset". Do we need this section?
>>
>> 7. If the above changes are made, the Introduction will be very short. I would move the "Vocabulary Overview" into the introduction (it makes sense to do an overview as early as possible in the document). Here's a possible table of contents, in which I also move "Namespaces" down, closer to the reference "Properties and Relationships" section:
>>
>> 1. Abstract
>> 2. Vocabulary Overview
>> 2.1. Terminology
>> 2.2. Rationale
>> 2.3. Example
>> 3. ADMS Domain Model
>> 3.1. Primary Concepts
>> 3.2. Secondary Concepts
>> 4. Conformance
>> 5. Namespaces
>> 6. Properties and Relationships
>> 7. Acknowledgements
>>
>> James
>>
>
>
>
>

-- 

Phil Archer
http://philarcher.org/
+44 (0)7887 767755
@philarcher1

Received on Thursday, 2 May 2013 23:35:02 UTC