Note that this question is at the border of StackOverflow and ProWebmasters, so please forgive me if you think that it belongs to SO; but I'm afraid that it would be closed over there as "not a programming question". Anyway:
I'm implementing a PHP library to parse schema.org structured data and represent them using objects that match schema.org types: Product
, Offer
, etc.
I've so far identified 3 ways properties are used:
The property has a Thing type, and is marked up as such
This is self-explanatory, and can be translated in code as a
$offers
property containing a list ofOffer
objects:"@type": "Product", "offers": { "@type": "Offer", "availability": "http://schema.org/InStock", "price": "55.00", "priceCurrency": "USD" },
This maps straight to code that could look like:
class Product { /** @var Offer[] */ public $offers; }
The property has a Text type, and is marked up using a simple string
This is self-explanatory as well:
Text
is a DataType. It can be mapped in code to a native data type such asstring
:"@type": "Product", "color": "red",
class Product { /** @var string */ public $color; }
The same goes with properties of type
Number
,Date
, etc. These are allDataType
s that could map to a native type in code, and that make sense to mark up as a simple string.The property has a Thing type, but the docs suggest to use it as a text property (!)
Example: ExerciseAction.distance
Distance is not a
DataType
, it's an object that extends fromThing
and whose only properties are those inherited fromThing
:Thing
>Intangible
>Quantity
>Distance
Still, the doc does not say to mark it up as an object with properties, but as a simple text string. Example straight from ExerciseAction:
"@type": "ExerciseAction", ... "distance": "100 miles",
I'm struggling with this last one, which seems to be a mix of a Thing
and a DataType
.
Question 1
How am I supposed to represent a Distance
in code, when it's represented as text in the markup?
As a Distance
is a Thing
, it would feel wrong to me to represent it as a string
in code; I'd rather convert this text value to a Distance
object. But then, where should the textual value go? In the name property for example?
Is handling of these Quantity
values documented anywhere? I found an issue on the schemaorg repo that seems to support the feeling that there's an ambiguity here.
Question 2
Is a text string the only correct usage for a Distance
property, or can we encounter a Distance
as an object, such as the following?
"@type": "ExerciseAction",
"distance": {
"@type": "Distance",
"name": ...
}
Note that Google's structured data testing tool does not seem to care and accepts both. It does not seem to apply any conversion either, i.e. it outputs a textual distance
as is, without converting it to a @type Distance
.
I've browsed for other implementations of schema.org parsers to get inspiration (and answers) from, in any language, but didn't find anything close to what I'm trying to achieve here.
URL
value. While this is also aDataType
, you can’t treat it as regular string, because the URLs might be relative references. – unor Jun 4 '19 at 5:00