search

urbanobservatory / standards

Standards and schema documentation for the observatories programme
2 stars 0 forks source link

Platform example added #36

Open SiBell opened 4 years ago

SiBell commented 4 years ago

I've had a quick crack at defining a Class (a Platform). Before doing the rest I figured I better check that the approach I've used is ok?

My biggest worry is that we end up with 2 things to maintain and sync, this HTML document and also our JSON file. So do we:

  1. Sack off the JSON file and define all our classes and properties in this html document.
  2. Auto-build the HTML document from the JSON file.
  3. Something else...
SiBell commented 4 years ago

Here's a screenshot to save faffing about serving the page.

Screenshot 2020-07-23 at 13 33 43
SiBell commented 4 years ago

@lukessmith, we were discussing this on today's call. The conclusion was that we should avoid trying to maintain a HTML document in addition to our JSON-LD file. Ideally, much of the HTML file should be built from the JSON-LD file.

Just wanted to get your opinion on this given that you touch on much of this in your Pull Request. In your comments you suggest building API documentation from the JSON schemas used to validate the API. I've shown this can work nicely. The question is how to build the more general ontology/vocabulary documentation. I.e. our equivalent of the Semantic Sensor Network Docs.

Clearly the JSON-LD file is a great starting point. It includes properties such as @type, label, and sameAs. All things we'd like to display in the build HTML, but what about the other stuff, e.g. an example JSON object (see example in yellow above), or restrictions, or a list of required properties. Some of these are captured in our JSON Schema documents. Can we pull these in somehow? W.r.t example JSON objects, this is something that the OpenAPI standard handles well.

Any thoughts welcome. Definitely no rush on this.