search

alps-io / spec

ALPS Specification documents.
59 stars 13 forks source link

$comment keyword in JSON format #99

Open koriym opened 3 years ago

koriym commented 3 years ago

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

See

mamund commented 3 years ago

question for @filip26: does this break the vlaidator?

filip26 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

$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 commented 3 years ago

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

filip26 commented 3 years ago

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 commented 3 years ago

Following up yesterday's meeting.  

@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 commented 3 years ago

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 commented 3 years ago

we should wrap up discussion on this one soon.

at this point i am interested in the following: