conversion:domain_name

What is first

• conversion:Enhancement provides an overview of all enhancements.

What we will cover

This page discusses how to add a type to the row of a table during conversion (and thus the subject of the triples created) using the conversion:domain_name enhancement.

Let's get to it

The following table talks about people and states, and it is good practice to explicitly type each kind of instance. In the naive RDF conversion below the table, it is rather difficult to automatically recognize that people and states are being mentioned.

First,Last,State
Anne,Armstrong,PA
Ben,Bailey,NY

eg:thing_2
   raw:first "Anne" ;
   raw:last "Armstrong" ;
   raw:state "PA" ;
   ov:csvRow "2"^^xsd:integer .

The conversion:domain_name can help make this clearer (and conversion:range_name behaves similarly for the resource objects created from cells in a table). If we look at the initial enhancement parameters [created the first time](Generating enhancement parameters) we pulled the conversion trigger, we see that the converter is being told to interpret each property as a string literal.

      conversion:enhance [
         ov:csvCol          1;
         ov:csvHeader       "First";
         #conversion:label   "First";
         conversion:comment "";
         conversion:range   todo:Literal;
      ];
      conversion:enhance [
         ov:csvCol          2;
         ov:csvHeader       "Last";
         #conversion:label   "Last";
         conversion:comment "";
         conversion:range   todo:Literal;
      ];
      conversion:enhance [
         ov:csvCol          3;
         ov:csvHeader       "State";
         #conversion:label   "State";
         conversion:comment "";
         conversion:range   todo:Literal;
      ];

If we add the conversion:domain_name enhancement to the first column with the label "Person", the row instances will be typed to a class for Person.

      conversion:enhance [                   
         ov:csvCol          1;               
         ov:csvHeader       "First";         
         conversion:domain_name "Person"; # <-- Add a type to the row.
         #conversion:label   "First";
         conversion:comment "";
         conversion:range   todo:Literal;    
      ]; 

eg_vocab:Person        # A new class is created for "Person"
   a rdfs:Class , 
     owl:Class ;
   rdfs:label "Person" .

eg:person_2            # The row subject is renamed (from "thing_2") to suggest its type.
   a eg_vocab:Person ; # A new class is created for "Person" and the row is typed.
   e1:first "Anne" ;
   e1:last "Armstrong" ;
   e1:state "PA" ;
   ov:csvRow "2"^^xsd:integer .

eg:person_3 
   a eg_vocab:Person ;
   e1:first "Ben" ;
   e1:last "Bailey" ;
   e1:state "NY" ;
   ov:csvRow "3"^^xsd:integer .

Putting it all together

The conversion:domain_name enhancement is often used together with the following enhancements. We apply all of them to make a much more useful RDF structure from the table:

• The subject URIs were renamed to more informative (e.g. :Anne_Armstrong" instead of :thing_2)
• Human-readable strings are provided for the URI (e.g. "Anne Armstrong")
• The Person URIs are typed to the very comment foaf:Person class.
• The first and last names reuse the FOAF vocabulary.
• The relation between the person and the state

eg:Anne_Armstrong
   rdfs:label "Anne Armstrong" ; dcterms:identifier "Anne Armstrong" ; coin:slug "Anne_Armstrong" ;
   a foaf:Person , eg_vocab:Person ;
   foaf:firstName "Anne" ;
   foaf:family_name "Armstrong" ;
   e2:lives_in     typed_state:PA ;
   foaf:based_near typed_state:PA ;
   ov:csvRow "2"^^xsd:integer .
   
eg:Ben_Bailey 
   rdfs:label "Ben Bailey" ; dcterms:identifier "Ben Bailey" ; coin:slug "Ben_Bailey" ;
   a foaf:Person , eg_vocab:Person ;
   foaf:firstName "Ben" ;
   foaf:family_name "Bailey" ;
   e2:lives_in     typed_state:NY ;
   foaf:based_near typed_state:NY ;
   ov:csvRow "3"^^xsd:integer .

eg:thing_2 con:preferredURI eg:Anne_Armstrong .
eg:thing_3 con:preferredURI eg:Ben_Bailey .

typed_state:PA 
   dcterms:identifier "PA" ;
   a eg_vocab:State , wgs:SpatialThing ;
   rdfs:label "PA" .

typed_state:NY 
   dcterms:identifier "NY" ;
   a eg_vocab:State , wgs:SpatialThing ;
   rdfs:label "NY" .

Older discussions

csv2rdf4lod-automation is licensed under the [Apache License, Version 2.0](https://github.com/timrdf/csv2rdf4lod-automation/wiki/License)

(apologies for the bad escaping - a bug in github?)

"What does each row represent?" is one of the first questions about an unfamiliar table of data. The conversion:domain_name enhancement answers this common question. For example, in our [quick and easy conversion](A quick and easy conversion), each row is an oil well; In the White House visitor records, each row is a person's visit to the White House.

Because many data curators commonly need to specify the conversion:domain_name, it is included in the default enhancement parameters.

      #conversion:enhance [
      #   conversion:domain_template "thing_[r]";
      #   conversion:domain_name     "Thing";
      #];
      #conversion:enhance [
      #   conversion:class_name "Thing";
      #   conversion:subclass_of <http://purl.org/...>;
      #];

  conversion:enhance [
     ov:csvCol          1;
     ov:csvHeader       "First";
     #conversion:label   "First";
     conversion:comment "";
     conversion:range   todo:Literal;
  ];
  conversion:enhance [
     ov:csvCol          2;
     ov:csvHeader       "Last";
     #conversion:label   "Last";
     conversion:comment "";
     conversion:range   todo:Literal;
  ];
  conversion:enhance [
     ov:csvCol          3;
     ov:csvHeader       "State";
     #conversion:label   "State";
     conversion:comment "";
     conversion:range   todo:Literal;
  ];

Example - Oil Wells

If conversion:domain_name is not set, you'll end up with something like:

:thing_2
   raw:quadrant_no "106" ;
   raw:tvdss_driller "0" ;
   raw:well_registration_no "106/20- 1" ;
   raw:completion_date "1990-11-01" ;

but after setting the enhancement parameters to:

      conversion:enhance [
         conversion:domain_name     "Oil Well";
      ];

you will get:

:oil_Well_2
   a local_vocab:Oil_Well ;
   e1:quadrant_no "106" ;
   e1:tvdss_driller "0" ;
   e1:well_registration_no "106/20- 1" ;
   e1:completion_date "1990-11-01" ;
.

local_vocab:Oil_Well 
   a rdfs:Class , owl:Class ;
   rdfs:label "Oil Well" .

:thing_2 con:preferredURI :oil_Well_2 .

Effects

• Types the subject row (e.g. local_vocab:Oil_Well).
• changes the local name of the subject (e.g. oil_Well_2 instead of thing_2). For more control of the local name or the full URI of the subject, see conversion:domain_template.
• asserts a con:preferredURI from the thing_2 row instance to (e.g.) oil_Well_2. This will lead anybody that was familiar with :thing_2 to the preferred URI that includes a bit more human-friendly meaning.

Datasets that use this enhancement

(results):

PREFIX conversion: <http://purl.org/twc/vocab/conversion/>
SELECT distinct ?dataset ?template
WHERE {
  GRAPH <http://logd.tw.rpi.edu/vocab/Dataset>  {
    ?dataset conversion:conversion_process [
       conversion:enhance [
          conversion:domain_name ?template
       ]
    ]
  }
}