Re: [Qemu-devel] [PATCH v4 2/3] qapi: Add a primitive to include other files from a QAPI schema file

[Markus Armbruster]

Eric Blake <address@hidden> writes:

> On 03/03/2014 08:27 AM, Markus Armbruster wrote:
>
>>>>> +The QAPI schema definitions can be modularized using the 'include'
>>>>> directive:
>>>>> +
>>>>> + include("sub-system/qapi.json")
>>>
>>>> And now it isn't JSON anymore.
>>>
>>>> To keep it JSON, use syntax like
>>>
>>>>     { "include": "sub-system/qapi.json" }
>
> I actually think this looks nicer - makes the file more consistent.

I suspect qapi.py would look nicer, too :)

>>>> If you absolutely must make it non-JSON, you better rename the .json
>>>> files.
>>>
>>>> Hmm, we already are non-JSON, because we use ' instead of " for no sane
>>>> reason.
>
> A weak argument: ' is easier than " to type (at least on US keyboards -
> no shift key required).
>
> Another weak argument: using ' in the qapi files vs. " in actual QMP
> makes it easy to interleave discussions about semantics vs. examples of
> those semantics in use (you can see whether a code snippet is talking
> about qapi or wire format based on what quoting it used)
>
> Our files are already non-JSON due to comments (JSON has no notion of #
> introducing a comment to ignore text to the next newline).  But both our
> use of comments and our use of ' instead of " can be remedied in a
> one-pass sed script to get a true JSON output if such is needed, at
> least as long as we don't need to quote any " characters in the schema.
>
> Therefore, I agree that making the include syntax closer to true JSON is
> desirable, whether or not we also decide to use " in the files to begin
> with.  I don't see any way around the fact that JSON doesn't define
> comments, vs. our absolute need for comments in our schema files, though.

We certainly can't do without comments.

JSON is designed for easy data exchange, but we use it as programming
language syntax.  Its restrictions make sense for easy data exchange,
but hurt our use.  We're not the first ones experiencing that pain:
http://json5.org/

No idea how much momentum this JSON5 thingy has...

>>>> Our JSON parser accepts ' as an extension, to save us quoting in C
>>>> strings.  That reason doesn't apply to .json files.
>>>
>>> Is it a problem if they are not pure JSON? In the end, they are parsed by
>>> qapi.py (which already knows about file syntax), and having a separate 
>>> syntax
>>> for includes makes it somewhat easier to spot when that happens.
>> 
>> I don't particularly care whether schema syntax is pure JSON, some
>> bastardized variation of JSON, or something else entirely.  But as long
>> as we advertize schema files it as .json, they better contain JSON.  If
>> they contain something else, they should be called something else.
>
> Maybe .qapi? But the name qapi-schema.qapi sounds redundant...

schema.qapi?

Switch to JSON5 and call it qapi-schema.json5?