The SEMIC Style Guide for Semantic Engineers

This style guide is intended primarily for semantic engineers, data architects and knowledge modelling specialists who are acting as editors or reusers of Core Vocabularies and Application Profiles.

This style guide may constitute a good source of information and explanations for the European Commission’s officers, collaborating consultants, and stakeholders involved in inter-institutional standardisation.

The main purpose of this style guide is to provide guidance and decision-making support for the creators, maintainers and publishers of the Core Vocabularies and Application Profiles. In the context of European Interoperability Framework (EIF) [eif] this style guide primarily addresses the Semantic Interoperability layer. The main part of this document is organised as a series of self-contained rules and guidelines.

In the scope of this document are included:

It is considered out of the scope of this document to provide:

This style guide is recommended to be used in combination with complementary documents, among which we consider relevant, but not limited to, the following ones:

This document is organised in two parts. The first part provides a brief context description and scope and offers an architectural overview. It introduces important terminological clarifications, the benefits of adopting the separation of concerns principle, and explanations of how it is played out in the SEMIC context.

The second part of the document provides a series of guidelines, conventions and assumption specifications. These guidelines are organised according to the aspects they cover. A guideline is a stand-alone description containing an indicative statement and a detailed description providing the rationale, benefits and limitations, implications and practical requirements, and eventually examples.

Users who may choose to bypass introductory details may decide to proceed with reading the general guidelines and the ones on the conceptual model first.

Definition
A conceptual model, also referred to as conceptual model specification, is an abstract representation of a system and comprises well-defined concepts, their qualities or attributes, and their relationships to other concepts. A system is a group of interacting or interrelated elements that act according to a set of rules to form a unified whole.

Description
A conceptual model is a representation of a system that uses concepts to form said representation. A concept can be viewed as an idea or notion, a unit of thought [skos]. However, what constitutes a unit of thought is subjective, and this definition is meant to be suggestive rather than restrictive. That is why each concept needs to be well named by providing preferred and alternative labels and should have a clear and precise definition supported by examples and explanatory notes. The conceptual model comprises representations of concepts, their qualities or attributes and relationships to other concepts. Most commonly, these are association and generalisation relations.

In addition, the conceptual model can be materialised in a graphical representation facilitating knowledge elicitation, organisation and interaction with domain experts. This is relevant because interactions and discussions within a Working Group for a data specification are often driven by a graphical representation. However, the need for a conceptual model and a visual representation shall not be conflated. Thus, we keep clear separation of concerns, which is addressed in detailed in the next section [Separation of concerns in SEMIC].

There is no perfect candidate for representing the conceptual model. And, although not without limitations, risks for misunderstandings and mis-interpretations, we choose (a subset of) UML language [epo-cm2owl] as most appropriate and instrumental in addressing (a) the concern for having a conceptual model established and (b) the concern for providing a graphical representation. The UML appropriateness has been acknowledged based on a longstanding experience and practices. An entire section of this style guide is dedicated to (UML) conceptual model [see Conceptual model conventions].

The subset of the UML language considered in this style guide is comprised (but not limited to) in the following set of UML elements:

For visual representation only UML Class Diagrams are considered.

Note: UML will be the recommended language for defining the conceptual models until a better and more appropriate alternative with robust tool support is developed, that is also addressing the SEMIC methods and practices [see Architectural clarification].

Definition
An ontology, also referred to as ontology specification, is a a formal specification describing the concepts and relationships that can formally exist for an agent or a community of agents (e.g. domain experts) [gruber93]. It encompasses a representation, formal naming, and definition of the categories, properties, and relations between the concepts, data, and entities that substantiate one, many, or all domains of discourse [wiki-onto].

Description
The ontology constitutes the formal (machine-readable) definition of concepts. Although the languages for expressing ontologies vary in expressivity, we shall keep it light and simple, from the formal point of view, with minimal detail and level of expressivity [SC-R2]. Backer & Sutton explain well how lightweight semantics supports interoperability and reuse [baker15].

In the SEMIC context, we only consider lightweight ontologies [defined in rule SC-R2]. Therefore, even if this aspect is not emphasised as "lightweight ontology", it is implicitly meant even when simple "ontology" reference is used.

We assume that the ontology is expressed in OWL 2 language [SC-R1].

The main purpose of this component is to declare the classes, properties, datatypes and controlled lists. Each construct is established by assigning a URI and decorating it with human-readable labels and descriptions, and constitutes the mechanism to establish common references for humans and machines.

Definition
A data shape specification, also referred to as data shape constraint specification, or simply as data shape constraint or data shape, provides a set of conditions on top of an ontology, limiting how the ontology can be instantiated.

Description
The conditions and constraints that apply to a given ontology are provided as shapes and other constructs expressed in the form of an RDF graph. We assume that the data shapes are expressed in SHACL language.

This document will refer to data shape constraint specifications simply as "data shapes", but occasionally also as "data shape constraints" or "data shape specifications".

Definition
A data specification document, also referred to as specification document, is the human-readable representation of an ontology, a data shape, or a combination of both.

Description
A data specification document is created with the objective of making it simple for the end-user to understand (a) how a model encodes knowledge of a particular domain, and (b) how this model can be technically adopted and used for a purpose. It is to serve as technical documentation for anyone interested in using (e.g. adopting or extending) a semantic data specification (see [What is a semantic data specification?]). We assume that the data specification documents are published in HTML format (optionally, others). See, for example, the Core Person specification [cpv] or the CPSV-AP specification [cpsv-ap].

Definition
A data specification artefact, often referred to as specification artefact or simply artefact, is a materialisation of a semantic data specification in a concrete representation that is appropriate for addressing one or more concerns (e.g. use cases, requirements).

Description
In the SEMIC context, we consider the following artefact types as primary: ontologies, data shapes, and specification documents. For a description of various concerns addressed in the SEMIC context, please see the section [Separation of concerns in SEMIC].

Additionally, we are concerned with syntax bindings and serialisation formats (XML/XSD and JSON-LD in particular). Still, these are not in the scope of this document and are addressed elsewhere. For more, see section on [Data specification and artefact types].

Definition
A semantic data specification , often called simply data specification, is a union of machine- and human-readable artefacts addressing clearly defined concerns, interoperability scope and use-cases. A semantic data specification comprises at least an ontology and a data shape (or either of them individually) accompanied by a human-readable data specification.

Description
One general categorisation of semantic data specifications is along the reuse axis.

Some semantic data specifications are built with the intent that the terms of the conceptual model can be used in as much as possible contexts. Typically, it is possible to use the terms independently of each other. In this case, the definitions of the terms are usually very broad and abstract, and only the bare minimum of (usage) constraints are expressed. Often, the terms are presented as a list to the reader, with identifiers for each term in the same namespace. Those semantic data specifications are usually denoted with terms such as vocabularies or terminology.

On the other side of the spectrum are the data specifications that precisely encode the semantics of the conceptual model that is being used in a single data exchange context, implemented in software or API. They usually have a strong connection with technical data representations (see section on [Technical artefacts and concerns]) and documentations such as XSD schema, OpenAPI specifications, etc. Conceptual models for this purpose will contain precise constraints, technical datatypes, the code-lists that are being used, refer to implementation decisions, etc. Semantic data specifications that are created for that purpose are denoted with Implementation Models. As that name indicate, their objective is to encode the conceptual model of an implementation.

Between those two extremes, i.e. contextfree reuse (vocabularies) and unique usage context (Implementation Models), there are semantic data specifications that aim to capture the conceptual model for a broad, yet well-defined, usage context. Typically, these data specifications do not intend to introduce new terms in the conceptual model, but will exploit terms from other semantic data specifications. These exploited terms are augmented with additional usage constraints making the terms more fit for purpose. These semantic data specifications are often denoted with terms such as Application Profiles or Profiles.

Readers should understand that the usage relationships between semantic data specifications form a complex network. An attempt to provide a structured view on this network was initiated in the draft W3C Profile Guide [profile-guide]. Also, the Application Profiles do not necessarily have to address all the technical needs related to an implemented system. Distinction between technical and semantic interoperability layers is attempted in this section.

This categorisation along the reuse axis indicates the importance of expressing the interoperability scope for semantic data specifications. However, due to the absence of widely accepted definitions for those categories, outlining the exact Dos and Don’ts (for each category), may result to different expectations for each category. This style guide is a document that defines the commonly accepted and applied rules for SEMIC.

In the SEMIC context, two types of semantic data specifications are considered: [Core Vocabulary] and [Application Profile]. Semantic data specifications of the third category, Implementation Models, are not part of the activities of SEMIC. Nevertheless, their existence, is taken into account when building the Core Vocabularies and Application Profiles.

Occasionally, this document will refer to semantic data specifications shortly as "data specifications". With a similar meaning, the term "semantic asset" is used in the literature (e.g. ADMS [adms]). However, in our understanding, the term "semantic asset" is broader than "data specification" and includes controlled vocabularies and possibly other types of assets.

Definition
A Core Vocabulary (CV) is a basic, reusable and extensible data specification that captures the fundamental characteristics of an entity in a context-neutral fashion. Its main objective is to provide terms to be reused in the broadest possible context.

Broad context (on vocabularies)
On the Semantic Web, vocabularies define the concepts and relationships (also referred to as "terms") used to describe and represent an area of concern. Vocabularies are used to classify the terms that can be used in a particular application, characterise possible relationships, and define possible constraints on using those terms. In practice, vocabularies can be very complex (with several thousands of terms) or very simple (describing one or two concepts only) [vocab].

There is no clear division between what is referred to as "vocabulary" and "ontology". The trend is to use the word "ontology" for a more complex and possibly quite formal collection of terms, whereas "vocabulary" is used when such strict formalism is not necessarily used or used only in a very loose sense [vocab].

SEMIC context (on Core Vocabularies)
Formally, a Core Vocabulary encompasses a lightweight ontology, and, optionally, a (permissive) data shape specification, and it is expressed in a condensed, comprehensive data specification document.

For more details see section on [Data specification and artefact types].

The qualifications lightweight and permissive are used to better emphasise the intention to be reused in the broadest possible context. More precise boundaries are defined further in this document.

NOTE: "Vocabularies", in general, are not the same as "controlled vocabularies", as the latter usually refers to SKOS artefacts. However, in other contexts (similar to SEMIC), a Core Vocabulary might often be simply denoted as "vocabulary".

Definition
An Application Profile is a data specification aimed to facilitate the data exchange in a well-defined application context. It re-uses concepts from one or more semantic data specifications, while adding more specificity, by identifying mandatory, recommended, and optional elements, addressing particular application needs, and providing recommendations for controlled vocabularies to be used [dcat-ap].

Description
An Application Profile (AP) is a data shape specification which addresses particular application needs (operating within some domain or community) while providing semantic interoperability with other applications based on one or more shared ontologies (vocabularies) [dc-ap].

Formally, the Application Profile encompasses (a) reused ontology specifications (one or many) and (b) its own data shape specification. Optionally it may include (c) reused data shape specifications (one or many), and (d) it may provide its own ontology specification to fill the ontological gaps.

SEMIC context
In SEMIC, Application Profiles encompass an ontology, which is largely composed of importing the reused ontologies, complemented with an appropriate data shape specification. Terms that are introduced because of the Application Profile needs are, by preference, added to existing Core Vocabularies. If this is not possible, an Application Profile-specific Vocabulary is created.

The data specification document of an Application Profile is elaborated. It provides the application scope and context, and documents the ontology and the data shapes through the conceptual model. It also provides additional information that stimulates the adoption and correct usage of the AP in implementations.

The consumers of SEMIC standards specification can be divided into three categories:

The SEMIC goal is to bring these groups together, help them "speak the same language" and share meaning and conceptual references. Besides the very useful and much needed alignment of domains experts on what concepts mean, it is necessary to bridge the gap between domain experts and the technical experts who implement information systems. Then, the domain experts and business users shall interact with the information systems using the very same set of concepts, agnostic to and undistorted by the technology in the implementation process.

Standard semantic data specifications fulfil the purpose keeping these three groups in sync.

Ultimately, if the systems are based on standards the purpose is to build interoperable machines - machines that share data with each other and are able to operate on them seamlessly. The developers implement those machine interactions, and therefore the machines and developers must "find a common language". However, in order to ensure that the developers take the appropriate steps, the business/domain experts have to interact with them and convey their domain knowledge. This closes the loop: that the machine interactions correspond with the business/domain expert expectations.

The data specification shall address the following information needs: visual representation, textual description, machine interpretable representation, and optionally additional representations that facilitate and promote adoption.

The aim of this style guide is to ensure the creation of coherent data specifications that can be read and used by domain experts, developers and machines. It is mainly meant for the editors of the data specifications (e.g. semantic engineers, data architects, knowledge modelling specialists).

Such data specifications are primarily developed in collaboration with domain experts. To achieve synergy with the domain experts, graphical representation is an indispensable medium that facilitates knowledge elicitation, ideation and knowledge organisation. This becomes especially relevant when shared conceptualisation needs to be attained within a Working Group.

The successful application of an ontology or the development of an ontology-based system depends not merely on building a good ontology but also on fitting this into an appropriate development process and implementation into an information system.

Generally, computing information models suffer from the intertwining of two types of semantic concerns. As George Box said, "All models are wrong, but some are useful", and what a model is useful for depends on what concern it is primarily addressing. On the one hand, the model represents (purely) the domain; on the other hand, it represents the implemented system, which encompasses a representation of the domain (domain knowledge intertwined with technical specificities). These different representation requirements place different demands upon its structure [partridge13]. For example, the concept of "location" can be described by domain experts (in a domain model) in a way that is not isomorphic to how the "location" class may be appropriately modelled for an information system (i.e., captured in an Implementation Model).

One of the common ways to manage this problem is by separating concerns. We take inspiration from OMG’s Model Driven Architecture (MDA) [mda], which is a well-documented structure where a model is built for each concern, which is transformed into a different model for a different concern. This approach is adapted to the SEMIC needs.

Transformation deals with producing different models, viewpoints, or artefacts from a model based on a transformation pattern. In general, transformation can produce one representation from another or cross levels of abstraction or architectural layers [mda-guide].

The Core Vocabularies (CVs) and the specialised Application Profiles (APs) aim to address the following concerns:

In addition, when multiple artefacts addressing each concern are produced, keeping them in synch is a serious editorial and maintenance burden that needs to be considered.

On the editorial side the artefacts composing a data specification need to be kept in sync. A modification done in one shall pervade and propagate in all others. This is a difficult, tedious and expensive activity if such synchronisation is to be done manually.

Experience shows that using a pivot representation as a single source of truth is a viable solution. Such representation needs to be expressive enough to fulfill all the information needs of the derived artefacts.

UML conceptual models can be used as the single source of truth [CMC-R1]. This means it is sufficiently expressive to capture multiple modelling aspects/concerns simultaneously. The other artefacts are then fully or partially derived from the conceptual model.

With UML as the single source of truth, the update process is easier to perform as it only has to be done in a single place. The other representations are automatically derived from the conceptual model; the maintenance is less error-prone, uniform and easy [Transformation].

This approach facilitates consistent maintenance of semantic data specification interrelationship and solves the editorial synchronisation problem.

However, using UML is not enough, by itself, as the risk of ambiguity and multiple interpretations of the meaning of the UML model elements used in the conceptual model still exists. This risk is mitigated by adopting precise interpretation rules, such as the ones provided in this style guide [CMC-R2]. The different concerns that each data specification is trying to address might lead to different interpretations of the same UML constructs. Therefore, [CMC-R2] defines only a minimal set of such interpretation rules (that can be further extended, if necessary).

Additionally, UML cannot cover all potential needs specific to each derived representation. Therefore, the scope of this architecture is limited by what can be expressed in UML and how that information is utilised to generate formal statements. But from our experience it is sufficient to cover all the needs of establishing semantic interoperability standards.

Relations between the artefacts are depicted in the figure above. The conceptual model is the source from which a) the data shapes, b) the formal ontology and c) the data specification document can be generated. Each artefact in the figure is qualified with two terms, the representation standard and the most characteristic feature. The conceptual model is expressed in UML language and shall be conformant with the conventions provided in this style guide and the interpretation rules [CMC-R2]. The formal ontology is expressed in OWL 2 language and shall be lightweight as indicated in this convention [SC-R2]. The data shape is expressed in SHACL language and is characterised by the appropriate level of permissiveness [DSC-R2]. The documentation is represented in HTML format and the wording used shall be as precise as possible to capture the meaning accurately and clearly express the intention of the authors.

Although not shown in this diagram, the generation of other artefacts is not excluded. For example, more heavyweight ontologies (i.e. with higher level of logical expressivity) can also be included in the data specification as additional artefacts (see note on [SC-R2]).

The figure above depicts that it is also possible to derive from the conceptual model additional artefacts, such as the XSD or JSON schemas and JSON-LD context definitions. These, however, are not addressed in this style guide.

One condition the conceptual model shall satisfy is that it shall comply with a set of pre-established conventions (general conventions and UML conventions) and have a fixed interpretation [CMC-R2].

The guidelines in this document enable and constrain the transformation process, making it precise enough to implement a toolchain that automatically performs conformance checking and necessary transformation operations. How this is done, however, is beyond the scope of this document, and the reader may refer to SEMIC toolchain [semic] or other similar implementations such as model2owl [model2owl] or OSLO toolchain [oslo-toolchain] projects.

For any given data specification, various concerns shall be addressed separately, each in a dedicated artefact type. Therefore, the CVs or APs shall be published as a set of artefacts, each addressing a specific concern. The union of these artefacts forms the intended semantic data specification [What is a semantic data specification?].

The table below summarises which artefacts shall be published for each type of data specification addressed in the SEMIC context.

It is difficult to draw a clear line between semantic and technical interoperability artefacts and concerns. This section aims at providing some guidelines and hints on how to distinguish between the two (but no guidelines on technical artefacts are considered as this is out of scope of this work). The best way to look at them is in terms of concerns addressed within each layer, which resembles a lot the discussion on distinguishing "Conceptual Data Models", "Logical Data Models" and "Physical Data Models" in ANSI [ansi] from 1975.

EIF [eif] defines the technical interoperability as covering the applications and infrastructures linking systems and services. The concerns considered in this layer are related, but not limited, to:

The technical layer deals with how to represent, how to transmit data, how the data/entities are bundled when served by a service (i.e. API design or transmission, with impact on performance, usability, and interface), what are the access rights, how is the security ensured, access and storage performance, interfacing with the service, usability, etc.

EIF defines the semantic interoperability as ensuring that precise (format and) meaning of exchanged data and information is understood throughout exchanges between parties: "what is sent is what is understood". It covers two aspects: semantic and syntactic. The semantic aspect refers to the meaning of data elements and the relationship between them. The syntactic aspect refers to describing the exact format of the information to be exchanged in terms of grammar and format.

The concerns considered in this layer are related, but not limited, to developing vocabularies and define data meaning in exchanges. This layer is agnostic to access right, security, transmission protocol, physical representation, how it is presented to the user, etc.

In the SEMIC context, Semantic Web and Linked Data technology standards are chosen by default. This means that the syntactic aspect is covered by the RDF specifications [rdf], whereas the semantic aspect is addressed within the Core Vocabulary and Application Profile, expressed in OWL 2 [owl2] and SHACL [shacl] languages.

Connecting the semantic layer and the technical layers may not always be straightforward. Three types of technical artefacts are of a particular importance, which rely on three different technologies: XML and XSD, JSON and JSON schema, and relational databases. We briefly comment on each below.

RDF. In case the system is gnostic of Semantic Web technologies, if the implementation uses RDF natively, then the technical layer is (near) isomorphic to the semantic specification. There is a perfect alignment.

JSON. When system implementation is based on JSON representations, a mapping shall be provided to establish semantics-syntax alignment. Luckily, how such an alignment is done is already specified in the JSON-LD standard specification [json-ld]. It contains a canonical mapping algorithm. The syntaxt semantic binding is provided by the so-called context definitions.

As a consequence, if the JSON structure is ought to be aligned with the semantic specification, it imposes a strong constraint on how it shall be organised, otherwise the mapping is not possible. So, an advantage of JSON-LD is that the semantics gets coupled nicely with the syntax, and it is in the reach of the developer.

XML. When the system implementation is based on XML representation, then the interplay between syntax and semantics is more problematic, as there is NO canonical way os linking the two. The only transformation we have is the XSLT [xslt] but no mapping language exists like in the case of JSON-LD. Hence, if one provides a mapping to an XSD schema, then one must also provide the XSLT specification that interprets that mapping. Furthermore, when we want to establish an alignment between syntax and semantics there is no constraint on the structure (like in the case of JSON). It is only good practices and alternative technologies, such as RML, that we can rely on in this case. [rml].

RDB. If the implementation is based on relational databases, the story is similar to the XML. There is no organic way of mapping syntax and semantics. The mapping is at the level of the database schema, and there is no canonical way of doing this. So, just like in the case of XML we rely on good practices and alternative technologies to encode an interpretation, such as D2RML [d2rm] and RML [rml].

Ideally, syntax-binding artefacts that show how to map from a semantic data specification into technical layer artefacts is also provided as part of the specification. Showing how to interface with the semantic layer is especially important when Application Profiles (and Implementation Model specifications) are developed and published.

Specification reuse is the act of sourcing an established specification into a new one (referred to as the "current" or "own" specification).

Technically, reuse may mean either or both of the following:

The following subsections offer a systematic description of six cases of reuse based on what is reused: (a) a class or (b) a property, and types of frequently encountered variations: (i) as-is, (ii) with terminological adaptations, and (iii) with semantic adaptations.

In each case, we describe as appropriate the implications on the following aspects:

This scenario applies when the original class is reused without terminological or semantic changes.

This scenario applies when the original class is reused without semantic changes. Still, a label or definition needs to be modified to reflect the meaning in the new context accurately.

Example

For example, the wording of FOAF definitions can benefit from light adaptations and adjustments, yet the meaning is not changing. Hence, in Core Person Vocabulary, the definitions are slightly adjusted. Such adaptations might be made when the original label or definition does not follow the guidelines laid out in this document. For example, the one on circular definitions [GC-R5].

This scenario applies when the original class is reused with semantic changes, which also implies terminological adaptations.

Example

For example, in the Core Public Organisation Vocabulary, the reused class org:Organisation is specialised as cv:PublicOrganisation.

This scenario applies when the original property is reused without terminological or semantic changes.

This scenario applies when the original property is reused without semantic changes. Still, a label or definition needs to be modified to reflect the meaning in the new context accurately.

Example

For example, in DCAT-AP the reused property adms:status is relabeled from "status" to "change type" for Catalogue Record class. Note that the diagram does not reflect this, but it is reflected in the associated documentation.

This scenario applies when the original property is reused with semantic changes, which also implies terminological adaptations.

Example

For example, in the DCAT-AP the reused property dct:hasPart is specialised as dcat:dataset. Note that the subproperty relation between the two is not depicted in the diagram, but is stated in the data shape specification.

Description:

A methodology is a set of methods, processes, and practices that are repeatedly carried out to deliver projects (TOGAF [togaf]). It helps by using a clear set of processes for managing projects that everyone in the organisation understands, reducing risks, and improving the chances of success. A good methodology that fits the context and environment of an organisation can provide clear guidance on what, who, when, and how a project should be done. It also provides a clear path and a systematic strategy to solve the in-field problems.

We do not outline a concrete methodology here but merely point to the benefits of adopting and using one. In the SEMIC context, conceptual model development will benefit greatly from embracing some or a combination of techniques and frameworks in data modelling (e.g. Bottom-Up, Top-Down, Case-Based, Entity-Relationship, Object-Oriented, Star/Snowflake Schema data modelling techniques, etc.), ontology engineering methodologies (e.g. Methontology [fernandez-lopez97], DOGMA [jarrar08], OntoClean [guarino04], TOVE [fox92], DILIGENT [pinto04], NeOn [neon], etc. [sure09]), data management body of knowledge (DAMA-DMBOK [dama-dmbok]) or architecture frameworks and practices (e.g. TOGAF [togaf], Zachman Framework [zachman87], EAP [spewak06], etc.).

Among other benefits of adopting a clear and well-defined methodology are:

Description:

Establishing project scope ensures that the modelling work is focused and executed to expectations. It also helps define where the boundary of the model is and what shall be left out.

The clearer the scope the higher chances of success are.

It shall be possible to determine the scope of a data specification from the use cases for which it is drawn up. [oslo-rules, sec 3.1.4]

Description:

Divide and conquer method works in many situations, including in the modelling realm. It may not be easy, however, to make a clearcut separation between concepts belonging to one module or another, and such an attempt will certainly bring clarity.

Sometimes, a concept can be used for several domains. Then it shall be placed in a separate module. [oslo-rules, sec 3.1.3]

The need for modularisation typically emerges when the to-be-modelled space grows. As the terms are to be identified by URIs [PC-R2], it is recommended to include in the used URI structure modularisation potential.

Description:

Only use constructs with semantics (human and machine-readable) that support the use case or domain. A similar reflex must be considered by reusing properties and classes from other vocabularies. As a general rule, it is safe to reuse annotation properties, as they carry no logical semantics. Conversely, no concepts shall be redefined unless they are significant variations of the existent ones. In order to achieve a common approach to reuse, apply the reuse guidelines as specified above [Clarification on the reuse].

See more [ ld-bp, ldp-bp, dwbp, epo-arch, oslo-rules ]

Description:

Some projects are implemented and closed, while some other ones keep being maintained. The maintenance usually aims at (a) fixing errors, (b) making gradual improvements, and (c) supporting users in using the released data specification, to mention the least. Maintenance of the project can also include URI dereferencing and handling open issues in a timely fashion. Some projects may foresee an evolution roadmap, defined in a change and release policy, with a series of evolution stages planned.

Description:

Terms and concepts are not the same things. A term is a word, compound word, or multi-word expression that, in specific contexts, is given specific meanings – these may deviate from the meanings the same words have in other contexts and in everyday language. A concept can be viewed as an idea or notion, a unit of thought [skos]. However, what constitutes a unit of thought is subjective, and this definition is meant to be suggestive rather than restrictive. That is why each concept needs to be well-named (termed) by providing preferred and alternative labels and should have a clear and precise definition supported by examples and explanatory notes. So, we need a precise way to refer to concepts. The mechanism offering such a possibility is using URIs to establish the identity of a concept’s "meaning". URIs also enable referencing, an essential feature of meaning exchange (communication). Such a reference allows for establishing a common meaning, not only between humans and machines but also among humans. Finally, the meaning of the term must be clear. Its definition is associated with the term via the URI. To make the term reusable, it should be published as part of a data specification.

See more [ ld-bp, ldp-bp, dwbp, epo-arch, oslo-rules ]

Description:

In practice, some variation in terminology style (concept naming conventions) can be noticed across a wide range of semantic data specifications. Whatever the adopted style may be, the author shall consistently apply it to the whole model. These names will be reflected in all artefacts and in the URIs.

Next, we provide a set of loose recommendations:

Description:

In practice, different styles of defining concepts can be noticed across a range of semantic data specifications.

The SEMIC Principles for creating good definitions [semic-defs] are a basis for writing definitions. They are based on advice found in the literature and are the following:

Compliance checking with an application semantic data specification shall be permissive. This means that what is not forbidden is permitted. If the context requires more restrictions,then an application profile needs to be established for a narrow(er) scenario.

Technically, we envisage compliance checking limited to correct referencing of the concept URIs and respecting the cardinality constraints and value constraints in the case of properties. This falls within the scope of data shape definitions. Additionally, more specific compliance requirements and constraints can be added as necessary.

Compliance checking may involve multiple levels of severity. For example in the SHACL specifications three levels are defined: Violation, Warning, Info. We assume by default the SHACL severity specifications unless other denotations systems are provided (i.e. different labels and delimitation of severity). Also in absense of specifications, any unfulfilled compliance check is considered a Violation.

The semantic data specifications may provide such severity levels. How it is realised in the conceptual model is open at the moment. The main place to provide such specifications is the data shape artefact. In the future we can return to this aspect and provide more guidance.

Deontic modalities indicate levels obligation, permission, necessity and related concepts.

As a general recommendation, to use deontic indicators in the semantic data specifications is discouraged. Such indicators could be of editorial or guiding role for the users and adopters of the data specifications. However, it should be noted that they are not considered as part of any compliance validation or semantic interpretation of the data model.

In the standardisation community a common practice is to indicate levels of obligation or permission for concepts in a semantic data specification. Obligation indicator signals whether a statement using a class or a property is required in an instantiation; while, Permission indicator signals whether a statement using a class or a property is allowed or forbidden in an instantiation.

The common deontic indicator values are:

Still, there are ways to achieve the same effect as the these indicators through other means. For properties, the main instrument is employment of cardinality constraints (per property per class). To make a property mandatory set the minimum cardinality to one or more [1..*], otherwise relax the minimum cardinality constraint to keep the property optional [0..*].

For classes, it is possible to mark a class as abstract, which means that it cannot be directly instantiated, therefore achieving the effect of forbidden. However, deontic indicators shall be avoided for classes because a class may be mandatory and optional in different instantiation or exchange scenarios within the same application profile.

For example consider the DCAT-AP and two mandatory classes: dcat:Catalog and dcat:Dataset. When metadata of a catalogue (and its records) is exchanged, then both classes dcat:Catalog and dcat:Dataset must be instantiated; however when a single dataset metadata is being exchange then only dcat:Dataset instance shall be provided. Moreover, in the second scenario, providing an instance of dcat:Catalog will be counterproductive and possible leading to errors.

Descriptions of what classes can or shall be bundled together when participating in information exchange belong in "data exchange contracts", "API endpoint scheme definitions" or the likes of these. Such specifications belong in the Technical Interoperability layer of the European Interoperability Framework (EIF) [eif], and are (currently) out of scope of this style guide, which aims primarily at addressing the semantic interoperability.

If semantic engineers prefer or are compelled to employ deontic indicators, then deontic indicators must be precisely defined and those definitions must be published. No reliance on common sense understanding shall be assumed as the meaning of such deontic indicators may (and certainly) differ not only among readers of data specifications but also in different data specifications.

Description

By applying this principle, we can achieve consistency among all derived artefacts.

This implies:

It is recommended that recent versions of the UML (v2.5+) and XMI (v2.5+) specifications are used [epo-cmc, sec 4.1].

Description:

Using UML as a graphical language to encode a data specification according to the reuse guidelines requires defining a set of pre-established conventions on the UML notation to reach a fixed interpretation.

The interpretation of UML as a logical structure, including OWL 2, was and still is an active research topic. But even the OMG Ontology Definition Metamodel [omg-onto] does not address the notion of reuse. The goal of using UML is to provide for the SEMIC semantic data specifications a standard graphical notation, which many are familiar with. Therefore, the graphical notation should facilitate the understanding of the data specification. The UML notation should match the semantics that are to be expressed in the data specification (the ontology, data shapes and human-readable documentation).

The UML is the single source of truth [CMC-R1]. Using the conventions and associated interpretation expressed in this rule, other artefacts are derived from the UML. The benefit of defining such a precise set of mapping rules is that it allows for:

These rules will increase the coherency of the UML diagrams across projects and organisations.

Within SEMIC, the interpretation is implemented by the SEMIC toolchain [semic].

The table below provides recommended interpretations of UML elements in OWL 2 and SHACL. These interpretations can be considered high-level mapping rules implementable into transformation tools that generate OWL 2 ontology and, respectively, SHACL constraints from the UML conceptual model.

Description:

This convention aims at ensuring that URIs can be generated from UML Element names and shall be treated as an extension to the terminology style conventions [GC-R4].

The Element names are intended as human-readable denominations (called labels) and as machine-readable denominations (called identifiers).

This means that the Element names

Thus, in the UML model, the Element names must conform to RDF [rdf] and XML [xml] format specifications. Both languages effectively require that terms begin with an upper or lower case letter from the ASCII character set or an underscore (_). This tight restriction means that, for example, terms may not begin with a number, hyphen or accented character [cv-meth]. Although underscores are permitted, they are discouraged as they may be, in some cases, misread as spaces. A formal definition of these restrictions is given in the XML specification document [xml].

Note that, when the UML Element name cannot be used to effectively denominate and identify the concept then, UML Element Tags may be used to express explicitly URIs, labels, notes and other types of annotations [CMC-R6].

Internationalisation, if required, should be provided through the use of the UML Element Tags to specify labels that will be used for generation of specification documents in languages other than English. Country specific data specifications, which are meant to be used primarily at a national level, might decide to relax on this convention and permit the use of Unicode characters in the Element names, which will result in the generations of IRIs, instead of URIs [iri]. However, this is unnecessary, and strongly discouraged, in the SEMIC context.

Following this convention is also important in the context of generation of persistent URIs [PC-R2] according to the principles laid out in [10rules-puri].

Description:

The names begin with an upper or lower case letter (A–Z, a–z) for all terms in the model. Digits (0–9) are allowed in the subsequent character positions. [epo-cmc, sec 4.2]

Moreover, we can significantly improve the readability of an ontology if we use consistent capitalisation for concept names; therefore, UML Element names shall be CamelCased [epo-cmc, sec 3.2], [oslo-rules, sec 3.2.20].

The names of

The names of

Description:

To enable the reuse of names defined in other models, and the reuse of unique references for names that support easy identification, namespace management must be considered. We adopt the XML and RDF approach to defining and managing namespaces [xml-ns].

A namespace is a set of symbols that are used to organise objects of various kinds so that these objects may be referred to by name and uniquely identifiable [urn].

A qualified name denotes the URI, which is composed of concatenating the expanded prefix with the local segment [turtle]. A qualified name is a name subject to namespace interpretation [xml-ns]. Syntactically, they are either prefixed names or un-prefixed names. A binding declaration shall be maintained, which binds prefixes to namespace URIs and a default namespace applicable to un-prefixed Element names.

As the Element name is the primary source for deriving URIs, a base URI and a local segment are necessary. The Element name prefix, before the colon, plays the role of namespace name indicating which base URI shall be used, while the Element name, after the colon, is the local segment. See [xml-ns] for more info.

In case the editor decides to omit to specify a prefix in the Element name when a URI generation logic is devised, an implicit prefix can be assumed by default. The qualified names may be structured as follows:

Note: The prefixes and namespaces shall be well-defined, maintained, and published as part of the data specification.

Description:

UML Element tags are key-value pairs that are associated with a UML Element (class, attribute, connector, etc.). The tags can be used as an extension mechanism to the UML language. They can be used to provide information that is not expressible anywhere else on a UML Element.

For example, in this style guide, we recommend that the UML Element name shall be used to derive both the concept URI and the concept preferred label. However, if the model editor chooses to use the UML Element name for deriving the concept label alone, then the URI needs to be specified elsewhere. This is one example of how the UML tags can be used: simply specify a new tag, "uri", and provide the concept URI as a value (see figure below).

Another example where tags came in handy is the provisioning of notes of various types. According to the UML standard, UML Elements have only one general description. We recommend using this description solely for definitions. Yet the scope notes, examples, alternative labels, and any other annotations can be provisioned through the UML tagging mechanism (see figure below).

Description:

UML does not support an import mechanism comparable to the one specified in OWL 2. Yet, the reuse of models is a highly encouraged practice. To accommodate such practice, the reused Elements shall be created as in the original model and depicted in diagrams.

The external Elements shall be clearly marked. The easiest way to do so is by providing a namespace prefix. The original meaning shall be preserved without changes to the labels, concept definitions or URIs.

Reused classes shall be depicted in the UML diagrams. Reused properties shall be depicted in diagrams as connectors and attributes. It is not necessary to depict unused classes or properties [oslo-rules, sec 3.1.7].

Description:

This is a general modelling principle that should be respected, yet when it comes to reusing, such a requirement is often overlooked. This means that the model editor shall carefully analyse the reused model as a whole and how it is integrated with their own model.

See more [oslo-rules sec 3.2.3]

Description:

When a (super-)class is created for capturing a level of abstraction in the domain knowledge, it may not always be suitable for instantiation. Editors may choose to mark such classes as abstract and to indicate that their subclasses shall be used in practice. In UML, this can be done via << abstract >> stereotype [see CMC-R17: Using stereotypes].

Doing so has no impact on the OWL 2 [owl2] representation of the model (as this cannot be expressed in OWL). However, depending on the toolchain implementation, SHACL data shapes [shacl] can be generated to express that no instances of this class shall not occur in the data.

See [oslo-rules sec 3.2.6, epo-cmc, sec 4.4]

Description:

We recommend atomic types are used as attribute types and avoid using another class as the attribute type. Instead, those should be expressed as relationships (represented by Association connectors) between the two classes [CMC-R12].

The reason for this is to keep a clear separation between (a) properties that take a literal value (governed by a datatype, and conceptually corresponding to owl:DatatypeProperty) and (b) properties that take a reference value (governed by a class, corresponding to owl:ObjectProperty). Doing so has two advantages: (a) it confers homogeneity to the model, which enhances readability and decreases ambiguity; (b) the toolchain implementation is easier as there is a clear treatment and interpretation.

literal properties (expressed as attributes datatypes) and relations between two classes (expressed as association connectors). The advantage of

In case of primitive datatypes, high preference shall be given to using OWL 2 compliant XSD [xsd] and RDF [rdf] standard datatypes. For more detailed recommendations on the use of primitive datatypes see convention [CMC-R18].

Properties whose values come from a controlled vocabulary or authority table constitute a special case, because two modelling practices are recognised here: (a) as attributes with type "Code", and (b) as dependency relations pointing to a UML Enumeration named after the controlled list.

In the first case, the attribute type "Code" shall be mapped to the skos:Concept class. The advantage of this approach is the compactness of the diagrams, as fewer boxes appear in them. The disadvantage is the omission to specify precisely, which list the property values are restricted to. Arguably, the controlled list can be provided via the additional UML Tags [CMC-R6], but that value will not be visible in the diagrams.

In the second case, the property is modelled not as an attribute but by using a UML Dependency connector between the UML Class, and the UML Enumeration representing the controlled list, oriented from the Class towards the Enumeration. It denotes that the OWL 2 class has an owl:ObjectProperty whose range is of type skos:Concept and is limited to values of the specified controlled vocabulary. The connector must have a "Source→Target" direction. No other directions are acceptable, and a valid target role name and multiplicity shall be provided [CMC-R14].

Finally, we emphasise that UML Connectors are reserved for the object properties only. Hence, none shall be established between a UML Class element and a UML Datatype element.

Description:

If the UML model is developed to represent a Core Vocabulary, then the property cardinality (both UML Attributes and UML Association) shall be as permissive as possible, for example, [0..*], meaning any occurrence is allowed.

If a structural feature (attribute or association) is irrelevant for the domain or the applications, instead of setting a lower limit of multiplicity to 0, simply remove it from the model [oslo-rules, sec 3.2.15].

However, in the UML models representing Application Profiles, special attention shall be given to the multiplicity, reducing variation in the instance data to a minimum. And if a property (attribute or connector) is mandatory in the data, then its minimum cardinality shall be set to 1, for example [1..*] [epo-cmc, sec 4.5].

A good practice is to always indicate cardinality. It may be left unspecified, but this is not recommended. When in doubt, it is recommended to fall back on the implicit assumption of [0..*]. Not to be confused with the default cardinality assumed in tools. For example, Enterprise Architect by default assumes [1..1] cardinality for attributes and omits to display it; and a similar default assumption exists in XML/XSD.

Notation for multiple cardinality can be either with * or n. In principle using either notation is fine, however, it is recommended to use only one of those notations within a given data specification consistently, if possible, to enhance readability. It is worth highlighting this, as some UML tools, by default, might use a different notation for multiple cardinality depending on whether it is specifying the cardinality of attributes vs. that of connectors. The UML processing tools should be implemented so as to handle either of those notations, as their meaning is identical.

Unless, well explained, no rigid constraints shall be imposed on attributes and associations. In other words, if specified, the cardinality shall be the most permissive, where possible [oslo-rules, sec 3.2.15].

Limit the constraints to business rules, do not add technical constraints to the model [oslo-rules, sec 3.2.16].

If an attribute or an association from a reused vocabulary is irrelevant, do not set the lower limit of multiplicity to 0, but simply omit it in the model [oslo-rules, sec 3.2.15].

Description:

UML Connectors shall be used to denote object properties (see OWL 2 semantics, [owl2]).

First, we explain how the connectors ought to be used, i.e., where to specify the relationship names and multiplicity. Then we explain the optional usage of the dependency connector type.

On connector names, a generic UML connector may have a name applied to it, and it may have source/target roles specified in addition. This provides flexibility to how the domain knowledge may be expressed in UML; however, this freedom increases the level of ambiguity as well. Therefore, we foresee two distinct ways to express properties: using the connector (generic) name or using the connector source/target ends.

We strongly recommend using the source/target role name to indicate the relation name and leave empty the (generic) element name. So, if a target role is specified, then no connector name can be specified. Optionally a source role may be provided to indicate the inverse relation. In this case, the relation direction must be changed from "Source → Target" to "Bidirectional".

Or conversely, if the connector direction is "Bidirectional", then source and target roles must be provided. No other directions are permitted.

It is recommended that each association has a definition. The definition is then used for each role as they represent the same meaning manifested in the inverse direction. Alternatively, definitions can be specified along the target and source roles.

UML defines multiple types of connectors. We recommend relying mainly on the UML Association connector type. Optionally a UML Dependency Connector type may be used if the meaning and usage conditions are well-defined.

The UML Association connectors represent relations between a source and a target classes. The association connector cannot be used between other kinds of UML Elements.

The UML Dependency connector may be used between a UML Class and UML Enumeration boxes, oriented from the Class towards the Enumeration. It indicates the class has an owl:ObjectProperty, whose range is a controlled vocabulary [CMC-R14]. The connector must have the direction "Source → Target". No other directions are acceptable.

The UML Generalization connector signifies a class-subClass relation and is transformed into rdfs:subClassOf relation standing between a source and target classes. The connector must have no name or source/target roles specified in the UML model. If a model class should inherit a class from an external model, then proxies must be created for those classes [GC-R1, Reuse of a class with semantic adaptation]. For example, if Person specialises a foaf:Agent.

Description:

For semantic data specifications, accessibility to the information is not a concern. The sole concern is to specify the semantics of the information as precisely as possible. Therefore, the UML access or privacy annotations shall not be interpreted, and the "+" symbol shall always be used next to each property. This symbol means "public" [oslo-rules, sec 3.2.22].

Description:

References to controlled lists shall be done via UML Enumeration elements. Content and lifecycle management of controlled lists shall be separated from the management of the semantic data specification.

Controlled lists play an essential role in establishing interoperability standards. Management and publication of controlled lists are not part of this style guide. The expectation is that the controlled lists are published in accordance with best practices and represented with the SKOS model using persistent identifiers. In such an approach, the controlled list is expressed as a skos:ConceptScheme and the specific values as skos:Concept(s). Also, such controlled lists are often developed, published and maintained independently following their own lifecycle, so that they can be reused in other models.

Two use-cases can be identified in practice: (a) when the code list is known and is explicitly referred to as the range of a property, and (b) when a property is modelled but no code list reference is provided as its range.

When the authors of a conceptual model intend to omit which controlled list shall be used, then a class attribute with the range skos:Concept (in some cases Code is preferred) can be created to indicate that. This approach can be useful in situations when multiple (external) controlled lists can be used interchangeably. For example, the adms:status property of a dcat:CatalogueRecord shall be a skos:Concept, without specifying the controlled list.

It is advisable, however, to be specific concerning which controlled list shall be used. In such cases, an Enumeration shall be created representing the controlled list. The Enumeration shall be empty, i.e., not specifying any value, because the values are assumed to be maintained externally and only the reference is necessary.

The properties having this controlled list as range shall be depicted as UML connectors (dependencies or associations) between a Class and an Enumeration [CMC-R2]. For example, in ePO, dct:Location can have a country code represented as a dependency relation to at-voc:country (the country authority table published on the EU Vocabularies website).

The name of the Enumeration shall be resolved to a URI identical to that of the skos:ConceptScheme. As for the connector type we recommend using a dependency connector (depicted with a dashed line) because the semantic interpretation differs slightly from the association connector (depicted with a continuous line). Namely, the range of the property has to fulfil two constraints: (a) instantiating the skos:Concept class and (b) being skos:inScheme the intended controlled list [epo-arch].

If the controlled list is specific to the model then the author shall define the values of the UML Enumeration inside of it, which are interpreted as concepts belonging to the containing concept scheme [oslo-rules, sec 3.2.17].

Description:

It is highly recommended to avoid defining any semantic interpretation into UML Packages, as they are best used for organisational purposes, defining logical partitions in the model. Therefore, packages can serve as a method of slicing the conceptual model into subdomains.

It is also possible to use packages as namespace indicators. Although it works well for classes, it fails to cover the needs for managing namespaces of connectors and attributes. Moreover, it does not work in cases when an attribute, or a connector is used multiple times in several packages. Hence, namespace management is easier attained by using other methods such as using prefixes in Element names or using Element tags [epo-cmc, sec 4.3].

Description:

UML class diagrams are used for depicting the conceptual model. Their primary purpose is to construe the meaning of concepts, relations and their organisation to the human reader. Therefore, the diagrams shall be optimised for readability.

We recommend that the diagrams:

See also [ oslo-rules, semic-sgdraft ]

Description:

We strongly encourage semantic practitioners to avoid stereotypes of any normative or semantic value. One common usage of stereotypes is to provide deontic indicators. See [GC-7 on Deontic modals] where we explain why their use is discouraged and what can be done instead.

There is a practice to mark some classes as "abstract" with the intention of preventing those from being instantiated. This is also a technical level constraint and does not belong in the semantic layer.

We acknowledge that stereotypes can be useful for editorial and dissemination purposes; to indicate a classification or grouping of a specific sort. Stereotypes can be used to support concerns specific to an implementation of the transformation toolchain. See the examples below.

Description:

Similar to [epo-cmc, sec 4.7], this convention draws the distinction between primitive (or atomic) types (consisting of single literal value) and composite types (consisting of multiple attributes) (see also [cv-handbook, sec 3.1]). In fact, the composite datatypes must be defined as classes and handled as such. For example, Amount, Identifier, Quantity and Measurement are to be treated as classes, even if conceptually they could be seen as composite datatypes.

It is recommended to employ the primitive datatypes that are already defined in XSD [xsd] and RDF [rdf], in particular a subset of those that is OWL 2 compliant. This should cover the standard, and most common types. Thus, definitions of custom datatypes shall be avoided unless the model really needs them. Such cases are, however, rare.

The reason for avoiding complex datatypes, is that once we start structuring how data shall be organised, besides syntactic definitions, we inevitably embed semantic aspects as well. Doing so, the semantics of the structure is obscured and trapped in a technical interoperability layer. For example, xsd:duration encodes both the amount(s) and unit(s) of time into a regular expression that looks like this <period>P5Y2M10D</period>.

The definition of datatypes in the UML model should be also avoided, even in cases where a toolchain performing the transformation of UML can automatically resolve those into their XSD equivalent using a correspondence table, such as the one presented below.

Note that from the family of string datatypes we recommend using the following ones (in this order of preference): rdf:PlainLiteral, rdfs:Literal, xsd:string, and rdf:langString. Often enabling multilingual data specification is a necessity.

We strongly recommended the use of OWL 2 compliant XSD and RDF standard datatypes, if possible. They might be useful also for indicating a specific datatype, which is not possible with the UML ones. For example, making a distinction between a general string (xsd:string) and a literal with a language tag (rdf:langString), or XML encoded ones such as rdf:HTML and rdf:XMLLiteral.

The table above provides a simplified correspondence between UML and XSD datatypes, but for a complete list of available recommended datatypes the standard specifications shall be consulted:

Description:

In the Semantic Web domain, two formal languages can be used for expressing the ontology: RDFS [rdfs] and OWL 2 [owl2]. RDFS is simpler and only allows for some of the recommended expressions (for example, the distinction between datatype and object properties is not possible). OWL 2 is more complex and more expressive than RDFS.

We recommend using only a limited set of expression types available in OWL 2 language [SC-R2].

Description:

OWL 2 language provides a high level of expressivity. In the SEMIC interoperability context, the primary purpose of semantic artefacts is to establish the common set of concepts and how they are employed in data exchange. For this purpose, simple OWL 2 constructs suffice. Therefore, the OWL 2 ontology shall be kept lightweight, and no advanced logical definitions are necessary, which would make the ontology heavyweight. The Bulletin of the Association for Information Science and Technology, dedicated an entire section on the charm of weak semantics in the linked data world. Backer & Sutton explain well how lightweight semantics supports interoperability and reuse [baker15].

We recommend the formal ontology definition be limited to the following types of expressions:

The formal ontology shall not include other types of statements unless justified as necessary. The properties used, in particular those related to the ontology header, shall be aligned with the governance process.

No expressions of (a) property domain specification (rdfs:domain) and (b) property range specification (rdfs:range) shall be used unless justified as absolutely necessary. The need for setting property domain and range constraints is better fulfilled by the data shapes expressed in SHACL language.

Keeping the ontology lightweight allows the maximum freedom for reuse (e.g. in different application profiles, where domains/ranges can be specified or restricted), and does not interfere with the validation concerns covered by the data shapes.

Note: This recommendation does not prevent the generation of more heavyweight ontologies (i.e. with higher level of logical expressivity), as additional artefacts that would be included in the data specification. A data specification could even provide several such ontology versions, one for each OWL 2 profiles (EL/QL/RL), for example, if there are well-defined use cases identified for them. However, if such additional ontologies will be provided as part of the data specification, it is essential that they are all be kept consistent with all the other artefacts (including the lightweight ontology, the human-readable version, etc.) (see section on Transformation). Therefore, it is highly recommended having appropriate tool support, which enables the automatic generation of all the ontologies that are needed from the conceptual model. Regardless of how many ontology versions will be generated and published as part of the data specification, the most important thing, and hence the main point of this recommendation, is that there should always be at least one lightweight ontology, to support a highest level of interoperability and reuse. Often, this is called the "core" ontology, in data specifications that provide multiple ontology versions, while the other, more expressive, ontology versions have different names.

Description:

The lexicalisation of concepts in semantic artefacts can be implemented in multiple ways. Two popular approaches are used in practice: RDFS or SKOS lexicalisation. However, other types can be considered as well (e.g. [lemon], [vann], etc.).

RDFS allows for a simple lexicalisation and annotation:

SKOS offers a richer and more elaborate lexicalisation and annotation:

We recommend one, or the other is used. Both can be used at the same time without any consequence of semantics, but this will introduce redundancy and possibly a maintenance burden.

Description:

OWL 2 constructs correspond to Description Logic (DL) concepts (direct semantics). Logic, besides expressing knowledge in a knowledge base, can be used to perform automated reasoning, i.e., inferring new knowledge based on premises and reasoning rules. The inference is also possible with RDF-based semantics, based on translating the axioms into directed graphs. The latter is used for SPARQL entailments and SHACL data shape rules.

Automated reasoning is not consistently available across environments: small differences in the usage context or reasoning patterns may lead to different outcomes.

Therefore, the editors of interoperable semantic data specifications are strongly recommended to NOT rely on such capabilities. Thus, in practice, the model shall allow for an explicit statement of the intended knowledge, and as little as possible shall be left implicit.

Description:

Circular definition, i.e., definitions that use the element they define are incorrect.

For instance, we say that an ontology element (a class, an object property or a data property) is circular when used in its own definition. This can occur in situations such as the following:

Description:

There are various languages allowing for data shape expression and thus define validation rules for RDF data. Among the executable ones, the most well-known are SHACL [shacl] and ShEx [shex]. We are aware that a strong community of practice exists for ShEx. However, as SHACL is a W3C standard, we strongly recommend using it.

Description:

The Core Vocabularies are intended for a broad reuse and are concerned with establishing the concepts. This is addressed by the ontology artefact. Optionally it may be accompanied by a minimal set of data shape constraints expressing general domain limitations. For example, it may be already defined in the Core Vocabulary that a class cannot be instantiated without certain mandatory properties or that a declared property shall be used only with values from a pre-established controlled vocabulary. If a data shape artefact is provided, then any Application Profile reusing the Core Vocabulary shall not only import the ontology, but the data shapes as well.

The Application Profiles are usually intended for narrower use cases and mostly are concerned with setting restrictions on the way reused vocabulary ought to be used. It is a good practice to make such restrictions as restrictive as necessary but still provide space for variation as it typically occurs in practice. This is even more important when an Application Profile is conceived as reusable in other Application Profiles.

Description:

Operations on the data, such as automated reasoning and validation, are impacted by what is assumed about its completeness. If it is considered complete, then we say that we operate under the closed-world assumption; otherwise, in the cases of continually evolving and distributed data (that is more in line with reality), the data is considered possibly incomplete, and we say that operating is under the open-world assumption.

Under the closed-world assumption, it is presumed that a true statement is also known to be true. Therefore, conversely, what is not currently known to be true, is false [reiter81]. The opposite of the closed-world assumption is the open-world assumption stating that lack of knowledge does not imply falsity. The truth value of a statement may be true despite whether or not it is known to be true.

This means that when validating, the data must be considered complete to assess whether it fulfils the imposed constraints or recommended shapes. Therefore, everything that is not known to be true must be considered false.

This may have an impact, especially for larger vocabularies (such as the eProcurement ontology), on how the data shapes are organised. As data shapes may be used to suggest how the data may be fragmented and how it shall not.

Description:

When generating SHACL shapes, it is a good practice to create a node shape for each class in the Conceptual Model and, within it, a property shape for each property of that class. If the property shapes are defined within the node shapes (rather than freestanding), then we mirror the structure depicted in the Conceptual Model. Doing so is intuitive for the readers, the resulting constraint definitions are organically integrated, and the maintenance costs are decreased.

However, sometimes it may be useful to define the property shapes as freestanding, therefore making them reusable independent of the node shape context. Freestanding property shapes are universal constraints on the property. They apply to all usages, in all possible data exchanges. Therefore, their use should be limited to those cases that support the broadest reuse context, and do not encode a specific application usage context. As such, freestanding property shapes play more a role in the validation of the correct usage of the property in an application context, rather than in the correct data exchange. The above considerations do not exclude that property shapes used within a node shape could be named with a unique URI, through the reuse of which a coherent network of constraints can be facilitated.

The shapes shall be created in a separate namespace in order to allow dereferencing to either OWL 2 or SHACL definitions.

In some communities, the URIs used in the OWL 2 specifications are reused in SHACL. The class definitions are extended as node shapes. In SHACL semantics, this is interpreted as an equivalent to specifying a sh:targetNode class. This approach allows the use of a single reference in both the ontology and data shape definition yet specifies separate concerns in separate artefacts. The advantage of the approach is increased consistency and readability while maintenance costs decrease. Yet, this approach does not allow for dereferencing separately OWL 2 or SHACL representations. Hence, it is recommended to avoid such practice.

Description:

Data shapes can be assigned a level of severity. The specific values of severity have no impact on the validation but may be used by user interface tools to categorise validation results. The severity levels are:

Description:

Publishing a vocabulary as a Linked Open Data (LOD) resource means making it accessible, both human and machine-readable, in a standard way, thus supporting the semantic web. The publication as full LOD implies that the data is compliant with the highest grade of 5-Star [5star-od] open data evaluation:

On the same note, the FAIR Data Principles [fair-principles] is a more comprehensive and rich set of guidelines for publishing data on the web. They ensure the Findability, Accessibility, Interoperability and Reuse of digital assets. The principles emphasise machine-actionability (i.e., the capacity of computational systems to find, access, interoperate, and reuse data with none or minimal human intervention) because humans increasingly rely on computational support to deal with data, as a result of the increase in volume, complexity and creation speed of data [fair-guidelines].

See more [ dwbp, ld-bp, ldp-bp ]

Description:

When publishing data on the web [dwdp], it is crucial to have a structured and persistent system of URIs in place. Such URIs make it easy for the users to understand the vocabulary structure and retrieve information as they expect.

The 10 rules for Persistent URIs [10rules-puri] are base principles for the design of quality identifiers. Regarding URI design, the main consideration of creators should be that when a URI is created, all its parts should be resistant to change. For instance, locations and organisation names can change and therefore should not be used in URIs. First and foremost, when introducing semantics in URIs, the strings used need to reflect what the resources are (i.e. intrinsic characteristics such as the type or nature), not who owns them or where they are [uri-dp].

In 2014, the ISA Programme devised a common policy for managing persistent HTTP-based URIs of EU institutions [uri-dp, 10rules-puri, puri-gov-eu]. That has led to an EU wide URI resolution service, prescribing that each URI is of the following pattern:

http://data.europa.eu/{Collection}/{Reference}

The {Collection} is an organisation-agnostic name for a collection of terms. Within a {Collection} the local names, or references, are being maintained according to the policy of the {Collection}. For SEMIC data specifications, the names are dependent on the naming conventions mentioned in this style guide rules [GC-R4 + CMC-R3].

See more [ ld-bp, ldp-bp, dwbp, ]

Description:

The SEMIC versioning methodology is based on "semantic versioning" principles [sem-ver] and implements a simple set of rules and requirements that dictate how version numbers are assigned and incremented. It involves describing clearly and precisely what is being published and which features are included, and what the limitations are, setting the expectations and scope. Once the artefacts are identified for the public, the changes to the data specifications are communicated with specific increments to the version number and with associated change notes.

The version format is X.Y.Z (Major.Minor.Patch).

As a rule of thumb, bug fixes do not affect the artefact and increment the Patch version. Backwards compatible artefact additions/changes increment the Minor version. And, backwards-incompatible artefact changes increment the Major version.

Description:

Create a new version with each publication. Using the semantic version principles to determine the exact version number depends on whether it is a major, minor or patch update.

The version shall be assigned to the entire vocabulary or Application Profile and never to elements in the model (concepts, relations, constraints, etc.) [oslo-rules, sec 3.1.6]. The version shall be saved as the model metadata (for example, in the owl:Ontology header).

No version information shall be embedded into any artefact URIs unless it is a version URI provided via owl:versionIRI.

Description:

Dereferencing means that one can use the URI as an URL to retrieve related information back. The format and representation in which the information is returned depend on content negotiation. Content negotiation is the interaction between the client application and the server in which the client informs the server about its preferred format and representation and the server responds with the best-fitting result it can provide.

It is recommended to provide (format) content negotiation for HTTP which is based on the interpretation of the Accept: HTTP header.

The dereferencing shall be provided for both human-readable and machine-readable formats. A human-aimed HTML representation is the default response (if no content type is specified), and the other is RDF [10rules-puri].

Because the HTML representation is usally a long document, which makes it hard to find the information about a specific term, it is recommended that the HTML representation has landing points based on the used fragment identifier. Dereferencing can then route the reader to the most relevant information within the HTML document. For other representations/formats no additional requirements are imposed. For example, the dereferencing in the RDF representation, depends on the implemented recipe, i.e. based on # or /; and it may return either the corresponding fragment or the whole RDF document [pub-recipe].

Further technical details can be found in "Best Practice Recipes for Publishing RDF Vocabularies" [rdf-pub].

See more [ ld-bp, ldp-bp, dwbp ]

Description:

The documentation content shall follow a standard template for consistent formatting and content structuring.

It is a good practice to provide the following sections in the document:

Moreover, consider following the good practices for documenting OWL 2 and SHACL artefacts, and include the appropriate details in the data specification documentation. For OWL 2, we can mention tools like Widoco [widoco] and LODE [lode]; and for SHACL, follow the SHACL recommendation [shacl], or the metadata support implemented in tools such as SHACL-play [shacl-play]. For application profiles, consider aligning to the DCAP [dcap], which is an implementation agnostic recommendation.