discover.swiss data schema

Tip

We use the same properties from schemaOrg wherever appropriate and it fits the scope.

About properties

Warning

Generally all properties can be null - missing in the response.
There are some remarks in this documentation, but the detailed definition about "nullable" you find in the OpenApi definition which can be downloaded in the developer portal.

Localisation

schema.org has text properties but no word about handling their values in different languages. JSON-LD makes different suggestions how to handle it. We chose to deliver an object always only in 1 language in 1 request based on the accept-language header in the request.

Like this the client does not need to worry about which properties are translated and which ones are not and we can change that any time and extend certain properties to support different languages.

Cardinality of properties

(1:1 or 1:n)

schema.org does not define the cardinality of a property. So there could be many names and only one opening hour. But this is not what makes sense to us and our customers. We decided which properties represent lists and which represent single values although the property names are always singular.

Sketch of a discover.swiss graph

Vertex

(v1, v2, v3)

These are the nodes in the graph and individual objects in the real world

• have their @id (resource identifier) and an endpoint in the api to load their detailed data
• all schema.org classes derived from
  • Place
  • CreativeWork
  • Event
  • Organization
  • Product
• can have relationships between each other

Edge = Relationship

(r1, r2, r3)

r1 is 1 to many relationship
r2 is 1 to 1 relationship
r3 is many to many relationship

In REST and GraphQL relationships are represented as properties of a vertex and there are no public endpoints to query relationships only. In the REST api the referenced object is represented by a simplified object structure including the @id link to load the complete object

The Graph api is able to travers the graph along the edges (relationships).

Property

(p1, … )

Properties represent values and arrays of values with datatypes like string, int, datetime, … (structs) which are represented in schema.org by classed derived from DataType

Member

(m1 … )

These are properties of complex types which are represented in schema.org by classes derived from StructuredValue. They can be a list of values as well.