Guest post: Dan Selman, Maintainer Hyperledger Composer, Accord Project Cicero, CTO Clause Inc.
Is the business logic in your blockchain chaincode hard to find because it is buried in code that is doing JSON serialization and data validation? Are you developing REST APIs by hand for your domain model? The good news is that there is now a better way!
In this article for developers and blockchain solution architects, I introduce the Concerto npm module and show you how you can use it from Hyperledger Fabric v1.3 Node.js chaincode.
Concerto is a lightweight, 100% JavaScript schema language and runtime. It works in both a Node.js process or in your browser. The browserified version of Concerto is ±280 KB and the maintainers are working to make it even smaller.
Concerto has recently been modularized and moved out of Hyperledger Composer into the composer-concerto npm module, so you can use it in your Node.js applications, Fabric Node.js chaincode or even in your web browser!
Things you can do using Concerto:
All software applications have a data or domain model.
Models are required to create generic tools because you need to reason about the structure of user-defined domain models. As soon as you want to implement something like an Object-Relational-Mapper or REST API browser or web-form generator, you need a data model.
The data model for your application can either be implicit (duck typing…) or explicit. If it is explicit, it can be expressed using a wide range of technology including XML Schema, JSON Schema, protobufs, NoSQL design documents, Loopback schema, Java classes, Go structs, RDBMS tables, ad-hoc JSON or YAML documents…the list is almost endless.
These different model representations make different trade-offs with respect to:
If developers define models as part of application development, they tend to favour creating Java classes, Go structs, Typescript or similar, because they want to express the model in a language they are familiar with and that integrates closely with the type-system used for computation. The major downside with this approach is that it is almost impossible to then share and reuse these models outside of a single application. It also doesn’t integrate well with modern application development, where we may use different technology across the web, mobile, middle and backend tiers of an application. Out of sync models (or model mapping) is a huge source of anguish and bugs.
When industry-standard bodies define models, they tend to favour representations that are more cross-platform and less tied to computation, such as publishing XML Schemas. Developers tend not to like using these models because the mapping from things like XML Schema to Java classes or Go structs for use at runtime is lossy/messy/complex.
Concerto solves many of these problems by providing an Object-Oriented schema language that allows models to be moved outside of applications while mapping quite naturally to most common programming languages. We like to think of it as a “goldilocks” approach to modeling, “just enough” to cover most business use cases, with a natural mapping to most common programming languages, and with a JSON serialization.
I’ve published a detailed code sample for Node.js chaincode and a HLF v1.3 client so you can start to experiment with using Concerto in HLF v1.3 Node.js chaincode: https://github.com/clauseHQ/fabric-samples/blob/master/concerto/README.md
The sample shows you how to deploy Concerto models to the blockchain and then use the models to validate instances and to serialize them to JSON for long-lived persistence.
Editing a Concerto model using the Concerto Form Generator
The sample defines a simple Concerto domain model for an employee, which is deployed to the blockchain.
Here is the definition of the Concerto model:
namespace io.clause
enum Gender {
o MALE
o FEMALE
o OTHER
}
asset Employee identified by email {
o String email
o String firstName
o String lastName
o String middleName optional
o Gender gender
o DateTime startDate
o DateTime terminationDate optional
}The sample then uses the model to validate instances and to serialize them to JSON for long-lived persistence on the blockchain.
A React form, dynamically generated from the Concerto model
First the client creates a valid instance of an employee, and the chaincode validates it and stores it on the blockchain:
{
$class : 'io.clause.Employee',
email : 'bob@clause.io',
firstName: 'Bob',
lastName: 'Concerto',
gender: 'MALE',
startDate : Date.now()
}When the client attempts to create an instance that is missing the required firstName field:
{
$class : 'io.clause.Employee',
email : 'bob@clause.io',
lastName: 'Concerto',
gender: 'MALE',
startDate : Date.now()
}The instance fails validation, and the chaincode refuses to create the instance:
ValidationException: Instance io.clause.Employee#bob@clause.io missing required field firstName
We’ve just scratched the surface of what you can do with Concerto. The metamodel is flexible enough to capture almost any business domain model.
Here are some ideas for what to do next:
If you are using Concerto already or would like to get involved with improving it further, please don’t hesitate to get in touch. In the true spirit of Open Source we welcome all contributions.