Add guidance around use of polymorphic types

[jack-berg]

On multiple occasions I've tried to use allOf to model polymporphic types only to be reminded that the jsonschema2pojo tool we're using in opentelemetry-java doesn't support anyOf, allOf, oneOf. I suspect this is the case in other languages as well.

I propose we provide modeling guidance to explicitly avoid this tempting trap.

[marcalff]

On multiple occasions I've tried to use allOf to model polymporphic types only to be reminded that the jsonschema2pojo tool we're using in opentelemetry-java doesn't support anyOf, allOf, oneOf. I suspect this is the case in other languages as well.

I propose we provide modeling guidance to explicitly avoid this tempting trap.

I Agree.

In case of C++, the available tooling is so poor (or nonexistent) that:

• we are not even using a schema validator
• we are not using code generated from a schema

Validation of yaml nodes against the schema is done ad-hoc.

[marcalff]

LGTM.

Not related to this PR, but I think it is time to split README.md into multiple documents, and have a docs/ subdirectory.

[jack-berg]

Validation of yaml nodes against the schema is done ad-hoc.

That's too bad on the tooling. For what its worth, once the schema is stable, I'm strongly considering ripping out the code generation tooling from opentelemetry-java and maintaining the (previously) generated code by hand instead. Is very similar to the problem with exposing generated proto bindings from opentelemetry-proto as part of your public stable API: you can't guarantee that the code generation tooling won't change in a way that violates the guarantees you make for stable APIs.

[codeboten]

Re. tooling, on the go side i ended up having to split the model generation from the parsing logic, as the parsing code needed to be updated in a couple of places.

I guess this is a good opportunity to help move the json schema ecosystem forward where possible.