LADM Code List: Summary Documentation

The following documentation was drafted as a summary to an earlier implementation document proposing the following metamodel for the implementation of semantically enriched code lists. The figures and documentation that are contained within this document serve only as a summary for discussion within the workshop given as part of the 10th Annual Land Administration Domain Model Workshop. The full paper drafted and submitted to this workshop can be found here.

Figure 1. Proposed Metamodel for LADM Code Lists

1. SKOS for the Representation of the LADM Code List Metamodel

The structure defined above makes primary use of the Simple Knowledge Organisation System (SKOS) notation:

  • LADM code lists are represented as skos:ConceptSchemes and/or skos:Collections
  • LADM code list values are defined as skos:Concepts within a skos:ConceptScheme

1.1 LADM Code List as skos:ConceptScheme and/or skos:Collection

Each code list contained within the LADM is represented by this metamodel as a skos:ConceptScheme.

  • Code list name is represented by skos:prefLabel;
  • Code list identifier is represented by skos:identifier;
  • Code list values are related to the code list through the skos:inScheme relation.

Versioning

Versioning of code lists is captured through dct:hasVersion.

  • The time at which the version was made valid is represented by prov:created property.
  • Any modifications made to the code list are represented by the time this change was made through the dct:modified property.
  • If necessary, a code list can be invalidated and this is defined in time through prov:invalidatedAtTime.

Attributions

One of the requirements for the development of this metamodel was the ability to implement code lists according to country specific implementations. In order to capture the country or organisation to which a specific implementation of a code list can be attributed to, the metamodel for the code list includes an attribute prov:wasAttributedTo. This attribution should be to a prov:Agent.

Code lists related to other code lists

Two nuances are important to note here:

  1. It is possible to define code list values as part of skos:Colllection through skos:member; a collection which is completely different from a skos:ConceptScheme representing a given code list. This allows for a collection of code list values about a certain topic to be defined and have this be separate from their instantiation as part of a well-defined code list.

  2. It is also possible to capture the fact that every LADM code list can itself be a skos:member of a broader collection of code lists. The inclusion of this detail in the metamodel allows for (a given number of) code lists within the LADM to be aggregated into a single collection and this collection can be related to other collections of code lists that may exist, for example, within a different (external) standard, vocabulary or implementation.

Figure 2. LADM Code List: LA_MortgageType (ISO19152, 2012)

prefix con: <http://www.isoladm.org/model/con/>
prefix dct: <http://purl.org/dc/terms/>
prefix ladm: <http://www.isoladm.org/>
prefix prov: <http://www.w3.org/ns/prov#>
prefix skos: <http://www.w3.org/2004/02/skos/core#>
prefix scheme: <http://www.isoladm.org/model/scheme/>
prefix xsd: <http://www.w3.org/2001/XMLSchema#>

##prefixes for external models should be defined, stdm is just an example:
prefix stdm: <https://stdm.gltn.net/>

## Code List - LADM Mortgage Type

scheme:LA_MortgageType
  a skos:ConceptScheme;
  dct:isFormatOf ladm:Mortgage;
  skos:prefLabel "mortgage types"@en;
  skos:member ladm:LA_CodeListCollection_Administrative;
  rdfs:isDefinedBy "http://www.examplesource.com/mortgagetypes"^^xsd:anyURI;
  skos:relatedMatch stdm:Collateral;
  skos:identifier "http://www.isoladm.org/model/scheme/la_mortgagetype"^^xsd:anyURI;
  dct:description "The LA_MortgageType code list includes all the various mortgage types, such as linear or micro-credit, used in a specific land administration profile implementation. The LA_MortgageType code list is required only if the attribute type in LA_Mortgage class is implemented. Code list shall provide a complete list of all codes with a name and description"@en;
  dct:hasVersion "1";
  prov:created "01-01-2022"^^xsd:date. 

1.2 LADM Code List Value as skos:Concept

Each code list value associated with a given code list in the LADM is represented according to this metamodel as a skos:Concept with a unique skos:identifier. Each code list value is related to its associated code list through the relation skos:inScheme.

  • Each code list has a skos:prefLabel, as well as a dct:created date and dct:modified date. In a similar manner to the code list itself, the prov:wasAttributedTo property allows for a record of which actor specifically defined and implemented this code list value with this particular definition.

Code List Value Definition

One of the main contributions of this metamodel is the explicit inclusion of a skos:definition relation to the code list value where a definition (skos:definition), a source of the definition (rdfs:isDefinedBy) and versioning of the code list (dct:hasVersion) can be implemented.

  • Each change to a definition or attribute associated with a code list changes the version number of the code list value and updates the dct:modified value for the code list value.

Attributions

Each code list value allows for the definition of an attributed source through the attribute prov:wasAttributedTo. This attribute is intended to be implemented completely independently of the rdfs:isDefinedBy attribute where this attribute explicitly defines which country or organisation originally developed this value definition.

Figure 3. Code List Values for LA_MortgageType (ISO19151, 2012)

prefix con: <http://www.isoladm.org/model/con/>
prefix country: <http://www.isoladm.org/model/country/>
prefix dct: <http://purl.org/dc/terms/>
prefix ladm: <http://www.isoladm.org/>
prefix prov: <http://www.w3.org/ns/prov#>
prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>
prefix skos: <http://www.w3.org/2004/02/skos/core#>
prefix scheme: <http://www.isoladm.org/model/scheme/>
prefix xsd: <http://www.w3.org/2001/XMLSchema#>

## LADM 'Core' Code List Values for LA_MortgageType
con:LA_linear
  a skos:Concept;
  skos:inScheme scheme:LA_MortgageType;
  skos:identifier "http://www.isoladm.org/model/con/la_linear"^^xsd:anyURI;
  prov:wasAttributedTo country:LA;
  skos:prefLabel "linear"@en;
  dct:created "01-01-2022"^^xsd:date; 
  dct:hasVersion "1";
  skos:definition "The type of  mortgage with the gradually decreasing periodic payment"@en;
  rdfs:isDefinedBy "http://www.examplesource.com/mortgagedefinition/linear"^^xsd:anyURI .

con:LA_levelPayment
  a skos:Concept;
  skos:inScheme scheme:LA_MortgageType;
  skos:identifier "http://www.isoladm.org/model/con/la_levelPayment"^^xsd:anyURI;
  prov:wasAttributedTo country:LA;
  skos:prefLabel "level payment"@en;
  dct:created "01-01-2022"^^xsd:date; 
  dct:hasVersion "1";
  skos:definition "A level payment mortgage is a type of mortgage that requires the same payment each month or payment period"@en;
  rdfs:isDefinedBy "http://www.examplesource.com/mortgagedefinition/levelpayment"^^xsd:anyURI .

con:LA_microcredit
  a skos:Concept;
  skos:inScheme scheme:LA_MortgageType;
  skos:identifier "http://www.isoladm.org/model/con/la_microcredit"^^xsd:anyURI;
  prov:wasAttributedTo country:LA;
  skos:prefLabel "microcredit"@en;
  dct:created "01-01-2022"^^xsd:date; 
  dct:hasVersion "1";
  skos:definition "Microcredit, a means of extending credit, usually in the form of small loans with no collateral"@en;
  rdfs:isDefinedBy "http://www.examplesource.com/mortgagedefinition/microcredit"^^xsd:anyURI .

All code lists can themselves be a part of (skos:member) of a code list collection. In Figure 4, this aggregation is shown were the LA_AdministrativeSourceType code list is a skos:member of the code list collection LA_CodeListCollection_Administrative.

Figure 4. Application of skos:related country specific code list to LA Code List

prefix col: <http://www.isoladm.org/model/col/>
prefix con: <http://www.isoladm.org/model/con/>
prefix country: <http://www.isoladm.org/model/country/>
prefix dct: <http://purl.org/dc/terms/>
prefix scheme: <http://www.isoladm.org/model/scheme/>
prefix skos: <http://www.w3.org/2004/02/skos/core#>
prefix ladm: <http://www.isoladm.org/>
prefix prov: <http://www.w3.org/ns/prov#>

scheme:LA_AdministrativeSourceType skos:related scheme:MG_AdministrativeSourceType

scheme:LA_AdministrativeSourceType
  a skos:ConceptScheme;
  dct:isFormatOf ladm:AdministrativeType;
  skos:prefLabel "responsibility types"@en;
  skos:member col:LA_CodeListCollection_Administrative;
  prov:wasAttributedTo country:LA;
  rdfs:isDefinedBy "http://www.examplesource.com/mongolia_administrativetypes"^^xsd:anyURI.

scheme:MG_AdministrativeSourceType
  a skos:ConceptScheme;
  dct:isFormatOf ladm:AdministrativeType;
  skos:prefLabel "responsibility types for mongolian implementation"@en;
  skos:member col_mg:MG_CodeListCollection_Administrative;
  prov:wasAttributedTo country:MG;
  rdfs:isDefinedBy "http://www.examplesource.com/mongolia_administrativetypes"^^xsd:anyURI..

In the example above (Figure 4), the use of the relation skos:narrower allows for a generation of country-specific implementation of the LA_AdministrativeSourceType code list, which in this case is a more specific implementation of the code list by Mongolia by adding two other code list values to the existing code list to make it more specific in order to suit the country-specific context. The details of this implementation are shown in the figure below (Figure 5). Please note the use of the country code MG to denote a country-specific implementation of a code list and the aggregation of the code list to a country-specific collection through skos:member relations.

Figure 5. Application of skos:related, skos:broader and skos:narrower attributes to the country-specific code list MG_AdministrativeSourceType based on Munkhbaatar B., et al., 2018

prefix col: <http://www.isoladm.org/model/col/>
prefix con: <http://www.isoladm.org/model/con/>
prefix def: <http://www.isoladm.org/model/def/>
prefix ladm: <http://www.isoladm.org/>
prefix prov: <http://www.w3.org/ns/prov#>
prefix scheme: <http://www.isoladm.org/model/scheme/>
prefix skos: <http://www.w3.org/2004/02/skos/core#>
prefix xsd: <http://www.w3.org/2001/XMLSchema#>

scheme:MG_AdministrativeSourceType
  a skos:ConceptScheme;
  skos:prefLabel "administrative source types for mongolian implementation"@en;
  skos:member col:MG_CodeListCollection_Administrative;
  prov:wasAttributedTo country:MG;
  rdfs:isDefinedBy "http://www.examplesource.com/mongolia_administrativetypes"^^xsd:anyURI.

## Code List Values for MG_AdministrativeSourceType (Country-Specific Implementation)

con:MG_morrtgage # as implemented in source paper
  a skos:Concept;
  skos:inScheme scheme:MG_AdministrativeSourceType;
  prov:wasAttributedTo country:MG;
  rdfs:isDefinedBy "http://www.examplesource.com/mongolia_administrativetypes/morrtgages"^^xsd:anyURI;
  skos:identifier "http://www.isoladm.org/model/con/mg_morrtgage"^^xsd:anyURI;
  skos:related con:LA_mortgage;
  skos:prefLabel "morrtgage"@en;
  dct:created "01-01-2022"^^xsd:date .

con:MG_landCertificate
  a skos:Concept;
  skos:inScheme scheme:MG_AdministrativeSourceType;
  prov:wasAttributedTo country:MG;
  rdfs:isDefinedBy "http://www.examplesource.com/mongolia_administrativetypes/morrtgages"^^xsd:anyURI;
  skos:identifier "http://www.isoladm.org/model/con/mg_landcertificate"^^xsd:anyURI;
  rdfs:isDefinedBy "http://www.examplesource.com/mongolia_administrativetypes/landCertificate"^^xsd:anyURI;
  skos:prefLabel "land certificate"@en;
  skos:narrower con:LA_deed;
  dct:created "01-01-2022"^^xsd:date .

con:MG_titleDeed
  a skos:Concept;
  skos:inScheme scheme:MG_AdministrativeSourceType;
  prov:wasAttributedTo country:MG;
  rdfs:isDefinedBy "http://www.examplesource.com/mongolia_administrativetypes/titleDeed"^^xsd:anyURI
  skos:identifier "http://www.isoladm.org/model/con/mg_titledeed"^^xsd:anyURI;
  skos:prefLabel "title deed"@en;
  skos:related con:LA_title;
  skos:narrower con:deed;
  skos:broader con:MG_landCertificate;
  dct:created "01-01-2022"^^xsd:date .

con:MG_landPermissionDecision
  a skos:Concept;
  skos:inScheme scheme:MG_AdministrativeSourceType;
  prov:wasAttributedTo country:MG;
  rdfs:isDefinedBy "http://www.examplesource.com/mongolia_administrativetypes/landPermissionDeed"^^xsd:anyURI
  skos:identifier "http://www.isoladm.org/model/con/mg_landpermissiondecision"^^xsd:anyURI;
  skos:prefLabel "land permission decision"@en;
  skos:narrower con:LA_agriConsent;
  dct:created "01-01-2022"^^xsd:date .

con:MG_landRegisterAttachedDoc
  a skos:Concept;
  skos:inScheme scheme:MG_AdministrativeSourceType;
  prov:wasAttributedTo country:MG;
  rdfs:isDefinedBy "http://www.examplesource.com/mongolia_administrativetypes/landRegisterAttachedDoc"^^xsd:anyURI
  skos:identifier "http://www.isoladm.org/model/con/mg_landregisterattacheddoc"^^xsd:anyURI;
  skos:prefLabel "land register attached document"@en;
  skos:narrower con:LA_agriNotaryStatement;
  dct:created "01-01-2022"^^xsd:date .

2. Versioning using the LADM Code List Metamodel

2.1 skos:identifier

Each code list, code list value and value definition has an associated persistent identifier documented based on the attribute skos:identifier. In practice any significant changes to a concept, such as a change to a definition or an update to the primary source, would result in a new version of the concept and, therefore, a new identifier. The inclusion of this attribute is important for the management of versioning within code lists because the persistence identifier ensures that versioning of the concept does not necessarily affect the concept itself.

Figure 7. LADM Coe List Values for LA_MortgageType with Versioning Examples (ISO19152, 2012)

prefix con: <http://www.isoladm.org/model/con/>
prefix country: <http://www.isoladm.org/model/country/>
prefix dct: <http://purl.org/dc/terms/>
prefix ladm: <http://www.isoladm.org/>
prefix prov: <http://www.w3.org/ns/prov#>
prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>
prefix scheme: <http://www.isoladm.org/model/scheme/>
prefix skos: <http://www.w3.org/2004/02/skos/core#>
prefix xsd: <http://www.w3.org/2001/XMLSchema#>

## Value Definitions for Code List Values associated with LA_MortgageType

con:LA_linear
  a skos:Concept;
  skos:identifier "http://www.isoladm.org/model/con/la_linear/1"^^xsd:anyURI;
  skos:definition "The type of  mortgage with the gradually decreasing periodic payment"@en;
  prov:wasAttributedTo country:LA;
  rdfs:isDefinedBy "http://www.examplesource.com/mortgage/linear"^^xsd:anyURI;
  dct:hasVersion "1";
  dct:created "01-01-2022"^^xsd:date. 

con:LA_linear
  a skos:Concept;
  skos:identifier "http://www.isoladm.org/model/con/la_linear/2"^^xsd:anyURI;
  skos:definition "The type of  mortgage with the gradually decreasing periodic payment over the course of defined period of time"@en;
  prov:wasAttributedTo country:LA;
  rdfs:isDefinedBy "http://www.examplesource.com/mortgage/linear-2"^^xsd:anyURI;
  dct:hasVersion "2";
  dct:created "01-02-2022"^^xsd:date.

2.2 dct:hasVersion

The way in which dct:hasVersion is implemented across the model only differs in the rules which govern the generation of a new version of a given code list or code list value.

Code List

The dct:hasVersion attribute allows for the differentiation between different versions of the same code list.

  • A new version number is generated when there is an addition or removal of a code list value from the code list and a new version number is generated in line with a change to the dct:modified date.
  • The core identifier of a given code list remains stable and the identifier for different versions of the same code list is generated based on the combination of the identifier and version number. An example of this identifier strategy is illustrated above (Figure 7).

Code List Value

The dct:hasVersion allows for the differentiation between different versions of the same code list value based on differences in the definition associated with the code list value.

  • Minor changes to the definition of a code list value will only change the version of the code list value.
  • Changes to the original source of the definition, a fundamental change to the meaning of the definition used or a change to the country or organisation to which a given code list value with a given definition is associated will result in a new code list value and a new identifier for that value.

2.3 Versioning dates: dct:created and dct:modified

Each code list and code list value has an associated dct:created date based on the date on which the given entity was first instantiated.

  • At the level of the code list, the dct:modified attribute tracks changes to the code list itself based on the addition or removal of a code list value from that list. As such, the last modified data is the same as the latest dct:created/dct:modified date across all code list values in a code list.
  • At the level of code list value, updates dct:modified only happen when a code list value is being versioned. There are no other influences on this date.

2.4 prov:invalidatedAtTime

The attribute prov:invalidatedAtTime is used at all levels of the metamodel to signal the end of the validity of a particular code list or code list value.

Code List

The prov:invalidatedAtTime attribute denotes the point at which the code list itself is no longer valid for implementation.

  • When this time is actually instantiated is dependent on when the standard itself was changed and a code list was invalidated or when a country-specific implementation of a code list was invalidated by that country or organisation.
  • The instantiation of this attribute at the code list level does not necessarily invalidate the code list values and different versions of a code list can have the same version of a code list value.

Code List Value

The prove:invalidatedAtTime attribute is used when either the standard or a country-specific implementation explicitly invalidates a code list value.

  • Making use of the prov:invalidatedAtTime attribute is intended when a new version of a definition explicitly replaces an older version.

Note: Because of the variety of implementations across various contexts, it is the intention that this attribute is not frequently used and that versions of definitions remain valid for implementation across time. This allows for flexibility in implementation and easier maintenance of implemented code list values and their definitions across time.

To see the implementation of this metamodel in practice, please refer to this demonstation environment. Here live SPARQL queries are performed on fake data used for the purpose of showcasing the flexibility and ease at which questions that may surround code lists in different contexts could be answered.