1. Introduction

This guide aims to help developers import data to the GNTB Knowledge Graph and simultaneously help data consumers understand how data is imported. By doing so, the quality of data should improve, giving data consumers a sound data experience.

Please check our changelog regularly, especially before making modifications to the import.
There, we document recent adjustments or announce new features.

2. Guidelines

The guide is structured by topics that appear as the most common sources of error. Based on the experience made over the past years, each subsection addresses a common source of error.

2.1 Use the ODTA Domain Specifications

At the beginning of the GNTB Knowledge Graph project, the ODTA Domain Specifications were not yet mature enough to rely on as a data model. Therefore, the GNTB developed its own set of Domain Specifications to address the urgent need for data integrators. Those Domain Specifications were known as Touristische Domain Specifications (preliminary). In the meantime, the ODTA Domain Specifications and Vocabulary are ready to use and have been published on this list: https://semantify.it/list/CRkyvcqGqeUu.

Please note that the specifications are constantly being expanded. Take this into account in your mapping process and make the necessary adjustments.

Example:

❌ Event old: https://semantify.it/ds/mhpmBCJJt

✅ Event new: https://semantify.it/ds/BJfiOVFdvBak

2.2. Bring your URIs (@ids)

In JSON-LD, one of several RDF serializations, each data item (instance, entity - or, in JSON terms, object) needs an @id property with a URI as a value. If this property is not present, the object is considered a “blank node” (i.e., it has no global identifier) and a URI is generated by the GNTB KG platform’s import pipeline. This makes the data hard to update or link (see next point). Therefore, it is strongly recommended that the @id is added to each data item at the import.

Addon: if a URI is already used as the @id it must not be sent within the schema:identifier.

2.3. Link your data

The core of the Linked Data Principles, coined by Sir Tim Berners Lee in 2006, says: “When publishing data on the Web, other things should be referred to using their HTTP URI-based names.” Also, the Linked Open Data Principles, to which the GNTB KG adheres, state “links to other Linked Open Data sources.” In the GNTB KG project, those principles should be taken seriously. This is not only for earning the 5th start of the 5-star-open-data idea but also to avoid duplicates.

Example:

Event E1 takes place at location L. Another Event, E2, also takes place at location L. When importing the date, Location L should be identified using a URI in the @id. This @id must then link events E1 and E2 to the location L.

{
  "@context": {
    "@vocab": "https://schema.org/",
    "ds": "https://vocab.sti2.at/ds/"
  },
  "@graph": [
    {
      "@id": "https://example.com/event/E1",
      "@type": "Event",
      "name": "Event One",
      "schema:location": {
        "@id": "https://example.com/location/L"
      },
      "ds:compliesWith": "https://semantify.it/ds/BJfiOVFdvBak"
    },
    {
      "@id": "https://example.com/event/E2",
      "@type": "Event",
      "name": "Event Two",
      "schema:location": {
        "@id": "https://example.com/location/L"
      },
      "ds:compliesWith": "https://semantify.it/ds/BJfiOVFdvBak"
    },
    {
      "@id": "https://example.com/location/L",
      "@type": "Place",
      "name": "Location L",
      "ds:compliesWith": "https://semantify.it/ds/xGCRqopjRLFl"
    }
  ]
}

Listing 1: Working sample for an import linking two events to a location.

2.4 Avoid empty values

In a relational database, empty values are common. Any column that is not required by a database constraint can simply have no value.

In knowledge graphs, the situation is different. Information is represented as triples: a subject, a predicate, and an object—or visually, two nodes connected by an edge. If an empty value, such as an empty string (""), is stored in the graph, it results in a triple where the object is empty.

This is problematic for several reasons:

It doesn’t add meaningful information—a triple with an empty object is essentially useless.
It wastes storage space—every stored triple consumes resources.
It clutters JSON output—data consumers may receive triples like { "schema:name": "" }, which add noise without providing value.

To avoid this, it’s best to omit empty values altogether rather than storing them as explicit triples. So please ensure that, rather than sending an empty value to the graph, you send no value.

Example:

❌ Wrong (Storing an empty string)

{
  "@id": "http://example.com/event/456",
  "@type": "schema:Event",
  "schema:name": "My Event",
  "schema:description": ""
}

✅ Correct (Omitting the empty description)

{
  "@id": "http://example.com/event/456",
  "@type": "schema:Event",
  "schema:name": "My Event"
}

2.5 Name trails' start- and end locations properly

In the data, there are a lot of trails with empty names. You can’t omit the name because it’s mandatory by the DS. But if the start- and end locations do not have a name, instead of inventing your name, please use the following syntax recommendation:

EN: <Trailname> Start & <Trailname> End

DE: <Wegname> Startpunkt & <Wegname> Endpunkt

Where the <xxx> is a placeholder and should be replaced with the trail’s actual name.

Example:

{
  "@id": "http://example.com/trail/123",
  "@type": "odta:Trail",
  "ds:compliesWith": "https://semantify.it/ds/GCFskkOzCNdo",
  "schema:name": "My Trail",
  "odta:startLocation": "My Trail Start",
  "odta:endLocation": "My Trail End"
}

2.6 Be precise with the semantics of Date, Time, and DateTime

There is a reason why there are three different data types in schema.org for date, time, and datetime: They all have different meanings! Please use them appropriately, even if the DS allows multiple options.

Example: `schema:validFrom`

schema:OpeningHourSpecification might be valid from April 1st to September 30th (summer season, schema:Date), while a schema:Offer might be valid from 8 pm to 9 pm (happy hour, schema:Time). A ticket might be valid from June 1st, 2025, 10 pm to June 2nd, 2025, 4 am (night club entrance, schema:DateTime).

2.7 Use the schema:eventSchedule correctly

As defined by schema.org/Schedule

A schedule defines a repeating time period used to describe a regularly occurring Event. At a minimum a schedule will specify repeatFrequency which describes the interval between occurrences of the event. Additional information can be provided to specify the schedule more precisely. This includes identifying the day(s) of the week or month when the recurring event will take place, in addition to its start and end time. Schedules may also have start and end dates to indicate when they are active, e.g. to define a limited calendar of events.

Example:

✅ Good Example 1 (Correct use of Schedule for a recurring event)

{
  "@id": "http://example.com/event/001",
  "@type": "schema:Event",
  "schema:name": "Weekly Yoga Class",
  "schema:schedule": {
    "@type": "schema:Schedule",
    "schema:repeatFrequency": "P1W",
    "schema:byDay": "https://schema.org/Tuesday",
    "schema:startTime": "18:00",
    "schema:endTime": "19:30"
  }
}

The event recurs weekly (repeatFrequency: P1W), which is exactly what Schedule is meant for.

✅ Good Example 2 (Correct use of Schedule with a defined date range)

{
  "@id": "http://example.com/event/002",
  "@type": "schema:Event",
  "schema:name": "Seasonal Art Exhibition",
  "schema:schedule": {
    "@type": "schema:Schedule",
    "schema:repeatFrequency": "P1D",
    "schema:startDate": "2025-06-01",
    "schema:endDate": "2025-09-30"
  }
}

The event repeats daily within a specific date range (startDate and endDate), making Schedule a valid choice.

❌ Bad Example (Incorrect use of Schedule for a one-time event)

{
  "@id": "http://example.com/event/003",
  "@type": "schema:Event",
  "schema:name": "Grand Opening Concert",
  "schema:schedule": {
    "@type": "schema:Schedule",
    "schema:repeatFrequency": "P0D",
    "schema:startDate": "2025-04-15",
    "schema:endDate": "2025-04-15"
  }
}

This is a one-time event, so Schedule is unnecessary. Instead, schema:startDate and schema:endDate should be used directly inside Event.

Fixed Version of the Bad Example (Without Schedule)

{
  "@id": "http://example.com/event/003",
  "@type": "schema:Event",
  "schema:name": "Grand Opening Concert",
  "schema:startDate": "2025-04-15",
  "schema:endDate": "2025-04-15"
}

✅ Comprehensive good Example (week market)

{
  "@context": "https://schema.org",
  "@type": "schema:Event",
  "@id": "http://example.com/market/weekly",
  "schema:name": "Wochenmarkt",
  "schema:location": {
    "@type": "schema:Place",
    "schema:name": "Marktplatz",
    "schema:address": {
      "@type": "schema:PostalAddress",
      "schema:streetAddress": "Hauptstraße 1",
      "schema:addressLocality": "Beispielstadt",
      "schema:postalCode": "12345",
      "schema:addressCountry": "DE"
    }
  },
  "schema:eventSchedule": [
    {
      "@type": "schema:Schedule",
      "schema:name": "Öffnungszeiten Oktober - März",
      "schema:startDate": "2025-10-01",
      "schema:endDate": "2026-03-31",
      "schema:repeatFrequency": "P1W",
      "schema:byDay": [
        "https://schema.org/Monday",
        "https://schema.org/Wednesday"
      ],
      "schema:startTime": "08:00",
      "schema:endTime": "12:00"
    },
    {
      "@type": "schema:Schedule",
      "schema:name": "Öffnungszeiten April - September",
      "schema:startDate": "2025-04-01",
      "schema:endDate": "2025-09-30",
      "schema:repeatFrequency": "P1W",
      "schema:byDay": [
        "https://schema.org/Tuesday",
        "https://schema.org/Friday"
      ],
      "schema:startTime": "07:00",
      "schema:endTime": "12:00"
    }
  ]
}

The Wochenmarkt has two different schedulers. One for the summer season and one for the winter season.

2.8 Content URL vs. Thumbnail URL

The schema.org/ImageObject allows the specification of a content URL and a thumbnail URL. However, these are different things and should not be treated synonymously. The content URL holds the reference to the actual image, while the thumbnail url only references a minimal version of the image that can be used for previews.

Example:

{
  "@id": "http://example.com/image/123",
  "@type": "schema:ImageObject",
  "schema:contentUrl": "http://example.com/images/fullsize.jpg",
  "schema:thumbnailUrl": "http://example.com/images/thumbnail.jpg"
}

2.9 Event Example with “future” filtering

to be defined...

2.10 Use Multi-Typed Entities (excessively)

Real-live objects tend not to fit artificial categories very well. In RDF, that is not an issue. We can assign more than one @type to an object, which makes the instance a Multi-Typed Entity. While an instance complies with exactly one domain specification, it can feature multiple types. In that case, the domain specification must be chosen as specific as possible but as generic as required.

Example:

A given castle is also a museum. Both the castle aspect and the museum aspect are of equal importance semantically. So we can neither assign the “Castle” DS nor the “Museum” DS. Therefore, the “Tourist Attraction” DS is chosen, which is more generic but still correct. For the types we use schema:Museum and schema:Castle”.

{
  "@id": "http://example.com/place/001",
  "@type": ["schema:Museum", "schema:Castle"],
  "schema:name": "Historic Castle Museum",
  "ds:compliesWith": "https://semantify.it/ds/pxNgHzzhpeUu"
}

2.11 License is key!

Tell your users what they can do with your data!

Use schema:sdLicense to specify the license that applies to the structured data itself (sd stands for structured data).
The sdLicense must be accompanied by:
schema:sdPublisher (who published the structured data)
schema:sdDatePublished (when it was published)

For images or text content, use the following properties to define usage rights:

schema:license – Specifies the license governing the content.
schema:copyrightHolder – Indicates the owner of the copyright.
schema:copyrightYear – States the year of copyright.
schema:copyrightNotice – Provides a formal copyright statement.

Example:

{
  "@id": "http://example.com/dataset/001",
  "@type": "schema:Dataset",
  "schema:name": "Open Data Collection",
  "schema:sdLicense": "https://creativecommons.org/licenses/by/4.0/",
  "schema:sdPublisher": {
    "@type": "schema:Organization",
    "schema:name": "GNTB",
    "schema:url": "http://gntb.com"
  },
  "schema:sdDatePublished": "2025-03-21",
  "schema:hasPart": {
    "@id": "http://example.com/image/123",
    "@type": "schema:ImageObject",
    "schema:contentUrl": "http://example.com/images/photo.jpg",
    "schema:license": "https://example.com/image-license",
    "schema:copyrightHolder": {
      "@type": "schema:Person",
      "schema:name": "Foto Joe"
    },
    "schema:copyrightYear": "2025",
    "schema:copyrightNotice": "© 2025 Foto Joe. All rights reserved."
  }
}

2.12 Distinguish between text with markup and without markup

When importing descriptions, it's important to distinguish between text with and without markup.

Plain text version: Ideally, every description should have at least a plain text version, like this:
"schema:description": "My description"
Rich text version: If the description includes markup (such as HTML), it should be represented as a schema:CreativeWork. This allows you to capture more detailed, formatted content in a structured way.

Example:

{
  "@id": "http://example.com/event/001",
  "@type": "schema:Event",
  "schema:name": "Sample Event",
  "schema:description": "This is a plain text description of the event.",
  "schema:description": {
    "@type": "schema:CreativeWork",
    "schema:headline": "Sample Event Description with Rich Text",
    "schema:text": "<p>This is a <strong>rich text</strong> description with <em>markup</em> for the event.</p>"
  }
}

2.13 Encode strings

If you have special characters in your html or plaintext, please ensure they are encoded correctly.

Example:

{
  "@type": "schema:CreativeWork",
  "schema:text": "<p>This is a description with special characters like &lt;, &gt;, and &amp; in HTML.</p>"
}

Explanation:

The HTML tags (<p>, </p>) are used as part of the schema:text, and special characters are encoded:

< becomes <
> becomes >
& becomes &

2.14 Be specific!

The granularity of data annotation is key to good data quality and added value for data users. The easiest way is to type every instance as a place. That would be correct semantically, but it would still defeat the purpose of an open-data knowledge graph. There is an essential difference between a hotel, a lake, a castle, and a generic place. So please be specific. As specific as possible, as generic as needed!

Multi-typing for the win!

… and excessively use Enums for properties like odta:kindOf, odta:theme and alike.

A multi-typed entity is an entity which has more than one type. A hotel, for example, where a famous person once lived, can also be a tourist attraction. That would make it both a schema:Hotel and a schema:TouristAttraction. While the domain specification on an entity must be unique, the type must not be unique. Therefore, this example would be typed as ”@type”:["schema:Hotel,schema:TouristAttraction]”.

Additionally, for the data to be even more expressive, don’t hesitate to also add Enums to further specify your data.

Example 1: Apartment Hotel (a tourist attraction because Goethe lived there!)

An apartment hotel belongs to the domain specification Lodging Business. In schema.org terms it is a schema:Hotel. While this is accurate and expressive enough in a non-touristic context, it lacks a significant semantic for tourists and professionals in tourism. Therefore, we recommend giving the data more meaning by adding the property odta:kindOfLodging with the value odta:ApartmentHotel (which is of type odta:LodgingBusinessEnumeration and defined in this vocabulary: https://semantify.it/voc/AVJGTptnnkNN?term=odta:ApartmentHotel).

{
  "@type": ["schema:Hotel", "schema:TouristAttraction"],
  "@id": "http://example.com/hotel/001",
  "schema:name": "City Center Apartment Hotel",
  "schema:address": {
    "@type": "schema:PostalAddress",
    "schema:streetAddress": "Hauptstrasse 123",
    "schema:addressLocality": "Sample City",
    "schema:postalCode": "12345",
    "schema:addressCountry": "DE"
  },
  "odta:kindOfLodging": "odta:ApartmentHotel",
  "ds:compliesWith": "https://semantify.it/ds/RIExHpTXyEAD"
}

Example 2: dripstone cave (Tropfsteinhöhle)

From a schema.org perspective, it’s a schema:TouristAttraction. The fitting DS would be Tourist Attraction. Additionally, to enhance semantics, we recommend adding the property odta:kindOfPOI with the value odta:Cave (which is of type odta:CaveOrMineEnumeration and defined in this vocabulary: https://semantify.it/voc/LFnFyxZsfEXl?term=odta:CaveOrMineEnumeration).

{
  "@context": [
    "https://schema.org"
  ],
  "@type": "schema:TouristAttraction",
  "@id": "http://example.com/cave/001",
  "schema:name": "Musterhöhle Dripstone Cave",
  "schema:address": {
    "@type": "schema:PostalAddress",
    "schema:streetAddress": "Höhlenweg 1",
    "schema:addressLocality": "Beispielstadt",
    "schema:postalCode": "12345",
    "schema:addressCountry": "DE"
  },
  "odta:kindOfPOI": "odta:Cave",
  "ds:compliesWith": "https://semantify.it/ds/DStmDugCfIoc"
}

3. More Examples

Here, you can find more examples that did not fit the above scope but are either nice to see or essential to know.

3.1 Certificats & Certifications

Certifying things and publishing the certification can be important. scheme.org offers a hasCertification, and the ODTA offers a hasCertificate for the certification. A minimal example could look like this:

JSON example:

{
  "@id": "http://onlim.com/entity/43bc86e1-a1f8-44d2-af88-e2bb00fdeff7",
  "@type": "odta:ProtectedArea",
  "schema:hasCertification": {
    "@id": "http://onlim.com/entity/67fcf89b-520c-4f69-bfc5-872cace0d99d",
    "@type": "schema:Certification",
    "odta:hasCertificate": {
      "@id": "http://onlim.com/entity/74f244f3-5a90-47ca-8467-b9019cee46d3",
      "@type": "odta:Certificate",
      "odta:authority": {
        "@id": "http://onlim.com/entity/d21da5b3-48c3-4712-9daf-5a21e9a20531",
        "@type": "schema:Organization",
        "schema:name": "Partner Nationale Naturparklandschaften GmbH",
        "ds:compliesWith": {
          "@id": "https://semantify.it/ds/gHqNaQvGFxIt"
        }
      },
      "schema:name": "ZERTIFIKAT: Partner Nationale Naturparklandschaften",
      "ds:compliesWith": {
        "@id": "https://semantify.it/ds/xshwqVKJWREM"
      }
    },
    "schema:issuedBy": {
      "@id": "http://onlim.com/entity/fedded67-bd2e-4791-a6a4-2be5ba00059b",
      "@type": "schema:Organization",
      "schema:name": "Land Tirol",
      "ds:compliesWith": {
        "@id": "https://semantify.it/ds/gHqNaQvGFxIt"
      }
    },
    "schema:name": "Naturparkzertifikation",
    "ds:compliesWith": {
      "@id": "https://semantify.it/ds/WHvPecAqwAlt"
    }
  },
  "schema:image": {
    "@value": "https://www.naturpark-tiroler-lech.at/wp-content/uploads/NPTL-naturpark-comp.jpg",
    "@type": "xs:anyURI"
  },
  "schema:name": "Naturpark Lechauen",
  "ds:compliesWith": {
    "@id": "https://semantify.it/ds/EEeozrGBdhOq"
  }
}

1. Introduction

2. Guidelines

2.1 Use the ODTA Domain Specifications

Example:

2.2. Bring your URIs (@ids)

2.3. Link your data

Example:

2.4 Avoid empty values

Example:

❌ Wrong (Storing an empty string)

✅ Correct (Omitting the empty description)

2.5 Name trails' start- and end locations properly

Example:

2.6 Be precise with the semantics of Date, Time, and DateTime

Example: schema:validFrom

2.7 Use the schema:eventSchedule correctly

Example:

❌ Bad Example (Incorrect use of Schedule for a one-time event)

Fixed Version of the Bad Example (Without Schedule)

✅ Comprehensive good Example (week market)

2.8 Content URL vs. Thumbnail URL

Example:

2.9 Event Example with “future” filtering

2.10 Use Multi-Typed Entities (excessively)

Example:

2.11 License is key!

Example:

2.12 Distinguish between text with markup and without markup

Example:

2.13 Encode strings

Example:

Explanation:

2.14 Be specific!

Multi-typing for the win!

Example 1: Apartment Hotel (a tourist attraction because Goethe lived there!)

Example 2: dripstone cave (Tropfsteinhöhle)

3. More Examples

3.1 Certificats & Certifications

Example: `schema:validFrom`