DS-V7 - Changelog

In the following, the additions and changes of DS-V7 in contrast to the previously used version of DS (DS-V5) are explained.

1. Changes

1.1. Use the HTTPS version of schema.org

https should become the standard protocol for the schema.org vocabulary. With DS-V7 we want to switch to https for schema.org in all our tools. In the specification, all schema.org links and vocabulary terms should use the https version if possible. "Hacks" in tools that understand http and https interchangeably should only be used if there is no other option (e.g. for the verification, users should be allowed to verify their http schema.org annotations. An informational error could be added regarding the better https namespace).

The schema.org entry in the @context changes to:

"@context": {
  ...
  "schema": "https://schema.org/",
  ...
}

1.2. Change type of DS node

The @type for Domain Specifications is given in the DS node, where the following two classes have been used so far:

{
  "@type": [
    "sh:NodeShape",
    "schema:CreativeWork"
  ],
  "sh:targetClass": [
    "schema:Hotel"
  ],
  ...
}

With DS-V7 this is changed to a class defined in the DS vocabulary, which is ds:DomainSpecification. In the DS Vocabulary, the class ds:DomainSpecification is a subclass of the two previously used classes, this way we keep the semantic information that was provided before (especially that a DS node is a sh:NodeShape).

Example for DS node:

{
  "@type": "ds:DomainSpecification",
  "sh:targetClass": [
    "schema:Hotel"
  ],
  ...
}

1.3. Multilingual metadata

Metadata properties MUST use language tags in DS-V7. This allows the use of multiple descriptions for different languages. The default language for metadata depends on the tool used. Metadata terms concerned by these changes:

• DS node

  • schema:name

  • schema:description

• Property node

  • rdfs:comment

Example for DS node:

{
  "@type": "ds:DomainSpecification",
  "schema:name":  [
    {
      "@language": "en",
      "@value": "Example DS"
    }
  ],
  "schema:description": [
    {
      "@language": "en",
      "@value": "Example DS for our application"
    },
    {
      "@language": "de",
      "@value": "Beispiel DS für unsere Anwendung"
    }
  ],
  ...
}

1.4. DS and Data matching

The purpose of this change is to split the term used for the target selection, and the corresponding constraint that generates an error when the target entity does not comply with the expected match (details below). None of the following terms is mandatory, since there are now different ways to specify the link between data and DS.

1.4.1 sh:targetClass

Up to now, we have used sh:targetClass (and to some extent also sh:targetSubjectsOf for Knowledge Graphs) to define the target entities that match with the given DS. At the same time, this term has been used as a constraint, restricting the class of the target entity and generating an error if the class of the target entity did not match. In order to be more compliant with SHACL (where sh:targetClass does not generate errors, but creates only the link between data and schema), we will remove all errors generated by sh:targetClass and will add sh:class to the root node, so that we keep the constraint that generates an error. The classes defined in sh:targetClass and sh:class should be the same.

Example in DS node:

{
  "@type": "ds:DomainSpecification",
  "sh:targetClass": [
    "schema:SkiResort"
  ],
  "sh:class": [
    "schema:SkiResort"
  ],
  ...
}

1.4.2 sh:targetObjectsOf

Additionally, sh:targetObjectsOf is officially added to the DS specification (see SHACL specification). In this case, an additional sh:class constraint is possible for the DS node. The range of this property is the @id of the target property term. An entry is added into the standard @context for convenience reasons.

Addition to @context:

"@context": {
  ...
  "sh:targetObjectsOf": {
    "@type": "@id"
  },
  ...
}

Example in DS node (any entity that is object of the property schema:address is seen as a target for this DS):

{
  "@type": "ds:DomainSpecification",
  "sh:targetObjectsOf": "schema:address",
  ...
}

1.4.3 sh:targetSubjectsOf

sh:targetSubjectsOf is also added to the DS specification (see SHACL specification). An additional sh:class constraint is possible for the DS node. The range of this property is the @id of the target property term. An entry is added into the standard @context for convenience reasons.

Addition to @context:

"@context": {
  ...
  "sh:targetSubjectsOf": {
    "@type": "@id"
  },
  ...
}

Example in DS node (any entity that is subject of the property schema:address is seen as a target for this DS):

{
  "@type": "ds:DomainSpecification",
  "sh:targetSubjectsOf": "schema:address",
  ...
}

1.4.4 ds:compliesWith

We also adopt ds:compliesWith into the DS specification (similar to sh:shapesGraph, see SHACL specification), which enables a method for entities to specify the Domain Specification(s) to which they comply. The range of this property is the @id of the said DS. Keep in mind that this term is not used in Domain Specifications, but in the data (any "Thing" can use the ds:compliesWith property). Multiple ds:compliesWith assertions are treated as a conjunction (an instance MUST fit all DS defined on it).

Example for a JSON-LD annotation:

{
  "@context": {
    "@vocab":"https://schema.org/",
    "ds": "https://vocab.sti2.at/ds/"
  },
  "@type": "Person",
  "ds:compliesWith": {
    "@id": "https://semantify.it/ds/-fYx5D34d"
  },
  "name": "Jane Doe",
  "jobTitle": "Professor",
  "telephone": "[phone]",
  "url": "http://www.janedoe.com"
}

1.5. Update schema:schemaVersion

Schema.org has stopped releasing dedicated pages for new vocabulary versions (see schema.org GitHub issues). The old URLs of those pages are not available anymore (e.g. https://schema.org/version/9.0/). Those URLs were used for the property schema:schemaVersion in Domain Specifications to specify the used schema.org vocabulary version. Since they are not valid anymore, the value of schema:schemaVersion must be changed.

The new URLs specified at https://schema.org/schemaVersion are not "attractive", therefore the used version is now given as a string (only the version number) instead of an URL, e.g. the previous URL https://schema.org/version/3.2/ converts to the string "3.2".

Example in DS node:

{
  "@type": "ds:DomainSpecification",
  "schema:schemaVersion": "12.0",
  ...
}

1.6. Move sh:class into sh:node

Currently, a property range that defines a certain class has the terms sh:class and sh:node, where sh:node contains a sh:NodeShape with sh:property defining the properties of that class. We chose this structure to simplify the definition of a "standard class" (the range must have the specified class, but its properties are not constrained, therefore we simply omitted sh:node).

In DS-V7 we want to allow the use of references as ranges, therefore we want to change the structure to have sh:class and sh:property both inside the sh:NodeShape (like in a DS node). This makes the definition of a standard class a little more complex, but it makes it much easier to handle references because we have sh:class and sh:property at the same level for DS nodes and Class nodes.

Example Class node for a restricted class:

{
  "sh:node": {
    "@type": "sh:NodeShape",
    "sh:class": ["schema:PostalAddress"],
    "sh:property": [
      {
        "@type": "sh:PropertyShape",
        ...
      },
      ...
    ]
  }
}

Example Class node for a standard class:

{
  "sh:node": {
    "@type": "sh:NodeShape",
    "sh:class": ["schema:PostalAddress"]
  }
}

1.7. Move @id of a DS from graph into DS root node

In the raw JSON-LD of a Domain Specification (see example) an @id is used to identify the Domain Specification. In theory, the DS itself (the so-called DS node, which is inside the @graph) should have the @id, and not the outter @graph (which is the case at the moment). So far, this has been no problem, but now that we want to use DS references more often (sub-DS, property value is a "copy by reference", etc.), it makes sense to move the @id to the correct position.

Example DS in DS-V5 (@id of DS at outmost position):

{
  "@context": {
    ...
  },
  "@graph": [
    {
      "@id": "_:RootNode",
      "@type": "ds:DomainSpecification",
      ...
    }
  ],
  "@id": "https://semantify.it/ds/47tJxjyLE"
}

Example DS in DS-V7 (correct @id of DS in DS node):

{
  "@context": {
    ...
  },
  "@graph": [
    {
      "@id": "https://semantify.it/ds/47tJxjyLE",
      "@type": "ds:DomainSpecification",
      ...
    }
  ]
}

1.8. Bugfix standard @context

In DS-V7 a minimal @context is provided: If a tool or use-case needs further changes to the @context they should be done in a pre-processing step. The standard @context for DS-V7 and further explanation can be found in Context.md.

1.9. Bugfix terms from the DS vocabulary

During the revision of the DS vocabulary file, we have encountered some terms that we want to change.

Domain Specification:

• ds:usedVocabularies is renamed to ds:usedVocabulary (this term should only be used if there is at least one external vocabulary used).

Verification Report:

• ds:errors is renamed to ds:error.

Additionally, the @context entry for the DS vocabulary is changed to https, resulting in "ds": "https://vocab.sti2.at/ds/".

2. Additions

2.1. ds:version

The new term ds:version is used at the DS node level to specify the DS Specification version that was used to create the Domain Specification. This information will be important for software parsing Domain Specifications to handle different versions of DS (expected properties, grammar, etc.).

The range of ds:version is a string that specifies the used version number with one decimal place, e.g. if the specification is titled "DS-V7", the ds:version is "7.0". The decimal place allows us to release minor upgrades to the specification (if wished in the future).

Be careful to not confound this term with other version-terms like schema:schemaVersion (the used schema.org vocabulary version) or schema:version (the version of the DS itself, which increases on changes of the content).

Example in DS node:

{
  "@type": "ds:DomainSpecification",
  "sh:targetClass": ["schema:SkiResort"],
  "sh:class": ["schema:SkiResort"],
  "ds:version": "7.0",
  "schema:schemaVersion": "12.0",
  "schema:version": 1.06,
  ...
}

2.2. DataType handling for Language Strings

In DS-V7 a new datatype is introduced: rdf:langString

Until now, we have used xsd:string and allowed it to have language tags, which is not possible in theory. With DS-V7 we do NOT allow xsd:string to have language tags anymore (that means this datatype MUST NOT have language-related constraints), and rdf:langString is introduced to express a string that MUST have a language tag (the only datatype that CAN have language-related constraints). By language tag, we understand a string representing a language (see the language tag specification).

For the schema <-> xsd datatype-mapping we use, this means that schema:Text is mapped to xsd:string if no language tag is allowed, or to rdf:langString if a language tag MUST be used. In theory, a DS-Editor could allow the user to add both of these datatype options for schema:Text (e.g. to make language tags optional). For the verification, the division of these two data types must be clear.

Example in a Property node (must use a language tag):

{
  "@type": "sh:PropertyShape",
  "sh:path": "schema:description",
  "sh:or": [
    {
      "sh:datatype": "rdf:langString",
      "sh:languageIn": [
        "en",
        "de",
        "es"
      ]
    }
  ],
  ...
}

2.3. ds:hasLanguage

The new constraint ds:hasLanguage specifies that the given set of language tags (see the language tag specification) MUST be used. This constraint can be used only in a Datatype node with "sh:datatype": "rdf:langString".

Example in a Property node:

{
  "@type": "sh:PropertyShape",
  "sh:path": "schema:description",
  "sh:or": [
    {
      "sh:datatype": "rdf:langString",
      "sh:languageIn": [
        "en",
        "de",
        "es"
      ],
      "ds:hasLanguage": [
        "en",
        "de"
      ],
      "sh:uniqueLang": true
    }
  ]
}

In this example, the constraint sh:languageIn is used to specify the possible language tags (3). ds:hasLanguage specifies the mandatory language tags (2). Additionally, sh:uniqueLang is used to specify that each language tag can be used at most one time. In this example, the property description must have at least 2 string values, from which one has the language tag en, and the other has the language tag de. There could be a third string value with the language tag es.

2.4. ds:defaultLanguage

The new term ds:defaultLanguage specifies a default language tag for a Datatype node with "sh:datatype": "rdf:langString". This term does not have any effects on the verification result but has only informational character.

Example in a Property node:

{
  "@type": "sh:PropertyShape",
  "sh:path": "schema:name",
  "sh:or": [
    {
      "sh:datatype": "rdf:langString",
      "ds:defaultLanguage": "en"
    }
  ]
}

2.5. ds:subDSOf

2.5.1. Syntax

With DS-V7 the concept of Sub Domain Specifications is introduced. The term ds:subDSOf specifies that the Domain Specification is a Sub-DS of the referenced DS (by its @id). A Domain Specification can have only one Super-DS but could have multiple Sub-DS.

Example in a DS node:

{
  "@type": "ds:DomainSpecification",
  "sh:targetClass": ["schema:Hotel"],
  "sh:class": ["schema:Hotel"],
  "ds:subDSOf": "https://semantify.it/ds/fBhz5h78s",
  ...
}

Addition to the standard @context:

"@context": {
  ...
  "ds:subDSOf": {
    "@type": "@id"
  },
  ...
}

2.5.2 Semantics

• The constraints defined in a Sub-DS MUST be as restrictive as the Super-DS or more restrictive. In order to be in compliance with a DS that has a Super-DS, a data instance MUST also be compliant to that Super-DS (instances that fit a Sub-DS MUST be a subset of those that fit its Super-DS).

• A Sub-DS can introduce new constraints. This is also possible for already defined constraints, but they MUST be as restrictive as the Super-DS or more restrictive. This is a delicate challenge, e.g.

  • Adding a new PropertyShape makes a Sub-DS more restrictive.

  • Adding a new range to an inherited PropertyShape makes a Sub-DS less restrictive.

  • Adding a cardinality constraint (e.g. sh:maxCount) to an inherited PropertyShape makes a Sub-DS more restrictive.

  • Increasing the value of an inherited sh:maxCount constraint makes a Sub-DS less restrictive.

  • Increasing the value of an inherited sh:minCount constraint makes a Sub-DS more restrictive.

  • The sh:targetClass of a Sub-DS MUST be the same or a sub-class of the sh:targetClass of its Super-DS.

  • Adding additional target classes (MTE) would make a Sub-DS invalid (due to our semantics of sh:targetClass).

2.5.3. Implications for the implementation

The most challenging part of this new term is to ensure the consistency between hierarchical DS when creating/editing/deleting Domain Specifications. Tools must aid users to not take actions that result in an invalid ds:subDSOf definition.

Tools presenting Domain Specifications should show/link the Super-DS in a prominent way, and/or show the total resulting constraints of a DS and its Super-DS (and recursively their Super-DS). For the verification the total resulting constraints are important. All these tools that read a DS assume that the ds:subDSOf link is valid (that the target DS exists and that the semantic rules are followed).

2.6. Use of references

When defining a range for a property it is possible to reference an already created class definition. These class definitions could be taken from the DS that is being created (an inner sh:NodeShape), or from an external Domain Specification (their DS node). In any case, the range is given by using the @id of the referenced DS/NodeShape.

2.6.1. Internal reference

In order to reference NodeShapes that are part of a DS, those NodeShapes need an IRI. It makes sense to give them the same BaseIRI as the DS in which they are in, with the addition of a fragment id, e.g. in the DS with the IRI https://semantify.it/ds/OBbzsh4_B there could be a NodeShape with the IRI https://semantify.it/ds/OBbzsh4_B#DpruH.

Example Class node (inner NodeShape):

{
  "sh:node": {
    "@id": "https://semantify.it/ds/OBbzsh4_B#DpruH",
    "@type": "sh:NodeShape",
    "sh:class": ["schema:PostalAddress"],
    "sh:property": [
      {
        "@type": "sh:PropertyShape",
        ...
      },
      ...
    ]
  }
}

Example Property node that references the previous example Class node:

{
  "@type": "sh:PropertyShape",
  "sh:path": "schema:address",
  "sh:or": [
    {
      "sh:node": {
        "@id": "https://semantify.it/ds/OBbzsh4_B#DpruH"
      }
    }
  ]
}

In order to make the use of internal references more convenient, we introduce the following rules:

• Every NodeShape inside a DS receives an IRI, even if it hasn't been referenced yet.

• The NodeShape that specifies the class node (the referenced NodeShape) contains "@type": "sh:NodeShape" and all the constraints needed.

• The internal references contain only the @id property. They can not add additional constraints.

• Only valid matches can be used as a reference for a range, for this, the sh:class constraint of the target NodeShape is checked. If the target class of a NodeShape is schema:Hotel, but the property in question can not have that class as a valid range, then that NodeShape can not be referenced.

• It is possible to create circular Domain Specifications.

2.6.2. External reference

External references enable the reuse of whole Domain Specifications. To do this, a property range has just to specify the IRI of the external DS.

Example Property node that references an external DS with the IRI https://semantify.it/ds/OBbd74jf9:

{
  "@type": "sh:PropertyShape",
  "sh:path": "schema:address",
  "sh:or": [
    {
      "sh:node": {
        "@id": "https://semantify.it/ds/OBbd74jf9"
      }
    }
  ]
}

In order to make the use of external references more convenient, we introduce the following rules:

• The external references contain only the @id property. They can not add additional constraints.

• Only valid DS matches can be used as a reference for a range, for this the matching mechanics of the external DS are checked (e.g. sh:targetClass , sh:targetObjectsOf). If the target class of a DS is schema:Hotel, but the property in question can not have that class as a valid range, then that DS can not be referenced.

• For the verification, the matching mechanics of the external DS are ignored (e.g. sh:targetClass , sh:targetObjectsOf), only the constraints are important (e.g. sh:class, sh:property).

2.7 sh:closed

See SHACL specification.

The term sh:closed can be used in NodeShapes to specify if additional properties (other than the properties allowed by sh:property) are allowed or not. In the past, Domain Specifications had "sh:closed": true implicitly in all NodeShapes. Now the DS creator should be able to specify the wished behaviour.

Example (the schema:PostalAddress entity is allowed to have additional properties that are not specified in sh:property):

{
  "sh:node": {
    "@type": "sh:NodeShape",
    "sh:class": ["schema:PostalAddress"],
    "sh:closed": false,
    "sh:property": [
      ...
    ]
  }
}