[Draft] Clarify serialization and discoverability

[roll]

• fixes Yaml as well as JSON for Data Package descriptor files datapackage#292
• fixes Naming convention of additional properties in the descriptor datapackage#663

---

Overview

It's the first attempt to clarify the specifications serialization and discoverability. Also it deals with often requested YAML

[cloudflare-workers-and-pages]

Deploying datapackage with    Cloudflare Pages

Latest commit:	610a788
Status:	✅  Deploy successful!
Preview URL:	https://9094971e.datapackage.pages.dev
Branch Preview URL:	https://292-clarify-serialization.datapackage.pages.dev

View logs

[nichtich]

A data producer MAY use any suitable serialization format. A data consumer MUST support JSON serialization format and > MAY support other serialization formats like YAML or TOML.

The above states that JSON is the only serialization format that MUST be used for publishing

The data producer is the publishing agent, so either it MUST use JSON or it MAY use JSON. I guess you meant to say something like

A data producer MUST publish JSON but it MAY use any suitable serialization format to create JSON from.

[roll]

@nichtich
The point was that one can serialize a descriptor using any format, but only JSON is guaranteed to be understood by consumers. It reflects that we can't forbid e.g. frictionless-py or Open Data Editor generate YAML descriptors but we can state that it's not acceptable for external data publishing

[roll]

Hi @peterdesmet,

WDYT? Does it make sense?

[nichtich]

Sorry, but this reads like "please use JSON and name the file datapackage.json but you can also use anything else" so nothing is guaranteed. The fact that JSON can internally be serialized in YAML, TOML etc. should better be a sidenote but not part of the specification.

[peterdesmet]

The extra text in this PR makes sense. But it also includes relaxing the format and the datapackage.json name. I think it is fine to relax the format for internal use, but the text should be clearer on "publishing" (the "The above states..." is unclear to me). Personally, when provided/published as a JSON file, I think it should remain being called datapackage.json.

[roll]

Thanks @peterdesmet!
I've merged your suggestions at it is

[roll]

I'll put this under the draft label to take some extra time working on it as, it will be probably better if we move the definitions in one place (like glossary/terminology spec) instead of duplicating it in all the specs

[roll]

CLOSED in favour of #50