diff --git a/.vitepress/theme/index.js b/.vitepress/theme/index.js index 55ba4fd..bc87b24 100644 --- a/.vitepress/theme/index.js +++ b/.vitepress/theme/index.js @@ -55,6 +55,7 @@ import MyLayout from "./MyLayout.vue"; // register components globally import { FontAwesomeIcon } from "@fortawesome/vue-fontawesome"; +import ButtonComponent from "../../src/vue-components/Button.vue"; import CardComponent from "../../src/vue-components/Card.vue"; import Disqus from "../../src/vue-components/Disqus.vue"; import FeatureComponent from "../../src/vue-components/Feature.vue"; @@ -78,6 +79,7 @@ export default { ...DefaultTheme, Layout: MyLayout, enhanceApp({ app }) { + app.component("Button", ButtonComponent); app.component("CardComponent", CardComponent); app.component("Disqus", Disqus); app.component("FeatureComponent", FeatureComponent); diff --git a/src/docs/articles/creating-a-dataset.md b/src/docs/articles/creating-a-dataset.md new file mode 100644 index 0000000..81c9e82 --- /dev/null +++ b/src/docs/articles/creating-a-dataset.md @@ -0,0 +1,217 @@ +--- +title: Defining a vocabulary and creating a dataset +outline: [2, 3] +--- + +# Defining a vocabulary and using it to create a dataset + +Describo is built around RO-Crate which primarily uses schema.org. But what do you do if you need to +describe things that are not defined by schema.org? And how can you stand on the shoulders of the +many Ontologies that came before? + +This article will show you, step by step, how to: + +- create a Vocabulary for describing TKLabels; +- use the Vocabulary to create the dataset of TKLabel definitions; +- use the AI Assistant to verify the data you created against the RO-Crate spec; +- and finally, load it into your personal datastore in Describo for use in other projects. + +::: tip info + +- You will need access to the Vocabulary tool in Describo so be sure to + [register](/docs/guide/register.html) which will give you two months of free access to the tool. + +- In order to perform the verification steps you will need to + [purchase credits to use the Assistant.](/docs/guide/purchase-credits.html) + +- [Detailed documentation for the Vocabulary tool is available here.](/docs/guide/vocabulary.html). + +::: + +::: warning info + +This article does not go into detail about every little feature. It is designed as a step by step +how to that is supposed to be read in conjunction with +[the detailed documentation for the Vocabulary tool.](/docs/guide/vocabulary.html) + +::: + +## Definitions + +- A `class` is a definition for a type of `entity`. For example, defining a class `TKLabel` will + enable you to create entities whose type is `TKLabel`. + +## Licensing your work + +Too often, licensing is an afterthought. With Describo, licensing your data and metadata is trivial. + +Start Describo and select a folder to work in. We'll start by creating the data and metadata +licenses. Look in the navigation bar for a button named . The +following two images show the license creation dialog. In the first we're defining the data license +(CC-BY-SA 4.0) and in the second, the metadata license (CC0 Public Domain). + + + + +After we've created the licenses we see that the root dataset has the CC-BY-SA license. + + + +Whilst the root descriptor has the CC0 license. + + + +## Creating the Vocabulary + +### Setup + +Load the vocabulary tool. On this page you can define the Vocabulary metadata like name, description +and version. + + + +### Classes + +Navigate to the classes tab. + +To create a new class, type the name into the input next to `Add a class to your vocabulary`. As you +type, Describo will lookup the Ontologies known to it. If you find a definition that matches what +you want to describe, select it. Otherwise, type in the class name you want and press enter to +select it. + +In this case, create the class `TKLabel` (remember to press enter). Note that it's capitalised and +singular. Also note that we've set the definition to `override`. This means that the class +definition will define the properties so Describo will not traverse the inheritance hierarchy to +determine which properties to show. + +Also note that the class hierarchy can be changed here. By default, any class added (from either an +Ontology or invented by you) will be subclassed to Thing. You can change that here. In addition, +your class can have multiple parent classes. + + + +### Properties - TKLabel class + +Navigate to the properties tab and select the `TKLabel` class. + +Upon selection you will see the properties from the hierarchy (inherited from the default parent +Thing). This happens when the class definition is first created even though you set the definition +to override. + + + +Go ahead and delete all of those properties. In this example, we just need to define the `@id` and +`name` properties which Describo always makes available. + + + +### Properties - Dataset + +In order to use the TKLabel class, we need to say `where` it can be used. In this case, we'll edit +the `hasPart` property on Dataset to specify that we can add TKLabel entities at that point. In the +following image we've loaded the Dataset class on the properties tab and expanded the hasPart +property. + +Notice the select where we can see TKLabel as an option? Describo allows you to associate anything +you've defined at any point in the hierarchy. + + + +By Selecting TKLabel in the select box we see (in the following image) that the hasPart property on +Dataset will now allow TKLabel entities to be created and associated. + + + +Before we leave, let's just check the Vocabulary. Press the button labelled . When you do, a new window will open with the Vocab +presented as HTML. + + + +And finally, be sure to press the button named to not only save it, +but also load it into Describo for use. + +## Using your Vocabulary + +Navigate from the Vocabulary section back to the Describe section. + +The Describo metadata editor will show in the middle pane. Go to the `Content` tab. + +In the following image we can see the `hasPart` property and the ability to add entities of type +CreativeWork, URL, File, Dataset and our new class `TKLabel`. By pressing the TKLabel button we can +start creating the TKLabel definitions. + + + +However, since there are 20 of them, let's use the Bulk Add control. In the next image we see a +dropdown where we've set the @type to TKLabel and defined 6 of the labels using the URL as the value +of the @id property and the name as the value of the name property. + + + +When we we get: + + + +And so we can continue to create all of the other TK Labels. + +Don't forget to add the other metadata like a description and define yourself as an author! + +## Verifying your work + +::: tip info + +You will need credits to use the Assistant for this part. + +::: + +An important part of any project is verifying your work. On the Describe tab, in the left panel +where the file browser is, there is another tab `Verify`. Select it and press the button + . + + + +When you do, the assistant will read the RO-Crate spec and your metadata. When it's ready, you can +query your data for correctness against the spec. + + + +In the following image we pressed the button . In the message +view we see the question (in the blue box) and the assistant's response (in green). + + + +In this way, you can direct the assistant to check your work. + +## Using your dataset + +So you've now created a dataset that you can use in other work. The question is how do we make it +available for lookups in other projects? Firstly, save your work by pressing and then go back to the dashboard. + +Notice the highlighted section in the following screenshot. That's where we manage our saved +templates (which are like our very own personal knowledge base). In the screenshot you can see that +there are two templates: one describing the Describo organisation and one describing me as a Person. + + + +Press the button . A sidebar will open where you +can select a folder containing an RO-Crate. Select the folder where you just created the TKLabels +dataset. Describo will load the RO-Crate metadata and show you the entity types it contains. In this +case we want to ingest all of the TKLabel entities (20 of them) so select that and +press . + + + +When it's done, those entities will now be loaded into your personal datastore. + + + +## Next steps + +So if you've made it here then you've created your own TKLabels dataset and made it available to +Describo for future use. + +In your next project, you can create a Vocabulary where you might define a property on File entities +called `hasTkLabel` and specify that it should have a TKLabel associated. Then, Describo will offer +these as lookups for you to use when describing your files! diff --git a/src/public/images/articles/creating-a-dataset/dataset1.png b/src/public/images/articles/creating-a-dataset/dataset1.png new file mode 100644 index 0000000..96d7373 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset1.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset1.webp b/src/public/images/articles/creating-a-dataset/dataset1.webp new file mode 100644 index 0000000..a9ccad8 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset1.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset10.png b/src/public/images/articles/creating-a-dataset/dataset10.png new file mode 100644 index 0000000..b6f71e6 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset10.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset10.webp b/src/public/images/articles/creating-a-dataset/dataset10.webp new file mode 100644 index 0000000..827fd29 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset10.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset11.png b/src/public/images/articles/creating-a-dataset/dataset11.png new file mode 100644 index 0000000..ecd3584 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset11.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset11.webp b/src/public/images/articles/creating-a-dataset/dataset11.webp new file mode 100644 index 0000000..1f0b2eb Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset11.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset12.png b/src/public/images/articles/creating-a-dataset/dataset12.png new file mode 100644 index 0000000..d9dc2d2 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset12.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset12.webp b/src/public/images/articles/creating-a-dataset/dataset12.webp new file mode 100644 index 0000000..a27ec36 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset12.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset13.png b/src/public/images/articles/creating-a-dataset/dataset13.png new file mode 100644 index 0000000..e20d88a Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset13.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset13.webp b/src/public/images/articles/creating-a-dataset/dataset13.webp new file mode 100644 index 0000000..7490536 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset13.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset14.png b/src/public/images/articles/creating-a-dataset/dataset14.png new file mode 100644 index 0000000..bf879fd Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset14.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset14.webp b/src/public/images/articles/creating-a-dataset/dataset14.webp new file mode 100644 index 0000000..af0442d Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset14.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset15.png b/src/public/images/articles/creating-a-dataset/dataset15.png new file mode 100644 index 0000000..0830759 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset15.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset15.webp b/src/public/images/articles/creating-a-dataset/dataset15.webp new file mode 100644 index 0000000..343f26b Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset15.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset16.png b/src/public/images/articles/creating-a-dataset/dataset16.png new file mode 100644 index 0000000..1520abd Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset16.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset16.webp b/src/public/images/articles/creating-a-dataset/dataset16.webp new file mode 100644 index 0000000..1d82469 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset16.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset17.png b/src/public/images/articles/creating-a-dataset/dataset17.png new file mode 100644 index 0000000..35fb5dc Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset17.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset17.webp b/src/public/images/articles/creating-a-dataset/dataset17.webp new file mode 100644 index 0000000..7f42e93 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset17.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset18.png b/src/public/images/articles/creating-a-dataset/dataset18.png new file mode 100644 index 0000000..e4c4390 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset18.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset18.webp b/src/public/images/articles/creating-a-dataset/dataset18.webp new file mode 100644 index 0000000..684b08a Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset18.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset19.png b/src/public/images/articles/creating-a-dataset/dataset19.png new file mode 100644 index 0000000..bccb927 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset19.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset19.webp b/src/public/images/articles/creating-a-dataset/dataset19.webp new file mode 100644 index 0000000..6b51cba Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset19.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset2.png b/src/public/images/articles/creating-a-dataset/dataset2.png new file mode 100644 index 0000000..5357ef4 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset2.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset2.webp b/src/public/images/articles/creating-a-dataset/dataset2.webp new file mode 100644 index 0000000..eea0efd Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset2.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset20.png b/src/public/images/articles/creating-a-dataset/dataset20.png new file mode 100644 index 0000000..ec80665 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset20.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset20.webp b/src/public/images/articles/creating-a-dataset/dataset20.webp new file mode 100644 index 0000000..f0af8f6 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset20.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset3.png b/src/public/images/articles/creating-a-dataset/dataset3.png new file mode 100644 index 0000000..1dcf5bc Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset3.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset3.webp b/src/public/images/articles/creating-a-dataset/dataset3.webp new file mode 100644 index 0000000..a21d1e2 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset3.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset4.png b/src/public/images/articles/creating-a-dataset/dataset4.png new file mode 100644 index 0000000..d631526 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset4.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset4.webp b/src/public/images/articles/creating-a-dataset/dataset4.webp new file mode 100644 index 0000000..8492472 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset4.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset5.png b/src/public/images/articles/creating-a-dataset/dataset5.png new file mode 100644 index 0000000..952496e Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset5.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset5.webp b/src/public/images/articles/creating-a-dataset/dataset5.webp new file mode 100644 index 0000000..2ebefb0 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset5.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset6.png b/src/public/images/articles/creating-a-dataset/dataset6.png new file mode 100644 index 0000000..feef752 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset6.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset6.webp b/src/public/images/articles/creating-a-dataset/dataset6.webp new file mode 100644 index 0000000..1fce29e Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset6.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset7.png b/src/public/images/articles/creating-a-dataset/dataset7.png new file mode 100644 index 0000000..f563937 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset7.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset7.webp b/src/public/images/articles/creating-a-dataset/dataset7.webp new file mode 100644 index 0000000..d65547c Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset7.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset8.png b/src/public/images/articles/creating-a-dataset/dataset8.png new file mode 100644 index 0000000..f359883 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset8.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset8.webp b/src/public/images/articles/creating-a-dataset/dataset8.webp new file mode 100644 index 0000000..e0d3404 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset8.webp differ diff --git a/src/public/images/articles/creating-a-dataset/dataset9.png b/src/public/images/articles/creating-a-dataset/dataset9.png new file mode 100644 index 0000000..4aceb83 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset9.png differ diff --git a/src/public/images/articles/creating-a-dataset/dataset9.webp b/src/public/images/articles/creating-a-dataset/dataset9.webp new file mode 100644 index 0000000..dc1c666 Binary files /dev/null and b/src/public/images/articles/creating-a-dataset/dataset9.webp differ diff --git a/src/vue-components/Button.vue b/src/vue-components/Button.vue new file mode 100644 index 0000000..5df1110 --- /dev/null +++ b/src/vue-components/Button.vue @@ -0,0 +1,3 @@ + diff --git a/src/vue-components/Feature.vue b/src/vue-components/Feature.vue index a0dce47..fc71223 100644 --- a/src/vue-components/Feature.vue +++ b/src/vue-components/Feature.vue @@ -1,6 +1,7 @@