Parsers

Messagevisor uses parsers to read and write authoring definitions. The parser layer lets the project model stay stable even when the source file format changes.

The built-in implementations and public parser types are published in @messagevisor/parsers. The core package consumes this Messagevisor-owned boundary, so custom authoring formats do not depend on another product's release lifecycle.

Built-in parser names#

Messagevisor accepts yml and json as built-in parser names, with yml as the default.

module.exports = {
  parser: "json",
};

Useful starter references in this repo:

• project-yml
• project-json
• project-raw

Custom parser objects#

Projects can also provide a custom parser object instead of a parser name, as long as it matches the parser contract expected by the core package.

TypeScript integrations can import the contract directly:

import type { CustomParser } from "@messagevisor/parsers";

This is useful when:

• your repo already uses a different file format
• you want to integrate with an internal serialization layer
• you need custom read/write behavior

For example, a project can use TOML through any library that provides parse and stringify functions:

const TOML = require("@iarna/toml");
module.exports = {
  parser: {
    extension: "toml",
    parse(content) {
      return TOML.parse(content);
    },
    stringify(value) {
      return TOML.stringify(value);
    },
  },
};

Install the parser library in the Messagevisor project itself. TOML is an example of the custom parser contract, not a built-in parser name.

What parsers affect#

Parsers affect:

• how project files are read
• how created or updated definitions are written
• how CLI workflows interact with authoring files

They do not change the underlying Messagevisor data model.

The YAML parser preserves comments attached to keys and values when the editorial API rewrites an existing document. It also retains unchanged scalar styles, flow collections, anchors, aliases, tags, and document directives where the existing YAML node can be reused. The supplied entity remains authoritative: fields removed from the entity are removed from the file rather than being retained merely because they had comments or YAML metadata.

Related#

• Configuration
• Projects
• Datasource