Best Practice: How to choose a term for a new attribute

State: Draft

Contact: Nick Crossley

Scope

This Best Practice recommends appropriate adoption of existing vocabulary terms for new attributes, and guidelines for choosing new ones where no existing term is appropriate.

This Best Practice is related to Best Practice: Enable users to specify URIs for custom attributes and values.

Recommendation

When creating a new attribute, choose carefully the RDF term (predicate) to be use for that new attribute. Once a term has been used and RDF data has been published with that term, it is difficult to change without breaking compatibility.

In order of preference:

• Use an existing term from one of the standard vocabularies used by OSLC for truly generic properties that might appear on any resource, and where the description of that term in the relevant vocabulary really does fit the intended use of the attribute. Terms may be chosen from any of the following vocabularies; others may be used subject to review.

• Use an OSLC domain-specific term for a resource in the corresponding domain, again where the description of that term in the relevant vocabulary fits the intended use of the attribute. Do not use an OSLC domain-specific term for an artifact in a different domain without considered discussion with the relevant OSLC Core and domain Technical Committees - the need to use a term in this way might imply the need to 'promote' a term from an OSLC domain to OSLC Core. Do not use any standard namespace (including OSLC ones) for a new term without approval from the relevant standards body. If you believe a new Core or domain-specific term is appropriate, raise the issue with the Linked Data Review Board.

• Use an existing term from a vocabulary already published on jazz.net, subject to the same guidelines as above - that is, use an appropriate term from a vocabulary for the same domain.

• Create a new term in the appropriate jazz.net vocabulary. When choosing the name and label for the new term, neither under- nor over-constrain the intended meaning. For example, the name 'references' in the standard term dcterms:references could be used for almost any link type, but does not provide much meaning, so is of limited value for queries and reports: for most purposes this would be under-constrained. Conversely, the link type affectedByChangeRequest might be over-constrained if you are not sure that the target will only ever be a ChangeRequest resource. Over-constrained terms limit reuse.

Examples

A resource in your application now has a user-visible name, where in previous releases the artifact was anonymous. In this case, you should add an attribute with the term dcterms:title.

Your application models fundamental particles, and you want to add a link indicating quantum entanglement of two instances of such particles. You determine that none of the existing standard or requirements management vocabularies define a term that matches the meaning of this new link type. You decide to create a new term in a vocabulary for your application, to be published at jazz.net.

@prefix my_app: <http://jazz.net/ns/xxx#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

my_app:linkType
    a rdfs:Property ;
    rdfs:isDefinedBy my_app: ;
    rdfs:comment "A particle entangled with this one." ;
    rdfs:label "entangledWith" .