Skip to content

feat(cicero-core): add support for Concerto vocabularies#882

Open
Anexus5919 wants to merge 1 commit intoaccordproject:mainfrom
Anexus5919:feat/concerto-vocabulary-support
Open

feat(cicero-core): add support for Concerto vocabularies#882
Anexus5919 wants to merge 1 commit intoaccordproject:mainfrom
Anexus5919:feat/concerto-vocabulary-support

Conversation

@Anexus5919
Copy link
Copy Markdown

@Anexus5919 Anexus5919 commented Mar 19, 2026

Closes #711

Summary

This PR adds locale-specific vocabulary support to Cicero templates using Concerto's existing VocabularyManager. Templates can now include .voc files (YAML) in a vocab/ directory to provide localized labels/terms for model concepts and properties.

  • Load/save .voc files from vocab/ directory and .cta archives with full round-trip fidelity (raw YAML preserved)
  • VocabularyManager on Template — exposed via getVocabularyManager() for direct access to Concerto's vocabulary API
  • getVocabulary(namespace, locale) convenience method with automatic fallback to defaultLocale
  • defaultLocale in Metadata — optional field under accordproject in package.json (e.g. "defaultLocale": "en")
  • cicero vocabulary CLI command — list available vocabularies or query terms for a specific --locale
  • Vocabularies included in template hash for signature integrity

Design decisions

Decision Rationale
.voc files live in vocab/ at template root Clean separation from model/, text/, logic/; aligns with Concerto codegen conventions
Raw .voc strings stored alongside parsed VocabularyManager Perfect round-trip without needing yaml as a dependency
defaultLocale is optional Backward compatible — templates without it still work identically
VocabularyManager lives on Template ModelManager in concerto-core has no vocabulary integration; follows same aggregation pattern as ScriptManager/LogicManager

Example

A template with vocabulary support looks like:

my-template/
├── package.json          ← { "accordproject": { "defaultLocale": "en", ... } }
├── model/
│   └── model.cto
├── text/
│   └── grammar.tem.md
└── vocab/
    ├── namespace_en.voc   ← English terms
    └── namespace_fr.voc   ← French terms

The .voc files follow Concerto's YAML vocabulary format:

locale: en
namespace: io.clause.example@1.0.0
declarations:
  - MyContract: My Contract
    properties:
      - amount: Amount
      - dueDate: Due Date

Files changed

cicero-core (source): metadata.js, template.js, templateloader.js, templatesaver.js, package.json
cicero-cli: commands.js, index.js
Tests: vocabulary.js (15 new tests), cli.js (5 new tests), template.js (hash updates)
Fixtures: latedeliveryandpenalty-vocab/ with English + French .voc files

Test plan

  • Load template with vocabularies from directory (en + fr)
  • Load template without vocabularies (backward compat)
  • Query declaration-level and property-level terms
  • defaultLocale read from package.json and preserved through archive
  • getVocabulary() falls back to defaultLocale when requested locale missing
  • Round-trip vocabularies through .cta archive (save → reload → verify terms)
  • Vocabularies included in getHash() computation
  • CLI vocabulary command lists files and queries terms
  • All 193 existing cicero-core tests pass
  • All 50 existing cicero-cli tests pass

…ct#711)

Add locale-specific vocabulary support to Cicero templates using
Concerto's VocabularyManager. Templates can now include .voc files
in a vocab/ directory to provide localized labels for model concepts
and properties.

Changes:
- Load/save .voc files from vocab/ directory and archives
- Add VocabularyManager to Template with getVocabulary() fallback
- Add defaultLocale to Metadata (package.json accordproject section)
- Add 'cicero vocabulary' CLI command with --locale option
- Add test fixtures with English and French vocabularies
- 20 new tests covering loading, round-trip, fallback, and CLI

Closes accordproject#711

Signed-off-by: Adarsh Singh <anexus5919@gmail.com>
@Anexus5919 Anexus5919 force-pushed the feat/concerto-vocabulary-support branch from d7c53a9 to 1d81787 Compare March 19, 2026 19:33
@Anexus5919
Copy link
Copy Markdown
Author

Hi @mttrbrts @dselman @ekarademir , I've opened a PR that implements vocabulary support for Cicero templates: #882

Here's what the PR covers:

  1. Core plumbing (cicero-core):
  • .voc files are stored under vocab/ at the template root, following the Concerto vocabulary YAML format
  • TemplateLoader detects and loads vocab/*.voc files from both directories and .cta archives
  • TemplateSaver writes .voc files back into archives with full round-trip fidelity (raw YAML preserved, no reformatting)
  • VocabularyManager from @accordproject/concerto-vocabulary is exposed on Template via getVocabularyManager()
  • A convenience method getVocabulary(namespace, locale) provides automatic fallback to defaultLocale
  1. Metadata:
  • Optional defaultLocale field under accordproject in package.json (e.g. "defaultLocale": "en") for backwards-compatible locale fallback
  1. CLI:
  • New cicero vocabulary command with --locale option to list available vocabularies or query terms for a specific locale
  1. Tests:
  • 20 new tests covering loading, round-trip archiving, defaultLocale, locale fallback, hash integrity, and CLI
  • All 193 existing cicero-core tests and 50 cicero-cli tests pass
  1. What's not in scope for this PR:
  • Locale-specific parsers / locale-specific template grammar text as discussed in the issue, this is a separate, larger feature that can build on top of this foundation

Happy to adjust the approach based on feedback. Would love to hear if vocab/ works as the canonical location or if you'd prefer something different.

@Anexus5919
Copy link
Copy Markdown
Author

@ekarademir @dselman @DianaLease I have raised this PR 4 days ago... Can you please review it when you get a chance!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support for Concerto Vocabularies

1 participant