Typing of objects

[rpatters1]

I am a big proponent of json. The fact that MNX switched to json is why I became interested in the project. But one disadvantage of json compared to xml is that a json object has no built-in mechanism that says what type an object is. With xml, the node name can be designed to serve this purpose.

With the introduction of universal object IDs into MNX, it becomes possible to create a cross-reference lookup for every object in the document that has an ID. (Up till now I have been creating separate lookup tables per type-with-ID. So I had a note-lookup table, an event-lookup table, a layout-lookup table, etc.) However, a single lookup table provides an easy way to detect duplicate ID errors and reduces code complexity.

The drawback is, a single lookup cannot identify the type of object it finds from the data. I am using C++, so for me this lookup table is going to be something like

std::unordered_map<std::string, json_pointer>;

That means that if I am going to bind the data in the json_pointer back to a type (which is the whole point of the lookup), I will have track the type externally to the data. However, if we added an optional type to every object with an id, then it would be embodied in the data. We already have this for content arrays, of course. I'm just suggesting that we consider expanding it to the other objects.

As I write this down, I am realizing that external type tracking is actually fairly workable. Still, it requires the program to hard-code the types and that means the program only captures the types it knows about. I thought I would toss this idea out for discussion. Two counter-arguments that do not sway me much are

• Bloat. We already have a ton of bloat, and a universal type value would not add that much more, especially if we stick with "event" as the default. Having teethed on 1980s microcomputers, I am continually astonished at how instantaneously a moderately priced 2025 PC can chew through a text file with millions of lines.
• Readability. Are we targeting MNX at humans or computers? I think we should be targeting computers, and they do not care what the file looks like. In fact, the chief way to reduce bloat will be to remove all tabs and newlines from the output, which will render MNX files completely unreadable by humans.

[adrianholovaty]

Just to make sure I understand your proposal and we're talking about the same thing, would you mind writing out one of our example docs with your proposed typing included?

When you say you need typing information, that term is a bit ambiguous. The new global "id" attribute is only available on MNX objects of type "dictionary" (aka a JSON object as opposed to an array, string or integer). Or do you mean you want to encode the MNX data type, such as the ones listed here?

To be brutally honest, I would probably never agree to requiring type information. It would be 100% derivable information, completely redundant, inviting only opportunities for errors. It goes against the MNX philosophy of "when possible, use one and only one way to encode things, and use the smallest number of data elements as possible, to avoid opportunities for encoding conflicting information."

Finally: I'm not a C++ programmer, but doesn't the JSON Schema give you a machine-readable way of "knowing" which type each object is? (Here I mean "type" in the sense of "MNX type.") Isn't that one of the main benefits of having a JSON Schema in the first place?

[rpatters1]

The proposal is to add an optional "type" field to _global_attr_, so only on dictionaries. It would be required if "id" is supplied, otherwise not. It basically is an extension to what we already have with content arrays. I added some IDs and type to hello world:

{
  "mnx": {"version": 1},
  "global": {
    "measures": [
      {
        "id": "gm1",
        "barline": {"type": "regular"}, // naming conflict here with "type"
        "time": {"count": 4, "unit": 4},
        "type": "globalMeasure"
      }
    ]
  },
  "parts": [
    {
      "id": "p1",
      "type": "part"
      "measures": [
        {
          "id": "p1m1",
          "type": "measure",
          "clefs": [
            {"clef": {"sign": "G", "staffPosition": -2}}
          ],
          "sequences": [
            {
              "content": [
                {
                  "id": "ev1",
                  "type": "event", // optional: (default is "event")
                  "duration": {"base": "whole"},
                  "notes": [
                    {
                      "id": "n1",
                      "type": "note",
                      "pitch": {"step": "C", "octave": 4}
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

I'm not aware of a C++ tool that would allow it to infer a type from an arbitrary json location (aka json_pointer) using the schema. I'm not sure it is even possible in principle.

Given your reaction, I'm not expecting it to happen. But if it did, there are some naming conflicts with type.

[rpatters1]

Another way to do it would be to turn the ID field itself into a dictionary that included the type.

[ahankinson]

This discussion was brought up in the proposal to change from XML to MNX.

#290 (comment)

I'm not sure it's really been addressed. "duck typing" in music data is pretty hard. For example, I see that "note" in MNX has pitch as the only required attribute, but not all notes have a pitch, or not a specific pitch, but currently that seems to be the only way to tell what a "note" object is by duck typing it. But if you make all your distinguishing attributes optional, then the likelihood of confusing one object for another is pretty high.

You can also say that they will be distinguished by where they appear -- their parent context; i.e., "notes" will only ever appear in an array of notes. But you then only know their type if you also reference the schema -- your software needs to be "schema-aware" and needs to parse a given document and interpret it through the lens of that schema, if you want to give a type to an arbitrary object. Reading arbitrary JSON and making sense of it is not possible in this scenario.

Fundamentally, it seems a bit strange to me to leave such a critical component of data understanding to implicit behaviours. The second principle of the "Zen of Python" says "Explicit is better than implicit." Given the choice between stating something directly, and hoping that the right answer emerges from a collection of properties and contexts, I would tend to favour the former. It seems the gain in clarity far outweighs some amount of redundancy.

[adrianholovaty]

You can also say that they will be distinguished by where they appear -- their parent context; i.e., "notes" will only ever appear in an array of notes. But you then only know their type if you also reference the schema -- your software needs to be "schema-aware" and needs to parse a given document and interpret it through the lens of that schema, if you want to give a type to an arbitrary object. Reading arbitrary JSON and making sense of it is not possible in this scenario.

I guess my response to this is: "Yes, and so...?"

Letting a consuming application read an arbitrary subsection of an MNX document, without the consuming application knowing what subsection it is, isn't really an MNX goal. What would the specific use case for this be? More precisely: in which case would it be useful for an application to be able to accept arbitrary MNX data types, without extra metadata about what type of data it is? I can think only of contrived examples.

We have thought about how it would be useful to reuse the note object encoding for other purposes — it's useful to have a standard way of encoding a musical note in JSON — but nothing about that particular use case would require every MNX object to redundantly encode its own type. It would simply require that the parsing code "know" that this bit of JSON data is an MNX note object.

If it turns out there are legitimate use cases for "a subset of an MNX document," we could specify a lightweight container format, whose only goal would be to specify how to interpret the data. All that it needs to know is the top-level MNX data type. Like:

{
  "mnxType": "key",
  "mnxData": {
    "fifths": 1
  }
}

This way, the ugliness/redundancy of that mnxType would be limited to the particular container format, instead of littering the MNX document itself. But, again, I'd want to see some practical use cases for this.

[paul-bayleaf]

Having an explicit object type would help to support forwards compatibility. If software written for MNX version x sees a file for version x + 1, it could still process the file provided it can safely ignore any objects it does not recognize. An object type field would help with identifying objects from the future.

[rpatters1]

I don't find appeals to "beauty/ugliness" convincing. The computer that consumes a file does not care about aesthetics. What I care about is making the file as easy to consume as possible. We have introduced a mechanism for universal object lookup by adding a universal id field. But we don't have any way to tell what we've just looked up other than some complex piece of code that involves re-parsing the schema.

[adrianholovaty]

For what it's worth, the uses of "id" within an MNX document are always consistently typed. For example, a beam's "events" is a list of IDs that will always point to events. A tie's "target" will always be the ID of a note. I don't believe there's any case where the target ID can be heterogenous.

Really the point of the global "id" attribute is to make objects addressable for applications that might need that. In other words, it's providing a hook. So as long as your application doesn't actually need that, I don't know if this is really a problem (?). You could simply continue with the method you've already been using (separate lookup tables by type).

[rpatters1]

For what it's worth, the uses of "id" within an MNX document are always consistently typed.

That's exactly why I could use an explicit type specifier in the data. My work with MNX has been mostly as exporter. But I have been concurrently developing a program that semantically validates an input MNX file. One if those checks is to check the existence and validity of id values. Schema validation does not, in fact, guarantee that an id is being used correctly or that it points to an entity of the expected type. That is (among other goals) what I aim to do with semantic validation.

Currently, because id was limited to just a few classes, I created separate id mappings per class. So I had a note mapping, an event mapping, a layout mapping, etc. There is (currently) no attempt to flag ids that are duplicated across domains: id values only have to be unique within each mapping.

Now, suppose I need to validate the target of a tie. I simply look it up in the note mapping, and if it's there, I know it is at least a valid note id. I then do some other checks on the mapped note, like making certain it is part of the same part and has the same pitch and maybe one or two others.

One of the attractions of the new universal id field is that I could now consolidate all these different mappings into a single map. This would

• guarantee that non-unique IDs are flagged.
• consolidate the code into a much simpler routine.
• be easily extensible to new types.

But think back to the task of validating a target note id. I can find the item with that ID in the now-unified mapping, but I have no idea if it is actually a note, short of hard-coding additional information about the json location on the input pass (which eliminates easy extensibility), or duck-typing it based on its json_pointer values and/or object properties (which is complex and likely not reliable).

If we end up with a standard where the data does not explicitly name its type, I will probably go the hard-coding route. So I can solve the problem. But it seems like a design flaw, which is why I brought it up.

[mscuthbert]

My proposal (repeated):

• Most objects have no typing. (Current situation)
• Any places where more than one type of object is placed (such as the content array in sequences which can have events, graces, tuplets, or spaces), it should be explicitly typed, as in one of these:

"sequences": {"content": [
    ["event", {...}],
    ["grace", {...}],
]}

or

"sequences": {"content": [
    {"type": "event", "value": {...}},
    {"type": "grace", "value": {...}},
]}

To my mind, it makes sense to either have the type listed inside every object (a view Adrian has rejected and has been settled for some time in my mind) or to have the type specified outside the object -- generally by the schema saying that only Object-Type-X (or null) can go here or with an external type specifier for the few cases such as sequences' "content" where multiple object types can be used (and unlike with notes vs kitNotes, the order does matter).

To generally not have the type specified in the object but occasionally have it done except with some defaults seems to me the worst choice to make. Unlike MusicXML, I expect the same object type/class to reappear in different parts of the standard—e.g., we will single rhythmic value object used wherever rhythms are needed and not have to have <beat-unit-dot> like here—so the notion that certain objects will always have their type known or always have their type be ambiguous neglects the fact that we won't always know the context in which an object appears (esp. if the object ends up appearing in _x extensions). Always internally typed or always externally typed solves this problem; sometimes internally typed does not.

[rpatters1]

I guess my question comes back to, why did we move id to __global-attr__ if it was not to be able to allow random access to every ID in the document? And if we are allowing random access to an arbitrary json location, we need to be able (generically) to determine what that location is. Saying, "get it from the schema" is hand-waving. That is a non-trivial task leading to a brittle solution at best.

As it is, I am reduced to deciding ahead of time (i.e., at compile time) which IDs I will map and what their types are. This seems to defeat the purpose of moving id to the global attributes. The net affect is, I am only mapping IDs in the classes that already had individual id properties and ignoring the rest.

[mscuthbert]

I think that there are several ways to access an object by id -- and not every way of doing that requires knowing what type of an object is being referenced. It doesn't necessarily need to be a reference to a JSON location -- it is a reference to a particular object. My way of using object-id references doesn't generally require knowing where that ID is located in a hierarchy -- but if it did I could store a parent-object weakref upon cataloging.

[rpatters1]

A proper validator that is guaranteeing ID-uniqueness needs to recursively traverse the json tree looking for id members. It won't necessarily have a class name/weak_ptr/variant instance (pick your poison) for every object it encounters. Yes, I could do this and then turn around and assign the class values to those that my code knows about. But two passes rubs me the wrong way. MNX json from Finale heads towards 100s of MB, and it will only grow as the MNX spec grows.

But I get it. Adding a type to every object would be a lot of overhead in the data. I wish the schema were more suitable to this task, but I don't see how. Backing into types from the schema looks non-trivial and unreliable to me.

[mscuthbert]

Adrian wrote:

If it turns out there are legitimate use cases for "a subset of an MNX document," we could specify a lightweight container format, whose only goal would be to specify how to interpret the data. All that it needs to know is the top-level MNX data type. Like:

{
  "mnxType": "key",
  "mnxData": {
    "fifths": 1
  }
}

I'll reveal myself as one of those talking a lot about how MNX is making itself useful not just as a complete-sheet-music encoding format but as a set of micro-formats for encoding musical concepts such as notes or metronome marks or (here) keys/key-signatures.

I don't think that MNX needs to worry about specifying a larger container format (or conversely constrain the user) unless these microformats end up used within MNX. I can imagine referencing this as ['mnx', 'key', {fifths: 1}] within a TS project of mine (treating the JS object as equivalent to JSON but without the quotes.

Apparently a recent change (which I didn't know about when I started #448) really helps this system, as now every Object-Class has its own entry in $defs even if it is used only once, so any different object type has a name that appears in the schema. #448 thus becomes just a request that we start calling object types by Tokens that are commonly allowed as Class/object names, like MultimeasureRest instead of multimeasure-rest.

[dpezely]

Regarding explicit vs implicit type with respect to consuming MNX:
Is it a goal to deserialize a whole MNX data structure such than only JSON syntax requires a parser?
i.e., Should deserializing MNX be stateless?

Currently, this requires tracking state:

• event has implicit type within JSON
• Look back to a parent context to determine type, or
• Filter / exclude others that have explicit type: grace, tuplet, space, etc.
• Otherwise, the fall-through case concludes event

I believe that makes the difference between deserializing and parsing.

That bit me when trying simple deserializing with Rust's serde and using data types generated from mnx-schema.json.

With an initial naive approach, tuplet gets miscategorized as event with literal string of "tuplet" because serde is strictly a serialize/deserialize library, and its companion library serde-json parses only for JSON syntax. It has directives for JSON that is flattened, untagged, etc. but insufficient for a fall-through case like event.

With serde and serde-json, a custom deserializer can peek at next character, but I have yet to explore whether it can also accommodate this kind of statefulness or not. I have yet to try other libraries or frameworks. I'm not opposed to writing a parser but have yet to start one for MNX.

An explicit type on event would simplify and immediately resolve all that.

[adrianholovaty]

Sorry, I'm not understanding your points here, and I think you may be overthinking it? If an element within a sequence doesn't have a type, that means the type is "event". Does your parsing library have the concept of a default/fallback value? There's no need to know any forward/backward state in order to make that decision.

[ahankinson]

I think what they’re saying is that without looking at the actual shape of the JSON (the keys and values in the object itself) it’s difficult to consistently disambiguate the type of event in the stream. Since the library only operates at the deserialize level, doing larger shape-based disambiguation can only happen after the full object has been deserialized in a kind of look-back operation.

[dpezely]

As @ahankinson framed it, the library for Rust only operates at the deserialize level.

(serde is the library most commonly used, and I have yet to try other libraries or frameworks that might also do parsing beyond JSON syntax.)