[Proposition] Move data from Markdown tables to common data format available for auto processing by scripts

[lorddaedra]

Problem

Docs are readable by humans but has not optimal format to be readable by different automatic tools.
Docs is "source of truth". We need use these data for different types of validators.
Of course, we should not break UX for humans.

Proposed Solution

Instead of markdown tables like this

| Attributes | Description |
| -----------| ----------- |
| **lago_id** &nbsp &nbsp <Type>String</Type> &nbsp &nbsp <NotNullable>Not null</NotNullable> | Unique identifier of the billable metric in Lago application. |
| **name** &nbsp &nbsp <Type>String</Type> &nbsp &nbsp <NotNullable>Not null</NotNullable> | Billable metric name. |
| **code** &nbsp &nbsp <Type>String</Type> &nbsp &nbsp <NotNullable>Not null</NotNullable> | Code identifying the billable metric. |
| **description** &nbsp &nbsp <Type>String</Type> | Billable metric description. |
| **aggregation_type** &nbsp &nbsp <Type>String</Type> &nbsp &nbsp <NotNullable>Not null</NotNullable><br></br> | Aggregation type that is used in event calculation. <br></br> <details><summary>**Possible values**</summary><div>- `count_agg` (metered)<br></br>- `sum_agg` (metered)<br></br>- `max_agg` (metered)<br></br>- `unique_count_agg` (metered)<br></br>- `recurring_count_agg` (persistent)<div></div></div></details> |
| **field_name** &nbsp &nbsp <Type>String</Type> | Field name used in events. |
| **created_at** &nbsp &nbsp <Type>String</Type> &nbsp &nbsp <NotNullable>Not null</NotNullable> &nbsp &nbsp <br></br><Comment>*ISO 8601 datetime in UTC*</Comment> | Date of billable metric creation. |
| **group** &nbsp &nbsp <Type>Object</Type> | Group (one or two dimensions) for pricing differently the billable metric |
| **active_subscriptions_count** &nbsp &nbsp <Type>Integer</Type> &nbsp &nbsp <NotNullable>Not null</NotNullable> | Count of active subscription attached to the billable metric. This field can be used to know the impact of deleting this billable metric. |
| **draft_invoices_count** &nbsp &nbsp <Type>Integer</Type> &nbsp &nbsp <NotNullable>Not null</NotNullable> | Count of draft invoices containing a subscription attached to the billable metric. This field can be used to know the impact of deleting this billable metric. |

you should use yaml, toml, json, xml or similar formats for storing data to construct such tables. (it's up to you what format to choose, vote for your preferred data format here: https://lago-community.slack.com/archives/C0499C4UMT7/p1678643968709619)

After that it will be possible to add Lago's API contract validators to OpenAPI schema repository.

From technical side: you use .mdx format (which allows to use Markdown tables and typical ts/js components, which may load data from files.)

https://mdxjs.com/docs/what-is-mdx/

I do not see technical troubles here to replace Markdown tables to something more useful for parsing by validators.

(Of course, it's possible to parse even Markdown tables with  , spaces and <SomeShit></SomeShit> inside, but it make result less predictable and lead to errors. Why it's a bad idea (html regex parsing, meme): https://stackoverflow.com/a/1732454)

[lorddaedra]

Some notes about design:

it's up to you what format to choose

One of the possible solutions here - just use swagger.yaml you already own:

• manually split it to parts and commit these parts as .yaml data files to this repository,
• create docs from this parts and replace Markdown tables,
• add build script, which will load these data files from lago-docs repository, combine them together and commit as swagger.yaml to lago-openapi repository (ex. using github workflows in lago-docs repository) so on every change in docs data files it will commit changes to lago-openapi repository

You can even add some fields with x-lago- prefix to this parts, which will be ignored for OpenAPI generation but used for docs generation.

The easiest way here is using yaml format but you can use any other format and make this yaml parts dynamically.

`.xml` parts ("source of truth") ---------> `.yaml` parts ---------> swagger.yaml
                                                         \---------> docs