cleveragents-core/docs/reference/uko_layer3_technology_vocabularies.md

UKO Layer 3 Technology Vocabularies

Overview

Layer 3 of the Unified Knowledge Ontology (UKO) extends Layer 2 paradigm vocabularies (or Layer 1 directly) with technology-specific semantic refinements for four programming languages:

• Python (uko-py:) -- decorators, .pyi type stubs, test associations
• TypeScript (uko-ts:) -- export markers, ambient types, generics, mapped/conditional types
• Rust (uko-rs:) -- visibility, lifetimes, trait bounds, derive macros, unsafe markers
• Java (uko-java:) -- package visibility, modifiers, annotations, checked exceptions

Each vocabulary defines OWL classes, properties, Layer 2 dependencies, and optional DetailLevelMap insertions per docs/specification.md ~lines 44405-44420.

Namespace Prefixes

Prefix	IRI	Layer
uko-py:	https://cleveragents.ai/ontology/uko/py#	3
uko-ts:	https://cleveragents.ai/ontology/uko/ts#	3
uko-rs:	https://cleveragents.ai/ontology/uko/rs#	3
uko-java:	https://cleveragents.ai/ontology/uko/java#	3

Python Vocabulary (uko-py:)

Classes

Class	Superclass	Description
uko-py:PythonModule	uko-code:Module	A Python module (.py file).
uko-py:PythonClass	uko-oo:Class	A Python class definition.
uko-py:PythonFunction	uko-oo:Method	A Python function or method.
uko-py:PythonDecorator	uko-code:TypeDefinition	A decorator chain entry.
uko-py:PythonTypeStub	uko-code:TypeDefinition	.pyi stub type annotation.

Properties

Property	Domain	Range	Type
uko-py:hasDecorator	PythonFunction, PythonClass	PythonDecorator	ObjectProperty
uko-py:hasTypeStub	PythonModule, PythonClass, PythonFunction	PythonTypeStub	ObjectProperty
uko-py:hasTest	PythonFunction, PythonClass	PythonFunction	ObjectProperty
uko-py:decoratorName	PythonDecorator	xsd:string	DatatypeProperty
uko-py:stubAnnotation	PythonTypeStub	xsd:string	DatatypeProperty

DetailLevelMap Insertions

Python inserts 3 levels into the OO parent map, producing a 15-level effective map:

Depth	Name	Description
7	DECORATED_SIGNATURES	Decorator chains (@property, @staticmethod, custom).
11	TYPE_STUBS	Type annotations from .pyi stub files.
14	WITH_TESTS	Full source + associated test cases.

TypeScript Vocabulary (uko-ts:)

Classes

Class	Superclass	Description
uko-ts:TypeScriptModule	uko-code:Module	A TypeScript module (.ts/.tsx).
uko-ts:TypeScriptClass	uko-oo:Class	A TypeScript class.
uko-ts:TypeScriptInterface	uko-oo:Interface	A TypeScript interface (generics, mapped/conditional).
uko-ts:TypeScriptFunction	uko-oo:Method	A TypeScript function or method.

Properties

Property	Domain	Range	Type
uko-ts:exportKind	TypeScriptClass, TypeScriptInterface, TypeScriptFunction, TypeScriptModule	xsd:string	DatatypeProperty
uko-ts:isAmbient	TypeScriptClass, TypeScriptInterface, TypeScriptFunction	xsd:boolean	DatatypeProperty
uko-ts:genericParameters	TypeScriptClass, TypeScriptInterface, TypeScriptFunction	xsd:string	DatatypeProperty
uko-ts:isMappedType	TypeScriptInterface	xsd:boolean	DatatypeProperty
uko-ts:isConditionalType	TypeScriptInterface	xsd:boolean	DatatypeProperty
uko-ts:implementsInterface	TypeScriptClass	TypeScriptInterface	ObjectProperty

DetailLevelMap Insertions

TypeScript extends at the SIGNATURES level with no new depth insertions (12-level identity map).

Rust Vocabulary (uko-rs:)

Classes

Class	Superclass	Description
uko-rs:RustStruct	uko-oo:Class	A Rust struct definition.
uko-rs:RustTrait	uko-oo:Interface	A Rust trait definition.
uko-rs:RustImpl	uko-code:TypeDefinition	A Rust impl block.
uko-rs:RustFunction	uko-oo:Method	A Rust function or method.
uko-rs:RustDeriveAttribute	uko-code:TypeDefinition	A #[derive(...)] macro attribute.

Properties

Property	Domain	Range	Type
uko-rs:visibility	RustStruct, RustTrait, RustFunction	xsd:string	DatatypeProperty
uko-rs:lifetimeParameters	RustStruct, RustImpl, RustFunction, RustTrait	xsd:string	DatatypeProperty
uko-rs:traitBounds	RustStruct, RustFunction, RustImpl	xsd:string	DatatypeProperty
uko-rs:isUnsafe	RustFunction, RustImpl, RustTrait	xsd:boolean	DatatypeProperty
uko-rs:deriveTraits	RustDeriveAttribute	xsd:string	DatatypeProperty
uko-rs:mustUse	RustStruct, RustFunction	xsd:boolean	DatatypeProperty
uko-rs:hasDerive	RustStruct	RustDeriveAttribute	ObjectProperty
uko-rs:implementsTrait	RustImpl	RustTrait	ObjectProperty

DetailLevelMap Insertions

Rust extends at the SIGNATURES level with no new depth insertions (12-level identity map).

Java Vocabulary (uko-java:)

Classes

Class	Superclass	Description
uko-java:JavaClass	uko-oo:Class	A Java class definition.
uko-java:JavaInterface	uko-oo:Interface	A Java interface.
uko-java:JavaMethod	uko-oo:Method	A Java method.
uko-java:JavaAnnotation	uko-code:TypeDefinition	A Java annotation entry.
uko-java:JavaCheckedException	uko-code:TypeDefinition	A checked exception declaration.

Properties

Property	Domain	Range	Type
uko-java:packageVisibility	JavaClass, JavaInterface, JavaMethod	xsd:string	DatatypeProperty
uko-java:isFinal	JavaClass, JavaMethod	xsd:boolean	DatatypeProperty
uko-java:isAbstract	JavaClass, JavaMethod	xsd:boolean	DatatypeProperty
uko-java:isSealed	JavaClass, JavaInterface	xsd:boolean	DatatypeProperty
uko-java:hasAnnotation	JavaClass, JavaInterface, JavaMethod	JavaAnnotation	ObjectProperty
uko-java:annotationName	JavaAnnotation	xsd:string	DatatypeProperty
uko-java:throwsException	JavaMethod	JavaCheckedException	ObjectProperty
uko-java:exceptionClass	JavaCheckedException	xsd:string	DatatypeProperty

DetailLevelMap Insertions

Java extends at the SIGNATURES level with no new depth insertions (12-level identity map).

Shared Base Types

All Layer 3 vocabularies use shared types from vocabulary.py:

Type	Description
ProvenanceInfo	Frozen Pydantic model with 2 required fields (source_resource, source_path) and 3 defaulted fields (source_range, valid_from, is_current).
UKOClass	Frozen OWL class definition (uri, label, comment, subclass_of, provenance).
UKOProperty	Frozen OWL property definition (uri, label, comment, domain, range_uri, is_object_property, provenance).
Layer2Dependency	Declared dependency on a Layer 1/2 URI (uri, layer, prefix, description).
UKOVocabulary	Container aggregating classes, properties, deps, inserted levels, and optional provenance.

Utility Functions

Function	Description
build_detail_level_map(parent_levels, insertions)	Merge parent + child insertions with consecutive integer re-numbering.
resolve_detail_level(name, levels, parent_levels=None)	Look up a named level in levels, falling back to parent_levels.

Source Files

File	Description
src/cleveragents/acms/uko/vocabulary.py	Shared base types and utility functions.
src/cleveragents/acms/uko/layer3_py.py	Python vocabulary definitions.
src/cleveragents/acms/uko/layer3_ts.py	TypeScript vocabulary definitions.
src/cleveragents/acms/uko/layer3_rs.py	Rust vocabulary definitions.
src/cleveragents/acms/uko/layer3_java.py	Java vocabulary definitions.
docs/ontology/uko-py.ttl	Python OWL/Turtle ontology.
docs/ontology/uko-ts.ttl	TypeScript OWL/Turtle ontology.
docs/ontology/uko-rs.ttl	Rust OWL/Turtle ontology.
docs/ontology/uko-java.ttl	Java OWL/Turtle ontology.