Re: ADMS review

Hi Phil,

Answers inline. In general, I am happy with all the changes.

On 2013-05-02, at 7:33 PM, Phil Archer wrote:

> 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...

I thought I was looking at that file, but maybe not since those typos do not appear now...


>> * 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.

Yes, the suggestion was just to be consistent; at the time, most cells had colons (in the version I was looking at), so I only suggested adding colons since it would be the less effortful way to achieve consistency. I am happy either way as long as it is consistent.


>> 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.

How about "The interoperability level (e.g. legal, organizational, political, etc.) of the asset. The interoperability level may be taken from a list of levels, such as that of the European Interoperability Framework [[EIF2]]." I'm still fuzzy about what an interoperability level is, but this is a bit more clear to me.



>> 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.

I'm not sure what added text you are referring to. Could you point one example out for me?


>> 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?

Does the ToC not appear in the raw file at https://dvcs.w3.org/hg/gld/raw-file/default/adms/index.html ? The ToC as you describe it sounds sufficient.


>> 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?)

If it's in use, then we can leave it as-is. Otherwise, I had proposed "It seems to me that representationTechnique acts as a note to dcterms:format. In that case, maybe 'formatNote' would be better than 'representationTechnique."

> Have I answered your points satisfactorily?

Yes! Thanks.

James



> 
> 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 Friday, 3 May 2013 02:52:16 UTC