JSON-LD specifications with embedded JSON-LD (and Microdata)

[kael]

Similarly to the Webmention specification which includes a <link rel="webmention" href="https://webmention.net/endpoint.php"> in its HTML code as defined in the spec itself, it'd be nice to have JSON-LD contexts embedded in the HTML code of the JSON-LD specifications, demonstrating a "proof by example".

Perhaps mixing with Microdata would be nice too.

For developers, it'd be a way to learn by example.

[iherman]

What you see as an editor's draft is the source in respec, which is not exactly the file that one sees when reading the official draft (ie, the file as stored in https://www.w3.org/TR/json-ld11 for example). We have added the right flag so that the generated HTML will contain a JSON-LD data block in the header, using the schema.org vocabulary. I think this is exactly what you are looking for.

We do not plan to add microdata, though. It would be duplicating the same information as what is in the JSON-LD data block.

Cc @BigBlueHat @azaroth42 @gkellogg

[kael]

Thanks, I didn't look in that version though. Yes, that's what I'm looking for.

TL;DR: Concretely, I was thinking to using structured data to:

• generate TypeScript definitions directly from a spec IDL embedded in JSON-LD (fetched over HTTP and parsed with a tool like jsonld.js or node-microdata) ;
• generate core IDL functions from the defined algorithms (we're not there yet) ;
• generate some "common documentation" including core concepts, with their definitions and relations with others ;
• generate the spec as a goodie.

Specifications have the same pattern, and I believe the https://schema.org/TechArticle is not enough to reflect the structure of specifications. Specifications contain:

• metadata ;
• references to other specifications ;
• core concepts definitions ;
• IDL by IDL, function by function defintion, usages, limits and examples ;
• IDL defintions ("the code is the law");
• what else ?

Thus, I was thinking to having a way to highlight, emphasize, these patterns ; and make them "machine-readable".

Core concepts could be defined with OWL (if I understand it correctly), perhaps for IDL too, and all embedded in JSON-LD.

Relations could be done using microdata in the HTML code (although not sure, considering there could be some redundancy).

Although having a way to automatically generate code from a specification could be used by a malicious author to embed, say, a fake random numbers generator, it could also be a way to mutualize efforts by, in the end, having potentially the best practices and feedbacks included "natively" in the spec and hence in the code.

There exists some related works like xml2rfc, SchemaOrg:APIReference, the Apache Software Foundation DOAP file (seems their website is partially broken currently) and their DOAP Extensions: Standards which adds reference, in a DOAP file, to the specifications used in the published software, the "capabilities" of the software.

Perhaps there's already a vocabulary for specifications that'd allow to model them in a detailed and "machine-readable" fashion, I got to investigate.

All of that to say that JSON-LD (and microdata) specifications could include some advanced usage of what they define.

Addendum: Could jsonld.js and node-microdata use the JSON-LD specifications to model their core behaviour and structure, in their index.d.ts file, for example ?

[iherman]

@kael, with my geek hat on I understand what you would like to have. However, these structures, vocabularies, etc, are either not yet existent or are not stable. I'm afraid it is not in the charter of the JSON-LD Working group to define those, nor can it possibly modify the publication style and rule of W3C Recommendations when defining, e.g., WebIDL. This group is only responsible for the syntax...

I would hope that, at some point, such structures, vocabularies, etc., will be defined and possibly combine with the W3C publishing rules, at which time a future version of a JSON-LD document could adopt them. But this specific Working Group would have difficulties going beyond what we have now...

That being said, our editor, @gkellogg, may have some further ideas...

[BigBlueHat]

@kael thanks for posting this! I love what you're working to create/produce, but as @iherman mentioned, this particularly Working Group is focused on the JSON-LD 1.1 version changes, and only tangentially on the tooling (though we'd all like to see many more tools!).

What you describe sounds very much like what the ScholarlyHTML Community Group was/is/will-be attempting to build as a future revision of a ScholarlyHTML format. It uses a mix of JSON-LD and RDFa to create a combined understanding of a scholarly article.

There's no reason a similar approach couldn't be applied to specifications! It just needs time and code. 😉

If you're interested in pursuing that, I'd recommend you: a) join the ScholarlyHTML Community Group and present your hopes/dreams/plans b) fork Respec (what we use to generate the JSON-LD spec) and play with adding RDFa to the various sections of its output. c) keep the ScholarlyHTML group updated on what you're building/attempting to build interest in your project (and to get help hopefully!).

Lastly, I'd recommend digging into RDFa in place of microdata as you'll find it's capabilities are much more on par with JSON-LD's and you'll consequently be far less constrained when modeling your vocabularies (or utilizing any existing ones).

Thanks for posting this! 🎩

[kael]

@BigBlueHat Actually I'm working on something else, it's a side idea though, based also, first, on my experience with Erlang typing and static analysis, like trying to automatically extract XML Schemas from XMPP spec and generate data types from them, and then to generate automated tested using "Property based testing" with PropEr a QuickCheck-like.

I believe the subject can be split into two topics though: adding "human-oriented" content (the specification) and "machine-oriented" content (the IDL). I've been searching a bit and came across SKOS and something perhaps a bit esoterical called the Unified Foundational Ontology which defines "OntoUML", « a pattern-based and ontologically well-founded version of the Unified Modeling Language (UML) ». There's also the HTTP Vocabulary in RDF 1.0 and WebIDL as related works. Looking at the 2144 contexts, there doesn't seem to be any for specifications.

1. Schema:Specification

I believe specifications should have their own vocabulary. There's already:

https://schema.org/TechArticle https://schema.org/APIReference https://schema.org/SoftwareSourceCode https://schema.org/SoftwareApplication

https://schema.org/Specifications looks like a yet undiscovered element of the SchemaOrg Periodic Table.

But until that, perhaps SKOS could be used with Schema:TechArticle. I've edited a version of the JSON-LD 1 draft with SKOS using microdata, with skos:Concept, skos:definition, skos:example, skos:note, skos:ChangeNote, Schema:articleBody and Schema:Code. I should try also with the DOAP Standards extension (assuming it'd be considered an accepted reference).

@iherman What you think ? Would you have to re-charter to enhance the structure of the spec ? Is it definitely out of the scope ?

2. Schema:WebIDL (approximative naming)

I realize this is much more complex that I had thought, and it'd probably require a spec about writing specs with JSON-LD and/or microdata, written itself with JSON-LD and/or microdata.

Assuming there were a JSON-LD context for WebIDL, it could be combined with the Memento Timemap of the specification, it'd be possible to extract the WebIDL for each revision of the spec, and having TypeScript related types associated with a version, and not incrementally updated without consideration of the version of the spec.

But one important limitation with TypeScript is that there's only one "number" type, typing is not precise enough (yet ?), which makes the idea not really doable for now, although having IDL embedded in JSON-LD could still be of interest.

[iherman]

@kael, I am sorry if I sound unfriendly, but I believe this issue should be moved elsewhere (maybe to the repository of the JSON-LD CG?). As we said, this work, and its implementation, cannot be done in the Working Group, and this repository should be kept free of non-WG issues...

@azaroth42 is the JSON-LD CG a suitable place for this?

[kael]

@iherman Sure, noted.

At least, you have an example of what an enhanced specification would look like and how it could be used.

Cheers.

[gkellogg]

Sorry, this fell out of my working memory.

ReSpec did use RDFa previously, but this was actively hated by the non-linked-data community. We added in something that was pretty much equivalent using JSON-LD and some schema.org classes and properties with the argument that this could improve SEO, but of course, it could do more. This could, of course, be improved by a PR to the schema.org project.

I'd eventually like the doJsonLd to become the default for ReSpec, but it probably needs to remain fairly focused. More would be cool, but should be managed using a separate configuration option. Motivating use cases would also be useful.

These are not really JSON-LD issues, but more generally those needed or useful for spec editors. I think this could use its own CG and try to get support from ReSpec and Bikeshed communities. If there's sufficient interest, that would be the best way to move forward. If not, then the work wouldn't be likely to gain wide use in any case.

[kael]

Thanks for the answer.

Regarding incentive to write RDF augmented specs, I guess if a popular tool started to make use of JSON-LD & Microdata, it'll motivate authors to add more of them.

In the meantime, I'm using the "w3p": "http://www.w3.org/2001/02pd/rec54#" context as a hint to label W3C docs as specifications - some SKOS-like layer would be awesome, but well. Perhaps, the IETF, the XSF and some other specs committees will start also to make use of JSON-LD & microdata.

And on the other side of the chain, Read The Doc, the API doc generator has a trace of APIReference although the current generated API docs use https://schema.org/Article.

So hopefully it's only a matter of time before we get more docs with more precise contexts than https://schema.org/Article & https://schema.org/TechArticle.

And regarding "TypeScript definitions ready RDF extractable IDL", I guess it'll happen in the next decade or something.

Indeed it's not really a JSON-LD matter, but it really looked like one of the spec where to demonstrate how useful JSON-LD & Microdata can be.

Keep up the good work. :+1:

Cheers.