Semantic Maturity Model

Level 1: Globally unique identifiers

The Semantic Web is built around the basic principle that we need to use the same names when we publish information about the same things. This does not only account for identifying real-world objects like a person or a building, but also for attribute/relationship names and more abstract concepts like a person's gender or interest. Doing this allows a machine to interpret how multiple sources of information relate to each other.

Create URIs

If data publishers want other organizations to be able to link to this beer (e.g. a beer review website), they should provide globally unique identifiers. Documents created by other organizations and published on external domains will then be able to provide link references to these resources.

The URI standard offers a uniform syntax for globally unique identifiers, which can be used to .....

TODO

Consistent URIs across multiple documents

Data is typically published in many forms, like HTML web pages and JSON(-like) documents provided by APIs or other services. In many cases, multiple documents provide the same information about the same thing(s), but in a different format and accessible via different interfaces and protocols.

Our DBeerPedia website offers a catalogue for craft beers, where information about each individual beer can be viewed in a web browser as an HTML web page. The URI for the web page offering information about the beer La Trappe Quadrupel would be:

            https://dbeerpedia.org/beers/6283746/la-trappe-quadrupel

Because we want developers to build cool end-user apps by leveraging our data, we also provide a REST API. The URI for the document providing the same information via a more machine-friendly interface is:

            https://api.dbeerpedia.org/v1/beers/6283746

In this example, it's interesting to note that both URIs serve a document describing the same beer. There could even be more than one API, such as a GraphQL or gRPC service, which even increases the number of access mechanisms for the same information.

Because multiple documents (accessible by different URIs) are describing the same thing, it's important that all documents contain references to the same globally unique identifier (URI) for the thing. Hence it's crucial that there is a clear distinction between a thing and the document(s) describing this thing.

By creating URIs for things, in addition to URIs for documents, data consumers can discover that multiple sources of information are describing the same thing and other data publishers will be able to link to the thing itself instead of an individual document describing the thing.

Web pages typically include Structured Data to help search engines to understand the content of the document. An example for a piece of Structured Data in a web page's `<head>` section would be:

            <script type="application/ld+json">
            {
              "@context": "http://schema.org",
              "@type": "Product",
              "name": "La Trappe Quadrupel",
              "description": "In 1991, The Koningshoeven brewery baptized her beloved Quadrupel under the approving glance of the monks. A closely guarded recipe became reality, and the first Quadrupel beer in the world was born."
            }
            </script>

The issue here is that this description does not contain a URI for the beer (product) itself. As a result, search engines and other consumers will interpret this as an anonymous piece of information, which happens to reside in this HTML document. Consequently, external parties will only be able to link to a particular document and not to the beer itself. Here is an example including a URI:

            <script type="application/ld+json">
            {
              "@context": "http://schema.org",
              "@id": "https://dbeerpedia.org/id/beer/6283746",
              "@type": "Product",
              "name": "La Trappe Quadrupel",
              "description": "In 1991, The Koningshoeven brewery baptized her beloved Quadrupel under the approving glance of the monks. A closely guarded recipe became reality, and the first Quadrupel beer in the world was born."
            }
            </script>

In this example, it's interesting to note that the URI for the beer differs from the web page's URI. This distinction is important, because other URIs (e.g. as part of a REST API) might publish the same information. See for example the same information served by the DBeerPedia REST API:

            {
              "@id": "https://dbeerpedia.org/id/beer/6283746",
              "name": "La Trappe Quadrupel",
              "description": "In 1991, The Koningshoeven brewery baptized her beloved Quadrupel under the approving glance of the monks. A closely guarded recipe became reality, and the first Quadrupel beer in the world was born."
            }

In this example, the attribute name `@id` is used for the URI because it aligns nicely with the JSON-LD standard. However, the choice is yours if you wish to use another name for arbitrary reasons.

Please note the corresponding URIs for the web page and REST resource remain unchanged:

            https://dbeerpedia.org/beers/6283746/la-trappe-quadrupel
            https://api.dbeerpedia.org/v1/beers/6283746

Upcoming API standards like GraphQL and gRPC do not follow REST principles, which (among other aspects) means that documents are not accessible by its URI. Therefore, it's even more important to include URIs in API responses, regardless of the exchange protocol or the document format.

URIs can be treated as opaque strings, and thus every standard supporting the string data-type (which is literally any standard) should be able to handle URIs as values.

Different URIs for different things

Documents often describe more than one thing, such as related resources or a collection of things. In addition, documents might contain links to other things (or documents) without describing the thing itself in the document. In both cases, the document should provide references to the corresponding URIs.

If we would want to provide information about the manufacturer of the beer (the brewery), the corresponding Structured Data representation would look like this:

            <script type="application/ld+json">
            {
              "@context": "http://schema.org",
              "@id": "https://dbeerpedia.org/id/beer/6283746",
              "@type": "Product",
              "name": "La Trappe Quadrupel",
              "description": "In 1991, The Koningshoeven brewery baptized her beloved Quadrupel under the approving glance of the monks. A closely guarded recipe became reality, and the first Quadrupel beer in the world was born.",
              "manufacturer": {
                "@id": "https://dbeerpedia.org/id/brewery/21823",
                "@type": "Organization",
                "name": "Bierbrouwerij de Koningshoeven",
                "url": "https://www.latrappetrappist.com"
              }
            }
            </script>

The REST/JSON equivalent for the previous example would be:

            {
              "@id": "https://dbeerpedia.org/id/beer/6283746",
              "name": "La Trappe Quadrupel",
              "description": "In 1991, The Koningshoeven brewery baptized her beloved Quadrupel under the approving glance of the monks. A closely guarded recipe became reality, and the first Quadrupel beer in the world was born.",
              "manufacturer": {
                "@id": "https://dbeerpedia.org/id/brewery/21823",
                "name": "Bierbrouwerij de Koningshoeven",
                "url": "https://www.latrappetrappist.com"
              }
            }

Introduction

Audience

Goals

Terminology

Level 1: Globally unique identifiers

Create URIs

Consistent URIs across multiple documents

Different URIs for different things

Guidelines

How to create good URIs