Support comments in JSON files

[bajtos]

@bajtos commented on Wed Apr 29 2015

At the moment, configuration files are using JSON, which does not support comments. We should consider using a JSON superset that supports comments, for example http://json5.org/ or http://yaml.org/ or at least apply https://www.npmjs.com/package/strip-json-comments when loading JSON files.

---

@ritch commented on Wed Apr 29 2015

The problem with stripping comments is that once you JSON.stringify() the content back into the file ...it removes all the comments. Its a 1/2 solution IMO.

---

@bajtos commented on Wed Apr 29 2015

Ouch, that's a good point, I completely forgot about editing JSON programatically from loopback-workspace. I'm removing the "Beginner Friendly" label then.

---

@sam-github commented on Wed Apr 29 2015

The round-tripping is the more pervasive problem.

The reason I'm looking for comments is there doesn't appear to be a good place to comment on the structure and meaning of the API. There is the description field, but that's pretty limited.

---

@bajtos commented on Wed Apr 29 2015

There is the description field, but that's pretty limited.

FWIW, the description field supports an array of strings as a value, if that's of any help.

// single-line
description: "a short one"

// multi-line
description: [
  "line1",
  "line2"
]

---

@sam-github commented on Wed Apr 29 2015

And it allows arbitrary properties, right? So, I could add a comment: property anywhere, and LB would ignore it, right? I could try doing that. Though my dividing paragraphs into arrays of strings is a bit messy to edit, though fine to read.

---

@bajtos commented on Thu Apr 30 2015

And it allows arbitrary properties, right? So, I could add a comment: property anywhere, and LB would ignore it, right?

Yes, I believe so.

---

@juodumas commented on Mon Feb 01 2016

Comments in config.json and others would be very nice. Maybe at least allow skipping config.json when config.local.js exists? Currently if I have config.local.js and have no config.json, loopback complains and doesn't load the config.

---

@tohagan commented on Thu Oct 05 2017

hjson might what you're looking for. Developers could opt to rename thier .json files to .hjson OR since hjson is backward compatible you'd just replace the JSON parser.

The hjson API includes the ability to preserve comments in editing round trips.

---

@tohagan commented on Thu Oct 05 2017

Many other apps provide sample configuration values and documentation as comment inside their configuration files. You also often want to keep old settings but comment them out or explanations of settings (e.g. reference to an issue number). Not having comments for configuration (or any code for that matter) is IMHO a major limitation for Loopback both for getting started and for on going code maintenance of JSON files. So I think adding this feature would be a valuable win.

An issue may be that some integrated tools would break as they would expect a standard JSON format but this should not be a deal breaker if they are open source.

---

@bajtos commented on Thu Oct 05 2017

@tohagan I agree with you. I am afraid we don't have bandwidth to address this in the near future, as our main focus is on the next version of LoopBack - see https://strongloop.com/strongblog/announcing-loopback-next/. Would you like to contribute this improvement yourself? I think there are two big pieces to make this happen:

• Modify loopback-boot to support config files containing comments. You will need to make the changes in the 2.x branch, as the master branch is tracking a 3.0 version that hasn't been released yet.

• Modify loopback-workspace to preserve comments when editing configuration JSON files. This package is used by all our tooling, from loopback-cli to IBM API Connect Editor. This second part will be probably tricky - the design of loopback-workspace has a steep learning curve, and we will need to find a way how to allow REST clients to preserve the comments. Since hjson stores comments are in non-enumerable __COMMENTS__ property, REST clients will not receive them and we may need to somehow merge the data from the client with the original comments when performing updates.

---

@tohagan commented on Thu Oct 12 2017

@bajtos Would be great to have this in Loopback Next!

[tohagan]

Awesome! Thanks very much.

[bajtos]

So far, almost all LB4 configuration happens in TypeScript sources which do support comments. The only exception is datasource configuration.

I am moving this issue to the epic Declarative Support #565 and removing from GA.