View source for EntitySchema talk:E1

<span id="creating-an-entityschema"></span>
= Creating an EntitySchema =

<span id="definitions"></span>
== Definitions ==

ShEx and EntitySchemas are used interchangibly for the most part, but to be precise in the semantics EntitySchemas are items found within the GeoKB with an EID (e.g. E1) that have ShEx statements within. ShExC stands for ShEx Compact, which is the syntax used (There is also ShExJ and ShExR but those cannot be used within the GeoKB).

<span id="resources"></span>
== Resources ==

* To learn more on how ShEx works, [https://book.validatingrdf.com/ Validating RDF] has plenty of examples for what’s possible
* The author of the book also had a [https://www.youtube.com/watch?v=nM8kXuZM3lQ workshop] showing how to create ShEx statements.
* Some of the notation is based on Regular Expressions. The Quantifiers section of this [https://www.rexegg.com/regex-quickstart.html#quantifiers page] could be useful in understanding.
* The [https://wikishape.weso.es/ WikiShape] tool is essential to make sure that the desired EntitySchemas are being created.

<span id="entering-into-geokb"></span>
== Entering into GeoKB ==

From the [https://geokb.wikibase.cloud/wiki/Main_Page Main Page] click on <code>New Schema</code>. If the link cannot be found or has been moved, go to <code>Special Pages</code> → <code>Wikibase</code> → <code>Create a new Entityschema</code> or follow this [https://geokb.wikibase.cloud/wiki/Special:NewEntitySchema link].

<span id="validation"></span>
== Validation ==

Validating a schema can be done using the [https://wikishape.weso.es/validate Wikishape tool]. Unfortunately the SPARQL endpoint doesn’t work properly and does not give a descriptive enough error as to why but the ShExC section works. An existing QItem must be in the GeoKB for the validation process to work.

<span id="example"></span>
=== Example ===

Within the <code>SPARQL_examples</code> discussion there is a query that finds [http://geokb.wikibase.cloud/query/#PREFIX%20wd%3A%20%3Chttps%3A%2F%2Fgeokb.wikibase.cloud%2Fentity%2F%3E%0APREFIX%20wdt%3A%20%3Chttps%3A%2F%2Fgeokb.wikibase.cloud%2Fprop%2Fdirect%2F%3E%0A%0ASELECT%20%3Fcommodity%20%3FcommodityLabel%20%3Finstance_ofLabel%0AWHERE%20%7B%0A%20%20%3Fcommodity%20wdt%3AP1%20wd%3AQ406%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20wdt%3AP1%20wd%3AQ280%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20wdt%3AP1%20wd%3AQ24%20.%0A%20%20%3Fcommodity%20wdt%3AP1%20%3Finstance_of%20.%0A%20%20SERVICE%20wikibase%3Alabel%20%7B%20bd%3AserviceParam%20wikibase%3Alanguage%20%22en%22%20.%20%7D%0A%7D mineral commodities]. By running the query we see that aluminum (Q293) is one of the results. Go to the Wikishape tool and add the item QID in the corresponding box and copy over the ShExC found within EntitySchema [https://geokb.wikibase.cloud/wiki/EntitySchema:E6 E6]. This [https://wikishape.weso.es/validate?endpoint=https%3A%2F%2Fgeokb.wikibase.cloud%2F&payload=https%3A%2F%2Fgeokb.wikibase.cloud%2Fentity%2FQ293&schema=prefix%20wd%3A%20%3Chttps%3A%2F%2Fgeokb.wikibase.cloud%2Fentity%2F%3E%0APREFIX%20wdt%3A%20%3Chttps%3A%2F%2Fgeokb.wikibase.cloud%2Fprop%2Fdirect%2F%3E%0A%0ASTART%20%3D%20%40%3CCommodity%3E%0A%0A%3CCommodity%3E%20EXTRA%20wdt%3AP1%20%7B%0A%20%20wdt%3AP1%20%5B%20wd%3AQ406%20%5D%20%2B%20%3B%20%23%20Mineral%20Commodity%0A%20%20wdt%3AP1%20%5B%20wd%3AQ280%20%5D%20%2B%20%3B%20%23%20Chemical%20Element%0A%20%20wdt%3AP1%20%5B%20wd%3AQ24%20%5D%20%2B%20%3B%20%23%20Mineral%0A%7D&schemaEngine=ShEx&schemaFormat=ShExC&schemaLabel&schemaSource=byText&tab=byShex&triggerMode=ShapeMap link] shows the result of the validation.

<span id="debugging-for-validity"></span>
=== Debugging for validity ===

A drawback of the Wikishape tool is that if an error occurs, it does not tell you what the issue is or where to find it within the schema. The best method I have found is to start from the loosest restrictions for the shape wanted and add restrictions one at a time, validating at each step. For example, if I wanted the least restrictions for E6 I would write

<pre>prefix wd: &lt;https://geokb.wikibase.cloud/entity/&gt;
PREFIX wdt: &lt;https://geokb.wikibase.cloud/prop/direct/&gt;

START = @&lt;Commodity&gt;

&lt;Commodity&gt; EXTRA wdt:P1 {
  wdt:P1 [ wd:Q406 ] * ; # Mineral Commodity
  wdt:P1 [ wd:Q280 ] * ; # Chemical Element
  wdt:P1 [ wd:Q24 ] * ; # Mineral
}</pre>
This will validate against any QItem successfully since <code>*</code> represents 0 or more matches.