Description of a core vocabulary

When you land on the datamodel page, you will first see the name of the datamodel and its basic information. 

Basic information on a datamodel includes: 

• datamodel type: an icon and a label indicating whether the datamodel is a core vocabulary or an application profile 
• datamodel identifier (a short identifier individualising the datamodel in this tool) 
• version number (if the datamodel has been published) 
• datamodel status 

If the datamodel has been published, the status may be Suggested or Valid. 

The status is Draft if the datamodel is still a work in progress, i.e., a working version. In that case, the datamodel is visible only to persons in the same organisation. A datamodel in Draft status does not have a version number. 

In the Search section, you can see the search field and below it, a list of all of the following resources included in the datamodel: 

• classes 
• attributes 
• associations. 

Use this datamodel’s own search function to filter the tool to display only the information you want in the list. Use the name of the resource to search for the resources included in the datamodel, i.e. classes, attributes and associations. 

The search result will be a list of resources that meet the search criteria. Go the desired class, attribute or association by clicking its heading on the list. 

The information describing the datamodel is almost the same for core vocabularies and application profiles, but in some respects these data model types differ. The information on a core vocabulary is described below. 

The tool lists the resources, i.e., terminologies and datamodels that have been used to draw up the datamodel, to the Links page.  

Additional functionalities for a data model editor 

More functionalities are visible to an editor who is logged in the Data Vocabularies tool, i.e. to a data model editor. 

If you have the editing rights for the datamodel, you can also see the Edit button on the page. Click the button and you will be able to add links by using an online form. 

The other option is that the tool adds the links automatically if you, when modelling, 

• link a new concept to a class, attribute or association in your datamodel or 
• add a resource from a new datamodel that has not previously been linked to your datamodel.  

Linking terminologies 

Click the Add terminology button when you want to add a link to one of the terminologies in the Terminologies tool.  

Find a suitable terminology either by entering a search word in the Search for terminology field or by browsing the list of terminologies. Select the desired terminology or terminologies by clicking the box next to the terminology and Add selected button. The tool adds the selected terminology or terminologies to the Links page. In the end, click Save. 

Linking datamodels i.e. namespaces 

Click the Add data model button when you want to add a link to a datamodel. 

Links can be made both to a datamodel located in the Data Vocabularies tool and to an external datamodel. You can search for datamodels with the name of the datamodel. 

The search results can be filtered with the following information: 

• Domain: filtering that has been conducted by subject area; the domains are the same as on the front page of the tool 
• Status: By default, the active statuses (statuses in use) are shown - that is, all data models in Suggested and Valid status, as well as those in Draft status within your own organization. Other options are All statuses and Statuses not in use, which are Superseded and Retired.  
• Content language: the languages used in the datamodel.  

Select the desired datamodel(s) by checking the box next to datamodel name. The tool adds the selected datamodel(s) to the Links page. In the end, click Save. 

Using external resources (namespaces) outside the Data Vocabularies tool 

Click the Add reference to external data model button to link datamodels external to the Data Vocabularies tool (namespaces) to your own datamodel.  

Select the desired datamodel from the drop-down menu. If the required datamodel does not appear on the list, contact Interoperability Platform developers. An external datamodel can be added if it is resolvable, i.e. a redirectable datamodel or ontology. 

• Namespace: the web address of a data model 
• Datamodel name: a text field in which you can enter the desired name in the languages that you have defined as the languages of your data model. 
• Prefix: the identifier of the data model in the Data Vocabularies tool. The identifier must be unique, i.e. it cannot be the same as the identifier of another resource already in the Interoperability Platform. 

After entering the required information, click the Add button. The tool adds the data model defined by you to the Links page. In the end, click Save button. 

Classes belonging to a core vocabulary 

Under the heading Classes, you will see a list of the classes included in the datamodel in alphabetical order according to the name of the class. 

Click the heading of the desired class to display more specific information on the class concerned, such as:  

• Class name
• Class identifier in the Data Vocabularies tool 
• Long identifier i.e. IRI address of the class: uniquely identifies the class across the entire internet. The IRI address allows the class to be referenced outside the Data Vocabularies tool, for example, in machine-readable interfaces. 
• Concept: a link to a concept in the Terminologies tool 
• Upper class: The name of the superordinate class and a link to it. A class that is semantically more general than this class. For example, learner > student 
• Equivalent classes: The name of the equivalent class and a link to it. Other classes that are (almost) the same as this class in terms of their semantic content. For example, shoe - footwear. 
• Disjoint classes: The name of the separate class and a link to it. Classes that cannot contain the same members as this class (mutually excluding classes). For example, an actor is either a person or an organisation, but not both at the same time. 
• Technical description: A brief description of the class and an example of its intended use.
• Attributes: A list of attributes included in the class. Click the name of the attribute to view more specific information on the attribute. 
• Associations: A list of associations related to the class. Click the name of the association to view more specific information on the association. 
• References: Information about the resources that have utilized this class’s resources, and a link to those resources. 
• Created: Date and time of creating the class. 
• Last modified at: Date and time when the information on the class was last changed.
• Work group comment: Comments and instructions for other persons editing information on the class. The content of this field is not visible to persons outside the same organisation. 
• Contributors: One or more organisations owning and maintaining the data in the Data Vocabularies tool. 

Additional functionalities for a data model editor 

If you have the data model editor’s rights for the tool, you will see the Actions menu in your organisation's datamodels and edit functions in the menu. You can edit the selected class or modify its identifier. You can also remove (delete) the class.

In the Classes view, you can 

• copy an IRI/URI address to clipboard 
• add attributes to a class 
• add associations to a class 
• view the references made to the class, i.e. those resources of the Data Vocabularies tool that have used this class. The class restriction of an application profile is an example of such resources. 

Under the heading Attributes, you will see a list of the attributes included in the datamodel in alphabetical order according to the name of the attribute. 

Information presented on an attribute 

Click the heading of the desired attribute to display more specific information on the attribute concerned, such as:  

• Attribute name 
• Attribute’s identifier: An identifier that individualises this resource in the Data Vocabularies tool 
• Long identifier i.e. IRI address of the attribute: uniquely identifies the attribute on the entire internet. The IRI address allows the attribute to be referenced outside the Data Vocabularies tool, for example, in machine-readable interfaces. 
• Concept: a link to a concept in the Terminologies tool if linking has been carried out. 
• Data type: Determines what kind of structure the attribute values must conform to. For example, it may be required that the value must be an integer, string, URI, data, etc. You do not have to indicate the data type in a core vocabulary, it can be defined in the application profile instead. In a core vocabulary, the selection of available data types is narrower than in an application profile. 
• Class: Indicates which class the restriction applies to if this attribute is used in a data model to limit the meaning/use of that class. 
• Upper attributes: The name of the upper attribute and a link to it.  An attribute (or property) that is semantically more general than this attribute. For example, identifier > personal identity code 
• Equivalent attributes: The name of the equivalent attribute and a link to the attribute concerned. 
• Other attributes: are (almost) the same as this attribute in terms of their semantic content. For example, shoe size - shoe number. 
• Functional attribute (single-valued attribute): A Boolean that indicates that the attribute can have only one value. For example, the value of an attribute by the name of "pi” can be only 3.14. 
• Attribute’s note: A description of the content or properties of a resource, that a user of the resource needs to know. For example, its intended purpose or other information not evident from the concept description (link to the terminology). 
• References: Open the References drop-down menu to display the resources that have used this attribute. 
• Created: Date and time of creating the attribute. 
• Last modified at: Date and time when the information on the class was last changed. 
• Work group comment: Comments and instructions for other persons editing the attributes of the class. The content of this field is not visible to persons outside the same organisation. 
• Contributors: One or more organisations owning and maintaining the data in the Data Vocabularies tool. 

If you want to give feedback on the definitions of the attribute to the contributor, click the Give feedback on the attribute link. The Data Vocabularies tool will open your email with the contributor’s email address already in the message recipient field. 

Additional functionalities for a data model editor 

More functionalities are visible to an editor who is logged in the Data Vocabularies tool, i.e. to a data model editor. 

If you have the data model editor’s rights for the tool, you will see the Actions menu in your organisation's datamodels and edit functions in the menu. You can edit the selected attribute or modify its identifier. You can also remove (delete) the attribute. 

Click Add attribute when you want to add an attribute to a core vocabulary. A modal will then be displayed in which you can select, search for or create the desired attribute.  

Please note that attributes are first created at the level of the entire datamodel, which means they are in common use. Once created, the attribute can be linked to one or more classes. 

In other words, the attribute is created only once, and a reference to this commonly used attribute is then simply added to a class.  For example, the very common attribute “identifier” does not need to be created separately for each class requiring it – the classes simply refer to the general attribute. 

If an attribute is no longer needed in a class, the reference to that attribute is removed from the class (using the Remove reference function). However, the attribute itself is not deleted from the entire data model, so references in other classes remain unchanged. 

Note also that if you edit a commonly used/shared attribute (for example, change its name), the changes will appear in all classes that reference that attribute. 

An attribute can be removed from a datamodel only when it is no longer referred to from any class. To remove an attribute, go to the description page of the attribute and select Remove from the Actions menu.

Adding a new attribute to a datamodel

1. If you already know the name of the desired attribute, you can retrieve it directly through the search field. Enter the name of the attribute in the search field. 
2. By default, the tool will search for attributes in the datamodels (namespaces) that you have added to your datamodel in the Links section. To search from all datamodels in the Data Vocabularies tool, change the selected option in step 2 to All data vocabularies. If you find a suitable attribute in a new datamodel and add the attribute to your datamodel, the tool will automatically add that datamodel to the Links section of the namespace. If too many options are offered, go back by selecting the option Datamodels added to this model. Attributes only from a filtered set of datamodels will then be displayed again. 
3. Filter the number of attributes by focusing the search only on the datamodels of a specific domain. 
4. Increase the number of available attributes by focusing the search on all datamodels – all statuses - or focus the search on statuses not in use, i.e. retired or superseded datamodels. 
5. Filter the number of attributes by focusing the search only on datamodels in a specific language. 
6. Browse the available attributes by scrolling the list. Select the desired attribute by clicking the radio button in front of it. Deselect it by clicking the radio button again. 
7. When you have selected an attribute, the Create new sub-attribute for selected button is activated. Click the button and the tool will display a new page on which you can enter more specific information on the sub-attribute. The tool will automatically mark the selected attribute as the upper attribute of the new attribute. 
8. If you did not find a suitable attribute among the ones defined above, click the Create new attribute button to display a new page on which you can enter the details of the new attribute. 
9. Click Cancel to cancel the addition of the attribute. 

You can add an attribute in two different ways: either from the class description page by clicking the Add Attribute button or through the visualization. In both cases, the same insert modal view will be displayed.  

In the visualisation, first select the desired class and then click the box with three dots in the top right corner. Then select the Add attribute option. 

Browse the list and select an attribute from the options offered by the tool. This activates the Add attribute button. Click the button and the tool will add the attribute you selected for the class, i.e. a reference to the attribute. If the desired attribute is not on the list, try changing the selected option under Datamodel (see point 2 above) to All data vocabularies to get more options.   

The tool will add the desired attribute (a reference to the attribute) to the class and it will also be visible in the visualisation. 

Under the heading Associations, you will see a list of the associations included in the datamodel in alphabetical order according to the name of the association. 

Information presented on an association 

Click the heading of the desired association to display more specific information on the association concerned, such as:  

• Association name
• Association’s identifier in the Data Vocabularies tool. 
• Long identifier i.e. IRI address of the attribute: uniquely identifies the association on the entire internet. The IRI address allows the association to be referenced outside the Data Vocabularies tool, for example, in machine-readable interfaces. Click the Copy to clipboard button and the tool will copy the IRI address to your workstation's clipboard. 
• Concept: a link to a concept in the Terminologies tool. 
• Associations source: The source class of the association relationship, from which the relationship is defined. 
• Associations target: A core data model class that has a semantic connection—i.e., an association—defined from another class. The target class of the association relationship. 
• Upper associations: The name of the superordinate association and a link to the association concerned. An association that is more general than this association in terms of its semantic content. For example, owner > private individual as owner 
• Equivalent associations: The name of the equivalent association and a link to the association concerned. Other associations that are (almost) the same as this association in terms of their semantic content. For example, link - join. 
• Transitive association: An association that can be derived or concluded from another association. For example, if X is Y’s employer, it can be concluded that similarly, Y is X’s employee 
• Reflexive association: An association that can relate to or refer to itself. For example, an organization may include sub-organizations, which are themselves also organizations
• Association's note: A description of the content or properties of a resource, that a user of the resource needs to know. For example, its intended purpose or other information not evident from the concept description (link to the terminology). 
• Created: Date and time of creating the association. Members of the same organisation can also see who has created the association. 
• Last modified at: Date and time when the information on the association was last changed. 
• Work group comment: Comments and instructions for other persons editing the association. The content of this field is not visible to persons outside the same organisation. 
• Contributors: One or more organisations owning and maintaining the data in the Data Vocabularies tool. 

Open the References drop-down menu to see the resources that have used this association. 

If you want to give feedback on the definitions of the association to the contributor, click the link Give feedback on an association. The Data Vocabularies tool will open your email with the contributor’s email address already in the message recipient field. 

If you have the data model editor’s rights for the tool, you will see the Actions menu in your organisation's datamodels and edit functions in the menu. You can edit the selected association or modify its identifier. You can also remove the association. 

Additional functionalities for a data model editor 

More functionalities are visible to an editor who is logged in the Data Vocabularies tool, i.e. to a data model editor. 

Click Add association button when you want to add an association to a core vocabulary. A modal will then be displayed in which you can select, search for or create the desired association.  

Please note that associations are first created at the level of the entire datamodel, which means they are in common use. Once created, the association can be linked to one or more classes. 

In other words, the association is created only once, and a reference to this shared association is then simply added to the classes.  For example, the very common association “related to” does therefore not need to be created separately for each class requiring it – the classes simply refer to this general association. 

If the association is no longer needed in a class, the reference to it is removed from the class (first select the association and in its Actions menu select the Remove reference function). However, the association itself will not be removed from the entire datamodel, but the references in the other classes will remain unchanged.  

Please also note that if you edit an association that is in common use, the changes will be visible in all classes that it has been used in. However, in different classes the same association may have a different target class, i.e. some of the association information, the references, are "local" to that class and association.  

An association can be deleted from a datamodel only when it is no longer referred from any class. To delete an association, go to the association description page and select the Remove option from the Actions menu. 

Adding a new association to a datamodel

1. If you already know the name of the desired association, you can retrieve it directly through the search field. Enter the name of the association in the search field. 
2. By default, the tool will search for associations in the datamodels (namespaces) that you have added to your datamodel in the Links section. To search from all datamodels in the Data Vocabularies tool, change the selected option in step 2 to All data vocabularies. If you find a suitable association in a new datamodel and add the association to your datamodel, the tool will automatically add that datamodel to the Links section of the namespace. If too many options are offered, go back by selecting the option Data models added to this model. Associations only from a filtered set of datamodels will then be displayed again. 
3. Filter the number of associations by focusing the search only on the datamodels of a specific domain. 
4. Increase the number of available associations by focusing the search on all datamodels – all statuses - or focus the search on statuses not in use, i.e. retired or superseded datamodels. 
5. Filter the number of associations by focusing the search only on datamodels in a specific language. 
6. Browse the available associations by scrolling up and down the list. Select the desired association by clicking the radio button in front of it. Deselect it by clicking the radio button again. 
7. When you have selected an association, the Create a new sub-association for the selected button is activated. Click this button and the tool will display a new page on which you can enter the details of the sub-association. The tool will automatically mark the selected association as an upper association of the new association. 
8. If you did not find a suitable association among the ones defined above, click the Create new association button to display a new page on which you can enter the details of the new association. 
9. Cancel the addition of the association by clicking Cancel. 

You can add an association in two different ways: either from the class description page by clicking the Add association button or through the visualization. In both cases, the same insert modal view will be displayed.  

In the visualisation, first select the desired class and then click the box with three dots in the top right corner. Then select the Add association option.  

From the options offered by the tool, select the desired association and click Add association. If the desired association is not on the list, try changing the selected option under Datamodel (see step 2 above) to All data vocabularies to get more options. 

Then select the association you added from class information. Add the target, i.e. the class that the association arrow will be drawn to from this class. Click the Choose association’s target button under title Association target in this class. 

Search for the target class and click Choose association’s target, and the tool will draw an association line between the classes. 

The basic information on the datamodel is provided in the Description field in the Details tab. On the Documentation tab, you can enter longer description texts and provide other supplementary documentation. 

The Documentation view contains a text field with extensive descriptions and additional information on the datamodel.  

If you have the editing rights, you can see the Edit button. Click the button to edit the text.  

In practice, the field uses a Markdown editor that allows you to format the text, such as adding headings, body text, bolding, links to images, and more. As you write and edit the text, the tool shows under the Preview heading how the text will look on the webpage after saving. 

Once you have added the desired information, click the Save button and the text you have added will remain visible in the field. 

For basic information on the Markdown markup language, see GitHub's instructions, for exampleOpens in a new window.. 

Technical formats visible to everyone 

From the Actions drop-down menu, select Show as file if you want the datamodel to be displayed on the website in the technical format you have selected. 

Select Download as file if you want to save the datamodel to your workstation in the selected file format. 

The technical formats of core vocabularies are JSON-LD, RDF and Turtle. 

Additional functionality for a logged-in user: email notifications 

When you log into the Data Vocabularies tool, you will also be able to see a function on the Actions menu, which enables you to subscribe to a notification for when a new version of the datamodel is released.  

If you have already subscribed to notifications, you will see an option that enables you to unsubscribe. 

Additional functionalities for data model editors and main users 

In addition to the above-mentioned functionalities visible to everyone, a couple of other additional functionalities are available to data model editors and main users in the Actions menu.

Click the chevron symbol if you want to hide the panel on the left so that only the datamodel diagram is visible on the page. Click the chevron again and the panel will reappear. 

Information presented in the diagram 

1. Change the content language of the datamodel information and the visualisation from the Content in language drop-down menu in the upper right corner. 
2. The classes of the core vocabulary are displayed in violet in the diagram. If you select a class from the diagram or the panel on the left, the class will be highlighted in orange in the diagram. 
3. To enlarge, or zoom in the diagram, click the plus sign. 
4. To reduce the size of the diagram, or zoom out, click the minus sign. 
5. Spread the diagram over the entire window. 
6. Refresh the screen. 
7. Align the desired class to the centre of the view. 
8. Download the visualisation as an image file in PNG format to your workstation. 
9. Save the location of the classes. Please note that the icon can be seen only by a user who is a data model editor in a contributor organisation, in other words, has the editing rights. Other users can move the position of the class in the diagram, but this information will not be retained when the user exits the application. 
10. Click the chevron symbol to display the Diagram settings window, in which you can change the data visible in the diagram. 

Use the switches in the Graph settings menu to change the visibility of the following information: 

• Show/hide the attributes under classes 
• Show/hide the associations under classes 
• Highlight/hide the associations of classes: you can normally click only an individual association but this function is used to highlight all association lines originating from a specific class. 

Use the Show from resource option to change the diagram to show either the plain language name (e.g., requires) or the identifier of the resource, i.e. the technical, machine-readable name (e.g., fi-eauth:requires). 

Additional functionalities for a data model editor 

More functionalities are visible to an editor who is logged in the Data Vocabularies tool, i.e. to a data model editor.

Add an attribute or association to the datamodel by clicking the square with three dots in the title bar of the class. 

A window will then be displayed in which you can select the desired attribute or association. 

Adding bends to association and hierarchy arrows 

If the lines representing an association or a hierarchic relationship between different classes overlap or cross badly, first try moving the classes (boxes) to a more suitable position in the diagram. This is not always possible, so add bends to the lines that indicate an association or hierarchic relationship in the diagram, if necessary.  

First, move the mouse, or cursor, over the association line (or the dashed line of the superordinate class) and select it with a mouse click. The line is highlighted when you hover over it. The tool also highlights the association of the initial class. 

The mouse cursor initially appears as an open hand. Move the mouse and right-click when the cursor changes to a hand pointing with the index finger at the line; the tool will then add a bend at that point. 

The bend you added will appear as a dot on the association line. Add as many bends as you want. Drag the dot to the desired position in the diagram. During dragging, the mouse cursor will appear as a closed fist. 

To remove an unnecessary bend, first click the dot. A cross associated with the dot will appear in the diagram. Move the cursor over the cross, and when the cursor changes to a hand pointing with the index finger, click the cross to remove the dot.