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

[jochenchrist]

Summary

Importing an ontology from an external format such as OWL/RDF currently loses any data that the core OSI spec does not model (labels, equivalence axioms, 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 spec does not interpret or constrain the structure of custom_properties. 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.

ontology:
  - concept: ContributionMargin
    type: ValueType
    extends: [Decimal]
    custom_properties:
      abbreviation: CM
      formula: revenue - variable_costs
      unit: EUR
      better_when: higher

An OWL importer would instead key properties by the source predicate (rdfs:label, owl:equivalentClass); see examples/foaf_owl_import.yaml. The choice of keys belongs to the tool that writes them, not the spec.

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 imported 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 a metrics example, and a version-history note.
• examples/foaf_owl_import.yaml: a small FOAF/OWL import example exercising custom_properties at the root, concept, and relationship levels, with a prefixes map and QName keys.

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.

[kurtStirewalt]

This is a nice addition!

[jbonofre]

Overall good, I just wonder if we should use custom_properties or custom_extensions.

@jochenchrist @kurtStirewalt thoughts?

[jochenchrist]

@jbonofre @kurtStirewalt
To push this PR, we would need a decision.

Option A

Structured custom_properties:

Example:

  - concept:
      name: Person
      type: EntityType
      custom_properties:
        iri: "http://xmlns.com/foaf/0.1/Person"
        rdfs:label@en: "Person"
        rdfs:label@fr: "Personne"
        rdfs:comment@en: "A person."
        owl:equivalentClass: "https://schema.org/Person"

Consequences:

• Different to core-spec v0.0.1 custom_extensions
• I would introduce a PR to deprecate custom_extensions and introduce custom_properties in core spec as well.

Option B

Same with custom_extensions

  - concept: Person
    type: EntityType
    custom_extensions:
      - vendor_name: OWL
        data: |
          {
            "iri": "http://xmlns.com/foaf/0.1/Person",
            "rdfs:label@en": "Person",
            "rdfs:label@fr": "Personne",
            "rdfs:comment@en": "A person.",
            "owl:equivalentClass": "https://schema.org/Person"
          }

Consequences:

• Following core-spec v0.0.1 version
• This data string (JSON in String...) is hard to read, serialize, and validate. But maybe good-enough?

What do you think?

[scotthenninger]

Option A would be my preference.

On language tags why not use the RDF convention of delimiting the string, e.g.
rdfs:comment “A person”@en

[Ostrzyciel]

This will be very messy to parse, in my opinion. Why not:

rdfs:label:
  en: "Person"
  fr: "Personne"

This would not require mixing in the language tag into the property IRI, which is some new invented syntax. The syntax I wrote above is already used in LinkML-Scala.