Skip to content

neumaRk — Formal Specification

1. Purpose of this document

This document defines the formal specification of the neumaRk language.

It normatively establishes:

  • which constructs are valid;
  • how they must be interpreted;
  • which rules must be followed by parsers, validators, and rendering tools.

Everything described in this document is to be considered binding.

2. Specification layers

The neumaRk specification is organized into multiple layers, each with a specific responsibility:

  1. Syntactic layer

  2. defines the textual grammar;

  3. establishes which character sequences are valid.

  4. Structural layer

  5. defines the logical structure of the document;

  6. establishes the relationships between its sections.

  7. Semantic layer

  8. defines the musical meaning of the constructs;

  9. clarifies ambiguities and edge cases.

  10. Validation layer

  11. defines validity conditions;

  12. establishes errors and invalid states.

2.1 Persistent musical context

The parsing of a neumaRk document takes place within a persistent musical context.

The musical context retains the most recent relevant explicit information (pitches, durations, metric state) and persists throughout the entire document, across:

  • lines;
  • measures;
  • consecutive datapacks.

The musical context is not automatically reset at the beginning of a new datapack.

A datapack represents a structural and vertical synchronization unit, but does not constitute a semantic boundary for musical deduction.

In the absence of explicit values, deduction rules always refer to the current state of the musical context.

3. Normative terminology

In this document, the following terms are used with normative meaning:

  • must / must not: mandatory requirement;
  • may / may not: optional behavior;
  • is invalid: the document must be rejected;
  • is interpreted as: deterministic behavior.

4. Contextual use of symbols

Some textual symbols in neumaRk have context-dependent semantics, determined by the type of musical line in which they appear.

In particular:

  • the symbol . (dot);
  • the symbol ! (exclamation mark);

assume different meanings depending on whether they appear in:

  • note lines (N));
  • chord lines (C)).

They may also assume different meanings within the same type of line, depending on their position and adjacency.

The line context and the symbol’s position relative to other elements are always sufficient to resolve its semantics deterministically.

There is no valid case in which a symbol can be ambiguous within the same line context.

5. General structure of a neumaRk document

A neumaRk document is a UTF-8 text file that may contain, in the following order:

  1. Header (metadata);
  2. Musical content and formatting content.

The order of sections is significant and must be respected.

Structural delimitation

In neumaRk, a blank line has structural meaning.

Blank lines delimit logical blocks of the document, in particular:

  • the end of the header;
  • the separation between consecutive musical datapacks.

A structural block (header or datapack) always consists of one or more consecutive non-empty lines.

This specification refers to the following documents:

  • neumaRk_overview.md
  • neumaRk_formats.md
  • neumaRk_specification.md
  • neumaRk_header.md
  • neumaRk_datapack.md
  • neumaRk_markers.md
  • neumaRk_chords.md
  • neumaRk_notes_and_durations.md
  • neumaRk_flow_and_repeats.md

Each document normatively elaborates a specific aspect of the language.

7. Compatibility and versioning

Each neumaRk document must explicitly declare the version of the language it uses.

The first line of the document must contain the sequence nrk: followed by the reference version in major.minor form.

Example:

nrk:0.5

Compatibility rules between versions are defined in neumaRk_validation.md.

8. Extensions

The neumaRk language may be extended only within the limits explicitly allowed by the specification.

Undefined or unrecognized constructs render the document invalid, unless explicitly stated otherwise.