diff --git a/src/include/mx/api/ApiCommon.h b/src/include/mx/api/ApiCommon.h
index 7c423a65..47186cee 100644
--- a/src/include/mx/api/ApiCommon.h
+++ b/src/include/mx/api/ApiCommon.h
@@ -24,6 +24,14 @@ inline bool areSame(Double left, Double right)
 constexpr int DEFAULT_TICKS_PER_QUARTER = 3 * 4 * 5 * 7;
 constexpr int TICK_TIME_INFINITY = std::numeric_limits<int>::max();
 
+// Named sentinels for legacy fields that predate std::optional, where -1 (or -1.0) means
+// "unspecified" or "absent". Do not use these for new fields; new absent-able fields use
+// std::optional instead (see "mx::api conventions" in AGENTS.md and issue #249).
+constexpr int INDEX_UNSPECIFIED = -1;        // staff/part indices and numbers, e.g. KeyData::staffIndex
+constexpr int NUMBER_LEVEL_UNSPECIFIED = -1; // MusicXML 'number' attributes, e.g. SpannerStart::numberLevel
+constexpr int VALUE_UNSPECIFIED = -1;        // other absent-able ints, e.g. DirectionData::voice
+constexpr Double DOUBLE_UNSPECIFIED = -1.0;  // absent-able doubles, e.g. StaffData::staffSize
+
 // Intentional ternary: absent-able bools use Bool::unspecified, not std::optional<bool>.
 // See "mx::api conventions" in AGENTS.md.
 enum class Bool
diff --git a/src/include/mx/api/CurveData.h b/src/include/mx/api/CurveData.h
index 83ea18a6..444148e5 100644
--- a/src/include/mx/api/CurveData.h
+++ b/src/include/mx/api/CurveData.h
@@ -100,8 +100,9 @@ struct CurveStart
     ColorData colorData;
 
     CurveStart(CurveType inCurveType)
-        : curveType{inCurveType}, numberLevel{-1}, curvePoints{}, curveOrientation{CurveOrientation::unspecified},
-          placement{Placement::unspecified}, lineData{}, isColorSpecified{false}, colorData{}
+        : curveType{inCurveType}, numberLevel{NUMBER_LEVEL_UNSPECIFIED}, curvePoints{},
+          curveOrientation{CurveOrientation::unspecified}, placement{Placement::unspecified}, lineData{},
+          isColorSpecified{false}, colorData{}
     {
     }
 };
@@ -119,8 +120,8 @@ struct CurveContinue
     double bezierOffset2;
 
     CurveContinue(CurveType inCurveType)
-        : curveType{inCurveType}, numberLevel{-1}, curvePoints{}, isBezierX2Specified{false}, bezierX2{0.0},
-          isBezierY2Specified{false}, bezierY2{0.0}, isBezierOffset2Specified{false}, bezierOffset2{0.0}
+        : curveType{inCurveType}, numberLevel{NUMBER_LEVEL_UNSPECIFIED}, curvePoints{}, isBezierX2Specified{false},
+          bezierX2{0.0}, isBezierY2Specified{false}, bezierY2{0.0}, isBezierOffset2Specified{false}, bezierOffset2{0.0}
     {
     }
 };
@@ -131,7 +132,7 @@ struct CurveStop
     int numberLevel;
     CurvePoints curvePoints;
 
-    CurveStop(CurveType inCurveType) : curveType{inCurveType}, numberLevel{-1}, curvePoints{}
+    CurveStop(CurveType inCurveType) : curveType{inCurveType}, numberLevel{NUMBER_LEVEL_UNSPECIFIED}, curvePoints{}
     {
     }
 };
diff --git a/src/include/mx/api/DefaultsData.h b/src/include/mx/api/DefaultsData.h
index ba6545e0..6742977b 100644
--- a/src/include/mx/api/DefaultsData.h
+++ b/src/include/mx/api/DefaultsData.h
@@ -140,8 +140,8 @@ class DefaultsData
     MeasureNumbering measureNumbering;
 
     DefaultsData()
-        : scalingMillimeters{-1.0}, scalingTenths{-1.0}, pageLayout{}, systemLayout{}, appearance{}, musicFont{},
-          wordFont{}, lyricFonts{}, measureNumbering{MeasureNumbering::unspecified}
+        : scalingMillimeters{DOUBLE_UNSPECIFIED}, scalingTenths{DOUBLE_UNSPECIFIED}, pageLayout{}, systemLayout{},
+          appearance{}, musicFont{}, wordFont{}, lyricFonts{}, measureNumbering{MeasureNumbering::unspecified}
     {
     }
 };
diff --git a/src/include/mx/api/DirectionData.h b/src/include/mx/api/DirectionData.h
index 167f3c06..78ef9f4c 100644
--- a/src/include/mx/api/DirectionData.h
+++ b/src/include/mx/api/DirectionData.h
@@ -84,7 +84,7 @@ struct DirectionData
     // direction includes a default-x attribute, the offset value will be ignored when determining
     // the appearance of that element.
 
-    // voice value of -1 means unspecified
+    // a voice value of VALUE_UNSPECIFIED means unspecified
     int voice;
 
     // Direction elements are placed inside the StaffData object in mx api.  This would mean that
@@ -128,7 +128,7 @@ struct DirectionData
     std::vector<DirectionComponent> orderedComponents;
 
     DirectionData()
-        : tickTimePosition{0}, placement{Placement::unspecified}, voice{-1}, isStaffValueSpecified{true},
+        : tickTimePosition{0}, placement{Placement::unspecified}, voice{VALUE_UNSPECIFIED}, isStaffValueSpecified{true},
           isSoundDataSpecified{false}, soundData{}, marks{}, wedgeStarts{}, wedgeStops{}, ottavaStarts{}, ottavaStops{},
           bracketStarts{}, bracketStops{}, dashesStarts{}, dashesStops{}, pedalStarts{}, pedalStops{}, words{},
           chords{}, segnos{}
diff --git a/src/include/mx/api/EncodingData.h b/src/include/mx/api/EncodingData.h
index 55ce2213..662b5d70 100644
--- a/src/include/mx/api/EncodingData.h
+++ b/src/include/mx/api/EncodingData.h
@@ -44,7 +44,7 @@ class EncodingDate
     int month;
     int day;
 
-    EncodingDate() : year(-1), month(-1), day(-1)
+    EncodingDate() : year(VALUE_UNSPECIFIED), month(VALUE_UNSPECIFIED), day(VALUE_UNSPECIFIED)
     {
     }
 
diff --git a/src/include/mx/api/FiguredBassData.h b/src/include/mx/api/FiguredBassData.h
index 72c311dc..26263fbd 100644
--- a/src/include/mx/api/FiguredBassData.h
+++ b/src/include/mx/api/FiguredBassData.h
@@ -48,7 +48,7 @@ class FiguredBassData
     // The optional <duration>, in ticks. A value less than 0 means 'unspecified' (no duration child).
     int durationTimeTicks;
 
-    FiguredBassData() : figures{}, parentheses{Bool::unspecified}, durationTimeTicks{-1}
+    FiguredBassData() : figures{}, parentheses{Bool::unspecified}, durationTimeTicks{VALUE_UNSPECIFIED}
     {
     }
 };
diff --git a/src/include/mx/api/FontData.h b/src/include/mx/api/FontData.h
index ef29e621..77f30b5e 100644
--- a/src/include/mx/api/FontData.h
+++ b/src/include/mx/api/FontData.h
@@ -69,7 +69,7 @@ struct FontData
     int lineThrough;
 
     FontData()
-        : sizeType{FontSizeType::unspecified}, sizePoint{-1.0}, sizeCss{CssSize::unspecified},
+        : sizeType{FontSizeType::unspecified}, sizePoint{DOUBLE_UNSPECIFIED}, sizeCss{CssSize::unspecified},
           style{FontStyle::unspecified}, weight{FontWeight::unspecified}, fontFamily{}, underline{0}, overline{0},
           lineThrough{0}
     {
diff --git a/src/include/mx/api/KeyData.h b/src/include/mx/api/KeyData.h
index d7f585f6..f0c745ec 100644
--- a/src/include/mx/api/KeyData.h
+++ b/src/include/mx/api/KeyData.h
@@ -3,6 +3,7 @@
 // Distributed under the MIT License
 
 #pragma once
+#include "mx/api/ApiCommon.h"
 #include "mx/api/KeyComponent.h"
 
 namespace mx
@@ -66,7 +67,7 @@ struct KeyData
     // Supports changing the key somewhere other than at the start of a measure.
     int tickTimePosition;
 
-    // this value is optional. -1 means unspecified. when value is
+    // this value is optional. INDEX_UNSPECIFIED means unspecified. when value is
     // unspecified it means that the key signature applies to all staves
     // within the part
     int staffIndex;
@@ -77,7 +78,9 @@ struct KeyData
     // alterations. When custom is non-empty, then fifths and mode are ignored.
     std::vector<KeyComponent> nonTraditional;
 
-    KeyData() : fifths{0}, cancel{0}, mode{KeyMode::unspecified}, tickTimePosition{0}, staffIndex{-1}, nonTraditional{}
+    KeyData()
+        : fifths{0}, cancel{0}, mode{KeyMode::unspecified}, tickTimePosition{0}, staffIndex{INDEX_UNSPECIFIED},
+          nonTraditional{}
     {
     }
 };
diff --git a/src/include/mx/api/MeasureData.h b/src/include/mx/api/MeasureData.h
index 595c1e97..36fb7b04 100644
--- a/src/include/mx/api/MeasureData.h
+++ b/src/include/mx/api/MeasureData.h
@@ -4,6 +4,7 @@
 
 #pragma once
 
+#include "mx/api/ApiCommon.h"
 #include "mx/api/BarlineData.h"
 #include "mx/api/ClefData.h"
 #include "mx/api/DirectionData.h"
@@ -91,8 +92,9 @@ class MeasureData
     std::optional<PartSymbolData> partSymbol;
 
     MeasureData()
-        : staves{}, timeSignature{}, number{}, measureNumbering{MeasureNumbering::unspecified}, multiMeasureRest{-1},
-          implicit{Bool::unspecified}, nonControlling{Bool::unspecified}, width{-1.0}
+        : staves{}, timeSignature{}, number{}, measureNumbering{MeasureNumbering::unspecified},
+          multiMeasureRest{VALUE_UNSPECIFIED}, implicit{Bool::unspecified}, nonControlling{Bool::unspecified},
+          width{DOUBLE_UNSPECIFIED}
     {
     }
 };
diff --git a/src/include/mx/api/PageImageData.h b/src/include/mx/api/PageImageData.h
index 786d3d2d..dcad1523 100644
--- a/src/include/mx/api/PageImageData.h
+++ b/src/include/mx/api/PageImageData.h
@@ -44,7 +44,8 @@ class PageImageData
     /// modeled here.)
     PositionData positionData;
 
-    PageImageData() : source{}, type{}, height{-1.0}, width{-1.0}, pageNumber{0}, positionData{}
+    PageImageData()
+        : source{}, type{}, height{DOUBLE_UNSPECIFIED}, width{DOUBLE_UNSPECIFIED}, pageNumber{0}, positionData{}
     {
     }
 };
diff --git a/src/include/mx/api/PartData.h b/src/include/mx/api/PartData.h
index b2a7c44e..2fcd731f 100644
--- a/src/include/mx/api/PartData.h
+++ b/src/include/mx/api/PartData.h
@@ -31,16 +31,16 @@ struct MidiData
     std::string device;
     std::string name;
 
-    // -1 indicates absence of value
+    // VALUE_UNSPECIFIED indicates absence of value
     int bank;
 
-    // -1 indicates absence of value
+    // VALUE_UNSPECIFIED indicates absence of value
     int channel;
 
-    // -1 indicates absence of value
+    // VALUE_UNSPECIFIED indicates absence of value
     int program;
 
-    // -1 indicates absence of value
+    // VALUE_UNSPECIFIED indicates absence of value
     int unpitched;
 
     // percent, valid range 0.0 to 100.0
@@ -56,9 +56,9 @@ struct MidiData
     bool isElevationSpecified;
 
     MidiData()
-        : virtualLibrary{}, virtualName{}, device{}, name{}, bank{-1}, channel{-1}, program{-1}, unpitched{-1},
-          volume{0.0}, isVolumeSpecified{false}, pan{0.0}, isPanSpecified{false}, elevation{0.0},
-          isElevationSpecified{false}
+        : virtualLibrary{}, virtualName{}, device{}, name{}, bank{VALUE_UNSPECIFIED}, channel{VALUE_UNSPECIFIED},
+          program{VALUE_UNSPECIFIED}, unpitched{VALUE_UNSPECIFIED}, volume{0.0}, isVolumeSpecified{false}, pan{0.0},
+          isPanSpecified{false}, elevation{0.0}, isElevationSpecified{false}
     {
     }
 };
diff --git a/src/include/mx/api/PartGroupData.h b/src/include/mx/api/PartGroupData.h
index 8743865b..b9ea4684 100644
--- a/src/include/mx/api/PartGroupData.h
+++ b/src/include/mx/api/PartGroupData.h
@@ -4,6 +4,8 @@
 
 #pragma once
 
+#include "mx/api/ApiCommon.h"
+
 #include <string>
 #include <vector>
 
@@ -63,12 +65,13 @@ class PartGroupData
 
     // The number attribute is used to distinguish overlapping
     // and nested part-groups, not the sequence of groups.
-    // -1 indicates the absence of a number attribute
+    // NUMBER_LEVEL_UNSPECIFIED indicates the absence of a number attribute
     int number;
 
     PartGroupData()
-        : firstPartIndex{-1}, lastPartIndex{-1}, name{}, bracketType{BracketType::unspecified},
-          groupBarline{GroupBarline::unspecified}, number{-1}
+        : firstPartIndex{INDEX_UNSPECIFIED}, lastPartIndex{INDEX_UNSPECIFIED}, name{},
+          bracketType{BracketType::unspecified}, groupBarline{GroupBarline::unspecified},
+          number{NUMBER_LEVEL_UNSPECIFIED}
     {
     }
 };
diff --git a/src/include/mx/api/PartSymbolData.h b/src/include/mx/api/PartSymbolData.h
index 80a67696..6e1b0d9c 100644
--- a/src/include/mx/api/PartSymbolData.h
+++ b/src/include/mx/api/PartSymbolData.h
@@ -18,11 +18,11 @@ class PartSymbolData
     BracketType value;
 
     // 1-based staff numbers indicating which staves the symbol spans.
-    // -1 means unspecified (the symbol covers all staves in the part).
+    // INDEX_UNSPECIFIED means unspecified (the symbol covers all staves in the part).
     int topStaff;
     int bottomStaff;
 
-    PartSymbolData() : value{BracketType::unspecified}, topStaff{-1}, bottomStaff{-1}
+    PartSymbolData() : value{BracketType::unspecified}, topStaff{INDEX_UNSPECIFIED}, bottomStaff{INDEX_UNSPECIFIED}
     {
     }
 };
diff --git a/src/include/mx/api/SoundData.h b/src/include/mx/api/SoundData.h
index acfb8304..8f9edfa5 100644
--- a/src/include/mx/api/SoundData.h
+++ b/src/include/mx/api/SoundData.h
@@ -53,8 +53,8 @@ struct SoundData
     std::string fine;
 
     SoundData()
-        : tempo{-1.0}, dynamics{-1.0}, dacapo{Bool::unspecified}, forwardRepeat{Bool::unspecified},
-          pizzicato{Bool::unspecified}, segno{}, dalsegno{}, coda{}, tocoda{}, fine{}
+        : tempo{DOUBLE_UNSPECIFIED}, dynamics{DOUBLE_UNSPECIFIED}, dacapo{Bool::unspecified},
+          forwardRepeat{Bool::unspecified}, pizzicato{Bool::unspecified}, segno{}, dalsegno{}, coda{}, tocoda{}, fine{}
     {
     }
 
diff --git a/src/include/mx/api/SpannerData.h b/src/include/mx/api/SpannerData.h
index 1359f80d..fcb2757a 100644
--- a/src/include/mx/api/SpannerData.h
+++ b/src/include/mx/api/SpannerData.h
@@ -4,6 +4,7 @@
 
 #pragma once
 
+#include "mx/api/ApiCommon.h"
 #include "mx/api/LineData.h"
 #include "mx/api/PositionData.h"
 #include "mx/api/PrintData.h"
@@ -23,7 +24,7 @@ struct SpannerStart
     PrintData printData;
     LineData lineData;
 
-    SpannerStart() : numberLevel{-1}, tickTimePosition{0}, positionData{}, printData{}, lineData{}
+    SpannerStart() : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, tickTimePosition{0}, positionData{}, printData{}, lineData{}
     {
     }
 };
@@ -35,7 +36,7 @@ struct SpannerStop
     PositionData positionData;
     LineData lineData;
 
-    SpannerStop() : numberLevel{-1}, tickTimePosition{0}, positionData{}, lineData{}
+    SpannerStop() : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, tickTimePosition{0}, positionData{}, lineData{}
     {
     }
 };
diff --git a/src/include/mx/api/StaffData.h b/src/include/mx/api/StaffData.h
index 2dadf6ad..37c8c1ba 100644
--- a/src/include/mx/api/StaffData.h
+++ b/src/include/mx/api/StaffData.h
@@ -4,6 +4,7 @@
 
 #pragma once
 
+#include "mx/api/ApiCommon.h"
 #include "mx/api/ClefData.h"
 #include "mx/api/DirectionData.h"
 #include "mx/api/KeyData.h"
@@ -18,15 +19,15 @@ namespace api
 class StaffData
 {
   public:
-    int staffLines = -1;
+    int staffLines = VALUE_UNSPECIFIED;
 
     // Specifies the staff space size relative the the global staff space size
-    double staffSize = -1.0;
+    double staffSize = DOUBLE_UNSPECIFIED;
 
     // Specifies the scaling of the notation. The MusicXml spec calls out the case
     // of percussion staves with wider spaced lines as an example where this differs
     // from staffSize. For example it might be staffSize=150, staffScaling = 100.
-    double staffScaling = -1.0;
+    double staffScaling = DOUBLE_UNSPECIFIED;
 
     std::vector<ClefData> clefs;
 
diff --git a/src/include/mx/api/TempoData.h b/src/include/mx/api/TempoData.h
index 965e238f..dba06bbc 100644
--- a/src/include/mx/api/TempoData.h
+++ b/src/include/mx/api/TempoData.h
@@ -3,6 +3,7 @@
 // Distributed under the MIT License
 
 #pragma once
+#include "mx/api/ApiCommon.h"
 #include "mx/api/DurationData.h"
 #include "mx/api/PositionData.h"
 #include "mx/api/PrintData.h"
@@ -25,7 +26,8 @@ struct BeatsPerMinute
     int dots;
     int beatsPerMinute;
 
-    BeatsPerMinute() : durationName{DurationName::unspecified}, dots{-1}, beatsPerMinute{-1}
+    BeatsPerMinute()
+        : durationName{DurationName::unspecified}, dots{VALUE_UNSPECIFIED}, beatsPerMinute{VALUE_UNSPECIFIED}
     {
     }
 };
@@ -39,8 +41,8 @@ struct MetricModulation
     BeatsPerMinute playbackBeatsPerMinute;
 
     MetricModulation()
-        : leftDurationName{DurationName::unspecified}, leftDots{-1}, rightDurationName{DurationName::unspecified},
-          rightDots{-1}, playbackBeatsPerMinute{}
+        : leftDurationName{DurationName::unspecified}, leftDots{VALUE_UNSPECIFIED},
+          rightDurationName{DurationName::unspecified}, rightDots{VALUE_UNSPECIFIED}, playbackBeatsPerMinute{}
     {
     }
 };
diff --git a/src/include/mx/api/TupletData.h b/src/include/mx/api/TupletData.h
index 64a82373..3991f110 100644
--- a/src/include/mx/api/TupletData.h
+++ b/src/include/mx/api/TupletData.h
@@ -22,7 +22,7 @@ class TupletStart
 {
   public:
     // used to id when nested
-    // -1 means unspecified
+    // NUMBER_LEVEL_UNSPECIFIED means unspecified
     int numberLevel;
 
     PositionData positionData;
@@ -47,9 +47,11 @@ class TupletStart
     Bool bracket;
 
     TupletStart()
-        : numberLevel{-1}, positionData{}, actualNumber{-1}, actualDurationName{api::DurationName::unspecified},
-          actualDots{-1}, normalNumber{-1}, normalDurationName{api::DurationName::unspecified}, normalDots{-1},
-          showActualNumber{Bool::unspecified}, showNormalNumber{Bool::unspecified}, bracket{Bool::unspecified}
+        : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, positionData{}, actualNumber{VALUE_UNSPECIFIED},
+          actualDurationName{api::DurationName::unspecified}, actualDots{VALUE_UNSPECIFIED},
+          normalNumber{VALUE_UNSPECIFIED}, normalDurationName{api::DurationName::unspecified},
+          normalDots{VALUE_UNSPECIFIED}, showActualNumber{Bool::unspecified}, showNormalNumber{Bool::unspecified},
+          bracket{Bool::unspecified}
     {
     }
 };
@@ -58,12 +60,12 @@ class TupletStop
 {
   public:
     // used to id when nested
-    // -1 means unspecified
+    // NUMBER_LEVEL_UNSPECIFIED means unspecified
     int numberLevel;
 
     PositionData positionData;
 
-    TupletStop() : numberLevel{-1}, positionData{}
+    TupletStop() : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, positionData{}
     {
     }
 };
diff --git a/src/include/mx/api/WedgeData.h b/src/include/mx/api/WedgeData.h
index dc04e522..efd03ef5 100644
--- a/src/include/mx/api/WedgeData.h
+++ b/src/include/mx/api/WedgeData.h
@@ -31,8 +31,8 @@ struct WedgeStart
     ColorData colorData;
 
     WedgeStart()
-        : numberLevel{-1}, wedgeType{WedgeType::unspecified}, isSpreadSpecified{false}, spread{0.0}, lineData{},
-          positionData{}, colorData{}
+        : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, wedgeType{WedgeType::unspecified}, isSpreadSpecified{false},
+          spread{0.0}, lineData{}, positionData{}, colorData{}
     {
     }
 };
@@ -44,7 +44,7 @@ struct WedgeStop
     bool isSpreadSpecified;
     double spread;
 
-    WedgeStop() : numberLevel{-1}, positionData{}, isSpreadSpecified{false}, spread{0.0}
+    WedgeStop() : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, positionData{}, isSpreadSpecified{false}, spread{0.0}
     {
     }
 };
diff --git a/src/private/mx/api/MarkData.cpp b/src/private/mx/api/MarkData.cpp
index dee51df8..17c9727c 100644
--- a/src/private/mx/api/MarkData.cpp
+++ b/src/private/mx/api/MarkData.cpp
@@ -220,7 +220,7 @@ int numTremoloSlashes(MarkType markType)
         return 5;
     }
 
-    return -1;
+    return VALUE_UNSPECIFIED;
 }
 
 MarkData::MarkData()
diff --git a/src/private/mx/api/NoteData.cpp b/src/private/mx/api/NoteData.cpp
index 70cdeb2b..5ec9de7a 100644
--- a/src/private/mx/api/NoteData.cpp
+++ b/src/private/mx/api/NoteData.cpp
@@ -11,8 +11,8 @@ namespace api
 NoteData::NoteData()
     : isRest{false}, isMeasureRest{false}, isUnpitched{false}, isDisplayStepOctaveSpecified{false}, isChord{false},
       isTieStart{false}, isTieStop{false}, tieLetRing{}, noteType{NoteType::normal}, notehead{Notehead::normal},
-      pitchData{}, userRequestedVoiceNumber{-1}, stem{Stem::unspecified}, tickTimePosition{0}, durationData{}, beams{},
-      positionData{}, printData{}, noteAttachmentData{}, lyrics{}
+      pitchData{}, userRequestedVoiceNumber{VALUE_UNSPECIFIED}, stem{Stem::unspecified}, tickTimePosition{0},
+      durationData{}, beams{}, positionData{}, printData{}, noteAttachmentData{}, lyrics{}
 {
 }
 } // namespace api
diff --git a/src/private/mx/impl/CurveFunctions.h b/src/private/mx/impl/CurveFunctions.h
index 3ec60c54..4e2456f8 100644
--- a/src/private/mx/impl/CurveFunctions.h
+++ b/src/private/mx/impl/CurveFunctions.h
@@ -91,7 +91,7 @@ api::CurveStart parseCurveStart(const SLUR_OR_TIE_ELEMENT_TYPE &inSlurOrTie)
     }
     else
     {
-        c.numberLevel = -1;
+        c.numberLevel = api::NUMBER_LEVEL_UNSPECIFIED;
     }
 
     c.curvePoints = parseCurvePoints(inAttributes);
@@ -124,7 +124,7 @@ api::CurveContinue parseCurveContinue(const SLUR_OR_TIE_ELEMENT_TYPE &inSlurOrTi
     }
     else
     {
-        c.numberLevel = -1;
+        c.numberLevel = api::NUMBER_LEVEL_UNSPECIFIED;
     }
 
     if (inAttributes.bezierX2().has_value())
@@ -161,7 +161,7 @@ template <typename SLUR_OR_TIE_ELEMENT_TYPE> api::CurveStop parseCurveStop(const
     }
     else
     {
-        c.numberLevel = -1;
+        c.numberLevel = api::NUMBER_LEVEL_UNSPECIFIED;
     }
 
     c.curvePoints = parseCurvePoints(inAttributes);
diff --git a/src/private/mx/impl/DirectionReader.cpp b/src/private/mx/impl/DirectionReader.cpp
index c94f71be..2e099df6 100644
--- a/src/private/mx/impl/DirectionReader.cpp
+++ b/src/private/mx/impl/DirectionReader.cpp
@@ -174,10 +174,10 @@ void DirectionReader::parseValues()
         }
 
         // The <direction>'s editorial-voice <voice> assigns the direction to a voice. A value of
-        // -1 on DirectionData::voice means none was present.
+        // VALUE_UNSPECIFIED on DirectionData::voice means none was present.
         if (myDirection->editorialVoiceDirection().voice().has_value())
         {
-            int parsedVoice = -1;
+            int parsedVoice = api::VALUE_UNSPECIFIED;
             if (utility::stringToInt(myDirection->editorialVoiceDirection().voice()->c_str(), parsedVoice))
             {
                 myOutDirectionData.voice = parsedVoice;
diff --git a/src/private/mx/impl/FontFunctions.h b/src/private/mx/impl/FontFunctions.h
index 443dc877..debd1a7d 100644
--- a/src/private/mx/impl/FontFunctions.h
+++ b/src/private/mx/impl/FontFunctions.h
@@ -83,7 +83,7 @@ api::FontSizeType getFontSize(const ATTRIBUTES_TYPE &inAttributes, double &outPo
 {
     if (!checkHasFontSize<ATTRIBUTES_TYPE>(&inAttributes))
     {
-        outPointSize = -1.0;
+        outPointSize = api::DOUBLE_UNSPECIFIED;
         outCssSize = api::CssSize::unspecified;
         return api::FontSizeType::unspecified;
     }
@@ -93,7 +93,7 @@ api::FontSizeType getFontSize(const ATTRIBUTES_TYPE &inAttributes, double &outPo
 
     if (coreFontSize.isCSSFontSize())
     {
-        outPointSize = -1.0;
+        outPointSize = api::DOUBLE_UNSPECIFIED;
         outCssSize = converter.convert(coreFontSize.asCSSFontSize());
         return api::FontSizeType::css;
     }
diff --git a/src/private/mx/impl/LayoutFunctions.cpp b/src/private/mx/impl/LayoutFunctions.cpp
index cf7f41cb..f9cf6563 100644
--- a/src/private/mx/impl/LayoutFunctions.cpp
+++ b/src/private/mx/impl/LayoutFunctions.cpp
@@ -350,8 +350,8 @@ void addScaling(const core::ScoreHeaderGroup &inScoreHeaderGroup, api::DefaultsD
     }
     else
     {
-        outDefaults.scalingMillimeters = -1.0;
-        outDefaults.scalingTenths = -1.0;
+        outDefaults.scalingMillimeters = api::DOUBLE_UNSPECIFIED;
+        outDefaults.scalingTenths = api::DOUBLE_UNSPECIFIED;
     }
 }
 
diff --git a/src/private/mx/impl/MeasureReader.cpp b/src/private/mx/impl/MeasureReader.cpp
index 58be9a03..8a4c706e 100644
--- a/src/private/mx/impl/MeasureReader.cpp
+++ b/src/private/mx/impl/MeasureReader.cpp
@@ -476,7 +476,7 @@ std::optional<api::TransposeData> MeasureReader::parseAttributes(const core::Att
             keyData.staffIndex = key.number()->value() - 1;
             if (keyData.staffIndex > myCurrentCursor.getNumStaves() - 1)
             {
-                keyData.staffIndex = -1;
+                keyData.staffIndex = api::INDEX_UNSPECIFIED;
             }
         }
 
@@ -987,7 +987,7 @@ int MeasureReader::getUserRequestedVoiceNumber(const api::VoiceData &voiceData)
 {
     if (voiceData.notes.empty())
     {
-        return -1;
+        return api::VALUE_UNSPECIFIED;
     }
 
     return voiceData.notes.front().userRequestedVoiceNumber;
diff --git a/src/private/mx/impl/MeasureWriter.cpp b/src/private/mx/impl/MeasureWriter.cpp
index 9eac215f..43a49647 100644
--- a/src/private/mx/impl/MeasureWriter.cpp
+++ b/src/private/mx/impl/MeasureWriter.cpp
@@ -132,7 +132,7 @@ void MeasureWriter::writeMeasureGlobals()
     {
         if (staff.staffLines >= 0 || staff.staffSize >= 0.0)
         {
-            int desiredStaffIndex = -1;
+            int desiredStaffIndex = api::INDEX_UNSPECIFIED;
             if (myHistory.getCursor().getNumStaves() > 1)
             {
                 desiredStaffIndex = localStaffCounter;
@@ -432,7 +432,7 @@ void MeasureWriter::writeVoices(const api::StaffData &inStaff)
             {
                 if (myMeasureKeysIter->tickTimePosition <= myHistory.getCursor().tickTimePosition)
                 {
-                    myPropertiesWriter->writeKey(-1, *myMeasureKeysIter);
+                    myPropertiesWriter->writeKey(api::INDEX_UNSPECIFIED, *myMeasureKeysIter);
                     ++myMeasureKeysIter;
                 }
             }
@@ -496,7 +496,7 @@ void MeasureWriter::writeVoices(const api::StaffData &inStaff)
         {
             if (myMeasureKeysIter->tickTimePosition)
             {
-                myPropertiesWriter->writeKey(-1, *myMeasureKeysIter);
+                myPropertiesWriter->writeKey(api::INDEX_UNSPECIFIED, *myMeasureKeysIter);
                 ++myMeasureKeysIter;
             }
         }
diff --git a/src/private/mx/impl/MeasureWriter.h b/src/private/mx/impl/MeasureWriter.h
index 0371e6b1..3abaa5dc 100644
--- a/src/private/mx/impl/MeasureWriter.h
+++ b/src/private/mx/impl/MeasureWriter.h
@@ -229,7 +229,7 @@ class MeasureWriter
     // clef writes agree and single-staff parts do not emit a spurious number="1".
     inline int clefStaffIndex(int staffIndex) const
     {
-        return cursor().getNumStaves() > 1 ? staffIndex : -1;
+        return cursor().getNumStaves() > 1 ? staffIndex : api::INDEX_UNSPECIFIED;
     }
 
     template <typename T> std::vector<T> findItemsAtTimePosition(const std::vector<T> &inItems, int inTickTimePosition)
diff --git a/src/private/mx/impl/MetronomeReader.cpp b/src/private/mx/impl/MetronomeReader.cpp
index d63389b7..99eb5fcc 100644
--- a/src/private/mx/impl/MetronomeReader.cpp
+++ b/src/private/mx/impl/MetronomeReader.cpp
@@ -90,7 +90,7 @@ void MetronomeReader::parseBeatsPerMinute() const
     myOutTempoData.beatsPerMinute.durationName = converter.convert(grp.beatUnit());
     myOutTempoData.beatsPerMinute.dots = static_cast<int>(grp.beatUnitDot().size());
     const auto bpmStr = beatUnitPer.choice().asPerMinute().value();
-    int bpm = -1;
+    int bpm = api::VALUE_UNSPECIFIED;
     bool isNumeric = utility::stringToInt(bpmStr, bpm);
     if (!isNumeric)
     {
diff --git a/src/private/mx/impl/NoteReader.cpp b/src/private/mx/impl/NoteReader.cpp
index d100ba14..62eb71c8 100644
--- a/src/private/mx/impl/NoteReader.cpp
+++ b/src/private/mx/impl/NoteReader.cpp
@@ -301,7 +301,7 @@ void NoteReader::setStaffNumber()
 
 void NoteReader::setVoiceNumber()
 {
-    myVoiceNumber = -1;
+    myVoiceNumber = api::VALUE_UNSPECIFIED;
 
     if (!myNote.editorialVoice().voice().has_value())
     {
diff --git a/src/private/mx/impl/NoteWriter.cpp b/src/private/mx/impl/NoteWriter.cpp
index 77d0dc5d..b2fa7dac 100644
--- a/src/private/mx/impl/NoteWriter.cpp
+++ b/src/private/mx/impl/NoteWriter.cpp
@@ -408,7 +408,7 @@ void NoteWriter::setStaffAndVoice() const
         myOutNote.setStaff(myCursor.staffIndex + 1);
     }
 
-    const bool sourceHadVoice = myNoteData.userRequestedVoiceNumber != -1;
+    const bool sourceHadVoice = myNoteData.userRequestedVoiceNumber != api::VALUE_UNSPECIFIED;
     const bool isNonDefaultVoice = myCursor.voiceIndex > 0;
     const bool isMultiVoiceStaff = myNumVoices > 1;
     if (myCursor.voiceIndex >= 0 && (sourceHadVoice || isNonDefaultVoice || isMultiVoiceStaff))
diff --git a/src/private/mx/impl/PartReader.cpp b/src/private/mx/impl/PartReader.cpp
index 253a80c3..2311ff00 100644
--- a/src/private/mx/impl/PartReader.cpp
+++ b/src/private/mx/impl/PartReader.cpp
@@ -371,7 +371,7 @@ int PartReader::findPartIndex(const std::string &inPartId) const
             ++index;
         }
     }
-    return -1;
+    return api::INDEX_UNSPECIFIED;
 }
 } // namespace impl
 } // namespace mx
diff --git a/src/private/mx/impl/PropertiesWriter.cpp b/src/private/mx/impl/PropertiesWriter.cpp
index 6351f413..a580d19c 100644
--- a/src/private/mx/impl/PropertiesWriter.cpp
+++ b/src/private/mx/impl/PropertiesWriter.cpp
@@ -183,12 +183,12 @@ void PropertiesWriter::writeNumStaves(int value)
 
 void PropertiesWriter::writeStaffDetails(int staffIndex, int staffLines)
 {
-    writeStaffDetails(staffIndex, staffLines, -1.0, -1.0);
+    writeStaffDetails(staffIndex, staffLines, api::DOUBLE_UNSPECIFIED, api::DOUBLE_UNSPECIFIED);
 }
 
 void PropertiesWriter::writeStaffDetails(int staffIndex, int staffLines, double staffSize)
 {
-    writeStaffDetails(staffIndex, staffLines, staffSize, -1.0);
+    writeStaffDetails(staffIndex, staffLines, staffSize, api::DOUBLE_UNSPECIFIED);
 }
 
 void PropertiesWriter::writeStaffDetails(int staffIndex, int staffLines, double staffSize, double staffScaling)
diff --git a/src/private/mx/impl/ScoreReader.cpp b/src/private/mx/impl/ScoreReader.cpp
index 71925ce7..61b3c199 100644
--- a/src/private/mx/impl/ScoreReader.cpp
+++ b/src/private/mx/impl/ScoreReader.cpp
@@ -402,7 +402,7 @@ api::PartGroupData ScoreReader::popMostRecentGroupFromStack() const
 
 int ScoreReader::parsePartGroupNumber(const core::PartGroup &inPartGroup) const
 {
-    int num = -1;
+    int num = api::NUMBER_LEVEL_UNSPECIFIED;
 
     if (inPartGroup.number().has_value())
     {
diff --git a/src/private/mx/impl/SpannerFunctions.h b/src/private/mx/impl/SpannerFunctions.h
index 9800acb1..0894f334 100644
--- a/src/private/mx/impl/SpannerFunctions.h
+++ b/src/private/mx/impl/SpannerFunctions.h
@@ -14,12 +14,12 @@ namespace mx
 namespace impl
 {
 MX_OPTIONAL_HAS_FUNC(number, Number);
-MX_OPTIONAL_GET_INT_FUNC(number, Number, -1);
+MX_OPTIONAL_GET_INT_FUNC(number, Number, api::NUMBER_LEVEL_UNSPECIFIED);
 
 template <typename ATTRIBUTES_TYPE> api::SpannerStart getSpannerStart(const ATTRIBUTES_TYPE &inAttributes)
 {
     api::SpannerStart start;
-    start.numberLevel = -1;
+    start.numberLevel = api::NUMBER_LEVEL_UNSPECIFIED;
     if (checkHasNumber(&inAttributes))
     {
         start.numberLevel = checkNumber(&inAttributes);
@@ -33,7 +33,7 @@ template <typename ATTRIBUTES_TYPE> api::SpannerStart getSpannerStart(const ATTR
 template <typename ATTRIBUTES_TYPE> api::SpannerStop getSpannerStop(const ATTRIBUTES_TYPE &inAttributes)
 {
     api::SpannerStop stop;
-    stop.numberLevel = -1;
+    stop.numberLevel = api::NUMBER_LEVEL_UNSPECIFIED;
     if (checkHasNumber(&inAttributes))
     {
         stop.numberLevel = checkNumber(&inAttributes);