Author: Asmit Phuyal, a contributor to Google Summer of Code 2025
GSoC project link
Project Overview
Decorator Command Set (DCS) allows us to separate decorator definitions from the model and programmatically apply them at runtime.
However, DCS, when represented in JSON, are often verbose, less human-readable, and harder to edit manually. To improve the usability, we aimed to provide a YAML-based representation for DCS.
This project focuses on developing reliable methods to perform round-trip conversions between DCS in JSON and YAML formats, ensuring semantics remain identical across both representations.
Development Journey and Implementation
Designing the YAML Schema
The project started with designing a custom YAML format for DCS, so that the existing verbosity in JSON could be reduced while keeping all necessary details intact for round-trip conversion.
From the mentor’s suggestion, I started with a technical design document:
Nearly a month was spent finalizing the YAML schema. This step formed the foundation of the project. Preparing the technical design document turned out to be very useful for all the later stages.
Method Implementations
Two methods were added: jsonToYaml and yamlToJson.
They are exposed in the DecoratorManager,with core logic in dcsconverter.js
API Usage:
The biggest challenge while implementing these was handling the type system differences between JSON (JavaScript) and YAML. The priority was round-trip safety, meaning JSON -> YAML -> JSON must return the same structure without change or loss.
CLI Extension
After the methods were implemented, the next step was extending the existing Concerto CLI.
The task involved adding a new CLI command to convert DCS files between JSON and YAML formats using the methods from @accordproject/concerto-core.
Usage:
- If –output is not provided, the converted content is printed to the console.
- Input file extension determines conversion direction:
.json → YAML
.yaml/.yml → JSON
Example usage:
Convert JSON to YAML and print to console:
Convert YAML to JSON and write to file:
Detailed documentation has also been updated so contributors and users can easily try the feature:
https://concerto.accordproject.org/docs/design/decoratorcommands
https://concerto.accordproject.org/docs/tools/ref-concerto-cli/#concerto-convert-dcs
In short, the development journey went through following stages:
- Schema Design: Finalizing the YAML format with a technical design doc.
- Conversion Methods: Implementing jsonToYaml and yamlToJson, ensuring round-trip safety.
- CLI Integration: Adding a new convert-dcs command and updating docs for developer use.
Related Issues & PRs
Issues Corresponding PRs YAML Schema Design https://github.com/accordproject/concerto/issues/1024
https://github.com/accordproject/concerto/issues/1030JSON to YAML https://github.com/accordproject/concerto/pull/1037 https://github.com/accordproject/concerto/issues/1032
YAML to JSON https://github.com/accordproject/concerto/pull/1044 CLI Extension https://github.com/accordproject/concerto-cli/pull/75 Documentation: https://github.com/accordproject/concerto-docs/pull/80 Extra improvement: https://github.com/accordproject/concerto/pull/1059 To manage milestones and tasks, a separate project was created on GitHub:
https://github.com/orgs/accordproject/projects/26Future Work
Although the main objectives of the project were achieved, there are still opportunities for improvement. This project treats YAML as syntactic sugar for DCS, reducing JSON’s verbosity and making definitions easier to read and write. However, Concerto’s validator currently relies on JSON ASTs, so YAML inputs must first be converted back to JSON.
Looking ahead, a possible extension would be to enhance Concerto’s validator so that it can directly parse and validate YAML inputs. Doing so would remove the intermediate conversion step and allow YAML not only to serve as a more concise format but also to potentially improve efficiency in both storage and processing.
Learnings & Experience
This summer with GSoC was a time of constant improvement for me. Day by day, I learned new ways of thinking and approaching problems. One of the biggest takeaways was understanding the importance of technical design documents and proper planning before starting to code. On the technical side, I became more comfortable with the programming language used, learned the value of solid testing practices, and figured out how to deal with edge cases more effectively.
I had the chance to meet amazing people whose expertise and support made my GSoC journey smooth and memorable. Special thanks to my mentors Sanket Shevkar and Daniel Selman. Regular calls with Sanket helped me plan the project, share progress, and resolve blockers quickly. The weekly technology working group calls also gave me clarity and direction in case of blockers.
I am also grateful to Matt, Jamie, Ertugrul, Diana and everyone in the Accord Project community for their feedback and suggestions. My heartfelt thanks to the everyone involved, directly and indirectly, throughout the project. Overall, this has been a memorable experience, and I look forward to continuing contributions to the Accord Project in the future.