Skip to content

Rename ontology uri property to iri #400

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jochenchrist wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Rename ontology uri property to iri #400

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b16c4fa
Rename ontology uri property to iri
jochenchrist Sep 15, 2026
7b61d8e
Document IRIs and prefixes in the ontology specification
jochenchrist Sep 15, 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
12 changes: 6 additions & 6 deletions ontology/ontology.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
},
Expand Down Expand Up @@ -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"],
Expand Down Expand Up @@ -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"],
Expand Down
58 changes: 58 additions & 0 deletions ontology/ontology.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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

@Ostrzyciel Ostrzyciel Sep 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not directly related to this PR, but... Please note that deciding which form to parse here is not really possible to do for all possible cases. For example urn:isbn:whatever is a valid IRI. What if you have a prefix urn:?

In LinkML there is the exact same issue with the uriorcurie datatype. See: linkml/linkml#3906

Should there be a follow-up to define a clear algorithm for how iri should be parsed and serialized?

@scotthenninger scotthenninger Sep 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

URNs are valid IRIs (from RDC 3987) so they should be allowed. @jochenchrist perhaps the md can reflect this:

The ‘irk’ field accepts two forms:

  • A full IRI, e.g. http://xmlns.com/foaf/0.1/Agent, urn:foaf:Agent
  • A QName …

I’m also curious about @Ostrzyciel’s statements that it’s not possible to implement all cases. RDF processors have been doing this for years. Do I misunderstand your statement?

@jochenchrist jochenchrist Sep 16, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. I think @Ostrzyciel is pointing that how can we decide if a value is a QName (to lookup the prefix) vs. an URN, as both have the form schema:values.

However, URNs always start with urn:....

An idea might be to not allow a prefix urn.

I will update the PR accordingly to mention that URNs are alos allowed as IRI.

@Ostrzyciel Ostrzyciel Sep 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’m also curious about @Ostrzyciel’s statements that it’s not possible to implement all cases. RDF processors have been doing this for years. Do I misunderstand your statement?

In Turtle, these two have different syntaxes. Full IRIs are: <urn:fullIri>. And CURIES/QNames are: urn:qname. They are interpreted differently.

An idea might be to not allow a prefix urn.

URNs are just one possible case where this will break :) IRIs have a ton of forms. You can get a sample here: https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#Example_URIs

As for the solution to this conundrum: I would recommend a solution along the lines of this one proposed in LinkML: linkml/linkml#3906 (comment)

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
Expand Down Expand Up @@ -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

---

Expand Down