Repository navigation
Argue for the back-end layer, not just the choice of STIX - #40
Merged
Merged
Conversation
The document said "back-end" seven times and never once argued for having a back end. Every use was assertive: question 1 was "why STIX as the back-end representation", section 3 was "why not OSCAL as the back-end format". The distinction the whole design rests on was assumed, so a reader could absorb the document and reasonably conclude these are all candidate formats for the thing we publish -- because that is the only argument the text contained. Structured as a format bake-off, it reads as one. Section 5 made it worse by listing STIX first among the publication formats, alongside OSCAL and Excel. The document put the source on the same shelf as its outputs, so "STIX is a potentially interesting output format alongside OSCAL" was a reading the text supported. And the most-proposed alternative was never addressed. Section 4 rejected CSAF, OSV, CVE JSON, CVRF and the semantic-web family -- five formats nobody had suggested -- while plain JSON or YAML with a published schema, which is the actual alternative on the table, appeared only in the publication list. The document endorsed YAML as an output, never declined it as a back end, and left the back-end choice looking arbitrary to anyone who preferred it. Four changes: - A design principle, in the section that is the single home for them: one canonical representation, every published format a projection of it. A format that carries the catalog is not the same kind of thing as a format it is published in, and two authoritative formats mean no canonical layer at all. - A new section 2 making the argument: the catalog serves audiences that want genuinely different shapes; without a canonical layer each output path answers the modelling questions independently and the conversions grow with the number of pairs of formats; with one, the questions are answered once and every format inherits them. Notes the observable symptom -- some outputs carrying less than others, not by design -- and why the back end must be a superset rather than a compromise. - Plain JSON/YAML-with-a-schema added to the not-adopted list, with the real reason: a serialization is not a model. No relationship primitive, no identity scheme, no way to declare a type so a consumer can discover it, no versioning model. Each would have to be invented, which is a purpose-built format wearing a familiar syntax. The distinction is not JSON versus STIX -- STIX is JSON. - Section 6 now presents STIX as the source and the rest as projections of it, rather than as the first entry in a list of peers, and states that no output is authoritative. README and both agent-context files carried the same blur and are corrected to match. Sections renumbered; internal cross-references updated. No object or schema changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The document said "back-end" seven times and never once argued for having a back end.
Every use was assertive — question 1 was "why STIX as the back-end representation", §3 was "why not OSCAL as the back-end format". The distinction the whole design rests on was assumed rather than made, so a reader can absorb the document and reasonably conclude these are all candidate formats for the thing we publish. Structured as a format bake-off, it reads as one.
§5 made it worse by listing STIX first among the publication formats, alongside OSCAL and Excel. The document put the source on the same shelf as its outputs — so "STIX is still a potentially interesting output format alongside OSCAL" was a reading the text actively supported.
And the most-proposed alternative was never addressed. §4 rejected CSAF, OSV, CVE JSON, CVRF and the semantic-web family — five formats nobody suggested — while plain JSON or YAML with a published schema, the actual alternative on the table, appeared only in the publication list. The document endorsed YAML as an output, never declined it as a back end, and left the back-end choice looking arbitrary to anyone who preferred it.
Four changes
README.mdand both agent-context files carried the same blur and are corrected to match. Sections renumbered, cross-references updated.No object or schema changes. Doc-discipline checks,
coverage.py --checkand the YAML round-trip all pass.