ASDL Documentation of object types

[smnmyr]

Currently, the doc says: "For object types, the documentation MAY define additional properties."

I'd rather have it say: "For object types, the documentation MUST give a description of the type of object it refers to, and MUST give at least three examples of such objects. Additionally, it MAY define additional object properties."

There are certainly better ways to express this (e.g., why three examples... ;-)) but I want it to enforce at least a short, understandable, description.

[dret]

sounds reasonable. the question is how you want to enforce this. for example, if somebody went through the effort of defining some kind of JSON schema for the object type, that should be sufficient as well, without requiring any number of examples, right? so i agree that the object type should be defined/described/documented somehow, but i'd be hesitant to hardcode one particular way of doing it. for RDF-centric users, i'd imagine they might start with some RDF/OWL model and then have a JSON-LD context that would "define" the JSON serialization of it. that would be yet another way to do it.