Skip to content

quick-start.md

Latest commit

 

History

History
149 lines (104 loc) · 4.13 KB

quick-start.md

File metadata and controls

149 lines (104 loc) · 4.13 KB
Raw
sidebar_position 3

Quick Start

What you'll need

  • Node.js version 22 or above:
    • When installing Node.js, you are recommended to check all checkboxes related to dependencies.

Install the Concerto Command Line Interface (CLI)

Open a shell and run the command:

npm install -g @accordproject/concerto-cli

You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.

The command also installs all necessary dependencies you need to run the Concerto CLI.

Test your install

Run the CLI help command:

concerto --help

If Concerto has been successfully installed you will see output like this:

concerto <cmd> [args]

Commands:
  concerto validate           validate JSON against model files
  concerto compile            generate code for a target platform
  concerto get                save local copies of external model dependencies
  concerto parse              parse a cto string to a JSON syntax tree
  concerto print              print a JSON syntax tree to a cto string
  concerto version <release>  modify the version of one or more model files
  concerto compare            compare two Concerto model files
  concerto infer              generate a concerto model from a source schema
  concerto generate <mode>    generate a sample JSON object for a concept
  concerto decorate           apply the decorators and vocabs to the target models from given list of dcs files and vocab files
  concerto extract-decorators extract the decorator command sets and vocabularies from a list of model files
  concerto convert-dcs        convert decorator command set between JSON and YAML formats
  concerto lint               lint concerto model file

Options:
      --version  Show version number                                   [boolean]
  -v, --verbose                                                 [default: false]
      --help     Show help                                             [boolean]

Create your first Concerto model

Note, if you use the VSCode IDE you can install the Accord Project (Concerto) extension to benefit from syntax highlighting, compilation, and more.

Open a code or text editor and create a plain text file, with the contents:

namespace test@1.0.0

concept Person identified by email {
  o String email
  o DateTime dob
}

Save the file as test.cto.

Generate a sample instance of the model

Run the Concerto CLI generate sample command to generate an instance of the test@1.0.0.Person concept:

concerto generate sample --model test.cto --concept test@1.0.0.Person

The output should be similar to:

{
  "$class": "test@1.0.0.Person",
  "email": "resource1",
  "dob": "2022-12-13T10:46:46.109Z"
}

Save this output as person.json.

Validate data using your data model

Modify person.json to remove the dob property and save the file:

{
  "$class": "test@1.0.0.Person",
  "email": "resource1",
}

Run the CLI command:

concerto validate --input person.json --model test.cto

The output should be:

10:50:57 - INFO: Input is invalid
10:50:57 - ERROR: The instance "test@1.0.0.Person#resource1" is missing the required field "dob".

Indicating that the person.json instance of test@1.0.0.Person is invalid with respect to the model.

Now modify test.cto to declare that the dob property is optional:

namespace test@1.0.0

concept Person identified by email {
  o String email
  o DateTime dob optional
}

Rerun the validate command:

concerto validate --input person.json --model test.cto

The output should now be:

10:53:43 - INFO: Input is valid
{"$class":"test@1.0.0.Person","email":"resource1"}

Congratulations!

Well done, you've created your first Concerto model and used the CLI to validate data against the model! This is just the start...

You may want to continue to read about static code generation, or using the JavaScript runtime API to introspect models at runtime.