Skip to content
Open
Show file tree
Hide file tree
Changes from all 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
5 changes: 5 additions & 0 deletions .github/workflows/validation-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ on:
- "examples/flights*.yaml"
- "examples/tpcds_semantic_model.yaml"
- "examples/renamed_fields.yaml"
- "examples/foaf_owl_import.yaml"
- ".github/workflows/validation-ci.yml"
- "scripts/generate-spec-types.py"
- "scripts/audit-spec-changes.py"
Expand All @@ -46,6 +47,7 @@ on:
- "examples/flights*.yaml"
- "examples/tpcds_semantic_model.yaml"
- "examples/renamed_fields.yaml"
- "examples/foaf_owl_import.yaml"
- ".github/workflows/validation-ci.yml"
- "scripts/generate-spec-types.py"
- "scripts/audit-spec-changes.py"
Expand Down Expand Up @@ -103,3 +105,6 @@ jobs:

- name: Validate renamed-fields example
run: uv run validation/validate.py examples/renamed_fields.yaml

- name: Validate FOAF example
run: uv run validation/validate.py examples/foaf_owl_import.yaml --schema ontology/ontology.json
65 changes: 65 additions & 0 deletions examples/foaf_owl_import.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# 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.3.0.dev0
name: foaf
description: >
Small ontology imported from the FOAF (Friend of a Friend) OWL vocabulary.
The importer writes RDF data that has a home in the spec to that field
(rdfs:comment becomes description) and preserves the rest (labels, axioms,
term status) in annotations, so the source can be round-tripped. This
importer keys annotations 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/"
vs: "http://www.w3.org/2003/06/sw-vocab-status/ns#"
annotations:
dc:title: "Friend of a Friend (FOAF) vocabulary"
ontology:
- concept: Person
type: EntityType
description: "A person."
iri: foaf:Person
annotations:
rdfs:label: "Person"
owl:equivalentClass: "http://schema.org/Person"
vs:term_status: "stable"
relationships:
- name: name
description: "A name for some thing."
iri: foaf:name
roles:
- concept: String
verbalizes: [ "{Person} has name {String}" ]
multiplicity: ManyToOne
annotations:
rdfs:label: "name"
rdfs:subPropertyOf: "rdfs:label"
vs:term_status: "testing"
- name: knows
description: "A person known by this person (indicating some level of reciprocated interaction between the parties)."
iri: foaf:knows
roles:
- concept: Person
name: acquaintance
verbalizes: [ "{Person} knows {Person:acquaintance}" ]
annotations:
rdfs:label: "knows"
vs:term_status: "stable"
17 changes: 17 additions & 0 deletions ontology/ontology.json
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,9 @@
"$ref": "#/$defs/OntologyMap"
}
},
"annotations": {
"$ref": "#/$defs/Annotations"
},
"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 @@ -58,6 +61,11 @@
"required": ["version", "name", "ontology"],
"additionalProperties": false,
"$defs": {
"Annotations": {
"type": "object",
"description": "Open set of annotations 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 @@ -111,6 +119,9 @@
},
"description": "Defines relationships that pertain primarily to the concept defined in this component"
},
"annotations": {
"$ref": "#/$defs/Annotations"
},
"iri": {
"type": "string",
"minLength": 1,
Expand Down Expand Up @@ -170,6 +181,9 @@
},
"description": "Natural language expressions that verbalize this relationship"
},
"annotations": {
"$ref": "#/$defs/Annotations"
},
"iri": {
"type": "string",
"minLength": 1,
Expand Down Expand Up @@ -251,6 +265,9 @@
"type": "string",
"minLength": 1,
"description": "Optional name of this role, used when the same concept plays multiple roles in the same relationship"
},
"annotations": {
"$ref": "#/$defs/Annotations"
}
},
"required": ["concept"],
Expand Down
45 changes: 45 additions & 0 deletions ontology/ontology.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ text and may be empty.
| `ontology` | list | Yes | Concepts and relationships they group that form this ontology |
| `prefixes` | object | No | Namespace prefixes used to abbreviate [IRIs](#global-identifiers); each prefix's IRI must be non-empty |
| `ontology_mappings` | list | No | Deprecated; accepted only so existing documents continue to validate. Write mappings as [mapping documents](#mapping-documents) instead |
| `annotations` | object | No | Open set of annotations for data not covered by this spec (see [Annotations](#annotations)) |

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 @@ -120,6 +121,7 @@ Concepts have the following schema:
| `requires` | list | No | Expressions that constrain this concept's population; each must be non-empty |
| `relationships` | list | No | Relationships where this concept plays the first role |
| `iri` | string | No | Optional [global identifier](#global-identifiers) of this concept; must be non-empty when present |
| `annotations` | object | No | Open set of annotations for data not covered by this spec (see [Annotations](#annotations)) |

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

Expand Down Expand Up @@ -165,6 +167,7 @@ Each relationship that is declared under a concept conforms to the following sch
| `requires` | list | No | Expressions that constrain this relationship's population; each must be non-empty |
| `verbalizes` | list | Yes | Patterns describing how to verbalize links; each must be non-empty |
| `iri` | string | No | Optional [global identifier](#global-identifiers) of this relationship; must be non-empty when present |
| `annotations` | object | No | Open set of annotations for data not covered by this spec (see [Annotations](#annotations)) |

Each relationship is uniquely identified by prepending its declared name with that of the containing
concept. For instance, in:
Expand Down Expand Up @@ -208,6 +211,7 @@ using this schema:
|-------|------|----------|-------------|
| `concept` | string | Yes | Name of the concept that plays this role; must be non-empty |
| `name` | string | No | Optional role name; must be non-empty when present |
| `annotations` | object | No | Open set of annotations for data not covered by this spec (see [Annotations](#annotations)) |

For instance, in:

Expand Down Expand Up @@ -443,6 +447,45 @@ 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.

### Annotations

The ontology root, concepts, relationships, and roles may each carry an `annotations` 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
`annotations`; tools that do not understand a given annotation should preserve it as-is.

Use `annotations` only for data that the spec cannot express. Data that has a home in the spec,
such as a description, a supertype (`extends`), a derivation (`derived_by`), a constraint (`requires`),
or a verbalization (`verbalizes`), belongs in that field.

For example, an importer from the OWL version of the [FOAF](http://xmlns.com/foaf/0.1/) vocabulary
writes `rdfs:comment` to `description` and keeps the RDF data that has no home in the spec, keyed by
the source predicate's qualified name:

```yaml
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#"
vs: "http://www.w3.org/2003/06/sw-vocab-status/ns#"
ontology:
- concept: Person
type: EntityType
description: A person.
iri: foaf:Person
annotations:
rdfs:label: Person
owl:equivalentClass: http://schema.org/Person
vs:term_status: stable
```

The full document is in [`examples/foaf_owl_import.yaml`](../examples/foaf_owl_import.yaml). Keying
annotations by qualified name is this importer's convention. 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 @@ -702,6 +745,8 @@ though `Store` plays a role in three of the relationships.
- Optional IRIs on concepts and relationships, with namespace prefixes declared at the top level
- Mapping documents (`ontology/mapping.json`) that reference one ontology and one semantic
model; embedded `ontology_mappings` is deprecated
- `annotations` 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