search

oasis-tcs / csaf

OASIS CSAF TC: Supporting version control for Work Product artifacts developed by members of TC, including prose specifications and secondary artifacts like meeting minutes and productivity code
https://github.com/oasis-tcs/csaf
Other
142 stars 38 forks source link

Aggregator schema typo `mirror` #663

Closed tschmidtb51 closed 4 months ago

tschmidtb51 commented 10 months ago

In the aggregator schema, we have a typo:

https://github.com/oasis-tcs/csaf/blob/5757eeb192f30dbf1752d15365e335c3408ce4df/csaf_2.0/json_schema/aggregator_json_schema.json#L178

lists mirror as required field - but the real name should be mirrors according to our naming logic and

https://github.com/oasis-tcs/csaf/blob/5757eeb192f30dbf1752d15365e335c3408ce4df/csaf_2.0/json_schema/aggregator_json_schema.json#L187

Tasks:

sthagen commented 10 months ago

Naming is Hard

As a software engineer I like to have the names optimal (not ideal) as the effort required to approach the latter may not be adequate.

But eitherway (fixing on spec level or not), I think that the first order of business in such cases (no prose but a schema i.e. a contract between (machine) agents) is to reach an understanding of two related facts:

  1. the scope (deployment so far) of distribution needed for any change from our side
  2. the hardness of coupling introduced by the actors specifically finding out if they a. either adapt their agents b. or insist on automatic derivation (from our schema)

Maybe the cost of change is not worth to maintain a perspective of perfect model expression.

After all, we could have named that key also abadcafe ... as long as the titles / descriptions in the schema (often used by tool builders to serve the human users) expose the intented meaning and thus foster value quality of the entries.

Even if we mess up the titles / descriptions, I learned, implementers come back and ask and then fix it for us in real life, kind of.

sthagen commented 9 months ago

As discussed in our weekly editor call, I will send a request to TC admins and in copy to our chair to answer the question:

Is our OASIS errata process adequate for adding a single character "s" into the key of our aggregator schema?

The prose is not impacted, as in the examples in there, the correct plural form is used.

The problem is, that no one seems to use the aggregator role in full for now and the fix is required. Otherwise it is not possible to have an aggregator JSON file that is valid against the schema.

sthagen commented 9 months ago

This comment is to acknowledge the receipt of the CSAF v2.0 Errata 01 starter document.

I did commit the file at

https://github.com/oasis-tcs/csaf/blob/csaf-2.0-errata-01-starter/csaf_2.0_errata_01/index.md

and tagged to our (this) TC repository:

https://github.com/oasis-tcs/csaf/releases/tag/csaf-2.0-errata-01-starter

tschmidtb51 commented 4 months ago

@sthagen I guess that can be closed, right?