Skip to content

Ontology: Add custom_properties (e.g. for OWL import)#146

Open
jochenchrist wants to merge 3 commits into
open-semantic-interchange:mainfrom
jochenchrist:feat/ontology-custom-properties
Open

Ontology: Add custom_properties (e.g. for OWL import)#146
jochenchrist wants to merge 3 commits into
open-semantic-interchange:mainfrom
jochenchrist:feat/ontology-custom-properties

Conversation

@jochenchrist

@jochenchrist jochenchrist commented Jun 3, 2026

Copy link
Copy Markdown
Contributor

Summary

Importing an ontology from an external format such as OWL/RDF currently loses any data that the core OSI spec does not model — IRIs, rdfs:label, owl:equivalentClass, annotations, provenance, and so on — because every ontology object is locked down with additionalProperties: false. There is no place to put it, so a round-trip (OWL → OSI → OWL) is lossy.

This PR adds an open custom_properties object to the ontology root, concepts, relationships, and roles. Keys are free-form and values may be any JSON, so importers can preserve foreign data and round-trip it. The rest of each object keeps additionalProperties: false, so custom_properties is the single, explicit escape hatch rather than letting arbitrary keys leak in anywhere.

For semantic-web sources, CURIEs such as owl:equivalentClass or rdfs:label are recommended so the origin of each property stays clear.

ontology:
  - concept:
      name: Person
      type: EntityType
      custom_properties:
        iri: "http://xmlns.com/foaf/0.1/Person"
        rdfs:label: "Person"
        owl:equivalentClass: "https://schema.org/Person"

Design notes

The core spec (logical model) already has a custom_extensions: [{vendor_name, data}] mechanism where data is a stringified JSON blob. I deliberately did not reuse that here:

  • OWL/RDF is a standard interchange format, not a single "vendor", so a vendor_name blob is an awkward fit.
  • A structured map keeps OWL annotations as real, queryable/validatable JSON instead of an opaque string.

If maintainers would prefer to unify on one extensibility mechanism spec-wide, I'm happy to switch this to the custom_extensions shape instead — flagging the choice explicitly.

Changes

  • ontology/ontology.json: add a reusable CustomProperties $def and reference it from the root, Concept, Relationship, and Role.
  • ontology/ontology.md: add the field to the four schema tables, a new "Custom properties" section with an OWL example, and a version-history note.
  • examples/foaf_owl_import.yaml: a small FOAF/OWL import example exercising custom_properties at the root, concept, relationship, and role levels.

Validation

  • ontology/ontology.json is well-formed JSON.
  • The new example and the existing examples/flights.yaml both validate against the updated schema (Draft 2020-12).
  • Confirmed unknown keys are still rejected everywhere except inside custom_properties.

Language-tagged literals

RDF literals are often language-tagged. The recommended convention is to append the BCP 47 tag to the key after an @ (rdfs:label@en, rdfs:label@fr); @ is not legal in a CURIE local name, so this parses unambiguously. For the cases the flat form cannot express (multiple values in one language, or a non-language datatype such as xsd:date), the docs point at the lossless JSON-LD value-object form. This is convention only; OSI still treats custom_properties as opaque.

Importing an ontology from an external format such as OWL/RDF loses any
data that the core OSI spec does not model (IRIs, rdfs:label,
owl:equivalentClass, annotations, provenance, ...), because every
ontology object is locked down with additionalProperties: false.

Add an open `custom_properties` object to the ontology root, concepts,
relationships, and roles. Keys are free-form and values may be any JSON,
so tools can preserve foreign data and round-trip it. CURIEs like
`owl:equivalentClass` are recommended for semantic-web sources. The rest
of each object keeps additionalProperties: false, so custom_properties
is the single, explicit escape hatch.

Includes a FOAF/OWL import example and documents the field in the spec.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@jochenchrist jochenchrist changed the title Add custom_properties to ontology elements (e.g. for OWL import) Ontology: Add custom_properties (e.g. for OWL import) Jun 3, 2026
jochenchrist and others added 2 commits June 3, 2026 10:10
RDF labels and comments are usually language-tagged and the previous
example used a plain string, which is lossy. Recommend the readable
`prefix:local@lang` key convention for language-tagged literals (the `@`
cannot appear in a CURIE local name, so it parses unambiguously), and
point at the JSON-LD value-object form for the multi-value and typed
literal cases that the flat form cannot express.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@khush-bhatia khush-bhatia requested a review from jbonofre June 3, 2026 17:43

@kurtStirewalt kurtStirewalt left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a nice addition!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants