Docs: merge sections "Attribute spec" and "Primitive data types" in KSY reference

[KOLANICH]

The rationale: thay contain the same info and they can contadict each other. Merging them would help to keep the doc consistent.

[GreyCat]

1. KSY reference will be hopefully deprecated soon in favor of JSON schema.
2. I don't see how they contain the same info — "Attribute spec" specifies attribute spec (i.e. map which contains id, type, doc, doc-ref, etc) and "Primitive data types" list reserved string contents of type.

[KOLANICH]

KSY reference will be hopefully deprecated soon in favor of JSON schema.

Glad to see that. There are JSONSchema to HTML tools that may be useful, though all of them are for Node and depend on the stuff from npm.

I don't see how they contain the same info — "Attribute spec" specifies attribute spec (i.e. map which contains id, type, doc, doc-ref, etc) and "Primitive data types" list reserved string contents of type.

contents of type are discussed in both sectio s in a bit different way. More precisely, str and strz. If one read only the first occuring (and unaware that there is one more) section he will have the wrong impression.

[GreyCat]

There are JSONSchema to HTML tools that may be useful, though all of them are for Node and depend on the stuff from npm.

Doesn't seem to be a major problem, does it? We're ok to run just about any stuff in docs CI...

More precisely, str and strz.

That's a good point. In terms of JSON schema, I guess we need to think how to make this section better — i.e. introduce some explanations and not just the raw list. Any ideas?

[KOLANICH]

Doesn't seem to be a major problem, does it? We're ok to run just about any stuff in docs CI...

... as long as it doesn't have commit access to repos (as I understand, it has access to more than one repo gecause GH rules forbid >1 bot account per alive user account and there are multiple sites needed to be regenerated: formats.kaitai.io, docs.kaitai.io, ci.kaitai.io ...), other than docs one. And even posting to docs repo may cause significant harm. For example an adversary may insert a backdoor into some widely used dependency and then try to monkey-patch some templating framework to make it insert links to exploit kits.

That's a good point. In terms of JSON schema, I guess we need to think how to make this section better — i.e. introduce some explanations and not just the raw list. Any ideas?

Keep it not as a enum.

"anyOf":[
  {
    "properties": {
      "type": {"const":"strz"},
      // stuff useful for strz
    }
  },
 {
   "properties":{
     "type":{"enum":[/*int types here*/]},
     // stuff useful for ints
    }
  },
  ...
]