Dxwg: Criteria for listing properties for each class

[andrea-perego]

Currently, the definitions of all subclasses of dcat:Resource have a paragraph listing all the properties inherited from such parent class.

The issue I see here, is that most of them are actually not going to be used for a given subclass of dcat:Resource (at least, based on the use cases and implementation evidence we have at the moment). Moreover, some of them may overlap with other properties specific to that class - about this, see https://github.com/w3c/dxwg/issues/763

My suggestion is not to remove them, but to move them into a separate, non-normative part of the section with the relevant class definition (it can be a sub-section or a note), and stating that, although we don't have evidence at the moment for their use in that context, they can be potentially used if need be.

This may also help in the preparation of the DCAT implementation report, where we should demonstrate implementation evidence for only the classes and properties which we keep in the normative parts of the spec.

[makxdekkers]

@andrea-perego I agree that the current way of presenting is confusing. However, it is only in the diagram in Fig. 1; the list of properties under the classes in the text only list the ones that are actually recommended for that class. Would it be sufficient to align the diagram with the text by deleting the properties in the diagram that are not in the text?

[andrea-perego]

@makxdekkers , yes, this could be an option.

However, after further review, I wonder whether we should change the approach, for a couple of reasons:

1. The current text denotes as "recommended" the properties specific to that class, and then lists those inherited from the parent class(es) (if any). I am afraid this approach can be misunderstood - i.e., a reader may think that the only important properties are the first ones (I mean, the only ones needed to document that resource type), and the other ones are not necessary. This is obviously not true. E.g., for dcat:Catalog, the properties listed as "recommended" are "catalog record, hasPart, dataset, service, catalog, homepage, themes". But properties like title and description are equally (or even more) important.
2. The "recommended" properties do not include all of those defined in DCAT 2014: in this case, a reader may have the impression that we recommend against their use.

Based on that, my suggestion is as follows:

• Include in the set of "recommended" properties all those properties we think are relevant for documenting a given class, irrespective of whether they are specific to that class, or inherited from parent class(es).
• State in a non-normative part of the same section that, for documenting that resource, it is possible to use, in addition to the "recommended" ones, those associated with the parent class(es) and not listed earlier.

[agbeltran]

@andrea-perego I agree that the text "The following properties are recommended for use on this class" for listing the class-specific properties only and separately listing the inherited properties is confusing.

I agree with your suggestion on how to fix this, and that would allow us to add specific details for properties in the specific context, even for those inherited that we are now only describing at the parent class level.

[andrea-perego]

Thanks, @agbeltran . Happy to help to work this out.

[dr-shorthair]

I've been maintaining Figure 1 using a UML tool. That makes it easy to show inherited attributes as a whole, but it is not possible to pick-and-choose. So if that conflicts with the message we want to send, it would need to be re-drafted using different software (at some stage).

[agreiner]

I have a version of it done with OmniGraffle, which can also save as PDF or SVG (and other options as well).

[davebrowning]

This hasn't been done. Given the (no) time available - it might be possible to make a minimal editorial change by adding the word 'recommended' to the 'inherited' paragraph - so it says:

"The following _recommended_ properties are inherited from the super-class..."

This would apply to dcat:Catalog, dcat:Dataset and dcat:DataService.

Worth doing?

[davebrowning]

Now that #1092 is merged, the text of the document is more explicit on what the recommended properties are, though it's perhaps possible that people will mis-read if they only look at the diagram. Possible that a future revision might want to take a run at re-drafting this, so rather than close this issue I suggest tagging as future work and letting it get pick up (or not) as per future priorities.

[riccardoAlbertoni]

+1 to close this

[andrea-perego]

Closing.