Recommendation for including contract ABI descriptions in EIPs and ERCs as YAML.
In the past, most ERCs/EIPs included an ABI description purely as a Solidity contract and/or interface. This has several drawbacks:
This proposal aims to solve all these issues.
The Standard Contract ABI is usually represented as a JSON object. This works well and several tools – including compilers and clients – support it to handle data encoding.
One shortcoming of the JSON description is its inability to contain comments. To counter this, we suggest the use of YAML for providing user readable specifications. Given YAML was designed to be compatible with JSON, several tools exist to convert between the two formats.
The following example contains a single function, transfer with one input and one output in YAML:
Specifications are encouraged to include comments in the YAML ABI.
For details on what fields and values are valid in the ABI, please consult the Standard Contract ABI specification.
The same in JSON:
The aim was to choose a representation which is well supported by tools and supports comments. While inventing a more concise description language seems like a good idea, it felt as an unnecessary layer of complexity.
This has no effect on backwards compatibility.
TBA
yamabi is a Javascript tool to convert between the above YAML and the more widely used JSON format.
Copyright and related rights waived via CC0.