Skip to main content


The Vocabulary module for Concerto optionally allows human-readable labels (Terms) to be associated with model elements. Terms are stored within a locale specific vocabulary YAML file associated with a Concerto namespace.

For example, a Concerto model that defines an enumeration with the values RED, GREEN, BLUE can be associated with an English vocabulary with the terms "Red", "Green", "Blue" and a French Vocabulary with terms "Rouge", "Vert", "Bleue".

The VocabularyManager class manages access to a set of Vocabulary files, and includes logic to retrieve the most appropriate term for a requested locale.

Example Model

namespace org.acme

enum Color {

asset Vehicle identified by vin {
o String vin
o Color color

asset Truck extends Vehicle {
o Double weight

Example Vocabulary Files

English - en

locale: en
namespace: org.acme
- Color: A color
- Vehicle: A road vehicle
- vin: Vehicle Identification Number
- model: Model of the vehicle
- Truck: A vehicle capable of carrying cargo
- weight: The weight of the truck in KG

British English - en-gb

locale: en-gb
namespace: org.acme
- Truck: A lorry (a vehicle capable of carrying cargo)
- Color: A colour
- Milkfloat

French - fr

locale: fr
namespace: org.acme
- Vehicle: Véhicule
- vin: Le numéro d'identification du véhicule (NIV)

Simplified Chinese zh-cn

locale: zh-cn
namespace: org.acme
- Color: 颜色
- RED: 红色
- GREEN: 绿色
- BLUE: 蓝色
- Vehicle: 车辆
- vin: 车辆识别代号
- color: 颜色

As you can see in the vocabularies above, a vocabulary can supplement or override terms from a base vocabulary, as is the case of the en-gb vocabulary which redefines and adds terms specific to British English over the generic English en vocabulary.

Creating a boostrap Vocabulary file

Use the following command to generate a bootstrap Vocabulary file in English Language. This file will give a boilerplate format for the Vocabulary YAML file. This file can be edited to any description that is required or any language that is required.

concerto compile --model test.cto --target vocabulary

Please refer to Vocabulary Code Generation for more information.

API Usage

Use the VocabularyManager classs to define new vocabularies, retrieve terms for a locale, or to validate a vocabulary using a ModelManager.

Adding a Vocabulary

Load the YAML file for the Vocabulary and add it to a VocabularyManager:

vocabularyManager = new VocabularyManager();
const enVocString = fs.readFileSync('./test/org.acme_en.voc', 'utf-8');

Retrieving a Term

Use the getTerm method on the VocabularyManager to retrieve a term for a declaration or property within a namespace:

const term = vocabularyManager.getTerm('org.acme', 'en-gb', 'Color');
// term.should.equal('A colour');
const term = vocabularyManager.getTerm('org.acme', 'en-gb', 'Vehicle', 'vin');
// term.should.equal('Vehicle Identification Number');

Resolve a Term using ModelManager Type Hierarchy

The resolveTerm method on the VocabularyManager may be used to lookup a term based on the type hierarchy defined by a ModelManager. In the example below, the property vin is not defined on the Truck declaration but rather on the Vehicle super-type.

modelManager = new ModelManager();
const model = fs.readFileSync('./test/org.acme.cto', 'utf-8');
const term = vocabularyManager.resolveTerm(modelManager, 'org.acme', 'en-gb', 'Truck', 'vin');
// term.should.equal('Vehicle Identification Number');

Validating a Vocabulary Manager

Use the validate method on the VocabularyManager to detect missing and redudant vocabulary terms — comparing the terms in the VocabularyManager with the declarations in a ModelManager. The return value from validate is an object containing information for the missing and additional terms.

Note that allowing vocabularies to evolve independently of their associated namespace provides definition and translation workflow flexibility.

const result = vocabularyManager.validate(modelManager);
// result.missingVocabularies.length.should.equal(1);
// result.missingVocabularies[0].should.equal('org.accordproject');
// result.additionalVocabularies.length.should.equal(1);
// result.additionalVocabularies[0].getNamespace().should.equal('com.example');
// result.vocabularies['org.acme/en'].additionalTerms.should.have.members(['Vehicle.model']);
// result.vocabularies['org.acme/en'].missingTerms.should.have.members(['Color.RED', 'Color.BLUE', 'Color.GREEN', 'Vehicle.color']);
// result.vocabularies['org.acme/en-gb'].additionalTerms.should.have.members(['Milkfloat']);
// result.vocabularies['org.acme/fr'].missingTerms.should.have.members(['Color', 'Vehicle.color', 'Truck']);
// result.vocabularies['org.acme/fr'].additionalTerms.should.have.members([]);
// result.vocabularies['org.acme/zh-cn'].missingTerms.should.have.members(['Truck']);
// result.vocabularies['org.acme/zh-cn'].additionalTerms.should.have.members([]);

Please refer to the JavaScript API for the concerto-vocabulary module for detailed API guidance.