Clarifying use of schema for documentation, not code generation

[Holger Reinhardt]

Great message thread on rocket:

ou CAN design extensible schemas even in XML Schema ... but it means you need to be extremely mindfull about it
i.e. you need to make both the attribute space and child elements extensible ... xsd:any is your friend .. but it is very tedious
most tooling interprets schema literally, not extensibly
so you DO need documentation and you might even choose to use Schemas
but how you design the Schema and how you end up using the Schema (for documentation vs for code generation) - that will make or break your extensibility and robustness
you could document your events RFC style .. and this is how the internet was build
you do not need schema
problem is that the step from schema as documentation to schema as input to code generation is tantalizing small and it takes a lot of will power and awareness to decide to not do it
that is all I am saying .. we are humans afterall

Caballero, Mallku @CaballeroM 9:29 AM
All I meant to say is that a non-enforced schema can be a good tool for documentation
👍 1

Reinhardt, Holger @reinhardth 9:29 AM
to which I wholeheartedly agree .. 100% ... +1
question is .. who do you document it for
humans?
probably
then how does Avro come into play
Humans do not need Avro ... machines, code, tooling needs avro 🙂

so it looks like we do not have a disagreement after all 🙂
non-enforced schemas are a great way to document ... so is RFC style
for as long as everyone know it should not be used for blindly auto-generating client code .. and/or if you do that ... a lot more attention has to be paid to make the schema extensible
maybe even enforced by have a lint which alerts you if non-extensible schema is being check-in or used
so you either protect yourself against human fallacies by using a format whcih can not be readily used for code generation or by tooling which enforces extensibility
the way to hell is paved with good intention .. and it is upon us to make sure we account for human fallacies
there will be developers other than those participating in this discussion writing code .. it is those folks in 6 months I worry about, not about you or anyone on this message thread

Caballero, Mallku @CaballeroM 9:35 AM
+1