Concertino - A Lightweight Concerto Format Converter
Concertino is a lightweight variant of the Concerto metamodel format, optimized for client applications that need to programmatically introspect declarations without taking a dependency on the full Concerto SDK.
Benefits of the Concertino Format
The Concertino format provides several advantages:
-
Flatter structure: By denormalizing the inheritance hierarchy, consumers don't need to traverse the hierarchy to understand a definition.
-
More explicit metadata: Additional metadata makes it clearer how properties should be interpreted.
-
Ready for consumption: The transformation prepares the data for easier consumption by tools and renderers, without requiring additional processing.
Features
- Fully Resolved Type References: No ambiguous shortnames
- Flattened Declarations: Declarations are not nested within models, enabling easier type lookup
- Denormalized Properties: Inherited properties are fully denormalized with references to their source types
- Extended Inheritance Chain: Concepts list their full inheritance chain, not just immediate parent
- Scalar Type Denormalization: For convenience in client applications
- Strict Mode By Default: Namespaces are always versioned.
- Support for Partial Models Allowing client applications to filter models to tailor payloads for their use cases.
- Lossless Conversion Concertino is designed for 100% lossless roundtrip conversion with Concerto models.
Concerto (Metamodel) → Concertino → Concerto (Metamodel)
Installation
npm install @accordproject/concertino
Usage
Using the ConcertinoConverter Class
const { ModelManager } = require('@accordproject/concerto-core');
const { ConcertinoConverter } = require('@accordproject/concertino');
// Prepare the Concerto model
const mm = new ModelManager();
mm.addModel(MODEL_FILE_CONTENTS);
const model = mm.getModelFile(MODEL_FILE_NAMESPACE).getAst();
// Initialize Concertino
const converter = new ConcertinoConverter();
const models = { models: [model] };
// Convert from Concerto metamodel to Concertino
const concertino = converter.fromConcertoMetamodel(models);
console.log('#### Concertino:')
console.log(JSON.stringify(concertino, null, 2));
console.log();
// Convert from Concertino back to Concerto metamodel
const metamodel = converter.toConcertoMetamodel(concertino);
console.log('#### Concerto AST (Full Metamodel Instance):')
console.log(JSON.stringify(metamodel, null, 2));
Checking a document against the Concertino schema
converter.isValid(concertino) checks a document against concertino.schema.json, and converter.getValidationErrors() returns the errors of the last check (ajv error objects), or null.
The schema checks are compiled at build time, so the package needs neither ajv nor new Function at run time (a strict Content-Security-Policy is fine). To check documents without the converter, import the ./schema subpath:
const { isValid, checkSchema } = require('@accordproject/concertino/schema');
isValid(concertino); // true or false
checkSchema(concertino); // null, or the errors
convertToConcertino and convertToMetamodel imported on their own leave the schema checks out of a bundle.
Model Size
Despite the denormalization of metadata, the JSON serialization of Concertino models are often smaller in size than their Concerto AST equivalents due to a flatter, dictionary-like design and the removal of type-discriminators (i.e. $class properties).
It is expected that models that make heavy use of inheritance would be larger than their equivalent Concerto AST.
Note that when converting models, the namespaces in the source Concerto model should be fully resolved (including for local type references).
Example Concertino JSON Format
Below is an example of how a simple Concerto model is represented in the Concertino format:
{
"declarations": {
"[email protected]": {
"properties": {
"city": {
"name": "city",
"type": "String",
"vocabulary": {
"label": "City/Town",
},
},
"country": {
"name": "country",
"type": "String",
},
"street": {
"name": "street",
"type": "String",
"vocabulary": {
"label": "Street Address",
},
},
"zipCode": {
"name": "zipCode",
"type": "String",
},
},
"type": "ConceptDeclaration",
"vocabulary": {
"label": "Physical Address",
},
},
"[email protected]": {
"regex": "/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$/",
"type": "StringScalar",
},
"[email protected]": {
"properties": {
"address": {
"isOptional": true,
"name": "address",
"type": "[email protected]",
"vocabulary": {
"label": "Mailing Address",
},
},
"age": {
"isOptional": true,
"name": "age",
"range": [
0,
null,
],
"type": "Integer",
},
"email": {
"isOptional": true,
"metadata": {
"sensitive": null,
},
"name": "email",
"regex": "/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$/",
"scalarType": "[email protected]",
"type": "String",
},
"firstName": {
"name": "firstName",
"type": "String",
"vocabulary": {
"label": "Given Name",
},
},
"lastName": {
"name": "lastName",
"type": "String",
"vocabulary": {
"label": "Family Name",
},
},
},
"type": "ConceptDeclaration",
"vocabulary": {
"additionalTerms": {
"plural": "People",
},
"label": "Individual",
},
},
},
"metadata": {
"concertinoVersion": "4.0.0-alpha.2",
"models": {
"[email protected]": {
"concertoVersion": "1.0.0",
"sourceUri": "org/example/models.cto",
"decorators": [
{
"name": "license",
"arguments": ["Apache-2.0"]
}
]
}
}
}
}
The equivalent Concerto CTO file would be:
@license("Apache-2.0")
namespace [email protected]
scalar Email extends String regex=/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/
@Term("Individual")
@Term_plural("People")
concept Person {
@Term("Given Name")
o String firstName
@Term("Family Name")
o String lastName
o Integer age optional range=[0, ]
@sensitive
o Email email optional
@Term("Mailing Address")
o Address address optional
}
@Term("Physical Address")
concept Address {
@Term("Street Address")
o String street
@Term("City/Town")
o String city
o String zipCode
o String country
}