search

HydraCG / Specifications

Specifications created by the Hydra W3C Community Group
Other
138 stars 26 forks source link

Create Hydra specification from JSON example #101

Open asbjornu opened 8 years ago

asbjornu commented 8 years ago

It would be awesome if a tool existed that could take a JSON document and create a Hydra specification (ontology? schema? document?) for it. The tool could recognize properties and map them to known Hydra properties and perhaps even known external ontologies (like schema.org, Dublin Core, etc.). For unknown properties, it could just use simple heuristics to deduce its type based on the property's JSON type.

I think this would make Hydra a lot more accessible to anyone who has an idea of what JSON they want to produce, but have no idea how to author a Hydra schema (or what it’s called) for it.

Mec-iS commented 8 years ago

Hi @asbjornu, As a developer, I have found pretty difficult to start with the Hydra schema. The spec has a great coverage but undoubtedly RDF doesn't make it easy to approach. It would be great to have a tool to generate Hydra ApiDoc from some kind of available human-readable documentation (JSON or YAML) like the one provided by the Swagger specification. Developers would really appreciate to have, at least, a starting barebone to base their properties definitions in a later time.

An example of such kind of documentation: https://github.com/swagger-api/swagger-spec/blob/master/examples/v2.0/yaml/api-with-examples.yaml

I have set up a test server with a basic YAML for this purpose at Mec-iS/mild-QL. In the beginning the idea was to deploy an HYDRA server by translating some basic properties in the YAML and later try some kind of binding with graphQL queries. Unfortunately I don't have much time to go on with that by myself.

Mec-iS commented 5 years ago

This idea is now partially implemented by the OpenAPI parser implemented at GSOC-2018.

The parser takes as input an OpenAPI spec in YAML or JSON format and defines automatically an usable Hydra ApiDoc:

asbjornu commented 5 years ago

@Mec-iS, that's awesome! Great job!

alien-mcl commented 5 years ago

There is also an option of an extension to Heracles.ts that would transform such a JSON on the fly and provide to the client. Heracles.ts is somehow enabled for such a scenario as there is a layer of media type related interpreters and a internal data model that fits somehow Hydra JSON-LD, but is disconnected from it.