From d717a5c8443b3987f587bf21d4fa458a15304e88 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 23 Jul 2026 18:53:06 +0200 Subject: [PATCH 1/3] Flatten concept declarations in extends example snippet --- ontology/ontology.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/ontology/ontology.md b/ontology/ontology.md index 3e9593fe..8fbac097 100644 --- a/ontology/ontology.md +++ b/ontology/ontology.md @@ -132,14 +132,12 @@ This ontology snippet: ```yaml name: EnterpriseOntology ontology: - - concept: - name: SocialSecurityNr - type: ValueType - extends: [Integer] - - concept: - name: Employee - type: EntityType - extends: [Person] + - concept: SocialSecurityNr + type: ValueType + extends: [Integer] + - concept: Employee + type: EntityType + extends: [Person] ``` declares two concepts that extend other concepts. From 3016d6341518114dc573701bb01d1f376e0267c5 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 23 Jul 2026 18:57:35 +0200 Subject: [PATCH 2/3] Flatten concept declarations in schema and remaining doc snippets --- ontology/ontology.json | 87 ++++++++++++++++---------------------- ontology/ontology.md | 96 ++++++++++++++++++------------------------ 2 files changed, 78 insertions(+), 105 deletions(-) diff --git a/ontology/ontology.json b/ontology/ontology.json index 943f6aa8..81578a39 100644 --- a/ontology/ontology.json +++ b/ontology/ontology.json @@ -51,12 +51,44 @@ "type": "object", "description": "Ontology component that defines a single concept and any relationships that are keyed primarily by that concept", "properties": { + "concept": { + "type": "string", + "description": "Unique name of the concept defined by this component" + }, + "type": { + "$ref": "#/$defs/ConceptType" + }, "description": { "type": "string", - "description": "Human-readable description of the component" + "description": "Human-readable description of the concept" }, - "concept": { - "$ref": "#/$defs/Concept" + "extends": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Indicates that this concept extends one or more other concepts" + }, + "derived_by": { + "type": "array", + "items": { + "$ref": "#/$defs/Expression" + }, + "description": "Expressions that define how this concept is derived" + }, + "identify_by": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Names of relationships to use as the preferred identifier of this concept" + }, + "requires": { + "type": "array", + "items": { + "$ref": "#/$defs/Expression" + }, + "description": "Expressions that constrain the population of this concept" }, "relationships": { "type": "array", @@ -66,7 +98,7 @@ "description": "Defines relationships that pertain primarily to the concept defined in this component" } }, - "required": ["concept"], + "required": ["concept", "type"], "additionalProperties": false }, "Expression": { @@ -120,53 +152,6 @@ "required": ["name", "verbalizes"], "additionalProperties": false }, - "Concept": { - "type": "object", - "description": "Defines a concept in the ontology", - "properties": { - "name": { - "type": "string", - "description": "Unique identifier for the concept" - }, - "type": { - "$ref": "#/$defs/ConceptType" - }, - "description": { - "type": "string", - "description": "Human-readable description of the concept" - }, - "extends": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Indicates that this concept extends one or more other concepts" - }, - "derived_by": { - "type": "array", - "items": { - "$ref": "#/$defs/Expression" - }, - "description": "Expressions that define how this concept is derived" - }, - "identify_by": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Names of relationships to use as the preferred identifier of this concept" - }, - "requires": { - "type": "array", - "items": { - "$ref": "#/$defs/Expression" - }, - "description": "Expressions that constrain the population of this concept" - } - }, - "required": ["name", "type"], - "additionalProperties": false - }, "ConceptMapping": { "type": "object", "description": "Mappings from logical model constructs to some ontology component", diff --git a/ontology/ontology.md b/ontology/ontology.md index 8fbac097..94002a5c 100644 --- a/ontology/ontology.md +++ b/ontology/ontology.md @@ -89,13 +89,9 @@ hierarchically, grouping each relationship under the concept that plays its firs | `ai_context` | string/object | No | Additional context for AI tools | | `ontology` | list | Yes | Concepts and relationships they group that form this ontology | -Each component of an ontology defines a concept and a list of relationships where that -concept plays the first role: - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `concept` | Concept | Yes | A concept in this ontology | -| `relationships` | list | No | Relationships where this concept plays the first role | +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 +the concept's remaining fields are declared alongside it. ### Concepts @@ -107,13 +103,14 @@ Concepts have the following schema: | Field | Type | Required | Description | |-------|------|----------|-------------| -| `name` | string | Yes | Unique name of this concept | +| `concept` | string | Yes | Unique name of this concept | | `type` | ConceptType | Yes | Entity type or value type | | `description` | string | No | Human-readable description | | `extends` | list | No | Names of this concept's supertypes | | `derived_by` | list | No | Expressions that derive this concept's population | | `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 | Each concept is either an entity type or a value type. @@ -159,15 +156,14 @@ Each relationship that is declared under a concept conforms to the following sch | `requires` | list | No | Expressions that constrain this relationship's population | | `verbalizes` | list | Yes | Patterns describing how to verbalize links | -Each relationship is uniquely identified by a prepending its declared name with that of the containing +Each relationship is uniquely identified by prepending its declared name with that of the containing concept. For instance, in: ```yaml ontology: - - concept: - name: Person - type: EntityType - identify_by: [ nr ] + - concept: Person + type: EntityType + identify_by: [ nr ] relationships: - name: nr roles: @@ -207,9 +203,8 @@ For instance, in: ```yaml ontology: - - concept: - name: Person - type: EntityType + - concept: Person + type: EntityType relationships: - name: files_married_joint verbalizes: [ "{Person} files married filing joint" ] @@ -232,9 +227,8 @@ the same relationship. For instance, in: ```yaml ontology: - - concept: - name: Store - type: EntityType + - concept: Store + type: EntityType relationships: - name: ships_to_in_days roles: @@ -279,7 +273,7 @@ the pair of relationships `License.acct` and `License.seat_nr` can be used to re its associated account and seat number. These relationships are always binary, and their first role is always played by the referent concept, i.e., the concept that the relationship is used to reference. The `identify_by` array allows modelers to list the names of relationships that form the preferred -idnetifier of a concept. +identifier of a concept. ### Derivation expressions @@ -289,9 +283,8 @@ relationships. For instance: ```yaml ontology: - - concept: - name: Person - type: EntityType + - concept: Person + type: EntityType relationships: - name: parent_of roles: @@ -304,7 +297,7 @@ ontology: name: "descendant" derived_by: - "Person.parent_of(descendant)" - "Person.ancestor_of.parent_of(descendant)" + - "Person.ancestor_of.parent_of(descendant)" - name: taxed_at roles: - concept: TaxRate @@ -338,15 +331,14 @@ using one or more expressions. For instance: ```yaml ontology: - - concept: - name: Employee - type: EntityType - extends: [Person] - derived_by: [ "EXISTS ( Person.earns )" ] + - concept: Employee + type: EntityType + extends: [Person] + derived_by: [ "EXISTS ( Person.earns )" ] ``` declares that the population of Employee is derived from the population of Person by -classifying each Person who earns some salary as a Employee. +classifying each Person who earns some salary as an Employee. ### Requires @@ -356,11 +348,10 @@ expression must reference the concept, as in: ```yaml ontology: - - concept: - name: SocialSecurityNr - type: ValueType - extends: [Integer] - requires: [ "0 < SocialSecurityNr", "SocialSecurityNr <= 999999999" ] + - concept: SocialSecurityNr + type: ValueType + extends: [Integer] + requires: [ "0 < SocialSecurityNr", "SocialSecurityNr <= 999999999" ] ``` When applied to a relationship, each expression must reference one or more roles of the @@ -368,9 +359,8 @@ relationship. For instance, in: ```yaml ontology: - - concept: - name: Item - type: EntityType + - concept: Item + type: EntityType relationships: - name: offers_in roles: @@ -427,15 +417,13 @@ a SQL expression. For instance, given this ontology snippet: ```yaml ontology: - - concept: - name: SocialSecurityNr + - concept: SocialSecurityNr type: ValueType extends: [ Integer ] requires: [ "0 < SocialSecurityNr", "SocialSecurityNr <= 999999999" ] - - concept: - name: Person - type: EntityType - identify_by: [ nr ] + - concept: Person + type: EntityType + identify_by: [ nr ] relationships: - name: nr roles: @@ -477,18 +465,19 @@ For instance, consider this ontology snippet: ```yaml ontology: - - concept: - name: OrderLineItem - type: EntityType - identify_by: [ "nr", "order" ] - requires: [ "OrderLineItem.nr", "OrderLineItem.order" ] + - concept: OrderLineItem + type: EntityType + identify_by: [ "nr", "order" ] + requires: [ "OrderLineItem.nr", "OrderLineItem.order" ] relationships: - name: nr roles: [ concept: LineNr ] multiplicity: ManyToOne + verbalizes: [ "{OrderLineItem} has line number {LineNr}" ] - name: order roles: [ concept: CustOrder ] multiplicity: ManyToOne + verbalizes: [ "{OrderLineItem} belongs to {CustOrder}" ] ``` and notice that `OrderLineItem` has a compound identifier. This concept mapping: @@ -538,15 +527,14 @@ For instance, this ontology snippet: ```yaml ontology: - - concept: - name: Item - type: EntityType - identify_by: [ nr ] + - concept: Item + type: EntityType + identify_by: [ nr ] relationships: - name: nr roles: [ concept: SkuNr ] multiplicity: OneToOne - verbalizes: "{Item} is identified by {SkuNr}" + verbalizes: [ "{Item} is identified by {SkuNr}" ] - name: active # A unary relationship verbalizes: [ "{Item} is actively sold" ] - name: active_in From e28b808dcf321cb827bc5205fbce1a1d5b4caa79 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 23 Jul 2026 19:52:59 +0200 Subject: [PATCH 3/3] Flatten concept declarations in flights example --- examples/flights.yaml | 354 ++++++++++++++++++------------------------ 1 file changed, 155 insertions(+), 199 deletions(-) diff --git a/examples/flights.yaml b/examples/flights.yaml index f0f64d13..803ff73d 100644 --- a/examples/flights.yaml +++ b/examples/flights.yaml @@ -22,110 +22,88 @@ requires: - COUNT[Airport] > 0 # there must be at least one Airport - COUNT[Carrier] > 0 # there must be at least one Carrier ontology: -- concept: - name: NrFeet - description: "Unit of measure for distance in feet" - type: ValueType - extends: [ Decimal ] -- concept: - name: NrPounds - description: "Unit of measure for weight in pounds" - type: ValueType - extends: [ Integer ] -- concept: - name: NrMiles - description: "Unit of measure for distance in miles" - type: ValueType - extends: [ Decimal ] -- concept: - name: NrMinutes - description: "Unit of measure for time in minutes" - type: ValueType - extends: [ Decimal ] -- concept: - name: CancelationCode - description: "The single character code that identifies the reason a flight is canceled" - type: ValueType - extends: [ String ] - requires: [ CancelationCode == 'A' OR CancelationCode == 'B' OR CancelationCode == 'C' OR CancelationCode == 'D' ] -- concept: - name: Capacity - description: "The capacity of an aircraft, measured in pounds." - type: ValueType - extends: [ NrPounds ] -- concept: - name: DegreesLatitude - type: ValueType - extends: [ Decimal ] - requires: [ DegreesLatitude <= 90, DegreesLatitude >= -90 ] -- concept: - name: DegreesLongitude - type: ValueType - extends: [ Decimal ] - requires: [ DegreesLongitude <= 180, DegreesLongitude >= -180 ] -- concept: - name: Polygon - description: "A polygon represented as a list of vertices, where each vertex is a pair of latitude and longitude coordinates." - type: ValueType - extends: [ String ] -- concept: - name: CityName - type: ValueType - extends: [ String ] -- concept: - name: Delay - type: ValueType - extends: [ NrMinutes ] -- concept: - name: Distance - type: ValueType - extends: [ NrMiles ] -- concept: - name: DistanceGroup - description: "A number used to group distances of different lengths, where 1 groups the shortest and 10 the longest." - type: ValueType - extends: [ Integer ] - requires: [ 1 <= DistanceGroup, DistanceGroup <= 10 ] -- concept: - name: RunwayGeometry - description: "A polygon that models the shape of a runway." - type: ValueType - extends: [ Polygon ] -- concept: - name: RunwayLength - description: "The unit for measuring the lengths of runways in American airports." - type: ValueType - extends: [ NrFeet ] -- concept: - name: RunwayDesignator - description: "Used to distinguish runways within a given airport." - type: ValueType - extends: [ String ] -- concept: - name: SerialNr - type: ValueType - extends: [ String ] -- concept: - name: StateCode - type: ValueType - extends: [ String ] -- concept: - name: StateName - type: ValueType - extends: [ String ] -- concept: - name: TailNr - type: ValueType - extends: [ String ] -- concept: - name: Year - type: ValueType - extends: [ String ] -- concept: - name: CancelationReason - description: "A curated set of reasons that explain why a flight is canceled" - type: EntityType - identify_by: [ code ] +- concept: NrFeet + description: "Unit of measure for distance in feet" + type: ValueType + extends: [ Decimal ] +- concept: NrPounds + description: "Unit of measure for weight in pounds" + type: ValueType + extends: [ Integer ] +- concept: NrMiles + description: "Unit of measure for distance in miles" + type: ValueType + extends: [ Decimal ] +- concept: NrMinutes + description: "Unit of measure for time in minutes" + type: ValueType + extends: [ Decimal ] +- concept: CancelationCode + description: "The single character code that identifies the reason a flight is canceled" + type: ValueType + extends: [ String ] + requires: [ CancelationCode == 'A' OR CancelationCode == 'B' OR CancelationCode == 'C' OR CancelationCode == 'D' ] +- concept: Capacity + description: "The capacity of an aircraft, measured in pounds." + type: ValueType + extends: [ NrPounds ] +- concept: DegreesLatitude + type: ValueType + extends: [ Decimal ] + requires: [ DegreesLatitude <= 90, DegreesLatitude >= -90 ] +- concept: DegreesLongitude + type: ValueType + extends: [ Decimal ] + requires: [ DegreesLongitude <= 180, DegreesLongitude >= -180 ] +- concept: Polygon + description: "A polygon represented as a list of vertices, where each vertex is a pair of latitude and longitude coordinates." + type: ValueType + extends: [ String ] +- concept: CityName + type: ValueType + extends: [ String ] +- concept: Delay + type: ValueType + extends: [ NrMinutes ] +- concept: Distance + type: ValueType + extends: [ NrMiles ] +- concept: DistanceGroup + description: "A number used to group distances of different lengths, where 1 groups the shortest and 10 the longest." + type: ValueType + extends: [ Integer ] + requires: [ 1 <= DistanceGroup, DistanceGroup <= 10 ] +- concept: RunwayGeometry + description: "A polygon that models the shape of a runway." + type: ValueType + extends: [ Polygon ] +- concept: RunwayLength + description: "The unit for measuring the lengths of runways in American airports." + type: ValueType + extends: [ NrFeet ] +- concept: RunwayDesignator + description: "Used to distinguish runways within a given airport." + type: ValueType + extends: [ String ] +- concept: SerialNr + type: ValueType + extends: [ String ] +- concept: StateCode + type: ValueType + extends: [ String ] +- concept: StateName + type: ValueType + extends: [ String ] +- concept: TailNr + type: ValueType + extends: [ String ] +- concept: Year + type: ValueType + extends: [ String ] +- concept: CancelationReason + description: "A curated set of reasons that explain why a flight is canceled" + type: EntityType + identify_by: [ code ] relationships: - name: code roles: @@ -137,10 +115,9 @@ ontology: - concept: String verbalizes: [ '{CancelationReason} has description- {String}' ] # The hyphen after "description" is significant when verbalizing constraints multiplicity: ManyToOne # Each CancelationReason has at most one description String -- concept: - name: State - type: EntityType - identify_by: [ code ] +- concept: State + type: EntityType + identify_by: [ code ] relationships: - name: code roles: @@ -154,10 +131,9 @@ ontology: verbalizes: - '{State} has {StateName}' multiplicity: ManyToOne -- concept: - name: City - type: EntityType - identify_by: [ name, state ] +- concept: City + type: EntityType + identify_by: [ name, state ] relationships: - name: name roles: @@ -171,10 +147,9 @@ ontology: verbalizes: - '{City} is located in {State}' multiplicity: ManyToOne -- concept: - name: Runway - type: EntityType - identify_by: [ designator, airport ] +- concept: Runway + type: EntityType + identify_by: [ designator, airport ] relationships: - name: airport roles: @@ -200,14 +175,12 @@ ontology: verbalizes: - '{Runway} has {RunwayGeometry}' multiplicity: ManyToOne -- concept: - name: ManufacturerName - type: ValueType - extends: [ String ] -- concept: - name: Manufacturer - type: EntityType - identify_by: [ name ] +- concept: ManufacturerName + type: ValueType + extends: [ String ] +- concept: Manufacturer + type: EntityType + identify_by: [ name ] relationships: - name: name roles: @@ -215,14 +188,12 @@ ontology: verbalizes: - '{Manufacturer} is identified by {ManufacturerName}' multiplicity: OneToOne -- concept: - name: ModelName - type: ValueType - extends: [ String ] -- concept: - name: Model - type: EntityType - identify_by: [ name, manufacturer ] +- concept: ModelName + type: ValueType + extends: [ String ] +- concept: Model + type: EntityType + identify_by: [ name, manufacturer ] relationships: - name: name roles: @@ -236,10 +207,9 @@ ontology: verbalizes: - '{Model} is manufactured by {Manufacturer}' multiplicity: ManyToOne -- concept: - name: Aircraft - type: EntityType - identify_by: [ tailnum ] +- concept: Aircraft + type: EntityType + identify_by: [ tailnum ] relationships: - name: serial_number roles: @@ -289,25 +259,21 @@ ontology: verbalizes: - '{Aircraft} is operated by {Carrier}' multiplicity: ManyToOne -- concept: - name: AirportName - type: ValueType - extends: [ String ] -- concept: - name: AirportCode - description: "The three-letter IATA code for the airport." - type: ValueType - extends: [ String ] -- concept: - name: AirportId - description: "Five digit number used as an alternate identifier for airports." - type: ValueType - extends: [ String ] -- concept: - name: Airport - type: EntityType - identify_by: [ code ] - requires: [ Airport.latitude, Airport.longitude ] +- concept: AirportName + type: ValueType + extends: [ String ] +- concept: AirportCode + description: "The three-letter IATA code for the airport." + type: ValueType + extends: [ String ] +- concept: AirportId + description: "Five digit number used as an alternate identifier for airports." + type: ValueType + extends: [ String ] +- concept: Airport + type: EntityType + identify_by: [ code ] + requires: [ Airport.latitude, Airport.longitude ] relationships: - name: city roles: @@ -359,33 +325,28 @@ ontology: verbalizes: - '{Airport} centers at {DegreesLatitude}' multiplicity: ManyToOne -- concept: - name: MarketName - type: ValueType - extends: [ String ] -- concept: - name: Market - type: EntityType - identify_by: [name] +- concept: MarketName + type: ValueType + extends: [ String ] +- concept: Market + type: EntityType + identify_by: [name] relationships: - name: name roles: [ { concept: MarketName }] verbalizes: [ '{Market} is identified by {MarketName}' ] multiplicity: OneToOne -- concept: - name: FlightNr - description: "The IATA flight number, which is typically a combination of the airline's IATA code and a numeric code (e.g., 'AA1234')." - type: ValueType - extends: [ String ] -- concept: - name: FlightId - description: "A unique identifier for an instance of a flight" - type: ValueType - extends: [ String ] -- concept: - name: Flight - type: EntityType - identify_by: [ id ] +- concept: FlightNr + description: "The IATA flight number, which is typically a combination of the airline's IATA code and a numeric code (e.g., 'AA1234')." + type: ValueType + extends: [ String ] +- concept: FlightId + description: "A unique identifier for an instance of a flight" + type: ValueType + extends: [ String ] +- concept: Flight + type: EntityType + identify_by: [ id ] relationships: - name: departure_delay roles: @@ -493,19 +454,16 @@ ontology: verbalizes: - '{Flight} is operated by {Carrier}' multiplicity: ManyToOne -- concept: - name: CarrierCode - description: "The two-letter IATA code for the airline carrier." - type: ValueType - extends: [ String ] -- concept: - name: CarrierName - type: ValueType - extends: [ String ] -- concept: - name: Carrier - type: EntityType - identify_by: [ code ] +- concept: CarrierCode + description: "The two-letter IATA code for the airline carrier." + type: ValueType + extends: [ String ] +- concept: CarrierName + type: ValueType + extends: [ String ] +- concept: Carrier + type: EntityType + identify_by: [ code ] relationships: - name: code roles: @@ -519,15 +477,13 @@ ontology: verbalizes: - '{Carrier} has {CarrierName}' multiplicity: ManyToOne -- concept: - name: RouteId - type: ValueType - description: "A unique identifier for a route between two airports. Constructed by concatenating the IATA codes of the departure and destination airports (e.g., 'ATL -> DCA')" - extends: [ String ] -- concept: - name: Route - type: EntityType - identify_by: [ id ] +- concept: RouteId + type: ValueType + description: "A unique identifier for a route between two airports. Constructed by concatenating the IATA codes of the departure and destination airports (e.g., 'ATL -> DCA')" + extends: [ String ] +- concept: Route + type: EntityType + identify_by: [ id ] relationships: - name: average_departure_delay roles: