Skip to content

Argue for the back-end layer, not just the choice of STIX - #40

Merged
kurtseifried merged 1 commit into
mainfrom
docs/why-a-back-end-at-all
Aug 12, 2026
Merged

kurtseifried merged 1 commit into
mainfrom
docs/why-a-back-end-at-all

Conversation

@kurtseifried

@kurtseifried kurtseifried commented Aug 12, 2026 •

Copy link
Copy Markdown
Contributor

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

  • A design principle, in the section that is their single home: one canonical representation; every published format is 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 §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, they are answered once and every format inherits them. Names 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.
  • §6 now presents STIX as the source and the rest as projections, rather than as the first entry in a list of peers, and states that no output is authoritative.

README.md and 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 --check and the YAML round-trip all pass.

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.
@kurtseifried
kurtseifried merged commit 97071d1 into main Aug 12, 2026
6 checks passed
@kurtseifried
kurtseifried deleted the docs/why-a-back-end-at-all branch August 12, 2026 04:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant