Skip to content
Open
Show file tree
Hide file tree
Changes from 3 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
39 changes: 39 additions & 0 deletions examples/foaf_owl_import.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
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 (IRIs, labels, and
axioms) that the core OSI spec does not model, so the source can be round-tripped.
ontology:
- concept:
name: Person
type: EntityType
custom_properties:
Comment thread
jochenchrist marked this conversation as resolved.
Resolved
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"
relationships:
- name: name
roles:
- concept: String
verbalizes: [ "{Person} has name {String}" ]
multiplicity: ManyToOne
custom_properties:
iri: "http://xmlns.com/foaf/0.1/name"
rdfs:label@en: "name"
- name: knows
roles:
- concept: Person
name: acquaintance
custom_properties:
rdfs:range: "http://xmlns.com/foaf/0.1/Person"
verbalizes: [ "{Person} knows {Person:acquaintance}" ]
custom_properties:
iri: "http://xmlns.com/foaf/0.1/knows"
rdfs:label@en: "knows"
owl:inverseOf: "http://xmlns.com/foaf/0.1/knows"
custom_properties:
owl:Ontology: "http://xmlns.com/foaf/0.1/"
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 @@ -35,11 +35,19 @@
"items": {
"$ref": "#/$defs/OntologyMap"
}
},
"custom_properties": {
"$ref": "#/$defs/CustomProperties"
}
},
"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; CURIEs such as 'owl:equivalentClass' or 'rdfs:label' are recommended when round-tripping semantic-web sources. Values may be any JSON.",
Comment thread
jochenchrist marked this conversation as resolved.
Resolved
"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 @@ -101,6 +109,9 @@
"type": "string"
},
"description": "Natural language expressions that verbalize this relationship"
},
"custom_properties": {
"$ref": "#/$defs/CustomProperties"
}
},
"required": ["name", "verbalizes"],
Expand Down Expand Up @@ -148,6 +159,9 @@
"$ref": "#/$defs/Expression"
},
"description": "Expressions that constrain the population of this concept"
},
"custom_properties": {
"$ref": "#/$defs/CustomProperties"
}
},
"required": ["name", "type"],
Expand Down Expand Up @@ -216,6 +230,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
66 changes: 66 additions & 0 deletions ontology/ontology.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ hierarchically, grouping each relationship under the concept that plays its firs
| `description` | string | No | Human-readable description |
| `ai_context` | string/object | No | Additional context for AI tools |
| `ontology` | list | Yes | Concepts and relationships they group that form this ontology |
| `custom_properties` | object | No | Open set of custom properties not covered by this spec (see [Custom properties](#custom-properties)) |

Each component of an ontology defines a concept and a list of relationships where that
concept plays the first role:
Expand All @@ -95,6 +96,7 @@ Concepts have the following schema:
| `derived_by` | list | No | Expressions that derive this concept's population |
| `identify_by` | list | No | Names of relationships that uniquely reference objects of this concept |
| `requires` | list | No | Expressions that constrain this concept's population |
| `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 @@ -141,6 +143,7 @@ Each relationship that is declared under a concept conforms to the following sch
| `derived_by` | list | No | Expressions that derive links of this relationship |
| `requires` | list | No | Expressions that constrain this relationship's population |
| `verbalizes` | list | Yes | Patterns describing how to verbalize links |
| `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 a prepending its declared name with that of the containing
concept. For instance, in:
Expand Down Expand Up @@ -185,6 +188,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 @@ -372,6 +376,66 @@ ontology:
the first expression requires any value that plays the `Amount` role to be positive while the second
requires any item that has sales in some store to be offered in that store.

### 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
preserve information that would otherwise be lost, which is especially useful when importing an ontology
from an external format such as OWL/RDF and round-tripping it back out.

Keys are free-form, and values may be any JSON. When carrying data from a semantic-web source, CURIEs
such as `owl:equivalentClass` or `rdfs:label` are recommended so the origin of each property stays clear.
Tools that do not understand a given property should preserve it as-is. For example, an OWL importer might
map an `owl:Class` to a concept while retaining its IRI and annotations:

```yaml
ontology:
- concept:
name: Person
type: EntityType
custom_properties:
iri: "http://xmlns.com/foaf/0.1/Person"
rdfs:label@en: "Person"
rdfs:label@fr: "Personne"
owl:equivalentClass: "https://schema.org/Person"
relationships:
- name: knows
roles:
- concept: Person
name: acquaintance
verbalizes: [ "{Person} knows {Person:acquaintance}" ]
custom_properties:
iri: "http://xmlns.com/foaf/0.1/knows"
owl:inverseOf: "http://xmlns.com/foaf/0.1/knows"
```

#### Language-tagged literals

RDF literals often carry a language tag (for example `rdfs:label` with values `"Person"@en` and
`"Personne"@fr`). The recommended convention is to append the [BCP 47](https://www.rfc-editor.org/info/bcp47)
language tag to the key after an `@`, giving keys of the form `prefix:local@lang`:

```yaml
custom_properties:
rdfs:label@en: "Person"
rdfs:label@fr: "Personne"
Comment thread
jochenchrist marked this conversation as resolved.
Resolved
```

`@` is not a legal character in a CURIE local name, so `prefix:local@lang` parses unambiguously into the
property and its language. This form holds at most one value per language per key. When a property needs
multiple values in the same language, or carries a non-language datatype such as `xsd:date`, use the
[JSON-LD](https://www.w3.org/TR/json-ld11/) value-object form instead, which is lossless:

```yaml
custom_properties:
rdfs:label:
- { "@value": "Person", "@language": "en" }
Comment thread
jochenchrist marked this conversation as resolved.
Resolved
- { "@value": "Persona", "@language": "en" }
dcterms:created:
"@value": "2020-01-01"
"@type": "xsd:date"
Comment thread
jochenchrist marked this conversation as resolved.
Resolved
```

## Ontology mappings

Ontology mappings declare how to map the values of fields at the logical level to objects and links
Expand Down Expand Up @@ -585,6 +649,8 @@ though `Store` plays a role in three of the relationships.
- **0.2.0.dev0** (2026-05-29): Basic support for ontologies and logical schema mappings
- Core ontology structure: Concepts, relationships, and business rules (requires and derived_by)
- Schema mappings from one or more logical models into an ontology
- `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