Single source of truth for metadata

[infojunkie]

The existence of 3 manually-maintained metadata files is a source of inconsistency and human error. There are documented cases such as #322, #290, #196, #193 .

Typically, such issues would be addressed with a "single source of truth" approach, where these 3 currently unrelated files would be unified. This can take many shapes:

• A single JSON where the proper hierarchy is expressed. From my limited understanding, this would be ranges => glyphnanes, with classes expressed as a list attribute of glyphnames. This approach still risks that duplicate classes be mistyped.
• A single JSON with JSON schema support (see Proposal / Feature Request: JSON Schema for SMuFL Metadata files #313) where classes can be defined separately and referenced by glyphnames.
• A relational database (e.g. SQLite) where the 3 files would be represented as tables, with foreign keys and referential integrity constraints added to ensure consistency.

It would still be possible to retrieve the current JSON files from whatever format is chosen, by crafting the corresponding queries (e.g. jq for JSON, SQL for SQLite) that recreate these files from the source. It also would provide a template for other application-specific queries, e.g. listing the glyph names of accidentals.

[knutnergaard]

It’s not entirely clear to me how a single metadata source, by itself, would reduce the risk of human error compared to the current structure. Would the proposal rely on additional validation or constraints beyond simply merging the files?

Since restructuring the metadata would represent a significant breaking change to the spec – and given that several of the inconsistencies reported so far stem from discrepancies between SMuFL and its reference font Bravura – it might be more effective to address this at the process level rather than the data structure level.

In particular, a more symbiotic validation workflow between the SMuFL metadata and Bravura could help catch these issues early. For example, introducing a validation step in CI that checks cross-file and cross-repository consistency would directly target the kinds of errors seen in the linked issues, without requiring structural changes to the spec.

This kind of validation could be implemented in a dependency-free script, or supported by external tooling. SMufoLib might serve very well as a basis for such checks, and I’d be happy to contribute validation logic if that’s useful – but the general approach wouldn’t need to depend on any particular library.

[infojunkie]

Would the proposal rely on additional validation or constraints beyond simply merging the files?

• Less typing means less errors
• Typing in one file rather than 3 means less errors
• The structure proposed in the single file/database aims at reducing or eliminating duplication of labels, thereby reducing or eliminating inconsistency errors

Since restructuring the metadata would represent a significant breaking change to the spec

I've addressed this issue by mentioning that the current JSON files can be recreated from the source file using data transformations. These transformations can be run in a build step at commit or publishing time.

and given that several of the inconsistencies reported so far stem from discrepancies between SMuFL and its reference font Bravura
In particular, a more symbiotic validation workflow between the SMuFL metadata and Bravura could help catch these issues early

Is Bravura the reference for SMuFL, or is SMuFL the reference for Bravura? If it's the latter, then we would want to avoid referring to Bravura when validating SMuFL.

[knutnergaard]

I’m still struggling to see how merging the files alone would reduce duplication or typing in practice. In the current structure, duplication comes from repeating glyph identifiers across classes and ranges. If those relationships remain list-based, the same identifiers would still need to be repeated – just within a single file rather than across multiple files.

The data could be restructured so that classes and ranges are indexed by glyph instead, but wouldn’t that primarily shift the duplication elsewhere (e.g. to class or range labels), rather than eliminate it?

It seems to me that the benefit would only materialize if the data model itself is changed – for example by normalizing relationships or enforcing references – rather than simply combining the files. Could you clarify how a table-based solution or a restructured JSON would reduce the number of duplicate labels?

On the question of Bravura: I agree it shouldn’t be treated as the authority for validating SMuFL. However, it could still be useful to validate SMuFL metadata against one or more conforming implementations as a separate step, without making the spec depend on any single font.