Add supporting document for autos

[danbri]

Mirek & co have drafted something, staged at http://sdo-auto-fix.appspot.com/docs/automotive.html

I'd like to add this under /docs/ alongside our other supporting documentation.

Ping @vholland @scor @nicolastorzec @rvguha @tmarshbing @tilid - can you take a look?

[tmarshbing]

This is very comprehensive. I like it! A few suggestions:

1. Add a link to the examples at the top. I imagine most readers will be most interested in the examples, so let's get them there quickly.
2. In the hybrid car example, shouldn't we use value instead of maxValue for the weightTotal and wheelbase attributes? It also might be nice to show the kWh for the electric engine. Finally, the pre-markup example is missing the offer that is in the markup.

[sopekmir]

Thanks! We will consider adding a line with in-page links to all the sections (we have 7 of them).
Your remarks about hybrid car example will also be taken care of!

[trypuz]

@tmarshbing, thank you for your suggestions. Almost all of them have been applied (see http://sdo-auto-fix.appspot.com/docs/automotive.html), i.e.:

• we added a table of contents to the document (as @sopekmir suggested)
• we used value instead of maxValue for the wheelbase property
• we added description "Battery Energy 1.56 kWh" to the example (please note that in our example we used Ah to describe the battery capacity - see fuelCapacity property)
• we added the offer info to the pre-markup example

I think it still makes sense to use maxValue for the weightTotal property.

@tmarshbing, would you say that the standard for measuring battery capacity is Watt Hours or Kilo-Watt Hours not of Amp Hours?

[tmarshbing]

Thanks for the changes. A few things:

• I don't see the change for wheelbase. I still see maxValue.
• For weightTotal, I double checked its definition, and it looks like it can be used either to describe the max weight supported or to describe the empty weight. Apparently, you're supposed to use the name attribute on the quantitative value to differentiate. Maybe we could add name: "Permitted total weight"? I think that minValue/maxValue are only supposed to be used if expressing a range. Although we have an implied range here [empty weight, max permitted weight], I think it's still more helpful to add the name + use value.
• For battery capacity, at least in the US, I think kWh is more common. E.g., see https://www.tesla.com/models/design, https://www.nissanusa.com/electric-cars/leaf/charging-range/, or http://www.chevrolet.com/byo-vc/client/en/US/chevrolet/bolt-ev/2017/bolt-ev/features/trims/?styleOne=388584.

[sopekmir]

Oops, @tmarshbing - thanks for the note and sorry - for quite a long time we did not correct the documentation's Example 2, where we still have maxValue. We will do it asap !

[trypuz]

@sopekmir, @tmarshbing as far as the change for "wheelbase" is concerned -- my fault; I've changed maxValule to value only in the example that is here: http://auto.sdo-auto-fix.appspot.com/wheelbase and completely forgot to update the documentation. Should be OK now.

[VladimirAlexiev]

A very useful doc! Suggestions for improvement:

1. The diagram makes it look that all the props apply to Car but in fact they apply to Vehicle. So rename the central node to Vehicle
2. The first one is a class diagram (very different from the second one which is a property diagram): mark it so, and I’d use a different style (eg a tree) to emphasize that
3. vehicleEngine should show the class holding the “subsidiary” properties: EngineSpecification
4. Can you put some dot on the branches showing enumerations: vehicleSpecialUse, driveWheelConfiguration, steeringPosition

In the list below the diagram (The complete hierarchy of all terms in the automotive extension):

5. Use violet instead of red for the “auto” terms, to match the color on the diagram
6. Use black instead of brown for auto terms in core
7. Include section “Enumerated values”

Further:

8. http://schema.org/vehicleModelDate has no comment. This is not ok, especially given that there is also http://auto.schema.org/modelDate . Explain and contrast the two
9. Give example of using both props
10. The TOC is very useful, but also include subheadings in the TOC (the doc is fairly long, so that will ease navigation)
11. The phrase “Drive & Wheel Configuration” is wrong. It’s "Drive-wheel Configuration" (which wheels drive the car)
12. In EXAMPLE 2, PRE-MARKUP and JSON-LD Markup don’t correspond (eg PRE-MARKUP doesn’t have productionDate, modelDate, cargoVolume; and "Last updated on" is not the same as availabilityStarts). Either make them the same, or remove PRE-MARKUP.

[trypuz]

@VladimirAlexiev thank you for your detailed and helpful comments! Please find below my answers to all your suggestions.

Ad 1 and 2: We did intentionally picture (in the first two diagrams) the types and properties this way. The only purpose of the two presented mind maps is to show the whole conceptual repertoire of types, properties, and enumerations that can be used to mark up automobiles. So I would leave them as they are.
Ad 3: @VladimirAlexiev could you please explain what you meant here?
Ad 4: Dotted arrows represent the instance-of relation. So there are dots on the branches showing enumerations. Did you mean something different?
Ad 5, 6 and 7: We've changed the colors of core and auto terms to make their look-and-feel compatible with the full type hierarchy "Core plus all extensions" doc. And since the list is shaped in such a way that it illustrates hierarchy (is-a), we decided not to list enumerations in the same way.
Ad 8 and 9: In #1650 and #1674 we have discussed the properties: http://schema.org/vehicleModelDate and http://auto.schema.org/modelDate. In the examples, in our doc, we have only used modelDate.
Ad 10: Subheadings have been added to the TOC.
Ad 11: Corrected.
Ad 12: Missing elements have been added to PRE-MARKUP.

@VladimirAlexiev, let us know if there is something more to be corrected/improved, please.

[VladimirAlexiev]

@trypuz @sopekmir
ad 1. Why the prop diagram has Car in the center? Should be Vehicle

ad 2. Could you make the two disconnected parts of the diagram look different, since they mean different things?

ad 3. vehicleEngine leads to a bag of props. That bag has a class (EngineSpecification) that should be shown on the diagram

ad 4. I don't see dotted arrows? The visual from vehicleSpecialUsage to DrivingSchoolVehicleUsage is just the same as from vehicleEngine to fuelType, but the meaning is different.

ad 7. I'm suggesting you include a section “Enumerated values”, after sections "Types" and "Properties"

ad 8. and 9. Then vehicleModelDate should be killed in favor of modelDate: #1746

ad 13. Would be nice to validate all examples, eg:

• tried to convert Example1 RDFa to Turtle using http://rdf-translator.appspot.com/ and got this:

parsing Error! mismatched tag: line 8, column 6

The problem is unclosed <meta> tags

• tried to convert Example3 JSONLD to Turtle using Jena RIOT and got this:

riot --formatted=turtle auto-eg3-hybridCar.jsonld  1>auto-eg3-hybridCar.ttl
java.lang.IllegalArgumentException: Illegal character in path at index 8: internal combustion engine

• rdf-translator gives a better error message:

"file:///base/data/home/apps/s%7Erdf-translator/1.380697414950152317/internal combustion engine"
does not look like a valid URI, I cannot serialize this as N3/Turtle. Perhaps you wanted to urlencode it?

• The reason is that engineType is declared a URL in the schema.org context (bug in the context: engineType wrongly declared URL in jsonld context #1747), so you can't use a string.

ad 14. Try to convert each variant to turtle and ensure they produce the same turtle

[trypuz]

Ad 13: Examples have been corrected and validated by https://search.google.com/structured-data/testing-tool. There were 3 problems. There was "," after ""vehicleSpecialUsage":"DrivingSchoolVehicleUsage"" in the example 3. In the example 1 (in rdfa and microdata) there was used the old version of numberOfAirbags prop, i.e. airbags. Thanks for noticing!

[trypuz]

Ad 1, 2, 3, 4: @VladimirAlexiev as I wrote yesterday - I do not think it is a good idea to change the two mind maps (but let us consult @sdml and @sopekmir in this matter). The different types of arrows have been used in section 5 "Basic models".

Ad 8 and 9: You do have my support!

[VladimirAlexiev]

ad 13 See #1747, #1748, which are bugs in schema or its jsonld context

• to fix engineType wrongly declared URL in jsonld context #1747 now, you need to pick some type URLs for bodyType engineType fuelType vehicleTransmission. Would you rather
  • use example URLs like http://auto-types.org/engine/InternalCombustionEngine, or
  • pick Wikidata entities (eg http://www.wikidata.org/entity/Q28777632), which was suggested by @vrandezo and sort of approved by the Schema community
• maybe unitText "AMH" should be unitCode?
• vehicleInteriorColor "beige interior" should be just "beige"

[VladimirAlexiev]

@trypuz #1749 also affects you.
So "validated by https://search.google.com/structured-data/testing-tool" is not enough. You also need to look at the data in a different format (see 14 above) and eyeball it to ensure the values make sense.