search

eclipse-rdf4j / rdf4j

Eclipse RDF4J: scalable RDF for Java
https://rdf4j.org/
BSD 3-Clause "New" or "Revised" License
352 stars 160 forks source link

Document the RDF4J binary query result format #2416

Open abrokenjester opened 3 years ago

abrokenjester commented 3 years ago

RDF4J has its own binary query result format . It is documented in the Javadoc (see https://rdf4j.org/javadoc/latest/org/eclipse/rdf4j/query/resultio/binary/BinaryQueryResultConstants.html), but we don't publish any sort of spec on the actual website. Would be good for visibility in the wider community to have it as a proper technical report / spec on the site.

abrokenjester commented 3 years ago

@hmottestad I know you have been looking into using Respec to write a report about the SHACL extensions - what are your experiences with it sofar? Should we consider using it for more reports (like this one, and perhaps also at some point convert our REST API spec)?

hmottestad commented 3 years ago

Haven't used it much yet. Just set up the basic webpage. Seems nice enough. Would not use it for documenting a REST spec, would use swagger for that.

abrokenjester commented 3 years ago

Haven't used it much yet. Just set up the basic webpage. Seems nice enough. Would not use it for documenting a REST spec, would use swagger for that.

Yes, I thought about Swagger too, but 'm not sure I like the idea of introducing yet another tool/syntax/markup format into the mix for our website and documentation, alongside hugo markdown and (now) respec html/js. Then again it does look good, and if this (https://www.tenfourty.com/hugo-oai-swagger-example/) is any indication it looks as if there may be a simple way to integrate swagger ui into hugo.

Still for the binary format I think Respec or just regular markdown makes more sense.

hmottestad commented 3 years ago

Yeah. For the binary format you choose what's most appropriate. The respec format is meant for W3C submissions, so it's very much centered around what's required for that.

Swagger is definitely the way to go for rest specs though.