Improve the narrative structure of the SDMX-CSV data specification

[hoehrmann]

The SDMX-CSV data specification should have an overview like this:

Column Name	Description	Order
STRUCTURE	Data structure type (dataflow, datastructure, dataprovision)	1
STRUCTURE_ID	Artefact identification information	2
STRUCTURE_NAME	Localized name of the artefact	3 (Optional)
ACTION	Action code (I - Information, A - Append, R - Replace, D - Delete)	4 (Optional)
SERIES_KEY	Series key for the observation	5 (Optional)
OBS_KEY	Observation key	6 (Optional)
Remaining Columns	Component IDs or localized names
Special cases:
EXAMPLE: text	Extra column with the localized name for the EXAMPLE component
EXAMPLE[]	Multi-valued
EXAMPLE[de;fr]	Multi-lingual
PARENT.CHILD	Nested metadata attribute
PARENT[].CHILD	Nested metadata attribute of multi-valued parent attribute

And then discuss them in detail, based on the type of column. The current document is very difficult to follow as it is at the moment.

(In doubt, please handle this as a public review comment on SDMX 3.1 once the comment period begins.)

[khaeru]

I was about to open a new issue for a couple of points, but I think this one already covers it.

Specifically, the current organization allows that there are some contradictions that are hard to spot on a first read. For instance, in the ## Columns section, see the use of the word always:

sdmx-csv/data-message/docs/sdmx-csv-field-guide.md

Lines 30 to 32 in 9a65b13

	- The next one or two columns are always used for the structure's identification.
	- The next column is always used for the action to be performed.
	- The next up to two columns are used for the series and/or observation key.

…whereas in the ## Column headers (first row) section:

sdmx-csv/data-message/docs/sdmx-csv-field-guide.md

Lines 46 to 47 in 9a65b13

	- The header field of the next column should contain the term `ACTION`. For convenience, if this column is not present, a default action ("Information") is assumed for the whole message.
	- The next up to two columns contain, if option `key=series|obs|both` (see *[here](#optional-parameters)*), in this order the terms `SERIES_KEY` and/or `OBS_KEY`.

…the words should and if this column is not present are used.

The latter implies that the ACTION column does not need to "always" be present in valid SDMX-CSV; thus the statement in the first snippet is false; the structure identification column(s) may be followed directly by the series and/or obs keys, or directly by specific dimension keyvalues.

A reorg as suggested by @hoehrmann would put suchs texts close together and help reveal contradictions, which could then be resolved. Some other suggestions I'd add:

• Use the RFC2119 keywords like must, should, may. Using these helps readers and reviewers a lot.
• Specifically identify the roles of at least (a) writers (senders, emitters; could be people or systems/software) and (b) readers (receivers, processors) of SDMX-CSV. This would allow very clear statements like:

  • The following column should have the header ACTION and values from the codelist […].
    A SDMX-CSV sender may omit this column.
  • If a SDMX-CSV data message does not contain an ACTION column, a receiver SHALL assume the value I (Information) for all rows.