OAS 3.0 initial ontology

[handrews]

The purpose of the ontology is to provide enough information for SHACL to correctly find target nodes and perform validation. The ontology does not need to be complete, and when it is easy to add a triple in the parsing code, that is probably better than trying to infer it through ontology declarations (at least until there is enough running code to run performance tests on inferencing with large API descriptions).

Note that ontologies go in the direction of "if it has properties A, B, and C that define class X, then it is of class X", and are therefore not useful for validation (SHACL performs validation). There is no need to include validation-oriented info in the ontology unless it serves another purpose listed below. See this video for details on OWL vs SHACL usage

For now this needs to document (xsd+rdf+rdfs+possibly some owl2+maybe look at skos):

• parsed types (corresponding directly to JSON Pointer locations in the API description file)
• semantic types (entities in the graph used for primary semantic validation; includes some parsed types)
• sub-types/sub-properties (e.g. the schema will parse each parameter type separately as each has its own schema object, but they are all subtypes of Parameter, which SHACL will need to know)
• how location information works (do we only map to instance JSON Pointers in the graph, and handle file/line number elsewhere? how much schema location information do we need to retain after schema parsing is done?)
• anything with a clearly beneficial inferencing impact (meaning it's easier/faster to use inferencing through rdflib than adding the triples in code)

It's unclear at this stage how much the ontology should attempt to describe JSON Schema. There is an RDF ontology for JSON schema draft-07 (I think) in the W3C Web of Things group, which is probably worth adapting if we need such a thing.