SHACL to JSON-schema conversion

[mathiasrichter]

Add support for converting the nodeshapes defined in a model into JSON-schema so models/model elements can directly be referenced in OpenAPI/Swagger definitions without breaking the OpenAPI tooling.

[ioggstream]

Hi @mathiasrichter,

in my experience, since JSON Schema and SHACL have different goals and data models, it is not always possible to consistently and interoperably derive JSON Schema out of SHACL.

In production, people will probably need to write a specific JSON Schema that is capable to provide all the required details.

[mathiasrichter]

Thanks for pointing this out Roberto. Agree with you, I might find that it is an impossible feat - I want to try and see under which conditions a conversion can succeed which use cases these would support in using the OpenAPI/Swagger tooling for implementing APIs.

[mathiasrichter]

As an add-on to my previous comment: have a look here https://groups.google.com/g/topbraid-users/c/814seb5h38Y

This kind of encourages me to try the conversion...

[ioggstream]

@mathiasrichter In this document you can find some more context about the limits of deriving data schema from ontologies. https://docs.google.com/document/d/1iTrseL5aA02ejIbcT-2bDUGwdLunKulzPA9ejdRXZL8/edit#heading=h.82rr9yl45cuy

The reasoning is quite articulated, as it applies to complex, long-standing ecosystem of services and providers and not to specific use cases. All my attempts for reliably deriving JSschema from RDF in real world services gave results that were not considered useful by API providers.

The document tries to formalize the problems I faced:

• Ontologies model the problem space;
• data schemas pertain to the solution space, that is affected by non-functional requirements
• using ontologies directly in the solution space shifts ontologies from a generic problem space to a service-specific solution space: there is no guarantee that non-functional requirements allow this shift without modifications. At this point, you're just defining data schemas in RDF (which is a language not designed for this).

I suggest reading the gdoc before starting this work, and verify whether the contained considerations make sense to you.
If you are not able to comment, please ask for access.

cc: @rob-metalinkage who is interested in the discussion.

[mathiasrichter]

initial version implemented. will certainly need improvements as it is being put to use in different use cases. Works with swagger-codegen.

[rob-metalinkage]

Can you expand on "initial version implemented" - where and how?

see json-schema-org/json-schema-vocabularies#13 for further discussions how the link to the model from the schema could look like after such a conversion. Do you have a suggestion for the link to the SHACL?

NB we have a generalised model for linking a conceptual "profile" to multiple resources such as SHACL, schema, context etc that perform different roles - see https://www.w3.org/TR/dx-prof/ - this is the way my organisation holds tool chains together doing this sort of thing - both as configuration to find all the resources and to publish such resources in a coherent Linked Data fashion.

[mathiasrichter]

Hi Rob, thanks for reaching out. Haven't had a chance to review your material yet and will elaborate once I had a chance to do so.

In the meantime, in terms of where have I implemented this:

1. To try this: pull down Shapiro, fire it up and use whatever REST client you like to send a request for a rdfs:Class or sh:NodeShape defined in one of the models hosted by Shapiro with accept-header applicaton/json or application/schema+json and Shapiro will reply with the JSON-SCHEMA.
2. In terms of code: have a look at JsonSchemaRenderer in shapiro_render.py
3. Also have a look at test/openapi/tutorial.json or tutorial.yml - this shows how you would use model entities defined using semantic tech and served by Shapiro in an OpenAPI declaration.

[ioggstream]

Hi @mathiasrichter, reading https://github.com/mathiasrichter/shapiro#writing-semantic-models-to-be-served-by-shapiro I understand that Shapiro requires modeling ontologies using specific constraints. Do you think this requires modifying existing ontologies to match the patterns supported by Shapiro?

[mathiasrichter]

Hi Roberto. In an ideal world Shapiro would not put any restrictions, and I am trying to keep them minimal, but I've got to take some assumptions. In the end it boils down to Shapiro knowing

1. what concept of class to look for (currently owl:Class, rdfs:class)
2. what concept of property to look for (currently, rdfs:Property and shacl:Property)
3. which constraint vocabulary to support (currently SHACL)

I am hoping that 1 and 2 would not impose too much restriction: I didn't find other definitions of class and owl:Class even derives from rdfs:Class, it seems everybody uses rdfs:Property, but if I have to extend Shapiro's view I will.

Regarding the generation of JSON-SCHEMA: that obviously requires NodeShapes to be defined as only those would come with the actual constraints you would want to see in your JSON-SCHEMA. You can generate JSON-SCHEMA for an ontology made of rdfs:Class entities without NodeShape definitions, this will create a JSON-SCHEMA with no constraints and therefore always validate to true.

But in all this, my imagination is limited to the cases I can think of, so I am more than happy to get support from the community trying their ontologies/vocabularies for HTML & JSON-SCHEMA rendering, so I can make Shapiro as little restrictive and as open as possible...