Go with extensions on extension types, and generation of comments.
There's just one wrinkle with generation of comments, which is that when you $ref a type it pulls in the description of the type as the description of the property. So the description of the field Foo myFoo; is copied from Foo, which is not what you want.
It's possible to use allOf to specify a second description, but that's pretty ugly, I suggest we use $comment, which is slightly worse in terms of what it means (nothing!) but looks nicer in the schema and is fine for generation. It's a bit annoying that we have to remember to use $comment only next to $ref, but that's easier to remember than using allOf with a description next to $ref :) what do you think?
Fix #6
Go with extensions on extension types, and generation of comments.
There's just one wrinkle with generation of comments, which is that when you
$refa type it pulls in the description of the type as the description of the property. So the description of the fieldFoo myFoo;is copied fromFoo, which is not what you want.It's possible to use
allOfto specify a seconddescription, but that's pretty ugly, I suggest we use$comment, which is slightly worse in terms of what it means (nothing!) but looks nicer in the schema and is fine for generation. It's a bit annoying that we have to remember to use$commentonly next to$ref, but that's easier to remember than usingallOfwith adescriptionnext to$ref:) what do you think?