EpJSON File Comments for Interfaces

[Myoldmopar]

I had a demo recently to a major EnergyPlus stakeholder and the topic of EpJSON came up. They understood that the change will definitely improve workflows and lower lifts for new interfaces, but are looking for ways to move forward with an existing IDF-based workflow. One question was around how to include comments in EpJSON. There are several classes of comments to consider:

• Individual field comments
• Object instance comments
• Object type comments
• File level comments (header)

In an IDF these are possible:

! Header comment 1
! Header comment 2

! Object Type Comment for ALL Zone Objects

Zone, ZoneA, 4;

Zone, ZoneB, 8;

! Object Instance Comment specific for Zone C
Zone, ZoneC, 1;

Zone,
  ZoneD, !- Field level comment for this field only
  5;

In EpJSON, the structure is:

{
  "Zone": {
    "ZoneA" : {
      "parameter": 4
    }
  }
}

The nature of JSON does not allow comments to be placed flexibly in the file, so we need to have specific locations for comments, and specific strategies to provide to interfaces to help them transition.

For field level comments, we could potentially suggest that they add a new field that EnergyPlus does not use. Consider an object which has a design flow rate, and they wanted to add a comment for the source:

{
  "ObjectType": {
    "ObjectName" : {
      "design_flow_rate": 4.0,
      "design_flow_rate_source": "Experimental measurement 2031/02/18"
    }
  }
}

I think EnergyPlus will allow extra fields that it does not process. That would work for that. In the same way, object instance level comments could be placed as a new unused field:

{
  "ObjectType": {
    "ObjectName" : {
      "comment": "Some comment about this object as a whole",
      "design_flow_rate": 4.0
    }
  }
}

I think that the object-type-level comments and the whole file level comments are not as easy, but I could be missing something. Anyone have any thoughts? As we move forward we'll just need to formalize this advice to help interfaces move from IDF to JSON.

@mjwitte @mbadams5 @jasondegraw @nealkruis @EnergyArchmage

[mitchute]

Maybe this is too naive, but in a "JSON" type paradigm we should only be reading in and validating the fields we care about. So if the user wants to add extra "comment" fields at the parameter-, object-, or file-level, they should be allowed to do so.

[mjwitte]

That's true for object-level comment fields, but I think we would need to add a new object type to the schema to hold file-level comments. Given there's some uncertainty about how this all flows, perhaps we should add a formal "AAAFileComments" object type (with a name that sorts to the top of the file) that is an extensible list of comment fields, and also insert a simple comment field into every object in the schema.

[mitchute]

I think we would need to add a new object type to the schema to hold file-level comments

Agreed, that is likely necessary for the file-level comments. "AAA"FileComments is perfect 😆

[shorowit]

This idea/discussion seems to have some overlap with the proposal for object tags/properties.

[jasondegraw]

Secure in the knowledge that whatever I write here will be completely ignored, I'd point out that as long as we're converting from the IDD to the JSON schema, we're always going to be a bit constrained by incompatibilities like this. A facility like this is better added once we've stopped doing the schema generation step (or as a modification of the schema after the bulk of the translation is done?), otherwise we're trying to write JSON schema by IDD. Not a great idea.

There are some dialects of JSON that allow C++ style // comments, but... no, never mind. This will get ignored anyway, so I'm going to finish this out in emoji:

👍 object instance comments
👎 object type comments
👎 field comments, this isn't an interchange format

💯 for @shorowit, yes this should be related to your tagging proposal

Sorry @mjwitte, but I don't think I have the emojis available to express how much I dislike the idea of a specially named object.

[amirroth]

@jasondegraw, my goto is 🤮 . Also fond of 🤬 .

[mitchute]

Secure in the knowledge that @jasondegraw will have strong opinions about anything I write...

we're always going to be a bit constrained by incompatibilities like this

Sure. I mean, JSON doesn't explicitly allow comments but we can add a way to handle them if it's important. I personally believe that it is something we should support, and the tool developers seem to feel the same (at least based on the original post). Unfortunately, it looks like having comments for anything beyond object type and object instance is going to require a restructure of the schema.

A facility like this is better added once we've stopped doing the schema generation step

I think I can agree with that - this is a complication that might be better if we kicked it down the road. I'm still not seeing why we can't have a "comment" field at the object type and object instance level, though. It's not as good as what we have now, but at least it's something.

There are some dialects of JSON that allow C++ style // comments

That's kinda cool. I did not know about that. I like the "idea" of this, but I think practically it's a non-starter for this situation.

[mjwitte]

@jasondegraw Thanks for keeping me in line. I wasn't suggesting that these new fields/objects be added to the IDD. We're already doing special things with the schema generation script, so this could easily be part of the epJSON-only world. But it would be highly valuable if the idf-epJSON converter would preserve at least full-line comments from incoming idf files for users who are moving from idf to epJSON.

So, you gave a thumbs-up to object-instance comments. That's a good start. For file-level comments, would you be open to a comment list in the Building or Version object?

{
        "Building": {
            "patternProperties": {
                ".*": {
                    "type": "object",
                    "properties": {
                        "north_axis": {
                            "type": "number",
                            "note": "degrees from true North",
                            "units": "deg",
                            "default": 0.0
                        },
. . . 
                        "comments": {
                            "type": "array",
                            "items": {
                                "properties": {
                                    "comment": {
                                        "type": "string"
                                    }
                                },
                            }
                        }
. . . 

I may not have gotten all the punctuation correct, but hopefully the concept is evident.

[jasondegraw]

Why not just put a single "Description" at the top level that contains the header type information? Preservation of comments is going to be hard in the sense that it's easy(ish) to do but unlikely to give people exactly what they want. But at least header info should be easy to identify.

[Myoldmopar]

Could the value associated with "Description" key be a JSON object? Just a plain object that we don't validate but it is allowed in the EpJSON input? That would allow interfaces to continue to tag their IDF with meaningful metadata of whatever form they like and we would of course just ignore it. Makes me think of the "extra_data" key which is common for JSON APIs to allow similar behavior.

[EnergyArchmage]

It used to be required that example files have a substantial header with a summary of what is in the model. I am surprised this sort thing has been kicked along this far. Just need a text blob of some kind.

[amirroth]

With an ASCII drawing of the floorplan! Bring that back!