Skip to content

GeneralVerification

Jump to bottom
omar edited this page Jan 13, 2021 · 3 revisions

General Verification of schema.org annotations

Introduction

The general verification of schema.org annotations is defined as the process of checking if a given schema.org annotation in JSON-LD format is in compliance with the following specifications:

  • JSON
  • JSON-LD
  • Schema.org

Additionally, restrictions are added/softened depending on real-world practices and usages (e.g. schema.org's pragmatic view on conformance)

The output of the verification process is provided as an error report in a structured way (JSON-LD) with a specific data model (GeneralVerificationReport). Any inconsistencies found are expressed through corresponding error entries. The documentation file "BasicVerification.md" provides the error list for JSON and JSON-LD specific errors. In the following the error list for schema.org is provided.

Error List for General Verification of schema.org annotations

Error Codes for the General Verification of schema.org annotations start with 3

ErrorCode Name Severity Description
300 Generic schema.org Verification error Any Can be used as generic error code regarding the general verification, e.g. if there is no other suitable error code
301 Non-conform @context Error There is an error with the (not) used @context
302 Non-conform @type Error Used @type is non-conform to schema.org
303 Non-conform property Error Used property is non-conform to schema.org
304 Non-conform action property Error Used action property (input-/output-) is non-conform to schema.org. The value must be a well-formatted string or a PropertyValueSpecification.
305 Non-conform domain Error Used property has a domain that is not allowed to use according to schema.org
306 Non-conform range Error Used property has a range that is not allowed to use according to schema.org
307 Unexpected string Warning Used property has a string as value, although it is not explicitly allowed by to schema.org
308 Non-conform enumeration Warning Used property has an enumeration value that is non-conform to schema.org (must be a URL stated as enumeration value)
309 Empty entity Warning Used property has a range that is an entity with no properties

Misc

In the following certain aspects of the verification that need further discussion are listened. The discussion about these topics should happen at https://github.com/semantifyit/sdo-check/issues

Context

The JSON-LD @Context allows to define a certain semantic in a lot of different syntactic ways (see JSON-LD spec), however, our algorithm expects/allows a certain sub-set of @context based on the presumable practices of schema.org annotations. Independent of the different syntactic variations, the most important takeaway is to use the right context URI for schema.org.

Schema.org context URI

GitHub issue: https://github.com/semantifyit/sdo-check/issues/1

The following RegularExpression is used to test acceptable formats:

/^(https?:\/\/)?(www\.)?schema\.org\/?$/

If no acceptable format was found a Critical Error is produced (301, Non-conform @context).

The following RegularExpression is used to test recommended formats:

/^https?:\/\/schema\.org\/?$/

If no recommended format was found a Warning is produced (300, Non-ideal @context).

Context variants

GitHub issue around this topic: https://github.com/semantifyit/sdo-check/issues/1

The context variant that we expect for most users is that of a compacted JSON-LD with a single URI as context:

{
  "@context": "http://schema.org/",
  "@type": "Person",
  "birthDate":  "1989-09-20"
}

Typed values

GitHub issue: https://github.com/semantifyit/sdo-check/issues/4

Typed values are those literals expressed by an object having @type of the data type and @value for the actual value. It is very useful to define a specific data-type, but unfortunately not embraced in practice. Our algorithm does not allow this syntax (yet?). (Example: 1. link is typed value).

Keep in mind that the schema.org context file has to be considered.

{
    "sameAs": [
        {
            "@type": "URL",
            "@value": "https://twitter.com/Link1"
        },
        "https://twitter.com/Link2"
    ]
}

Enumerations

The enumerations model of schema.org is very unclear. It is still to discuss/figure out, what is allowed/recommended regarding enumerations. Basically, they could be accepted as Entities (e.g. CreditCard) or URIs (e.g. Monday).

Actions

GitHub issue: https://github.com/semantifyit/sdo-check/issues/2

schema.org documentation about actions: https://schema.org/docs/actions.html

Action entities may have "action"-specific input and output properties. Those may have as value a String or a PropertyValueSpecification-typed object.

Clone this wiki locally