$comment keyword in JSON format

[koriym]

Make $comment a valid keyword in the ALPS JSON document by borrowing a notation from JSON Schema.

See

• https://json-schema.org/understanding-json-schema/reference/generic.html#comments
• "$comment" keyword json-schema-org/json-schema-spec#197

[mamund]

question for @filip26: does this break the vlaidator?

[filip26]

unknown elements/attributes should be ignored. I don't understand what value $comment brings to the alps. There is already doc and title.

JSON-Schema:

The $comment keyword is strictly intended for adding comments to the JSON schema source.

[mamund]

yep. adding $comment is a way to support inline comments like <!-- this is a comment --> in XML and # this is a comment in YAML. these would not be there for rendering purposes but only for authoring needs (human-readable comments, possibly tooling can use them, etc.)

this will be an optional element that could appear anywhere in the document. it'd be nice if the converter could retain the comments through various formats (XML, JSON, YAML), tho.

as long as the propsed change is not breaking for any of your code.

[filip26]

it does not break the code but what is the difference between a comment and a documentation/title? Does a comment really add a value?

I understand that '$' notation is well-adopted by JSON schema but looks inconsistent with alps+json and alps+yaml notation.

[mamund]

yes. i'll let @koriym weigh in here but my understanding was that this would be a JSON-only element. IOW, not change to XML and YAML since they each already support inline comments.

IOW, in converters $comment = <!-- --> = # and there would not be any $comment element in XML or YAML flavors of ALPS.

[koriym]

$comment is like a just comment in a programming language. It's for the maintainer not for users.

I found the following comments in https://github.com/alps-io/profiles/tree/master/xml repo. Most of them are comments for grouping by types (semantic/vocabulary or action/transition).

<!-- actions -->
<!-- structures -->
<!-- data vocabulary -->
<!-- transitions -->
<!-- semantic descriptors -->
<!-- transition descriptors -->

Those comments can't express in 'documentation/title'.

[koriym]

JSON lacks comments as argued here. json-schema-org/json-schema-spec#197
@mamund Yes, I intended this is only a JSON format element.

[filip26]

Most of them are comments for grouping by types (semantic/vocabulary or action/transition)

That's interesting. Perhaps, we could explore tag attribute or try to introduce something that helps with 'grouping'.

[filip26]

Following up yesterday's meeting.  

• Anyone can use $comment even if it's not part of the specification. The result is a valid JSON and ALPS parsers ignore unknown elements.
• Introducing $comment to the specification brings irregularities:
  • it is JSON only applicable (what about YAML/XML, do we need to say something about commenting here too?)
  • plausible confusion with doc and title (also opaque textual data)

@koriym What is the benefit of $comment being a part of the spec? Isn't enough just to ignore unknown elements like $comment by parsers?

[koriym]

Anyone can use $comment even if it's not part of the specification. The result is a valid JSON and ALPS parsers ignore unknown elements.

Some may use comment, "//comment" or even cmt? "You can use anything for the comment" doesn't seems good way.

Introducing $comment to the specification brings irregularities:

I understand this. You are right.

doc and title

doc and title are for users. Those describe the application but$comment is the only for maintainers and does not describe any form of application.

Only "ignore" is not enough for those who want to have more strict schema like me. I prefer "additionalProperties": false" setting JSON schema to discover syntax error input. I prefer no unknown single elements exists defined by schema in ALPS documents.

[mamund]

we should wrap up discussion on this one soon.

at this point i am interested in the following:

• what are the adjvantages of including $comment support as an optional element in the JSON representation?
• what are the downsides of including $comment support as an optional element in the JSON representation?