Meeting minutes
Agenda
Mahda: Agenda mostly about tooling
Minutes Review
Mahda: Wednesday meeting, https://
… Kaz applied some changes already
… I spotted "@@@"
Kaz: We need Cristiano's clarification for his words
… maybe we can simply remove "@@@" also given there are some more words after that
(just removed)
Mahda: meeting, https://
… any objections approving the minutes
… none -> minutes are approved
TD
Toolchain Discussion
<kaz> Mahda shows the WoT Thing Description 1.1 spec
Mahda: Current process is to finally generate HTML document
… some parts are manually written
… some tables, images etc are automatically generated from resources like ontology et cetera
… current process requires to setup ontology
… it is tedious
… SHACL/SHAPE difficult to construct
… JSON schema validation file is different again
… we require template files based on STTL
… difficult to maintain ... not a huge community
… that's why we look for a better solution
<mahda> SPARQL Template
Mahda: Is motivation clear?
Daniel: new tooling for new documents only, right?
Mahda: Yes
… new resources in similar shape
<mahda> w3c/
Mahda: <opens repo>
… that is the current project with the new toolchain
… there is a diagram about main idea
… we agreed to use LinkML
… LinkML based on object-oriented programming concept
… easier for most people
… single source of truth in LinkML
… output resources are generated like JSON Schema, SHACL, ...
… 2nd step if for generating HTML
… currently we use the template mechanism which we would like to replace
… static file index.template.html uses the placeholder which we fill in
… the 2nd step would use the generated resources and the html file to generate final TD HTML file
… the repo can be used already
… there is a quickstarter in the readme
Mahda: <showing the process>
Kaz: readme page summarizes whole mechanism. That is great
Mahda: back to process
… main.py is starting point
… script to generate
… so far we need to bring concepts to LinkML
… repo has "resources" directory with LinkML schemas
… we can define own types
… first draft ready for our schemas is available
… besides that we have index.template.html
… with placeholders
… there also test files in "test" directory
Mahda: The process generated merged LinkML file which could be hosted later somewhere
… now we are in the test phase
… basic tests pass... for example w.r.t. the JSON schema
… more complicated ones pass also
… but there is still a lot to do
… we have lots of test-cases
Daniel: Part of a CI test pipeline in the end?
Mahda: Yes
… generation, testing etc
Jan: For the document generation. DO we still use index.html or bikeshed ?
Mahda: No plan yet ... still working on JSON schema generation
… LinkML is work in progress also
… parts we need are worked on
… anyway, later we can look at bikeshed also
<kaz> Bikeshed Documentation
Cristiano: Congrats. I like it
… about testing
… we used to have validation folder in old repo
… can you make use of it?
Mahda: I considered valid vs. invalid TDs ... but testing pipeline is not in place yet
… we can use the "old" script in the future ...
Cristiano: Let's see how it goes
Cristiano: Bikeshed is python-based ... maybe we go along that
… what is the advantage of bikeshed?
Luca: Question: What is the alternative ?
Cristiano: Staying with ReSpec ?
Luca: Bikeshed takes in extended markdown and produces HTML (or PDF)
… can be still annotated with ReSpec
… but we can use Markdown
Mahda: we use mkdocs already
Luca: LinkML can produce Markdown
… we can convert index.html to Ginger and LinkML can fill in what we want
… OR LinkML is producing Markdown, which we can fill in later
… several possible steps
Mahda: Luca, maybe you can draft your proposal
… I have still concerns w.r.t. the placeholders and how to replace them
Luca: Are we okay with converting everything to Markdown?
… this is the first step
Luca: I can try to look at how we can integrate
… Markdown seems better to me
Mahda: Maybe we can convert HTML to Markdown also?
… but let's wait for Luca
Kaz: Given that we don't have both the main editors ... we don't need to make conclusion
… we need to think about compatibility
… not everyone is used to it and we should be careful
Mahda: agree, no resolutions today
Cristiano: If we have HTML already .. it is an effort to move it to Markdown
… there are templating mechanisms
Luca: Markdown is easier to handle ..
… LinkML has Markdown generator
… have PR ready
Luca: <sharing screen>
… at the moment mermaid rendering is not working correctly
… could write python to fill in placeholders
… OR use Markdown output so that it fits our needs
Mahda: Would be good test it
Daniel: Somewhat similar comment to Cristianos ... would stick to HTML for now.. look at it step by step
Kaz: Agree with Daniel
… would ask opinions from Koster and Ege too
… then if we as the whole TD TF would like to go for using Bikeshed, we can ask other groups who are already using Bikeshed about their tooling and know-how.
Issue 29
<mahda> LinkML JSON Schema Generator
Mahda: Issue 29 in tmp repo
Mahda: in LinkML composition can be used like anyOf etc
… I modeled security field
… LinkML adds type:string also ion JSON schema
… composition term is the issue
… it is of type object
… in the case of composition ... convert to object
… maybe propose fix to LinkML
… I wanted to discuss how we can proceed
Issue 28
<mahda> Issue 28 - Model JSON Schema keyword additionalProperties in LinkML
Mahda: Issue 28 is similar.. w.r.t. additionalProperties
… shall we do post processing ..or fixing LinkML
Cristiano: w.r.t. issue 29 ...
… can we define security is undefined
Mahda: can use range: any ... forces it to be object
… in some case it works fine
… in the forms cases it does not work
Cristiano: I am surprised that JSON schema is valid in first place
Mahda: Yes, not valid
Cristiano: Workaround possible ... with post processing.. if no fix on LinkML side
Daniel: should fix LinkML in the ideal case :-)
… at least try to open issues
… w.r.t. forms .. we should not use the same type
Mahda: Yes fixed that
… with title ... sometimes mandatory ..sometimes not
… ontology should have just one concept of title .. not several ones
Mahda: anything urgent?
… closing -> out of time
[adjourned]