Re: [csaf] Pull request just sent... "lang" changes

[Eric Johnson <eric@tibco.com>]

Hi Stefan,

> On Nov 6, 2018, at 3:57 PM, Stefan Hagen <stefan@dilettant.eu> wrote:
>
> Hi Eric,
>
>> Am 06.11.18 um 22:27 schrieb Eric Johnson:
>> Hi CSAF TC,
>>
>> I've just submitted a pull request to complete my long-overdue changes
>> to add "lang", and "source_lang" to the CSAF documents, as per
>> resolution of the TC.
>> https://github.com/oasis-tcs/csaf/pull/5
>
> approved from my side and submitted a comment to the notes (existed before the changes).
>
>> In addition to whether or not anyone has comments / thoughts about that
>> pull request, I have another question.
>>
>> I've been trying to find a tool that will take the JSON schema document,
>> and generate an easier-to-consume form - either Markdown or HTML seem to
>> be obvious options. Markdown is, in some ways easier, because the HTML
>> approaches will pay lots of attention to styling, interaction, etc.,
>> whereas I am just looking for something that will materialize an easier
>> to read descriptions of the contents of the schema.
>>
>> I've found two tools that claim to do jsonschema --> markdown, but they
>> appear to be failing on specific constructs used in the schema, yielding
>> unresolved references. I can probably go and debug the conversion, but
>> figured I'd start by asking my question.
>>
>> Does someone know of good tools to convert jsonschema to either HTML or
>> Markdown form?
>
> well json schema in its way of evolving might not be a good substrate for open source tools (sometimes progress seems to stall, sometimes everyone is in a rush ...) but there are tools claiming to support draft-07, but some expect a $id element, other interesting ones liek doca have problems with cyclic structures.
>
> To me https://github.com/adobe/jsonschema2md worled as in the name
> doing your minimal and direct requested transformation json 2 markdown.
>
> It does so by noting loads of unresolved refs but maybe you take a look at the markdown file, as it seems to be readably structured and might
> represent what you are looking for.

jsonschema2md is the tool Iâve been trying to wrestle to the ground.
Getting rid of the unresolved refs is what Iâm trying to figure out.

Eric
>
>
> Sample of markdown documentation run attached.
>
> PS: I would love to push the CSAF json schema towards SwaggerHub (OASIS is performing a trial currently ...) and I thought I had already kindly nagged for a prototype with CSAF on the list ...
>
> All the best,
> Stefan
>
>> Eric.
>>
>
>
> --
> Stefan Hagen
> read://shagen.de
> talk: eventually
> <csaf_json.schema.md>