[jdsika]

Mirror of linkml#4157, same head. Review there; this PR tracks the fork stack.

Read first: generators/common/annotations.py (120 lines), then owlgen.py (42); 184 lines of source in all; the rest is tests and docs.

An annotation whose tag a metaclass declares through instantiates now gets the RDF term that the slot's range gives a slot value, by the rule of linkml#4156 (linkml_runtime.utils.rdf_terms). gen-owl and gen-shacl (--include-annotations) share it through linkml.generators.common.annotations, and gen-owl applies the same rule to native metadata such as see_also.

Example

classes:
  Reviewable:
    attributes:
      reviewer: {range: nodeidentifier}
      review: {range: string}
  Person:
    instantiates: [ex:Reviewable]
    annotations: {reviewer: ex:alice, review: well defined}

	main	this PR
reviewer	"ex:alice"@en	<https://example.org/alice>
review	"well defined"@en	unchanged

On main the declared range is ignored: every annotation value is a string, and with --default-language every value is language-tagged, identifiers included. This is the pattern of the annotations guide; the metaclass needs no further declaration.

The rule

• A type range gives the term of a slot value of that type (fix(rdf): give values of URI-like types one RDF term kind in every generator linkml/linkml#4156): nodeidentifier, uri and uriorcurie give IRIs, or a blank node for a _: label; string gives text, with the language; curie gives an xsd:string literal; a string-derived xsd:anyURI type gives an xsd:anyURI literal.
• An enum range gives the permissible value's text as a plain literal.
• A class range, a structured value or an undeclared tag keeps the generator's earlier behaviour.
• Two metaclasses that declare the tag with different terms are an error.
• Native metadata in gen-owl follows the metamodel slot's range: see_also, source, created_by and the mappings are IRIs, with CURIEs expanded through the schema's prefixes; license, description and title are strings; created_on is an xsd:dateTime literal.

Standards and LinkML contract

• OWL 2 §10.1: an annotation value is an IRI, an anonymous individual or a literal, so every declared term is admissible.
• LinkML specification, part 5: instantiates makes a metaclass's slots the declarations of an element's annotations.
• specify IRI data type for annotations linkml/linkml#2892: cmungall, "We should implement this … declare the range in your custom annotation model". No new option and no vocabulary table: DCMI's rangeIncludes is a recommendation, and rdfs:Resource includes literals, so a property name cannot decide the term.

Behaviour changes

• Declared annotation values become nodes or typed literals; identifiers and enum values lose the language tag.
• Native created_on and last_updated_on become xsd:dateTime literals (were plain strings). Mapped uriorcurie metaslots stay IRIs, now by the shared rule instead of a name check.
• Fail fast for declared values: a uri annotation value that is a relative reference or a _: label is an error.
• Native link metadata that is neither an IRI nor a CURIE, such as a bare element name in see_also, is written as a plain literal, with a warning naming the element and metaslot. A relative IRI would make the whole graph non-standard RDF, and main writes one.
• No snapshot changes.

Not in this PR

• The OWL property role of metaclass slots: implements: [owl:AnnotationProperty] already declares the role, but the class restrictions are still emitted (Missing support for OWL annotation properties linkml/linkml#3249). Next PR.
• Annotations on types in gen-owl, which carries no type metadata today.
• license as an IRI (gen-owl emits rdfs:isDefinedBy and dcterms:license as string literals instead of URIs linkml/linkml#3546): the metamodel declares it a string; a linkml-model question.
• Undeclared annotations keep gen-owl's strings and gen-shacl's colon heuristic.
• fix: gen-owl places bare uri and uriorcurie values in default namespace linkml/linkml#4174 (open) writes a bare value of a uri-ranged metadata slot (see_also: README) as an IRI in the schema's default namespace. Here it is a plain literal with a warning: a value that is neither an IRI nor a CURIE has no absolute IRI (RDF 1.1 §3.2), and OWL 2 admits a literal as an annotation value (§10.1). Whichever of the two lands second has to reconcile with the first.

Testing

• test_declared_annotations.py (44): both generators; every range kind; tag as name, CURIE or IRI; annotated classes, slots, enums, permissible values and types; inherited and imported metaclasses; blank nodes; conflicting declarations; wrong-kind negatives; native metadata; the documented DCMI example; a pyshacl check that shape annotations do not constrain data.
• Rebased onto main d48b1976d (2026-11-04) after fix(rdf): give values of URI-like types one RDF term kind in every generator linkml/linkml#4156's squash merge; this commit is unchanged. tests/linkml 12,579 passed, tests/linkml_runtime 1,897 passed.

Fork review: #58. Refs linkml#2892, linkml#3543, linkml#3546.

[jdsika]

merged upstream