Formal Specification

[codello]

Suggestion

There should be a more formal specification of the file format. I suggest that the specification is maintained in a text file (markdown or Plain text) in this repository (and then potentially embedded in the website as well).

The website could serve as an overview aimed mainly at non-developers and could Highlight relevant features of the spec (as it does now). As an example https://tus.io/ does something similar (They have the FAQ section with an overview and the formal spec on the „Protocol“ page).

Use case

Currently the official spec seems to be the HTML-formatted website. While the website provides a convenient introduction and overview of the format it‘s currently missing many of the technical details. At the same time many end users are probably not interested in those details.

As a developer a more technical specification is really helpful when implementing parsers, generators and other software interacting with the format.

A simple text file has advantages over the HTML format because it makes it much simpler to create and review PRs with changes to the spec. Otherwise the HTML/CSS/design gets mixed with the spec discussion and limits potential contributors from proposing changes.

Extra info/examples/attachments

I‘d be happy to submit a PR with a first draft of a more formal specification if this is wanted. However, I‘m not sure what the best process is. The spec would contain a lot of small details that probably need to be discussed (See #46, #44, #43, #18). Having many different things in a single PR could be difficult to discuss. Maybe a maintainer could give me some guidance about the best process?

Also the question posed in #41 applies here as well: should there be a single spec that includes changes in newer versions or a standalone spec per version.

[Baklap4]

i find the idea of a text-based spec file great.
I'd opt for a markdown format since it has many ways to output the details into other formats.

I'd love for it to be the source of the website. Maybe through a library like showdownjs or something else.

The reason this project started was to contain all the info we gathered so far and to standardize the project in a more formal way than just a couple of blogs combined.

I think you can start by filling in the details of stuff that's already agreed upon and file issues/questions in discord if they don't exist already. The discussion for those items can happen there.

If the setup is right it'd be easy to add the blanks (those refered issues) at a later stage.
The setup itself can be reviewed on its own and stuff can be added later in multiple or one pr after

Please also keep in mind that we define a couple of versions. This is currently not visible on the website, but should be (#41 )
Personally i'd create a specfile per version just like swagger for example does.

A structure could be:

/
--->spec
--------> 0.0.1.md
--------> 0.0.3.md
--------> 1.0.0.md

etc

Todo

• Setup a structure so the spec can be easily edited
• Propose a strategy how additions/changes should be done
• Optional: Convert the markdown to html

[codello]

All right, thanks! I will try to leave out the parts that are still undecided. There will be some points where I will have to make some decisions (e.g. about white space) but I will try to highlight those for further discussion.

I'd prefer if at least for now we would just have a single Markdown document for the specification and just hightlight parts that have been added/removed/changed in different versions. At least for the beginning this would simplify the process significantly and avoid having different files containing contradictory specs. I think it would make sense to extract the fixed-version specs at some point in the future when the fundamentals have been decided on.

[Baklap4]

Sounds like a good way to go! 🎉

[codello]

I have created a first draft PR so that people can see the progress. There is still some work to be done (and some ideas that probably should be removed for the first PR) but the PR should still show the direction I'm going in.

This discussion should probably be continued in the PR.

[marwin89]

I agree with you, a textbased spec file (md) is good and it would be awesome if we can use it as source of the website.
thanks for your work so far. 🙂