From b16c4fa45ca31255f7d927437465c1aa401832ef Mon Sep 17 00:00:00 2001 From: jochen Date: Tue, 15 Sep 2026 11:29:14 +0200 Subject: [PATCH 1/2] Rename ontology uri property to iri Follow-up to #332. The global identifier on concepts and relationships is now called iri instead of uri, as agreed in the PR discussion (IRI per RFC 3987 covers both full IRIs and QNames). The prefixes map uses the JSON Schema iri format accordingly. --- ontology/ontology.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/ontology/ontology.json b/ontology/ontology.json index 47a00e03..a327505a 100644 --- a/ontology/ontology.json +++ b/ontology/ontology.json @@ -45,10 +45,10 @@ }, "prefixes": { "type": "object", - "description": "Maps namespace prefixes to the URIs they abbreviate, enabling QName expansion (e.g., 'foaf' -> 'http://xmlns.com/foaf/0.1/').", + "description": "Maps namespace prefixes to the IRIs they abbreviate, enabling QName expansion (e.g., 'foaf' -> 'http://xmlns.com/foaf/0.1/').", "additionalProperties": { "type": "string", - "format": "uri" + "format": "iri" } } }, @@ -105,9 +105,9 @@ }, "description": "Defines relationships that pertain primarily to the concept defined in this component" }, - "uri": { + "iri": { "type": "string", - "description": "Optional global identifier for this concept, expressed as a full URI or as a QName (prefix:local) resolved against the ontology-level 'prefixes' map." + "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." } }, "required": ["concept", "type"], @@ -160,9 +160,9 @@ }, "description": "Natural language expressions that verbalize this relationship" }, - "uri": { + "iri": { "type": "string", - "description": "Optional global identifier for this relationship, expressed as a full URI or as a QName (prefix:local) resolved against the ontology-level 'prefixes' map." + "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." } }, "required": ["name", "verbalizes"], From 7b61d8ee7f3e842f8d357b52b16499dae712f450 Mon Sep 17 00:00:00 2001 From: jochen Date: Tue, 15 Sep 2026 11:34:00 +0200 Subject: [PATCH 2/2] Document IRIs and prefixes in the ontology specification Adds the prefixes field to the top-level table, the iri field to the concept and relationship tables, and a Global identifiers section that explains IRIs, QName expansion against prefixes, and how IRIs relate to local names. --- ontology/ontology.md | 58 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/ontology/ontology.md b/ontology/ontology.md index 94002a5c..fb576cb5 100644 --- a/ontology/ontology.md +++ b/ontology/ontology.md @@ -88,6 +88,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 | +| `prefixes` | object | No | Namespace prefixes used to abbreviate [IRIs](#global-identifiers) | 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 @@ -111,6 +112,7 @@ Concepts have the following schema: | `identify_by` | list | No | Names of relationships that uniquely reference objects of this concept | | `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 | Each concept is either an entity type or a value type. @@ -155,6 +157,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 | +| `iri` | string | No | Optional [global identifier](#global-identifiers) of this relationship | Each relationship is uniquely identified by prepending its declared name with that of the containing concept. For instance, in: @@ -379,6 +382,60 @@ 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. +### Global identifiers + +Concept and relationship names are local to the ontology that declares them. To relate a concept +or relationship to a definition outside the ontology, for instance a class or property in an +existing RDF or OWL vocabulary, it can carry an optional `iri` field that holds a globally unique +identifier. An IRI (Internationalized Resource Identifier, [RFC 3987](https://www.rfc-editor.org/info/rfc3987/)) +is a generalization of a URI that permits characters beyond ASCII. Any URI is also a valid IRI. + +The `iri` field accepts two forms: + +- A full IRI, e.g. `http://xmlns.com/foaf/0.1/Agent`. +- A QName of the form `prefix:local`, e.g. `foaf:Agent`, where `prefix` is declared in the + ontology-level `prefixes` map. The QName expands to the prefix's IRI followed by the local + part, so `foaf:Agent` expands to `http://xmlns.com/foaf/0.1/Agent`. + +The `prefixes` map is declared at the top level of the specification. Each key is a prefix and each +value is the IRI that the prefix abbreviates: + +```yaml +name: OrganizationOntology +prefixes: + foaf: http://xmlns.com/foaf/0.1/ + org: http://www.w3.org/ns/org# +ontology: + - concept: Agent + type: EntityType + iri: foaf:Agent + description: "A generic agent (person, organization, etc.)" + relationships: + - name: has_homepage + iri: foaf:homepage + roles: + - concept: Homepage + multiplicity: ManyToOne + verbalizes: [ "{Agent} has {Homepage}" ] + - concept: Homepage + type: ValueType + extends: [String] + - concept: Organization + type: EntityType + extends: [Agent] + iri: http://www.w3.org/ns/org#Organization +``` + +Here `Agent` and `Agent.has_homepage` are identified by QNames that resolve against the `foaf` +prefix, while `Organization` is identified by a full IRI. Both forms denote the same kind of +identifier; the QName is merely shorthand. A QName whose prefix is not declared in `prefixes` +is invalid. + +An IRI does not change how a concept or relationship is referenced within its own ontology. +Expressions, roles, and mappings continue to use local names. The IRI serves tools that translate +between this specification and IRI-based languages and lets multiple ontologies state that they +refer to the same externally defined concept or relationship. + ## Ontology mappings Ontology mappings declare how to map the values of fields at the logical level to objects and links @@ -590,6 +647,7 @@ 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 + - Optional IRIs on concepts and relationships, with namespace prefixes declared at the top level ---