From 7e7b35fa71eb36d9accdc1c8f2690eedd94dac91 Mon Sep 17 00:00:00 2001
From: Matthew James Briggs <matthew.james.briggs@gmail.com>
Date: Thu, 20 Aug 2026 13:58:27 +0000
Subject: [PATCH 1/2] feat: model MusicXML ids with an api::Id type

An id attribute is not any old string. It has to follow the XML name rules, and
until now mx enforced that only at the last moment, inside mx::impl, by handing
the text to core::Token on the way out. The caller never learned that their id
had changed.

Replace std::optional<std::string> id with std::optional<api::Id> on all 41 api
id members. api::Id holds a core::Token behind a pimpl, so the text is scrubbed
once, as the Id is built, and mx::impl passes the token itself to mx::core. No
second conversion is possible. Callers who need to know whether their text was
legal compare Id::value() with what they passed in.

Id copies, assigns, compares, sorts, and hashes like a plain value. std::hash is
specialized for it, so an Id works as a key in std::map and std::unordered_map.
Copies share one immutable token instead of allocating, and a moved-from Id
still holds a token, so reading one is harmless.

IdAccess (private to mx) is the only door between Id and its token. The public
header names no core type.

The id explanation moves from ApiCommon.h to Id.h, where the type it describes
lives. SegnoData and CodaData keep their legacy std::string id plus
isIdSpecified; those belong with the rest of issue 249.
---
 .../mx/api/AccordionRegistrationData.h        |   3 +-
 src/include/mx/api/ApiCommon.h                |  11 -
 src/include/mx/api/BarlineData.h              |   5 +-
 src/include/mx/api/ClefData.h                 |   5 +-
 src/include/mx/api/CurveData.h                |  13 +-
 src/include/mx/api/DampData.h                 |   5 +-
 src/include/mx/api/DirectionData.h            |   5 +-
 src/include/mx/api/EyeglassesData.h           |   3 +-
 src/include/mx/api/FiguredBassData.h          |   5 +-
 src/include/mx/api/HarpPedalsData.h           |   3 +-
 src/include/mx/api/Id.h                       | 103 ++++++++++
 src/include/mx/api/ImageData.h                |   3 +-
 src/include/mx/api/KeyData.h                  |   5 +-
 src/include/mx/api/LyricData.h                |   5 +-
 src/include/mx/api/MarkDataChoice.h           |   7 +-
 src/include/mx/api/MeasureData.h              |   5 +-
 src/include/mx/api/NoteData.h                 |   9 +-
 src/include/mx/api/OtherDirectionData.h       |   3 +-
 src/include/mx/api/PedalLineData.h            |   5 +-
 src/include/mx/api/PercussionData.h           |   3 +-
 src/include/mx/api/PrincipalVoiceData.h       |   3 +-
 src/include/mx/api/RehearsalData.h            |   5 +-
 src/include/mx/api/ScordaturaData.h           |   3 +-
 src/include/mx/api/SoundData.h                |   5 +-
 src/include/mx/api/SpannerData.h              |   9 +-
 src/include/mx/api/StaffDivideData.h          |   3 +-
 src/include/mx/api/StringMuteData.h           |   3 +-
 src/include/mx/api/SymbolData.h               |   5 +-
 src/include/mx/api/TempoData.h                |   3 +-
 src/include/mx/api/TimeChoice.h               |   5 +-
 src/include/mx/api/TransposeData.h            |   5 +-
 src/include/mx/api/TupletData.h               |   9 +-
 src/include/mx/api/WedgeData.h                |   9 +-
 src/include/mx/api/WordsData.h                |   5 +-
 src/private/mx/api/Id.cpp                     | 100 +++++++++
 src/private/mx/api/IdAccess.h                 |  28 +++
 src/private/mx/impl/ArpeggiateFunctions.cpp   |   6 +-
 src/private/mx/impl/DirectionReader.cpp       |  60 ++----
 src/private/mx/impl/DirectionWriter.cpp       |  57 ++----
 src/private/mx/impl/DirectionWriter.h         |   2 +-
 src/private/mx/impl/IdFunctions.h             |  21 +-
 src/private/mx/impl/MetronomeReader.cpp       |   6 +-
 .../mx/impl/NonArpeggiateFunctions.cpp        |   6 +-
 src/private/mx/impl/NotationsWriter.cpp       |  15 +-
 src/private/mx/impl/NoteFunctions.cpp         |   5 +-
 src/private/mxtest/api/IdAttributeApiTest.cpp | 189 ++++++++++++++----
 46 files changed, 525 insertions(+), 248 deletions(-)
 create mode 100644 src/include/mx/api/Id.h
 create mode 100644 src/private/mx/api/Id.cpp
 create mode 100644 src/private/mx/api/IdAccess.h

diff --git a/src/include/mx/api/AccordionRegistrationData.h b/src/include/mx/api/AccordionRegistrationData.h
index 39a1be178..48f4724d3 100644
--- a/src/include/mx/api/AccordionRegistrationData.h
+++ b/src/include/mx/api/AccordionRegistrationData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -31,7 +32,7 @@ class AccordionRegistrationData
     PositionData positionData;
     FontData fontData;
     std::optional<ColorData> color;
-    std::optional<std::string> id;
+    std::optional<Id> id;
 
     AccordionRegistrationData() : high{false}, middle{}, low{false}, positionData{}, fontData{}, color{}, id{}
     {
diff --git a/src/include/mx/api/ApiCommon.h b/src/include/mx/api/ApiCommon.h
index 6efabd4b0..3ff4433aa 100644
--- a/src/include/mx/api/ApiCommon.h
+++ b/src/include/mx/api/ApiCommon.h
@@ -32,17 +32,6 @@ constexpr int NUMBER_LEVEL_UNSPECIFIED = -1; // MusicXML 'number' attributes, e.
 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
 
-// MusicXML lets most elements carry an optional id attribute, a name that identifies that one
-// element within the document. Software uses it to point at a particular note, measure, or
-// marking -- to line playback up with the score, to hang an annotation on a note, or to link one
-// file to another. Every mx::api type that models such an element has an `id` member. Leave it
-// empty and no id attribute is written.
-//
-// An id must be unique within the document and must follow the XML name rules: a letter or an
-// underscore first, then letters, digits, dots, hyphens, or underscores. mx repairs an id that
-// breaks the name rules when it writes the file, but it does not check uniqueness, so an id you
-// invent must not collide with one already in the score.
-
 // 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/BarlineData.h b/src/include/mx/api/BarlineData.h
index 05857f979..691bf2e82 100644
--- a/src/include/mx/api/BarlineData.h
+++ b/src/include/mx/api/BarlineData.h
@@ -5,6 +5,7 @@
 #pragma once
 
 #include "mx/api/ApiCommon.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -116,8 +117,8 @@ class BarlineData
     RepeatWinged repeatWinged;
     HorizontalAlignment location;
 
-    // The <barline> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <barline> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     BarlineData()
         : tickTimePosition{0}, barlineType{BarlineType::normal}, ending{}, repeat{false}, repeatTimes{0},
diff --git a/src/include/mx/api/ClefData.h b/src/include/mx/api/ClefData.h
index 81a788a87..e91d4b299 100644
--- a/src/include/mx/api/ClefData.h
+++ b/src/include/mx/api/ClefData.h
@@ -5,6 +5,7 @@
 #pragma once
 
 #include "mx/api/ApiCommon.h"
+#include "mx/api/Id.h"
 
 #include <optional>
 #include <string>
@@ -71,8 +72,8 @@ class ClefData
     // unspecified -> omit the attribute, yes/no -> write print-object verbatim.
     Bool printObject;
 
-    // The <clef> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <clef> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     std::string toString() const;
 
diff --git a/src/include/mx/api/CurveData.h b/src/include/mx/api/CurveData.h
index 178919df6..5b5408cff 100644
--- a/src/include/mx/api/CurveData.h
+++ b/src/include/mx/api/CurveData.h
@@ -6,6 +6,7 @@
 
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
+#include "mx/api/Id.h"
 #include "mx/api/LineData.h"
 #include "mx/api/PositionData.h"
 #include "mx/api/SpannerNumber.h"
@@ -104,8 +105,8 @@ struct CurveStart
     ColorData colorData;
 
     // The id attribute of the element this curve end is written as -- <slur> for a slur,
-    // <tied> for a tie (see ApiCommon.h).
-    std::optional<std::string> id;
+    // <tied> for a tie (see Id.h).
+    std::optional<Id> id;
 
     CurveStart(CurveType inCurveType)
         : curveType{inCurveType}, number{}, curvePoints{}, curveOrientation{CurveOrientation::unspecified},
@@ -127,8 +128,8 @@ struct CurveContinue
     double bezierOffset2;
 
     // The id attribute of the element this curve end is written as -- <slur> for a slur,
-    // <tied> for a tie (see ApiCommon.h).
-    std::optional<std::string> id;
+    // <tied> for a tie (see Id.h).
+    std::optional<Id> id;
 
     CurveContinue(CurveType inCurveType)
         : curveType{inCurveType}, number{}, curvePoints{}, isBezierX2Specified{false}, bezierX2{0.0},
@@ -144,8 +145,8 @@ struct CurveStop
     CurvePoints curvePoints;
 
     // The id attribute of the element this curve end is written as -- <slur> for a slur,
-    // <tied> for a tie (see ApiCommon.h).
-    std::optional<std::string> id;
+    // <tied> for a tie (see Id.h).
+    std::optional<Id> id;
 
     CurveStop(CurveType inCurveType) : curveType{inCurveType}, number{}, curvePoints{}, id{}
     {
diff --git a/src/include/mx/api/DampData.h b/src/include/mx/api/DampData.h
index eb17e7ffa..7870ef57d 100644
--- a/src/include/mx/api/DampData.h
+++ b/src/include/mx/api/DampData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -26,7 +27,7 @@ class DampData
     PositionData positionData;
     FontData fontData;
     std::optional<ColorData> color;
-    std::optional<std::string> id;
+    std::optional<Id> id;
 
     DampData() : positionData{}, fontData{}, color{}, id{}
     {
@@ -49,7 +50,7 @@ class DampAllData
     PositionData positionData;
     FontData fontData;
     std::optional<ColorData> color;
-    std::optional<std::string> id;
+    std::optional<Id> id;
 
     DampAllData() : positionData{}, fontData{}, color{}, id{}
     {
diff --git a/src/include/mx/api/DirectionData.h b/src/include/mx/api/DirectionData.h
index 6981d2200..b1adcd8d9 100644
--- a/src/include/mx/api/DirectionData.h
+++ b/src/include/mx/api/DirectionData.h
@@ -8,6 +8,7 @@
 #include "mx/api/ChordData.h"
 #include "mx/api/DirectionChoice.h"
 #include "mx/api/FiguredBassData.h"
+#include "mx/api/Id.h"
 #include "mx/api/SoundData.h"
 
 #include <optional>
@@ -81,8 +82,8 @@ struct DirectionData
     // serialize as their own <figured-bass> elements, not as direction-type content.
     std::vector<FiguredBassData> figuredBasses;
 
-    // The <direction> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <direction> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     DirectionData()
         : tickTimePosition{0}, placement{Placement::unspecified}, systemRelation{SystemRelation::unspecified}, offset{},
diff --git a/src/include/mx/api/EyeglassesData.h b/src/include/mx/api/EyeglassesData.h
index 39a3e7135..28a25140d 100644
--- a/src/include/mx/api/EyeglassesData.h
+++ b/src/include/mx/api/EyeglassesData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -27,7 +28,7 @@ class EyeglassesData
     PositionData positionData;
     FontData fontData;
     std::optional<ColorData> color;
-    std::optional<std::string> id;
+    std::optional<Id> id;
 
     EyeglassesData() : positionData{}, fontData{}, color{}, id{}
     {
diff --git a/src/include/mx/api/FiguredBassData.h b/src/include/mx/api/FiguredBassData.h
index a4ff4d9eb..65f2a23e5 100644
--- a/src/include/mx/api/FiguredBassData.h
+++ b/src/include/mx/api/FiguredBassData.h
@@ -5,6 +5,7 @@
 #pragma once
 
 #include "mx/api/ApiCommon.h"
+#include "mx/api/Id.h"
 
 #include <optional>
 #include <string>
@@ -49,8 +50,8 @@ class FiguredBassData
     // The optional <duration>, in ticks. A value less than 0 means 'unspecified' (no duration child).
     int durationTimeTicks;
 
-    // The <figured-bass> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <figured-bass> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     FiguredBassData() : figures{}, parentheses{Bool::unspecified}, durationTimeTicks{VALUE_UNSPECIFIED}, id{}
     {
diff --git a/src/include/mx/api/HarpPedalsData.h b/src/include/mx/api/HarpPedalsData.h
index 3b00837e3..01de07a0f 100644
--- a/src/include/mx/api/HarpPedalsData.h
+++ b/src/include/mx/api/HarpPedalsData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PitchData.h"
 #include "mx/api/PositionData.h"
 
@@ -57,7 +58,7 @@ class HarpPedalsData
     PositionData positionData;
     FontData fontData;
     std::optional<ColorData> color;
-    std::optional<std::string> id;
+    std::optional<Id> id;
 
     HarpPedalsData() : pedalTunings{}, positionData{}, fontData{}, color{}, id{}
     {
diff --git a/src/include/mx/api/Id.h b/src/include/mx/api/Id.h
new file mode 100644
index 000000000..3640e0520
--- /dev/null
+++ b/src/include/mx/api/Id.h
@@ -0,0 +1,103 @@
+// MusicXML Class Library
+// Copyright (c) by Matthew James Briggs
+// Distributed under the MIT License
+
+#pragma once
+
+#include "mx/api/ApiCommon.h"
+
+#include <cstddef>
+#include <functional>
+#include <memory>
+#include <string>
+
+namespace mx
+{
+namespace api
+{
+
+// The id attribute of a MusicXML element. An id is a name that identifies one element within the
+// document. Software uses it to point at a particular note, measure, or marking -- to line playback
+// up with the score, to hang an annotation on a note, or to link one file to another.
+//
+// An id must follow the XML name rules. The first character is a letter or an underscore. The rest
+// are letters, digits, dots, hyphens, or underscores. Building an Id scrubs out anything else, so
+// an id that breaks the rules cannot exist. Text with nothing usable left, empty text included,
+// becomes "X". Building the Id is the only place this happens: mx writes the id exactly as the Id
+// holds it.
+//
+// Scrubbing is silent. To find out whether your text was already a legal id, compare it with the
+// id you built:
+//
+//     const auto id = Id{myText};
+//     if (id.value() != myText)
+//     {
+//         // myText was not a legal id; decide what to do about it
+//     }
+//
+// An id must also be unique within the document. Uniqueness is a property of the whole score, not
+// of one name, so Id cannot check it. An id you invent must not collide with one already in the
+// score.
+//
+// To write no id attribute at all, leave the std::optional that holds the Id empty.
+//
+// Copy, assign, compare, sort, and hash an Id the way you would any other value. Two Ids are equal
+// when their text is equal, and std::hash is specialized for Id, so an Id works as a key in both
+// std::map and std::unordered_map.
+class Id
+{
+  public:
+    Id(std::string text);
+    Id(const char *text);
+
+    Id(const Id &other);
+    Id(Id &&other) noexcept;
+    Id &operator=(const Id &other);
+    Id &operator=(Id &&other) noexcept;
+    ~Id();
+
+    const std::string &value() const;
+
+    bool operator==(const Id &other) const;
+    bool operator<(const Id &other) const;
+
+  private:
+    // Holds the same type mx writes the attribute with, which is why the text cannot be scrubbed a
+    // second time. The definition is private to mx.
+    class Impl;
+    explicit Id(std::shared_ptr<const Impl> impl);
+    friend struct IdAccess;
+
+    std::shared_ptr<const Impl> myImpl;
+};
+
+MXAPI_NOT_EQUALS_AND_VECTORS(Id);
+
+inline bool operator>(const Id &lhs, const Id &rhs)
+{
+    return rhs < lhs;
+}
+
+inline bool operator<=(const Id &lhs, const Id &rhs)
+{
+    return !(rhs < lhs);
+}
+
+inline bool operator>=(const Id &lhs, const Id &rhs)
+{
+    return !(lhs < rhs);
+}
+
+} // namespace api
+} // namespace mx
+
+namespace std
+{
+template <> struct hash<mx::api::Id>
+{
+    std::size_t operator()(const mx::api::Id &id) const noexcept
+    {
+        return std::hash<std::string>{}(id.value());
+    }
+};
+} // namespace std
diff --git a/src/include/mx/api/ImageData.h b/src/include/mx/api/ImageData.h
index 0a9a1cb07..f90588403 100644
--- a/src/include/mx/api/ImageData.h
+++ b/src/include/mx/api/ImageData.h
@@ -5,6 +5,7 @@
 #pragma once
 
 #include "mx/api/ApiCommon.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -29,7 +30,7 @@ class ImageData
     std::optional<double> height;
     std::optional<double> width;
     PositionData positionData;
-    std::optional<std::string> id;
+    std::optional<Id> id;
 
     ImageData() : source{}, type{}, height{}, width{}, positionData{}, id{}
     {
diff --git a/src/include/mx/api/KeyData.h b/src/include/mx/api/KeyData.h
index ff4666ae0..46822bba8 100644
--- a/src/include/mx/api/KeyData.h
+++ b/src/include/mx/api/KeyData.h
@@ -4,6 +4,7 @@
 
 #pragma once
 #include "mx/api/ApiCommon.h"
+#include "mx/api/Id.h"
 #include "mx/api/KeyComponent.h"
 
 #include <optional>
@@ -124,8 +125,8 @@ struct KeyData
     // alterations. When custom is non-empty, then fifths and mode are ignored.
     std::vector<KeyComponent> nonTraditional;
 
-    // The <key> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <key> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     KeyData()
         : fifths{0}, cancel{0}, cancelLocation{CancelLocation::unspecified}, mode{KeyMode::unspecified},
diff --git a/src/include/mx/api/LyricData.h b/src/include/mx/api/LyricData.h
index e08993b94..28e50457a 100644
--- a/src/include/mx/api/LyricData.h
+++ b/src/include/mx/api/LyricData.h
@@ -5,6 +5,7 @@
 #pragma once
 
 #include "mx/api/ApiCommon.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 #include "mx/api/PrintData.h"
 
@@ -54,8 +55,8 @@ class LyricData
     PositionData positionData;
     PrintData printData;
 
-    // The <lyric> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <lyric> element's id attribute (see Id.h).
+    std::optional<Id> id;
 };
 
 MXAPI_EQUALS_BEGIN(LyricData)
diff --git a/src/include/mx/api/MarkDataChoice.h b/src/include/mx/api/MarkDataChoice.h
index 4eff58120..7b9b73b47 100644
--- a/src/include/mx/api/MarkDataChoice.h
+++ b/src/include/mx/api/MarkDataChoice.h
@@ -6,6 +6,7 @@
 
 #include "mx/api/ApiCommon.h"
 #include "mx/api/DynamicsData.h"
+#include "mx/api/Id.h"
 
 #include <optional>
 #include <string>
@@ -59,7 +60,7 @@ struct ArpeggiateMarkData
     Bool unbroken = Bool::unspecified;
 
     // The element's `id` attribute (MusicXML 3.1).
-    std::optional<std::string> id;
+    std::optional<Id> id;
 };
 
 MXAPI_EQUALS_BEGIN(ArpeggiateMarkData)
@@ -89,7 +90,7 @@ struct NonArpeggiateMarkData
     std::optional<int> number;
 
     // The element's `id` attribute (MusicXML 3.1).
-    std::optional<std::string> id;
+    std::optional<Id> id;
 };
 
 MXAPI_EQUALS_BEGIN(NonArpeggiateMarkData)
@@ -126,7 +127,7 @@ struct OtherNotationMarkData
     OtherNotationType type = OtherNotationType::single;
     std::optional<int> number;
     std::optional<std::string> smufl;
-    std::optional<std::string> id;
+    std::optional<Id> id;
 };
 
 MXAPI_EQUALS_BEGIN(OtherNotationMarkData)
diff --git a/src/include/mx/api/MeasureData.h b/src/include/mx/api/MeasureData.h
index 6968b6daa..6c3259ab3 100644
--- a/src/include/mx/api/MeasureData.h
+++ b/src/include/mx/api/MeasureData.h
@@ -6,6 +6,7 @@
 
 #include "mx/api/ApiCommon.h"
 #include "mx/api/BarlineData.h"
+#include "mx/api/Id.h"
 #include "mx/api/KeyData.h"
 #include "mx/api/PartSymbolData.h"
 #include "mx/api/StaffData.h"
@@ -111,8 +112,8 @@ class MeasureData
     // before this field existed.
     std::vector<TransposeData> transpositions;
 
-    // The <measure> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <measure> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     MeasureData()
         : staves{}, timeSignature{}, number{}, measureNumbering{MeasureNumbering::unspecified},
diff --git a/src/include/mx/api/NoteData.h b/src/include/mx/api/NoteData.h
index d746d18b7..28074a6a1 100644
--- a/src/include/mx/api/NoteData.h
+++ b/src/include/mx/api/NoteData.h
@@ -6,6 +6,7 @@
 
 #include "mx/api/CurveData.h"
 #include "mx/api/DurationData.h"
+#include "mx/api/Id.h"
 #include "mx/api/LyricData.h"
 #include "mx/api/NoteAttachmentData.h"
 #include "mx/api/PitchData.h"
@@ -82,8 +83,8 @@ struct TieLetRing
     bool isColorSpecified;
     ColorData colorData;
 
-    // The <tied> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <tied> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     TieLetRing()
         : positionData{}, curveOrientation{CurveOrientation::unspecified}, isColorSpecified{false}, colorData{}, id{}
@@ -208,8 +209,8 @@ class NoteData
     // will be parsed into these strings. do not use commas in your misc
     // data strings as these are the delimiter
 
-    // The <note> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <note> element's id attribute (see Id.h).
+    std::optional<Id> id;
     std::vector<std::string> miscData;
 };
 
diff --git a/src/include/mx/api/OtherDirectionData.h b/src/include/mx/api/OtherDirectionData.h
index e9296ffd7..7eda94432 100644
--- a/src/include/mx/api/OtherDirectionData.h
+++ b/src/include/mx/api/OtherDirectionData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -30,7 +31,7 @@ class OtherDirectionData
     PositionData positionData;
     FontData fontData;
     std::optional<ColorData> color;
-    std::optional<std::string> id;
+    std::optional<Id> id;
 
     OtherDirectionData() : text{}, printObject{Bool::unspecified}, smufl{}, positionData{}, fontData{}, color{}, id{}
     {
diff --git a/src/include/mx/api/PedalLineData.h b/src/include/mx/api/PedalLineData.h
index 8606bcfc9..4c1b59ef6 100644
--- a/src/include/mx/api/PedalLineData.h
+++ b/src/include/mx/api/PedalLineData.h
@@ -5,6 +5,7 @@
 #pragma once
 
 #include "mx/api/ApiCommon.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -53,8 +54,8 @@ struct PedalLineData
     int tickTimePosition;
     PositionData positionData;
 
-    // The <pedal> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <pedal> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     PedalLineData() : kind{PedalLineKind::unspecified}, tickTimePosition{0}, positionData{}, id{}
     {
diff --git a/src/include/mx/api/PercussionData.h b/src/include/mx/api/PercussionData.h
index 8fc25f55d..a2ea4abb5 100644
--- a/src/include/mx/api/PercussionData.h
+++ b/src/include/mx/api/PercussionData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -482,7 +483,7 @@ class PercussionData
     PositionData positionData;
     FontData fontData;
     std::optional<ColorData> color;
-    std::optional<std::string> id;
+    std::optional<Id> id;
 
     PercussionData() : choice{}, enclosure{Enclosure::unspecified}, positionData{}, fontData{}, color{}, id{}
     {
diff --git a/src/include/mx/api/PrincipalVoiceData.h b/src/include/mx/api/PrincipalVoiceData.h
index a009124bf..e84911e22 100644
--- a/src/include/mx/api/PrincipalVoiceData.h
+++ b/src/include/mx/api/PrincipalVoiceData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -49,7 +50,7 @@ class PrincipalVoiceData
     PositionData positionData;
     FontData fontData;
     std::optional<ColorData> color;
-    std::optional<std::string> id;
+    std::optional<Id> id;
 
     PrincipalVoiceData()
         : type{PrincipalVoiceType::start}, symbol{PrincipalVoiceSymbol::hauptstimme}, text{}, positionData{},
diff --git a/src/include/mx/api/RehearsalData.h b/src/include/mx/api/RehearsalData.h
index a34430155..e299c6962 100644
--- a/src/include/mx/api/RehearsalData.h
+++ b/src/include/mx/api/RehearsalData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -35,8 +36,8 @@ class RehearsalData
     // and says which edge of the text the position refers to; MusicXML defines both.
     HorizontalAlignment justify;
 
-    // The <rehearsal> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <rehearsal> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     RehearsalData()
         : text{}, positionData{}, isColorSpecified{false}, colorData{}, fontData{}, enclosure{Enclosure::unspecified},
diff --git a/src/include/mx/api/ScordaturaData.h b/src/include/mx/api/ScordaturaData.h
index e0d35240a..da82c0587 100644
--- a/src/include/mx/api/ScordaturaData.h
+++ b/src/include/mx/api/ScordaturaData.h
@@ -5,6 +5,7 @@
 #pragma once
 
 #include "mx/api/ApiCommon.h"
+#include "mx/api/Id.h"
 #include "mx/api/PitchData.h"
 
 #include <optional>
@@ -49,7 +50,7 @@ class ScordaturaData
 {
   public:
     std::vector<AccordData> accords;
-    std::optional<std::string> id;
+    std::optional<Id> id;
 
     ScordaturaData() : accords{}, id{}
     {
diff --git a/src/include/mx/api/SoundData.h b/src/include/mx/api/SoundData.h
index 121a12999..35e471525 100644
--- a/src/include/mx/api/SoundData.h
+++ b/src/include/mx/api/SoundData.h
@@ -5,6 +5,7 @@
 #pragma once
 
 #include "mx/api/ApiCommon.h"
+#include "mx/api/Id.h"
 
 #include <optional>
 #include <string>
@@ -87,8 +88,8 @@ struct SoundData
 
     std::optional<SwingData> swing;
 
-    // The <sound> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <sound> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     SoundData()
         : tempo{DOUBLE_UNSPECIFIED}, dynamics{DOUBLE_UNSPECIFIED}, dacapo{Bool::unspecified},
diff --git a/src/include/mx/api/SpannerData.h b/src/include/mx/api/SpannerData.h
index dd7c55d8a..78a3b8c48 100644
--- a/src/include/mx/api/SpannerData.h
+++ b/src/include/mx/api/SpannerData.h
@@ -5,6 +5,7 @@
 #pragma once
 
 #include "mx/api/ApiCommon.h"
+#include "mx/api/Id.h"
 #include "mx/api/LineData.h"
 #include "mx/api/PositionData.h"
 #include "mx/api/PrintData.h"
@@ -27,8 +28,8 @@ struct SpannerStart
     LineData lineData;
 
     // The id attribute of the element this spanner end is written as -- <bracket>,
-    // <dashes>, or <octave-shift> (see ApiCommon.h).
-    std::optional<std::string> id;
+    // <dashes>, or <octave-shift> (see Id.h).
+    std::optional<Id> id;
 
     SpannerStart() : number{}, tickTimePosition{0}, positionData{}, printData{}, lineData{}, id{}
     {
@@ -43,8 +44,8 @@ struct SpannerStop
     LineData lineData;
 
     // The id attribute of the element this spanner end is written as -- <bracket>,
-    // <dashes>, or <octave-shift> (see ApiCommon.h).
-    std::optional<std::string> id;
+    // <dashes>, or <octave-shift> (see Id.h).
+    std::optional<Id> id;
 
     SpannerStop() : number{}, tickTimePosition{0}, positionData{}, lineData{}, id{}
     {
diff --git a/src/include/mx/api/StaffDivideData.h b/src/include/mx/api/StaffDivideData.h
index 88b7ff898..fb5644e16 100644
--- a/src/include/mx/api/StaffDivideData.h
+++ b/src/include/mx/api/StaffDivideData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -37,7 +38,7 @@ class StaffDivideData
     PositionData positionData;
     FontData fontData;
     std::optional<ColorData> color;
-    std::optional<std::string> id;
+    std::optional<Id> id;
 
     StaffDivideData() : type{StaffDivideType::down}, positionData{}, fontData{}, color{}, id{}
     {
diff --git a/src/include/mx/api/StringMuteData.h b/src/include/mx/api/StringMuteData.h
index b156caba0..5c2414867 100644
--- a/src/include/mx/api/StringMuteData.h
+++ b/src/include/mx/api/StringMuteData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -34,7 +35,7 @@ class StringMuteData
     PositionData positionData;
     FontData fontData;
     std::optional<ColorData> color;
-    std::optional<std::string> id;
+    std::optional<Id> id;
 
     StringMuteData() : type{StringMuteType::on}, positionData{}, fontData{}, color{}, id{}
     {
diff --git a/src/include/mx/api/SymbolData.h b/src/include/mx/api/SymbolData.h
index 3b215534b..ad9d65eb0 100644
--- a/src/include/mx/api/SymbolData.h
+++ b/src/include/mx/api/SymbolData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -41,8 +42,8 @@ class SymbolData
     // symbol-formatting attributes mirror the text-formatting ones on `<words>`.
     HorizontalAlignment justify;
 
-    // The <symbol> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <symbol> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     SymbolData()
         : smufl{}, positionData{}, fontData{}, color{}, enclosure{Enclosure::unspecified},
diff --git a/src/include/mx/api/TempoData.h b/src/include/mx/api/TempoData.h
index 383817671..0d491557d 100644
--- a/src/include/mx/api/TempoData.h
+++ b/src/include/mx/api/TempoData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ColorData.h"
 #include "mx/api/DurationData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/NoteRelationData.h"
 #include "mx/api/PositionData.h"
 #include "mx/api/PrintData.h"
@@ -126,7 +127,7 @@ class TempoData
     PositionData positionData;
     FontData fontData;
     std::optional<ColorData> color;
-    std::optional<std::string> id;
+    std::optional<Id> id;
     HorizontalAlignment justify;
     Bool printObject;
     TempoChoice choice;
diff --git a/src/include/mx/api/TimeChoice.h b/src/include/mx/api/TimeChoice.h
index d26ba44e2..e1f742dcd 100644
--- a/src/include/mx/api/TimeChoice.h
+++ b/src/include/mx/api/TimeChoice.h
@@ -6,6 +6,7 @@
 
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ComplexTimeSignature.h"
+#include "mx/api/Id.h"
 #include "mx/api/TimeSignatureData.h"
 
 #include <optional>
@@ -59,9 +60,9 @@ class TimeChoice
     // Print/hide the time signature (<time print-object=...>). Ignored when isImplicit.
     Bool display{Bool::unspecified};
 
-    // The <time> element's id attribute (see ApiCommon.h). Only the measure that states the time
+    // The <time> element's id attribute (see Id.h). Only the measure that states the time
     // signature carries it; a measure that inherits the signature (isImplicit) has no id.
-    std::optional<std::string> id;
+    std::optional<Id> id;
 
     // Defaults to a simple, implicit 4/4.
     TimeChoice();
diff --git a/src/include/mx/api/TransposeData.h b/src/include/mx/api/TransposeData.h
index ac678af64..494a31e62 100644
--- a/src/include/mx/api/TransposeData.h
+++ b/src/include/mx/api/TransposeData.h
@@ -5,6 +5,7 @@
 #pragma once
 
 #include "mx/api/ApiCommon.h"
+#include "mx/api/Id.h"
 
 #include <optional>
 #include <string>
@@ -73,8 +74,8 @@ class TransposeData
     /// Supports a transposition change somewhere other than at the start of a measure.
     int tickTimePosition = 0;
 
-    /// The <transpose> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    /// The <transpose> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     /// If both chromatic and diatonic are zero, then TransposeData is unused (i.e. it need
     /// not be encoded in the MusicXML output).
diff --git a/src/include/mx/api/TupletData.h b/src/include/mx/api/TupletData.h
index 7868c564f..a6f1a73e0 100644
--- a/src/include/mx/api/TupletData.h
+++ b/src/include/mx/api/TupletData.h
@@ -6,6 +6,7 @@
 
 #include "mx/api/ApiCommon.h"
 #include "mx/api/DurationData.h"
+#include "mx/api/Id.h"
 #include "mx/api/LineData.h"
 #include "mx/api/PositionData.h"
 
@@ -49,8 +50,8 @@ class TupletStart
 
     Bool bracket;
 
-    // The <tuplet> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <tuplet> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     TupletStart()
         : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, positionData{}, actualNumber{VALUE_UNSPECIFIED},
@@ -71,8 +72,8 @@ class TupletStop
 
     PositionData positionData;
 
-    // The <tuplet> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <tuplet> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     TupletStop() : numberLevel{NUMBER_LEVEL_UNSPECIFIED}, positionData{}, id{}
     {
diff --git a/src/include/mx/api/WedgeData.h b/src/include/mx/api/WedgeData.h
index 505a465d8..dbdd5a4f0 100644
--- a/src/include/mx/api/WedgeData.h
+++ b/src/include/mx/api/WedgeData.h
@@ -6,6 +6,7 @@
 
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
+#include "mx/api/Id.h"
 #include "mx/api/LineData.h"
 #include "mx/api/PositionData.h"
 #include "mx/api/SpannerNumber.h"
@@ -35,8 +36,8 @@ struct WedgeStart
     bool isColorSpecified;
     ColorData colorData;
 
-    // The <wedge> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <wedge> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     WedgeStart()
         : number{}, wedgeType{WedgeType::unspecified}, isSpreadSpecified{false}, spread{0.0}, lineData{},
@@ -52,8 +53,8 @@ struct WedgeStop
     bool isSpreadSpecified;
     double spread;
 
-    // The <wedge> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <wedge> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     WedgeStop() : number{}, positionData{}, isSpreadSpecified{false}, spread{0.0}, id{}
     {
diff --git a/src/include/mx/api/WordsData.h b/src/include/mx/api/WordsData.h
index 11fb1a096..dcc868f88 100644
--- a/src/include/mx/api/WordsData.h
+++ b/src/include/mx/api/WordsData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
 #include <optional>
@@ -38,8 +39,8 @@ class WordsData
     // block against its anchor point; MusicXML defines both attributes on `<words>`.
     HorizontalAlignment justify;
 
-    // The <words> element's id attribute (see ApiCommon.h).
-    std::optional<std::string> id;
+    // The <words> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     WordsData()
         : text{}, positionData{}, fontData{}, isColorSpecified{false}, colorData{}, enclosure{Enclosure::unspecified},
diff --git a/src/private/mx/api/Id.cpp b/src/private/mx/api/Id.cpp
new file mode 100644
index 000000000..4d0fb41fe
--- /dev/null
+++ b/src/private/mx/api/Id.cpp
@@ -0,0 +1,100 @@
+// MusicXML Class Library
+// Copyright (c) by Matthew James Briggs
+// Distributed under the MIT License
+
+#include "mx/api/Id.h"
+
+#include "mx/api/IdAccess.h"
+
+#include <utility>
+
+namespace mx
+{
+namespace api
+{
+
+// core::Token is the type mx writes an id attribute with. It cannot hold text that breaks the XML
+// name rules, so an Id that holds one is valid for as long as it exists, and mx::impl hands the
+// token itself to mx::core rather than converting the text again.
+//
+// An Id never changes its token, so copies share one Impl instead of allocating another.
+class Id::Impl
+{
+  public:
+    explicit Impl(core::Token inToken) : token{std::move(inToken)}
+    {
+    }
+
+    // What a moved-from Id is left holding. An Id always holds an Impl, so reading one that has
+    // been moved from is harmless rather than undefined.
+    static const std::shared_ptr<const Impl> &movedFrom();
+
+    core::Token token;
+};
+
+const std::shared_ptr<const Id::Impl> &Id::Impl::movedFrom()
+{
+    static const std::shared_ptr<const Impl> value = std::make_shared<const Impl>(core::Token{});
+    return value;
+}
+
+Id::Id(std::string text) : myImpl{std::make_shared<const Impl>(core::Token{std::move(text)})}
+{
+}
+
+Id::Id(const char *text) : Id{std::string{text != nullptr ? text : ""}}
+{
+}
+
+Id::Id(std::shared_ptr<const Impl> impl) : myImpl{std::move(impl)}
+{
+}
+
+Id::Id(const Id &other) = default;
+
+Id::Id(Id &&other) noexcept : myImpl{std::move(other.myImpl)}
+{
+    other.myImpl = Impl::movedFrom();
+}
+
+Id &Id::operator=(const Id &other) = default;
+
+Id &Id::operator=(Id &&other) noexcept
+{
+    if (this != &other)
+    {
+        myImpl = std::move(other.myImpl);
+        other.myImpl = Impl::movedFrom();
+    }
+    return *this;
+}
+
+Id::~Id() = default;
+
+const std::string &Id::value() const
+{
+    return myImpl->token.value();
+}
+
+bool Id::operator==(const Id &other) const
+{
+    return myImpl == other.myImpl || myImpl->token == other.myImpl->token;
+}
+
+bool Id::operator<(const Id &other) const
+{
+    return myImpl->token.value() < other.myImpl->token.value();
+}
+
+const core::Token &IdAccess::token(const Id &inId)
+{
+    return inId.myImpl->token;
+}
+
+Id IdAccess::make(core::Token inToken)
+{
+    return Id{std::make_shared<const Id::Impl>(std::move(inToken))};
+}
+
+} // namespace api
+} // namespace mx
diff --git a/src/private/mx/api/IdAccess.h b/src/private/mx/api/IdAccess.h
new file mode 100644
index 000000000..004807ab0
--- /dev/null
+++ b/src/private/mx/api/IdAccess.h
@@ -0,0 +1,28 @@
+// MusicXML Class Library
+// Copyright (c) by Matthew James Briggs
+// Distributed under the MIT License
+
+#pragma once
+
+#include "mx/api/Id.h"
+#include "mx/core/Token.h"
+
+namespace mx
+{
+namespace api
+{
+
+// Reaches the core::Token that an api::Id holds. mx::impl uses this to carry an id between mx::api
+// and mx::core as a token, so the text is scrubbed when the Id is built and never again. This
+// header is private to mx and is not part of the public api.
+struct IdAccess
+{
+    // The token an Id holds. Pass it straight to a core element's setID.
+    static const core::Token &token(const Id &inId);
+
+    // An Id holding a token that mx::core already read from a file.
+    static Id make(core::Token inToken);
+};
+
+} // namespace api
+} // namespace mx
diff --git a/src/private/mx/impl/ArpeggiateFunctions.cpp b/src/private/mx/impl/ArpeggiateFunctions.cpp
index 79984af4c..d439b539f 100644
--- a/src/private/mx/impl/ArpeggiateFunctions.cpp
+++ b/src/private/mx/impl/ArpeggiateFunctions.cpp
@@ -5,6 +5,7 @@
 #include "mx/impl/ArpeggiateFunctions.h"
 #include "mx/core/generated/Arpeggiate.h"
 #include "mx/impl/Converter.h"
+#include "mx/impl/IdFunctions.h"
 #include "mx/impl/MarkDataFunctions.h"
 
 namespace mx
@@ -47,10 +48,7 @@ api::MarkData ArpeggiateFunctions::parseArpeggiate() const
         Converter converter;
         arpeggiateData.unbroken = converter.convert(*myArpeggiate.unbroken());
     }
-    if (myArpeggiate.id().has_value())
-    {
-        arpeggiateData.id = myArpeggiate.id()->value();
-    }
+    arpeggiateData.id = getId(myArpeggiate);
     markData.choice = arpeggiateData;
 
     return markData;
diff --git a/src/private/mx/impl/DirectionReader.cpp b/src/private/mx/impl/DirectionReader.cpp
index b24135e33..ee1920b5e 100644
--- a/src/private/mx/impl/DirectionReader.cpp
+++ b/src/private/mx/impl/DirectionReader.cpp
@@ -802,10 +802,7 @@ void DirectionReader::parseHarpPedals(const core::DirectionType &directionType)
     {
         outHarpPedals.color = getColor(harpPedals);
     }
-    if (harpPedals.id().has_value())
-    {
-        outHarpPedals.id = harpPedals.id()->value();
-    }
+    outHarpPedals.id = getId(harpPedals);
     myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outHarpPedals)});
 }
 
@@ -819,10 +816,7 @@ void DirectionReader::parseDamp(const core::DirectionType &directionType)
     {
         outDamp.color = getColor(damp);
     }
-    if (damp.id().has_value())
-    {
-        outDamp.id = damp.id()->value();
-    }
+    outDamp.id = getId(damp);
     myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outDamp)});
 }
 
@@ -836,10 +830,7 @@ void DirectionReader::parseDampAll(const core::DirectionType &directionType)
     {
         outDampAll.color = getColor(dampAll);
     }
-    if (dampAll.id().has_value())
-    {
-        outDampAll.id = dampAll.id()->value();
-    }
+    outDampAll.id = getId(dampAll);
     myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outDampAll)});
 }
 
@@ -853,10 +844,7 @@ void DirectionReader::parseEyeglasses(const core::DirectionType &directionType)
     {
         outEyeglasses.color = getColor(eyeglasses);
     }
-    if (eyeglasses.id().has_value())
-    {
-        outEyeglasses.id = eyeglasses.id()->value();
-    }
+    outEyeglasses.id = getId(eyeglasses);
     myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outEyeglasses)});
 }
 
@@ -872,10 +860,7 @@ void DirectionReader::parseStringMute(const core::DirectionType &directionType)
     {
         outStringMute.color = getColor(stringMute);
     }
-    if (stringMute.id().has_value())
-    {
-        outStringMute.id = stringMute.id()->value();
-    }
+    outStringMute.id = getId(stringMute);
     myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outStringMute)});
 }
 
@@ -902,10 +887,7 @@ void DirectionReader::parseStaffDivide(const core::DirectionType &directionType)
     {
         outStaffDivide.color = getColor(staffDivide);
     }
-    if (staffDivide.id().has_value())
-    {
-        outStaffDivide.id = staffDivide.id()->value();
-    }
+    outStaffDivide.id = getId(staffDivide);
     myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outStaffDivide)});
 }
 
@@ -931,10 +913,7 @@ void DirectionReader::parseScordatura(const core::DirectionType &directionType)
         outAccord.tuningOctave = accord.tuning().tuningOctave().value();
         outScordatura.accords.emplace_back(outAccord);
     }
-    if (scordatura.id().has_value())
-    {
-        outScordatura.id = scordatura.id()->value();
-    }
+    outScordatura.id = getId(scordatura);
     myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outScordatura)});
 }
 
@@ -976,10 +955,7 @@ void DirectionReader::parseImage(const core::DirectionType &directionType)
     {
         outImage.positionData.verticalAlignment = api::VerticalAlignment::unspecified;
     }
-    if (image.id().has_value())
-    {
-        outImage.id = image.id()->value();
-    }
+    outImage.id = getId(image);
     myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outImage)});
 }
 
@@ -1012,10 +988,7 @@ void DirectionReader::parsePrincipalVoice(const core::DirectionType &directionTy
     {
         outPrincipalVoice.color = getColor(principalVoice);
     }
-    if (principalVoice.id().has_value())
-    {
-        outPrincipalVoice.id = principalVoice.id()->value();
-    }
+    outPrincipalVoice.id = getId(principalVoice);
     myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outPrincipalVoice)});
 }
 
@@ -1035,10 +1008,7 @@ void DirectionReader::parseAccordionRegistration(const core::DirectionType &dire
     {
         outAccordion.color = getColor(accordion);
     }
-    if (accordion.id().has_value())
-    {
-        outAccordion.id = accordion.id()->value();
-    }
+    outAccordion.id = getId(accordion);
     myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outAccordion)});
 }
 
@@ -1169,10 +1139,7 @@ void DirectionReader::parsePercussion(const core::DirectionType &directionType)
         {
             outPercussion.color = getColor(percussion);
         }
-        if (percussion.id().has_value())
-        {
-            outPercussion.id = percussion.id()->value();
-        }
+        outPercussion.id = getId(percussion);
         myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outPercussion)});
     }
 }
@@ -1193,10 +1160,7 @@ void DirectionReader::parseOtherDirection(const core::DirectionType &directionTy
     {
         outOtherDirection.color = getColor(otherDirection);
     }
-    if (otherDirection.id().has_value())
-    {
-        outOtherDirection.id = otherDirection.id()->value();
-    }
+    outOtherDirection.id = getId(otherDirection);
     myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outOtherDirection)});
 }
 
diff --git a/src/private/mx/impl/DirectionWriter.cpp b/src/private/mx/impl/DirectionWriter.cpp
index dfeb9fefb..63fa15548 100644
--- a/src/private/mx/impl/DirectionWriter.cpp
+++ b/src/private/mx/impl/DirectionWriter.cpp
@@ -698,10 +698,7 @@ void DirectionWriter::emitTempo(const api::TempoData &tempo, core::Direction &di
     {
         setAttributesFromColorData(*tempo.color, metronome);
     }
-    if (tempo.id.has_value())
-    {
-        metronome.setID(core::Token{*tempo.id});
-    }
+    setId(tempo.id, metronome);
     if (tempo.justify != api::HorizontalAlignment::unspecified)
     {
         metronome.setJustify(myConverter.convert(tempo.justify));
@@ -868,7 +865,7 @@ void DirectionWriter::emitRehearsal(const api::RehearsalData &item, core::Direct
 core::EmptyPrintStyleAlignID DirectionWriter::createEmptyPrintStyleAlign(const api::PositionData &positionData,
                                                                          const api::FontData &fontData,
                                                                          const std::optional<api::ColorData> &color,
-                                                                         const std::optional<std::string> &id)
+                                                                         const std::optional<api::Id> &id)
 {
     core::EmptyPrintStyleAlignID element{};
     setAttributesFromPositionData(positionData, element);
@@ -877,10 +874,7 @@ core::EmptyPrintStyleAlignID DirectionWriter::createEmptyPrintStyleAlign(const a
     {
         setAttributesFromColorData(*color, element);
     }
-    if (id.has_value())
-    {
-        element.setID(core::Token{*id});
-    }
+    setId(id, element);
     return element;
 }
 
@@ -918,10 +912,7 @@ void DirectionWriter::emitStringMute(const api::StringMuteData &item, core::Dire
     {
         setAttributesFromColorData(*item.color, stringMute);
     }
-    if (item.id.has_value())
-    {
-        stringMute.setID(core::Token{*item.id});
-    }
+    setId(item.id, stringMute);
     core::DirectionType dt{};
     dt.setChoice(core::DirectionTypeChoice::stringMute(std::move(stringMute)));
     addDirectionType(std::move(dt), direction);
@@ -948,10 +939,7 @@ void DirectionWriter::emitStaffDivide(const api::StaffDivideData &item, core::Di
     {
         setAttributesFromColorData(*item.color, staffDivide);
     }
-    if (item.id.has_value())
-    {
-        staffDivide.setID(core::Token{*item.id});
-    }
+    setId(item.id, staffDivide);
     core::DirectionType dt{};
     dt.setChoice(core::DirectionTypeChoice::staffDivide(std::move(staffDivide)));
     addDirectionType(std::move(dt), direction);
@@ -984,10 +972,7 @@ void DirectionWriter::emitPrincipalVoice(const api::PrincipalVoiceData &item, co
     {
         setAttributesFromColorData(*item.color, principalVoice);
     }
-    if (item.id.has_value())
-    {
-        principalVoice.setID(core::Token{*item.id});
-    }
+    setId(item.id, principalVoice);
     core::DirectionType dt{};
     dt.setChoice(core::DirectionTypeChoice::principalVoice(std::move(principalVoice)));
     addDirectionType(std::move(dt), direction);
@@ -1011,10 +996,7 @@ void DirectionWriter::emitOtherDirection(const api::OtherDirectionData &item, co
     {
         setAttributesFromColorData(*item.color, otherDirection);
     }
-    if (item.id.has_value())
-    {
-        otherDirection.setID(core::Token{*item.id});
-    }
+    setId(item.id, otherDirection);
     core::DirectionType dt{};
     dt.setChoice(core::DirectionTypeChoice::otherDirection(std::move(otherDirection)));
     addDirectionType(std::move(dt), direction);
@@ -1053,10 +1035,7 @@ void DirectionWriter::emitImage(const api::ImageData &item, core::Direction &dir
     default:
         break;
     }
-    if (item.id.has_value())
-    {
-        image.setID(core::Token{*item.id});
-    }
+    setId(item.id, image);
     core::DirectionType dt{};
     dt.setChoice(core::DirectionTypeChoice::image(std::move(image)));
     addDirectionType(std::move(dt), direction);
@@ -1077,10 +1056,7 @@ void DirectionWriter::emitAccordionRegistration(const api::AccordionRegistration
     {
         setAttributesFromColorData(*item.color, accordion);
     }
-    if (item.id.has_value())
-    {
-        accordion.setID(core::Token{*item.id});
-    }
+    setId(item.id, accordion);
     core::DirectionType dt{};
     dt.setChoice(core::DirectionTypeChoice::accordionRegistration(std::move(accordion)));
     addDirectionType(std::move(dt), direction);
@@ -1118,10 +1094,7 @@ void DirectionWriter::emitHarpPedals(const api::HarpPedalsData &item, core::Dire
     {
         setAttributesFromColorData(*item.color, harpPedals);
     }
-    if (item.id.has_value())
-    {
-        harpPedals.setID(core::Token{*item.id});
-    }
+    setId(item.id, harpPedals);
     core::DirectionType dt{};
     dt.setChoice(core::DirectionTypeChoice::harpPedals(std::move(harpPedals)));
     addDirectionType(std::move(dt), direction);
@@ -1163,10 +1136,7 @@ void DirectionWriter::emitScordatura(const api::ScordaturaData &item, core::Dire
             scordatura.addAccord(std::move(accord));
         }
     }
-    if (item.id.has_value())
-    {
-        scordatura.setID(core::Token{*item.id});
-    }
+    setId(item.id, scordatura);
     core::DirectionType dt{};
     dt.setChoice(core::DirectionTypeChoice::scordatura(std::move(scordatura)));
     addDirectionType(std::move(dt), direction);
@@ -1296,10 +1266,7 @@ void DirectionWriter::emitPercussion(const api::PercussionData &item, core::Dire
     {
         setAttributesFromColorData(*item.color, percussion);
     }
-    if (item.id.has_value())
-    {
-        percussion.setID(core::Token{*item.id});
-    }
+    setId(item.id, percussion);
     core::DirectionType dt{};
     dt.setChoice(core::DirectionTypeChoice::percussion(core::OneOrMore<core::Percussion>{std::move(percussion)}));
     addDirectionType(std::move(dt), direction);
diff --git a/src/private/mx/impl/DirectionWriter.h b/src/private/mx/impl/DirectionWriter.h
index cb585d9aa..c8aad4eff 100644
--- a/src/private/mx/impl/DirectionWriter.h
+++ b/src/private/mx/impl/DirectionWriter.h
@@ -58,7 +58,7 @@ class DirectionWriter
     core::EmptyPrintStyleAlignID createEmptyPrintStyleAlign(const api::PositionData &positionData,
                                                             const api::FontData &fontData,
                                                             const std::optional<api::ColorData> &color,
-                                                            const std::optional<std::string> &id);
+                                                            const std::optional<api::Id> &id);
     void emitDamp(const api::DampData &item, core::Direction &direction);
     void emitDampAll(const api::DampAllData &item, core::Direction &direction);
     void emitEyeglasses(const api::EyeglassesData &item, core::Direction &direction);
diff --git a/src/private/mx/impl/IdFunctions.h b/src/private/mx/impl/IdFunctions.h
index d3cda7b7c..42f49da50 100644
--- a/src/private/mx/impl/IdFunctions.h
+++ b/src/private/mx/impl/IdFunctions.h
@@ -4,33 +4,34 @@
 
 #pragma once
 
-#include "mx/core/Token.h"
+#include "mx/api/Id.h"
+#include "mx/api/IdAccess.h"
 
 #include <optional>
-#include <string>
 
 namespace mx
 {
 namespace impl
 {
-// Read the id attribute from any core element that has one. Absent stays absent.
-template <typename CORE_TYPE> std::optional<std::string> getId(const CORE_TYPE &inCoreElement)
+// Read the id attribute from any core element that has one. Absent stays absent. The token moves
+// across as a token, so the text is not scrubbed again.
+template <typename CORE_TYPE> std::optional<api::Id> getId(const CORE_TYPE &inCoreElement)
 {
     if (!inCoreElement.id().has_value())
     {
         return std::nullopt;
     }
 
-    return inCoreElement.id()->value();
+    return api::IdAccess::make(*inCoreElement.id());
 }
 
-// Write the id attribute onto any core element that has one. An absent or empty id writes no
-// attribute. core::Token repairs an id that is not a valid XML name.
-template <typename CORE_TYPE> void setId(const std::optional<std::string> &inId, CORE_TYPE &outCoreElement)
+// Write the id attribute onto any core element that has one. An absent id writes no attribute. The
+// element receives the token the Id already holds, so the text is not scrubbed again.
+template <typename CORE_TYPE> void setId(const std::optional<api::Id> &inId, CORE_TYPE &outCoreElement)
 {
-    if (inId.has_value() && !inId->empty())
+    if (inId.has_value())
     {
-        outCoreElement.setID(core::Token{*inId});
+        outCoreElement.setID(api::IdAccess::token(*inId));
     }
 }
 } // namespace impl
diff --git a/src/private/mx/impl/MetronomeReader.cpp b/src/private/mx/impl/MetronomeReader.cpp
index 0efdcc41a..c03ccf55d 100644
--- a/src/private/mx/impl/MetronomeReader.cpp
+++ b/src/private/mx/impl/MetronomeReader.cpp
@@ -23,6 +23,7 @@
 #include "mx/core/generated/TimeModificationGroup.h"
 #include "mx/impl/Converter.h"
 #include "mx/impl/FontFunctions.h"
+#include "mx/impl/IdFunctions.h"
 #include "mx/impl/PositionFunctions.h"
 #include "mx/impl/PrintFunctions.h"
 
@@ -138,10 +139,7 @@ api::TempoData MetronomeReader::getTempoData() const
     {
         myOutTempoData.color = getColor(myMetronome);
     }
-    if (myMetronome.id().has_value())
-    {
-        myOutTempoData.id = myMetronome.id()->value();
-    }
+    myOutTempoData.id = getId(myMetronome);
     if (myMetronome.justify().has_value())
     {
         myOutTempoData.justify = converter.convert(*myMetronome.justify());
diff --git a/src/private/mx/impl/NonArpeggiateFunctions.cpp b/src/private/mx/impl/NonArpeggiateFunctions.cpp
index c78e957ac..8e2d4b209 100644
--- a/src/private/mx/impl/NonArpeggiateFunctions.cpp
+++ b/src/private/mx/impl/NonArpeggiateFunctions.cpp
@@ -4,6 +4,7 @@
 
 #include "mx/impl/NonArpeggiateFunctions.h"
 #include "mx/core/generated/NonArpeggiate.h"
+#include "mx/impl/IdFunctions.h"
 #include "mx/impl/MarkDataFunctions.h"
 
 namespace mx
@@ -30,10 +31,7 @@ api::MarkData NonArpeggiateFunctions::parseNonArpeggiate() const
     {
         nonArpeggiateData.number = myNonArpeggiate.number()->value();
     }
-    if (myNonArpeggiate.id().has_value())
-    {
-        nonArpeggiateData.id = myNonArpeggiate.id()->value();
-    }
+    nonArpeggiateData.id = getId(myNonArpeggiate);
     markData.choice = nonArpeggiateData;
 
     return markData;
diff --git a/src/private/mx/impl/NotationsWriter.cpp b/src/private/mx/impl/NotationsWriter.cpp
index f79da2233..2e97934d9 100644
--- a/src/private/mx/impl/NotationsWriter.cpp
+++ b/src/private/mx/impl/NotationsWriter.cpp
@@ -375,10 +375,7 @@ core::Notations NotationsWriter::getNotations() const
             {
                 nonArpeggiate.setNumber(core::NumberLevel{*nonArpeggiateData.number});
             }
-            if (nonArpeggiateData.id.has_value())
-            {
-                nonArpeggiate.setID(core::Token{*nonArpeggiateData.id});
-            }
+            setId(nonArpeggiateData.id, nonArpeggiate);
 
             outNotations.addChoice(core::NotationsChoice::nonArpeggiate(nonArpeggiate));
         }
@@ -410,10 +407,7 @@ core::Notations NotationsWriter::getNotations() const
                 Converter converter;
                 arpeggiate.setUnbroken(converter.convert(arpeggiateData.unbroken));
             }
-            if (arpeggiateData.id.has_value())
-            {
-                arpeggiate.setID(core::Token{*arpeggiateData.id});
-            }
+            setId(arpeggiateData.id, arpeggiate);
 
             outNotations.addChoice(core::NotationsChoice::arpeggiate(arpeggiate));
         }
@@ -433,10 +427,7 @@ core::Notations NotationsWriter::getNotations() const
             {
                 other.setSmufl(core::SmuflGlyphName{*payload.smufl});
             }
-            if (payload.id.has_value())
-            {
-                other.setID(core::Token{*payload.id});
-            }
+            setId(payload.id, other);
 
             outNotations.addChoice(core::NotationsChoice::otherNotation(other));
         }
diff --git a/src/private/mx/impl/NoteFunctions.cpp b/src/private/mx/impl/NoteFunctions.cpp
index 705c715df..28b95c9f2 100644
--- a/src/private/mx/impl/NoteFunctions.cpp
+++ b/src/private/mx/impl/NoteFunctions.cpp
@@ -316,10 +316,7 @@ void NoteFunctions::parseNotations() const
                 {
                     payload.smufl = other.smufl()->toString();
                 }
-                if (other.id().has_value())
-                {
-                    payload.id = other.id()->value();
-                }
+                payload.id = getId(other);
                 mark.choice = std::move(payload);
                 myOutNoteData.noteAttachmentData.marks.emplace_back(std::move(mark));
                 break;
diff --git a/src/private/mxtest/api/IdAttributeApiTest.cpp b/src/private/mxtest/api/IdAttributeApiTest.cpp
index c9d3ed7eb..4e6adf068 100644
--- a/src/private/mxtest/api/IdAttributeApiTest.cpp
+++ b/src/private/mxtest/api/IdAttributeApiTest.cpp
@@ -11,6 +11,9 @@
 #include "mxtest/api/RoundTrip.h"
 #include "mxtest/api/TestHelpers.h"
 
+#include <map>
+#include <unordered_map>
+
 using namespace std;
 using namespace mx::api;
 using namespace mxtest;
@@ -60,6 +63,12 @@ static const NoteData &idAttributeNote(const ScoreData &score)
     return idAttributeMeasure(score).staves.back().voices.at(0).notes.back();
 }
 
+// The text of an id, or an empty string when there is none.
+static std::string idAttributeText(const std::optional<Id> &id)
+{
+    return id.has_value() ? id->value() : std::string{};
+}
+
 // The <note> id, the reason for issue 399, plus the <measure> and <lyric> ids around it.
 TEST(noteMeasureAndLyricIds, IdAttribute)
 {
@@ -78,12 +87,12 @@ TEST(noteMeasureAndLyricIds, IdAttribute)
     CHECK(xml.find("id=\"n1\"") != std::string::npos);
 
     const auto out = roundTrip(score);
-    CHECK(std::optional<std::string>{"m1"} == idAttributeMeasure(out).id);
+    CHECK_EQUAL("m1", idAttributeText(idAttributeMeasure(out).id));
 
     const auto &onote = idAttributeNote(out);
-    CHECK(std::optional<std::string>{"n1"} == onote.id);
+    CHECK_EQUAL("n1", idAttributeText(onote.id));
     REQUIRE(onote.lyrics.size() == 1);
-    CHECK(std::optional<std::string>{"ly1"} == onote.lyrics.front().id);
+    CHECK_EQUAL("ly1", idAttributeText(onote.lyrics.front().id));
 }
 
 T_END;
@@ -122,15 +131,15 @@ TEST(attributesAndBarlineIds, IdAttribute)
     const auto out = roundTrip(score);
     const auto &omeasure = idAttributeMeasure(out);
 
-    CHECK(std::optional<std::string>{"t1"} == omeasure.timeSignature.id);
+    CHECK_EQUAL("t1", idAttributeText(omeasure.timeSignature.id));
     REQUIRE(omeasure.keys.size() == 1);
-    CHECK(std::optional<std::string>{"k1"} == omeasure.keys.front().id);
+    CHECK_EQUAL("k1", idAttributeText(omeasure.keys.front().id));
     REQUIRE(omeasure.staves.back().clefs.size() == 1);
-    CHECK(std::optional<std::string>{"c1"} == omeasure.staves.back().clefs.front().id);
+    CHECK_EQUAL("c1", idAttributeText(omeasure.staves.back().clefs.front().id));
     REQUIRE(omeasure.transpositions.size() == 1);
-    CHECK(std::optional<std::string>{"x1"} == omeasure.transpositions.front().id);
+    CHECK_EQUAL("x1", idAttributeText(omeasure.transpositions.front().id));
     REQUIRE(omeasure.barlines.size() == 1);
-    CHECK(std::optional<std::string>{"b1"} == omeasure.barlines.front().id);
+    CHECK_EQUAL("b1", idAttributeText(omeasure.barlines.front().id));
 }
 
 T_END;
@@ -152,7 +161,7 @@ TEST(inheritedTimeSignatureHasNoId, IdAttribute)
 
     const auto out = roundTrip(score);
     REQUIRE(out.parts.back().measures.size() == 2);
-    CHECK(std::optional<std::string>{"t1"} == out.parts.back().measures.front().timeSignature.id);
+    CHECK_EQUAL("t1", idAttributeText(out.parts.back().measures.front().timeSignature.id));
     CHECK(!out.parts.back().measures.back().timeSignature.id.has_value());
 }
 
@@ -217,17 +226,17 @@ TEST(directionIds, IdAttribute)
     REQUIRE(odirections.size() == 1);
     const auto &odirection = odirections.front();
 
-    CHECK(std::optional<std::string>{"d1"} == odirection.id);
-    CHECK(std::optional<std::string>{"so1"} == odirection.soundData.id);
+    CHECK_EQUAL("d1", idAttributeText(odirection.id));
+    CHECK_EQUAL("so1", idAttributeText(odirection.soundData.id));
 
-    std::optional<std::string> foundWords;
-    std::optional<std::string> foundSymbol;
-    std::optional<std::string> foundRehearsal;
-    std::optional<std::string> foundWedge;
-    std::optional<std::string> foundBracket;
-    std::optional<std::string> foundDashes;
-    std::optional<std::string> foundOttava;
-    std::optional<std::string> foundPedal;
+    std::optional<Id> foundWords;
+    std::optional<Id> foundSymbol;
+    std::optional<Id> foundRehearsal;
+    std::optional<Id> foundWedge;
+    std::optional<Id> foundBracket;
+    std::optional<Id> foundDashes;
+    std::optional<Id> foundOttava;
+    std::optional<Id> foundPedal;
 
     for (const auto &choice : odirection.directionTypes)
     {
@@ -269,14 +278,14 @@ TEST(directionIds, IdAttribute)
         }
     }
 
-    CHECK(std::optional<std::string>{"w1"} == foundWords);
-    CHECK(std::optional<std::string>{"sy1"} == foundSymbol);
-    CHECK(std::optional<std::string>{"r1"} == foundRehearsal);
-    CHECK(std::optional<std::string>{"we1"} == foundWedge);
-    CHECK(std::optional<std::string>{"br1"} == foundBracket);
-    CHECK(std::optional<std::string>{"da1"} == foundDashes);
-    CHECK(std::optional<std::string>{"o1"} == foundOttava);
-    CHECK(std::optional<std::string>{"p1"} == foundPedal);
+    CHECK_EQUAL("w1", idAttributeText(foundWords));
+    CHECK_EQUAL("sy1", idAttributeText(foundSymbol));
+    CHECK_EQUAL("r1", idAttributeText(foundRehearsal));
+    CHECK_EQUAL("we1", idAttributeText(foundWedge));
+    CHECK_EQUAL("br1", idAttributeText(foundBracket));
+    CHECK_EQUAL("da1", idAttributeText(foundDashes));
+    CHECK_EQUAL("o1", idAttributeText(foundOttava));
+    CHECK_EQUAL("p1", idAttributeText(foundPedal));
 }
 
 T_END;
@@ -321,17 +330,17 @@ TEST(notationIds, IdAttribute)
     REQUIRE(onotes.size() == 2);
 
     REQUIRE(onotes.front().noteAttachmentData.curveStarts.size() == 1);
-    CHECK(std::optional<std::string>{"s1"} == onotes.front().noteAttachmentData.curveStarts.front().id);
+    CHECK_EQUAL("s1", idAttributeText(onotes.front().noteAttachmentData.curveStarts.front().id));
     REQUIRE(onotes.back().noteAttachmentData.curveStops.size() == 1);
-    CHECK(std::optional<std::string>{"s2"} == onotes.back().noteAttachmentData.curveStops.front().id);
+    CHECK_EQUAL("s2", idAttributeText(onotes.back().noteAttachmentData.curveStops.front().id));
 
     REQUIRE(onotes.front().noteAttachmentData.tupletStarts.size() == 1);
-    CHECK(std::optional<std::string>{"tu1"} == onotes.front().noteAttachmentData.tupletStarts.front().id);
+    CHECK_EQUAL("tu1", idAttributeText(onotes.front().noteAttachmentData.tupletStarts.front().id));
     REQUIRE(onotes.back().noteAttachmentData.tupletStops.size() == 1);
-    CHECK(std::optional<std::string>{"tu2"} == onotes.back().noteAttachmentData.tupletStops.front().id);
+    CHECK_EQUAL("tu2", idAttributeText(onotes.back().noteAttachmentData.tupletStops.front().id));
 
     REQUIRE(onotes.back().tieLetRing.has_value());
-    CHECK(std::optional<std::string>{"lr1"} == onotes.back().tieLetRing->id);
+    CHECK_EQUAL("lr1", idAttributeText(onotes.back().tieLetRing->id));
 }
 
 T_END;
@@ -359,7 +368,7 @@ TEST(figuredBassId, IdAttribute)
     const auto &odirections = idAttributeMeasure(out).staves.back().directions;
     REQUIRE(odirections.size() == 1);
     REQUIRE(odirections.front().figuredBasses.size() == 1);
-    CHECK(std::optional<std::string>{"fb1"} == odirections.front().figuredBasses.front().id);
+    CHECK_EQUAL("fb1", idAttributeText(odirections.front().figuredBasses.front().id));
 }
 
 T_END;
@@ -410,18 +419,120 @@ TEST(idsAreReadFromSourceXml, IdAttribute)
     REQUIRE(score.parts.size() == 1);
     const auto &measure = score.parts.front().measures.front();
 
-    CHECK(std::optional<std::string>{"m1"} == measure.id);
-    CHECK(std::optional<std::string>{"t1"} == measure.timeSignature.id);
+    CHECK_EQUAL("m1", idAttributeText(measure.id));
+    CHECK_EQUAL("t1", idAttributeText(measure.timeSignature.id));
     REQUIRE(measure.keys.size() == 1);
-    CHECK(std::optional<std::string>{"k1"} == measure.keys.front().id);
+    CHECK_EQUAL("k1", idAttributeText(measure.keys.front().id));
     REQUIRE(measure.staves.front().clefs.size() == 1);
-    CHECK(std::optional<std::string>{"c1"} == measure.staves.front().clefs.front().id);
+    CHECK_EQUAL("c1", idAttributeText(measure.staves.front().clefs.front().id));
     REQUIRE(measure.barlines.size() == 1);
-    CHECK(std::optional<std::string>{"b1"} == measure.barlines.front().id);
+    CHECK_EQUAL("b1", idAttributeText(measure.barlines.front().id));
 
     const auto &notes = measure.staves.front().voices.at(0).notes;
     REQUIRE(notes.size() == 1);
-    CHECK(std::optional<std::string>{"n1"} == notes.front().id);
+    CHECK_EQUAL("n1", idAttributeText(notes.front().id));
+}
+
+T_END;
+
+// An id that breaks the XML name rules is scrubbed as the Id is built, so the api and the file
+// always hold the same text.
+TEST(idsAreScrubbedWhenBuilt, IdAttribute)
+{
+    CHECK_EQUAL("n1", Id{"n1"}.value());
+    CHECK_EQUAL("measure-1.a_b", Id{"measure-1.a_b"}.value());
+
+    // Characters the rules do not allow are dropped.
+    CHECK_EQUAL("blindmice", Id{"3 blind mice"}.value());
+
+    // An id cannot start with a digit, a hyphen, or a dot.
+    CHECK_EQUAL("abc", Id{"1abc"}.value());
+    CHECK_EQUAL("abc", Id{"-abc"}.value());
+
+    // Nothing usable left, so the id becomes "X".
+    CHECK_EQUAL("X", Id{""}.value());
+    CHECK_EQUAL("X", Id{"!!!"}.value());
+}
+
+T_END;
+
+// Compare the id you built with the text you gave it to find out whether the text was legal.
+TEST(scrubbingIsVisibleToTheCaller, IdAttribute)
+{
+    const std::string wanted = "3 blind mice";
+    const auto id = Id{wanted};
+    CHECK(id.value() != wanted);
+
+    const std::string legal = "n1";
+    CHECK(Id{legal}.value() == legal);
+}
+
+T_END;
+
+// A scrubbed id reaches the file scrubbed, and reads back the same way.
+TEST(scrubbedIdRoundTrips, IdAttribute)
+{
+    auto score = idAttributeMakeScore();
+    idAttributeNote(score).id = "3 blind mice";
+
+    const auto xml = toXml(score);
+    CHECK(xml.find("id=\"blindmice\"") != std::string::npos);
+
+    const auto out = roundTrip(score);
+    CHECK_EQUAL("blindmice", idAttributeText(idAttributeNote(out).id));
+}
+
+T_END;
+
+// Id behaves like any other value: copy it, assign it, compare it, sort it, hash it.
+TEST(idBehavesLikeAValue, IdAttribute)
+{
+    const Id first{"n1"};
+    const Id copy = first;
+    CHECK(first == copy);
+    CHECK(!(first != copy));
+
+    Id assigned{"other"};
+    assigned = first;
+    CHECK(first == assigned);
+    CHECK_EQUAL("n1", assigned.value());
+
+    // Assigning does not tie the two together.
+    assigned = Id{"n2"};
+    CHECK_EQUAL("n1", first.value());
+    CHECK(first != assigned);
+
+    // Equality is by text, not by where the id came from.
+    CHECK(Id{"n1"} == Id{"n1"});
+    CHECK(Id{"n1"} != Id{"n2"});
+
+    // Ordering is by text.
+    CHECK(Id{"a"} < Id{"b"});
+    CHECK(Id{"b"} > Id{"a"});
+    CHECK(Id{"a"} <= Id{"a"});
+    CHECK(Id{"a"} >= Id{"a"});
+
+    // Equal ids hash the same.
+    const std::hash<Id> hasher;
+    CHECK(hasher(Id{"n1"}) == hasher(copy));
+
+    // So an Id works as a key in either kind of map.
+    std::map<Id, int> ordered;
+    ordered[Id{"n2"}] = 2;
+    ordered[Id{"n1"}] = 1;
+    REQUIRE(ordered.size() == 2);
+    CHECK_EQUAL("n1", ordered.begin()->first.value());
+    CHECK_EQUAL(1, ordered.at(Id{"n1"}));
+
+    std::unordered_map<Id, int> hashed;
+    hashed[Id{"n1"}] = 1;
+    CHECK_EQUAL(1, hashed.at(Id{"n1"}));
+
+    // A moved-from Id is still readable.
+    Id source{"n3"};
+    const Id moved = std::move(source);
+    CHECK_EQUAL("n3", moved.value());
+    CHECK(!source.value().empty());
 }
 
 T_END;

From e06e4ba391597920fe0e449248c25ec34bbf35a2 Mon Sep 17 00:00:00 2001
From: Matthew James Briggs <matthew.james.briggs@gmail.com>
Date: Thu, 20 Aug 2026 14:50:31 +0000
Subject: [PATCH 2/2] feat: give SegnoData and CodaData the api::Id treatment

These two were the last api types spelling an id as a std::string plus an
isIdSpecified flag. Every other id in mx::api is now a std::optional<api::Id>,
so leaving these on the old pattern would mean two ways to say one thing.

Replace the pair with std::optional<Id>, drop isIdSpecified from the equality
block, and route the reader and writer through getId and setId like the rest.

The api-level direction test now covers the <segno> and <coda> ids alongside the
other direction-type ids.
---
 src/include/mx/api/CodaData.h                  | 11 ++++++-----
 src/include/mx/api/SegnoData.h                 | 11 ++++++-----
 src/private/mx/impl/DirectionReader.cpp        | 12 ++----------
 src/private/mx/impl/DirectionWriter.cpp        | 10 ++--------
 src/private/mxtest/api/IdAttributeApiTest.cpp  | 18 ++++++++++++++++++
 .../mxtest/impl/DirectionWriterTest.cpp        |  2 --
 6 files changed, 34 insertions(+), 30 deletions(-)

diff --git a/src/include/mx/api/CodaData.h b/src/include/mx/api/CodaData.h
index b85cdbdf9..1a18b7177 100644
--- a/src/include/mx/api/CodaData.h
+++ b/src/include/mx/api/CodaData.h
@@ -7,8 +7,10 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
+#include <optional>
 #include <string>
 
 namespace mx
@@ -28,12 +30,12 @@ class CodaData
     ColorData colorData;
     bool isSmuflSpecified;
     std::string smufl;
-    bool isIdSpecified;
-    std::string id;
+
+    // The <coda> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     CodaData()
-        : positionData{}, fontData{}, isColorSpecified{false}, colorData{}, isSmuflSpecified{false}, smufl{},
-          isIdSpecified{false}, id{}
+        : positionData{}, fontData{}, isColorSpecified{false}, colorData{}, isSmuflSpecified{false}, smufl{}, id{}
     {
     }
 };
@@ -45,7 +47,6 @@ MXAPI_EQUALS_MEMBER(isColorSpecified)
 MXAPI_EQUALS_MEMBER(colorData)
 MXAPI_EQUALS_MEMBER(isSmuflSpecified)
 MXAPI_EQUALS_MEMBER(smufl)
-MXAPI_EQUALS_MEMBER(isIdSpecified)
 MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(CodaData);
diff --git a/src/include/mx/api/SegnoData.h b/src/include/mx/api/SegnoData.h
index 520d83c4a..880932d9c 100644
--- a/src/include/mx/api/SegnoData.h
+++ b/src/include/mx/api/SegnoData.h
@@ -7,8 +7,10 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/ColorData.h"
 #include "mx/api/FontData.h"
+#include "mx/api/Id.h"
 #include "mx/api/PositionData.h"
 
+#include <optional>
 #include <string>
 
 namespace mx
@@ -28,12 +30,12 @@ class SegnoData
     ColorData colorData;
     bool isSmuflSpecified;
     std::string smufl;
-    bool isIdSpecified;
-    std::string id;
+
+    // The <segno> element's id attribute (see Id.h).
+    std::optional<Id> id;
 
     SegnoData()
-        : positionData{}, fontData{}, isColorSpecified{false}, colorData{}, isSmuflSpecified{false}, smufl{},
-          isIdSpecified{false}, id{}
+        : positionData{}, fontData{}, isColorSpecified{false}, colorData{}, isSmuflSpecified{false}, smufl{}, id{}
     {
     }
 };
@@ -45,7 +47,6 @@ MXAPI_EQUALS_MEMBER(isColorSpecified)
 MXAPI_EQUALS_MEMBER(colorData)
 MXAPI_EQUALS_MEMBER(isSmuflSpecified)
 MXAPI_EQUALS_MEMBER(smufl)
-MXAPI_EQUALS_MEMBER(isIdSpecified)
 MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(SegnoData);
diff --git a/src/private/mx/impl/DirectionReader.cpp b/src/private/mx/impl/DirectionReader.cpp
index ee1920b5e..107a1c0de 100644
--- a/src/private/mx/impl/DirectionReader.cpp
+++ b/src/private/mx/impl/DirectionReader.cpp
@@ -393,11 +393,7 @@ void DirectionReader::parseSegno(const core::DirectionType &directionType)
             outSegno.isSmuflSpecified = true;
             outSegno.smufl = segno.smufl()->toString();
         }
-        if (segno.id().has_value())
-        {
-            outSegno.isIdSpecified = true;
-            outSegno.id = segno.id()->value();
-        }
+        outSegno.id = getId(segno);
         myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outSegno)});
     }
 }
@@ -482,11 +478,7 @@ void DirectionReader::parseCoda(const core::DirectionType &directionType)
             outCoda.isSmuflSpecified = true;
             outCoda.smufl = coda.smufl()->toString();
         }
-        if (coda.id().has_value())
-        {
-            outCoda.isIdSpecified = true;
-            outCoda.id = coda.id()->value();
-        }
+        outCoda.id = getId(coda);
         myOutDirectionData.directionTypes.emplace_back(api::DirectionChoice{std::move(outCoda)});
     }
 }
diff --git a/src/private/mx/impl/DirectionWriter.cpp b/src/private/mx/impl/DirectionWriter.cpp
index 63fa15548..ac816db8c 100644
--- a/src/private/mx/impl/DirectionWriter.cpp
+++ b/src/private/mx/impl/DirectionWriter.cpp
@@ -807,10 +807,7 @@ void DirectionWriter::emitSegno(const api::SegnoData &item, core::Direction &dir
     {
         segno.setSmufl(core::SmuflSegnoGlyphName::parse(item.smufl));
     }
-    if (item.isIdSpecified)
-    {
-        segno.setID(core::Token{item.id});
-    }
+    setId(item.id, segno);
     core::DirectionType dt{};
     dt.setChoice(core::DirectionTypeChoice::segno(core::OneOrMore<core::Segno>{std::move(segno)}));
     addDirectionType(std::move(dt), direction);
@@ -829,10 +826,7 @@ void DirectionWriter::emitCoda(const api::CodaData &item, core::Direction &direc
     {
         coda.setSmufl(core::SmuflCodaGlyphName::parse(item.smufl));
     }
-    if (item.isIdSpecified)
-    {
-        coda.setID(core::Token{item.id});
-    }
+    setId(item.id, coda);
     core::DirectionType dt{};
     dt.setChoice(core::DirectionTypeChoice::coda(core::OneOrMore<core::Coda>{std::move(coda)}));
     addDirectionType(std::move(dt), direction);
diff --git a/src/private/mxtest/api/IdAttributeApiTest.cpp b/src/private/mxtest/api/IdAttributeApiTest.cpp
index 4e6adf068..ea70b8057 100644
--- a/src/private/mxtest/api/IdAttributeApiTest.cpp
+++ b/src/private/mxtest/api/IdAttributeApiTest.cpp
@@ -215,6 +215,14 @@ TEST(directionIds, IdAttribute)
     pedal.id = "p1";
     direction.directionTypes.emplace_back(DirectionChoice{pedal});
 
+    SegnoData segno;
+    segno.id = "sg1";
+    direction.directionTypes.emplace_back(DirectionChoice{segno});
+
+    CodaData coda;
+    coda.id = "co1";
+    direction.directionTypes.emplace_back(DirectionChoice{coda});
+
     direction.isSoundDataSpecified = true;
     direction.soundData.tempo = 120.0;
     direction.soundData.id = "so1";
@@ -237,6 +245,8 @@ TEST(directionIds, IdAttribute)
     std::optional<Id> foundDashes;
     std::optional<Id> foundOttava;
     std::optional<Id> foundPedal;
+    std::optional<Id> foundSegno;
+    std::optional<Id> foundCoda;
 
     for (const auto &choice : odirection.directionTypes)
     {
@@ -273,6 +283,12 @@ TEST(directionIds, IdAttribute)
         case DirectionChoice::Kind::pedal:
             foundPedal = choice.pedal().id;
             break;
+        case DirectionChoice::Kind::segno:
+            foundSegno = choice.segno().id;
+            break;
+        case DirectionChoice::Kind::coda:
+            foundCoda = choice.coda().id;
+            break;
         default:
             break;
         }
@@ -286,6 +302,8 @@ TEST(directionIds, IdAttribute)
     CHECK_EQUAL("da1", idAttributeText(foundDashes));
     CHECK_EQUAL("o1", idAttributeText(foundOttava));
     CHECK_EQUAL("p1", idAttributeText(foundPedal));
+    CHECK_EQUAL("sg1", idAttributeText(foundSegno));
+    CHECK_EQUAL("co1", idAttributeText(foundCoda));
 }
 
 T_END;
diff --git a/src/private/mxtest/impl/DirectionWriterTest.cpp b/src/private/mxtest/impl/DirectionWriterTest.cpp
index 4b41145f5..504088db4 100644
--- a/src/private/mxtest/impl/DirectionWriterTest.cpp
+++ b/src/private/mxtest/impl/DirectionWriterTest.cpp
@@ -140,7 +140,6 @@ TEST(segnoAndCodaRoundTrip, DirectionWriter)
     segno.colorData.alpha = 255;
     segno.isSmuflSpecified = true;
     segno.smufl = "segno";
-    segno.isIdSpecified = true;
     segno.id = "id3";
 
     api::CodaData coda;
@@ -157,7 +156,6 @@ TEST(segnoAndCodaRoundTrip, DirectionWriter)
     coda.colorData.blue = 56;
     coda.isSmuflSpecified = true;
     coda.smufl = "coda";
-    coda.isIdSpecified = true;
     coda.id = "id7";
 
     api::DirectionData directionData;