Skip to content
Open
Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
7b36b97
Add custom_properties for carrying data not covered by the spec
jochenchrist Jun 3, 2026
9388fec
Document language-tagged literals in custom_properties
jochenchrist Jun 3, 2026
118776e
Move root custom_properties below the ontology key in example
jochenchrist Jun 3, 2026
830f905
Merge branch 'main' into feat/ontology-custom-properties
jochenchrist Aug 18, 2026
ebe5e89
Flatten concept declaration in foaf example
jochenchrist Aug 18, 2026
e134875
Merge remote-tracking branch 'origin/main' into feat/ontology-custom-…
jochenchrist Sep 15, 2026
9d97812
Merge remote-tracking branch 'origin/main' into feat/ontology-custom-…
jochenchrist Sep 19, 2026
7856958
ontology: drop language-tag and CURIE conventions from custom_properties
jochenchrist Sep 19, 2026
412e557
ontology: use the uri field instead of an iri custom property in exam…
jochenchrist Sep 19, 2026
8ec0f51
ontology: metrics-style custom_properties example; QName keys in FOAF…
jochenchrist Sep 19, 2026
c8b373c
Merge remote-tracking branch 'origin/main' into feat/ontology-custom-…
jochenchrist Sep 30, 2026
c114388
Merge remote-tracking branch 'origin/main' into feat/ontology-custom-…
jochenchrist Oct 5, 2026
5bf47ec
Use the FOAF import as the custom_properties example
jochenchrist Oct 5, 2026
83abbd8
Rename custom_properties to annotations
jochenchrist Oct 12, 2026
5f6583b
Merge remote-tracking branch 'origin/main' into feat/ontology-custom-…
jochenchrist Oct 31, 2026
a11c6e5
Merge remote-tracking branch 'origin/main' into feat/ontology-custom-…
jochenchrist Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions examples/foaf_owl_import.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.

version: 0.2.0.dev0
name: foaf
description: >
Small ontology imported from the FOAF (Friend of a Friend) OWL vocabulary,
demonstrating how custom_properties preserves OWL/RDF data (labels, comments,
and axioms) that the core Ossie spec does not model, so the source can be
round-tripped. This importer keys custom properties by the source predicate's
qualified name; that is the importer's convention, not a requirement of the spec.
prefixes:
foaf: "http://xmlns.com/foaf/0.1/"
rdfs: "http://www.w3.org/2000/01/rdf-schema#"
owl: "http://www.w3.org/2002/07/owl#"
dc: "http://purl.org/dc/elements/1.1/"
ontology:
- concept: Person
type: EntityType
iri: foaf:Person
custom_properties:
rdfs:label: "Person"
rdfs:comment: "A person."
owl:equivalentClass: "https://schema.org/Person"
relationships:
- name: name
iri: foaf:name
roles:
- concept: String
verbalizes: [ "{Person} has name {String}" ]
multiplicity: ManyToOne
custom_properties:
rdfs:label: "name"
- name: knows
iri: foaf:knows
roles:
- concept: Person
name: acquaintance
verbalizes: [ "{Person} knows {Person:acquaintance}" ]
custom_properties:
rdfs:label: "knows"
owl:inverseOf: foaf:knows
custom_properties:
dc:title: "Friend of a Friend (FOAF) vocabulary"
17 changes: 17 additions & 0 deletions ontology/ontology.json
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,9 @@
"$ref": "#/$defs/OntologyMap"
}
},
"custom_properties": {
"$ref": "#/$defs/CustomProperties"
},
"prefixes": {
"type": "object",
"description": "Maps namespace prefixes to the IRIs they abbreviate, enabling QName expansion (e.g., 'foaf' -> 'http://xmlns.com/foaf/0.1/').",
Expand All @@ -55,6 +58,11 @@
"required": ["version", "name", "ontology"],
"additionalProperties": false,
"$defs": {
"CustomProperties": {
"type": "object",
"description": "Open set of custom properties for carrying data that is not covered by the core ontology spec, for example when importing an ontology from an external format such as OWL/RDF. Keys are free-form and values may be any JSON; the spec does not interpret their structure.",
"additionalProperties": true
},
"OntologyComponent": {
"type": "object",
"description": "Ontology component that defines a single concept and any relationships that are keyed primarily by that concept",
Expand Down Expand Up @@ -105,6 +113,9 @@
},
"description": "Defines relationships that pertain primarily to the concept defined in this component"
},
"custom_properties": {
"$ref": "#/$defs/CustomProperties"
},
"iri": {
"type": "string",
"description": "Optional global identifier for this concept, expressed as a full IRI or as a QName (prefix:local) resolved against the ontology-level 'prefixes' map."
Expand Down Expand Up @@ -160,6 +171,9 @@
},
"description": "Natural language expressions that verbalize this relationship"
},
"custom_properties": {
"$ref": "#/$defs/CustomProperties"
},
"iri": {
"type": "string",
"description": "Optional global identifier for this relationship, expressed as a full IRI or as a QName (prefix:local) resolved against the ontology-level 'prefixes' map."
Expand Down Expand Up @@ -231,6 +245,9 @@
"name": {
"type": "string",
"description": "Optional name of this role, used when the same concept plays multiple roles in the same relationship"
},
"custom_properties": {
"$ref": "#/$defs/CustomProperties"
}
},
"required": ["concept"],
Expand Down
35 changes: 35 additions & 0 deletions ontology/ontology.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ hierarchically, grouping each relationship under the concept that plays its firs
| `ai_context` | string/object | No | Additional context for AI tools |
| `ontology` | list | Yes | Concepts and relationships they group that form this ontology |
| `prefixes` | object | No | Namespace prefixes used to abbreviate [IRIs](#global-identifiers) |
| `custom_properties` | object | No | Open set of custom properties not covered by this spec (see [Custom properties](#custom-properties)) |

Each component of an ontology declares a concept and lists the relationships where that
concept plays the first role. The concept's name is the value of the `concept` field, and
Expand All @@ -113,6 +114,7 @@ Concepts have the following schema:
| `requires` | list | No | Expressions that constrain this concept's population |
| `relationships` | list | No | Relationships where this concept plays the first role |
| `iri` | string | No | Optional [global identifier](#global-identifiers) of this concept |
| `custom_properties` | object | No | Open set of custom properties not covered by this spec (see [Custom properties](#custom-properties)) |

Each concept is either an entity type or a value type.

Expand Down Expand Up @@ -158,6 +160,7 @@ Each relationship that is declared under a concept conforms to the following sch
| `requires` | list | No | Expressions that constrain this relationship's population |
| `verbalizes` | list | Yes | Patterns describing how to verbalize links |
| `iri` | string | No | Optional [global identifier](#global-identifiers) of this relationship |
| `custom_properties` | object | No | Open set of custom properties not covered by this spec (see [Custom properties](#custom-properties)) |

Each relationship is uniquely identified by prepending its declared name with that of the containing
concept. For instance, in:
Expand Down Expand Up @@ -201,6 +204,7 @@ using this schema:
|-------|------|----------|-------------|
| `concept` | string | Yes | Name of the concept that plays this role |
| `name` | string | No | Optional role name |
| `custom_properties` | object | No | Open set of custom properties not covered by this spec (see [Custom properties](#custom-properties)) |

For instance, in:

Expand Down Expand Up @@ -436,6 +440,35 @@ Expressions, roles, and mappings continue to use local names. The IRI serves too
between this specification and IRI-based languages and lets multiple ontologies state that they
refer to the same externally defined concept or relationship.

### Custom properties

The ontology root, concepts, relationships, and roles may each carry a `custom_properties` object: an
open set of key-value pairs for data that the core spec does not model. This gives tools a place to
attach their own metadata, or to preserve information when importing an ontology from an external
format so that it can be round-tripped.

Keys are free-form, and values may be any JSON. The spec does not interpret or constrain the structure of
`custom_properties`; tools that do not understand a given property should preserve it as-is. For example,
a metrics tool might annotate a value type with how it is computed and displayed:

```yaml
ontology:
- concept: ContributionMargin
type: ValueType
extends: [Decimal]
description: Revenue remaining after variable costs
custom_properties:
abbreviation: CM
formula: revenue - variable_costs
unit: EUR
better_when: higher
owner: finance-analytics
```

An importer from a semantic-web format might instead use the source vocabulary's qualified names as keys,
as in the [FOAF example](../examples/foaf_owl_import.yaml). Both are valid; the choice of keys belongs to
the tool that writes them.

## Ontology mappings

Ontology mappings declare how to map the values of fields at the logical level to objects and links
Expand Down Expand Up @@ -665,6 +698,8 @@ though `Store` plays a role in three of the relationships.
- Core ontology structure: Concepts, relationships, and business rules (requires and derived_by)
- Schema mappings from one or more logical models into an ontology
- Optional IRIs on concepts and relationships, with namespace prefixes declared at the top level
- `custom_properties` on the ontology root, concepts, relationships, and roles for carrying
data not covered by the core spec (e.g. when importing from OWL/RDF)

---

Expand Down
Loading