Knowledge Artefact Meta-data

This page is for discussing just the descriptive meta-data of archetypes, templates and other knowledge artefacts.

Design Approach

The meta-data model only includes meta-data items that are definitional, not ones that are classificatory or otherwise arbitrary. The latter would be stored in a registry. The definitional items are separated into three groups.

  •  Things that don't make sense to translate, e.g. original_language (coded), original_author (a person's name) and so on. Non-translatable things are in the description property.
  • Items that should be translated (things like keywords, use, misuse, etc), in the description.details property. 
  • The meta-data of translations (i.e. who did it etc) are in the translations property.

Proposed Model

In the AOM 2 model of meta-data below:

  • copyright has been moved to the non-translated top-level description
  • licence has been added to the description
  • custodian_namespace has been added to the description
  • custodian_organisation has been added to the description
  • original_namespace has been added to the description
  • original_publisher has been added to the description

Moving Forward

Below are two tables, the first containing the definitional properties, and the second an initial set of registry properties. Although registry properties are open-ended, it seems useful to list some key ones and name them, primarily to allow us to a) know we don't want them in the definitional property list and b) standardise them (at least somewhat) for tools. It is clear that various improvements can be made, so the tables provide a way to crystallise a new proposal.

Reviewers are encouraged to modify this list potentially according to this scheme (to retain a bit of sanity):

  • for something you want to modify (including move): put the modification in the 'Review comments' column
  • for something you want to add: add a new row and colour it e.g. red
  • for something you want to remove: don't delete the row, just mark it in the review comments
  • please include your name & date against the comment.

These tables may not be sufficiently broken down to accommodate really detailed review, at which point we need to re-organise in a more fine-grained way.

Definitional Properties

Property idFormal defMeaningCorrespondencesTranslatableReview comments
original_languageTERMINOLOGY_CODE [1]ISO 639 code for the language in which the archetype was originally authored. - 
is_controlledBoolean  - 
provenance_idUIDId set at creation and thereafter never modified; serves as a handle on the artefact, no matter how it is changed over its lifetime - 
instance_idUIDId set and changed every single time the artefact is changed at the character level. - 
description.copyrightStringCopyright string NMove from translatable to non-translatable resource
description.licenseStringLicense text or license reference URL NNot only the copyright is important, but also the applicable license to the archetype.
description.custodian_namespaceINTERNET_IDReverse internet domain of current custodian organisation N 
description.custodian_organisationStringHuman readable name of current custodian organisation N 
description.original_namespaceINTERNET_IDReverse internet domain of original publishing organisation N 
description.original_publisherStringHuman readable name of original publishing organisation N 
translations.languageTERMINOLOGY_CODE [1]  N 
translations.authorHash <String, String>  N 
translations.accreditationString  N 
translations.other_details   N 
translations.version_last_translatedString  N 
description.original_author   N 
description.other_contributors   N 
description.details.language Main detailed description of archetype contents Y 
description.details.purpose   Y 
description.details.use   Y 
description.details.misuse   Y 
description.details.keywords   Y 
description.validation_dateStringDate of validation (not present if not validated) NTB: should be a registry item
description.valid_untilStringDate when this archetype needs to be revised NTB: should be a registry item
description.validatorStringEntity, Organization, or person who is responsible of the validity of the archetype N

Maybe a better world for this field would be 'expeditor'

TB: should be a registry item


Acknowledgements of 3rd party copyrights, trademarks etc. This probably should be in the form of the shortest possible text plus (reliable) URL references to pages containing the full text of each relevant statement, e.g. of the following form for each recognised trademark (using SNOMED CT as an example, and CIMI as an example publishing organisation):

  • SNOMED CT(R) terms used in this artefact are from the SNOMED CT(R) terminology, used under licence by CIMI under agreement <http://page/of/cimi/snomed/agreement>

If we did it this way, it would mean one String per 'acknowledgement'. If we need more, then the structure gets more complicated.

Note that we want to absolutely minimise the text in the archetype to the minimum reliable text legally possible, and leave all other details to the referred-to page - because these details can change, and we don't want to have to revision hundreds or thousands of archetypes because e.g. IHTSDO decides to change its name (which apparently is quite likely in 2015).

Things that need to be acknowledged include:

  • direct use of copyrighted material, to do with the content - e.g. design of copyrighted scales in clinical medicine
  • direct use of terminology, i.e. where concept codes are mentioned (typically in bindings), typically under some wide-ranging license agreement
  • use of trademarked material.

Normally this is just done by including text like 'copyright (c) Orgname' and 'xxxx(R)' to indicate recognition of the IP status.


Registry Properties

The following are properties that can't realistically be a) stable or b) maintained as meta-data within an archetype, but can or do make sense in a registry of a particular publisher / governance organisation.

Property idFormal DefinitionMeaningUse
valid_rmsList<String>List of Reference model releases for which this artefact is valid 
versionStringVersion of the archetype