diff --git a/docs/common/diagrams/rendered/ies-specification-diagrams/EAID_C9919009_48A5_4db1_8123_90396A6F3AD0.png b/docs/common/diagrams/rendered/ies-specification-diagrams/EAID_C9919009_48A5_4db1_8123_90396A6F3AD0.png index 19e024d..f0e19d9 100644 Binary files a/docs/common/diagrams/rendered/ies-specification-diagrams/EAID_C9919009_48A5_4db1_8123_90396A6F3AD0.png and b/docs/common/diagrams/rendered/ies-specification-diagrams/EAID_C9919009_48A5_4db1_8123_90396A6F3AD0.png differ diff --git a/docs/common/examples/sample-data/capacity-class-level.ttl b/docs/common/examples/sample-data/capacity-class-level.ttl deleted file mode 100644 index ce820f5..0000000 --- a/docs/common/examples/sample-data/capacity-class-level.ttl +++ /dev/null @@ -1,151 +0,0 @@ -# Capacity Pattern Example: Class-Level Capacities (REVISED for Enhancement) -# This example demonstrates the IES Capacity pattern at the class level, -# following the capacity-enhancement.md pattern where eachHasCapacity has -# domain ies:ClassOfState (not ies:ClassOfElement). -# -# This shows how to express "All Eurofighters in operational condition can fly at Mach 2" - -@prefix rdf: . -@prefix rdfs: . -@prefix xsd: . -@prefix ies: . -@prefix ex: . -@prefix data: . - -# ============================================================================ -# Domain-Specific Class Hierarchy and Capacities -# ============================================================================ - -# ClassOfState: Eurofighter in Operational Condition -# This is a ClassOfState - a class whose members are States -ex:EurofighterInOperationalCondition a ies:ClassOfState ; - rdfs:label "Eurofighter in Operational Condition"@en-gb ; - rdfs:comment """A ClassOfState where members are States of Eurofighter aircraft -when they are in operational condition."""@en-gb ; - rdfs:subClassOf ies:VehicleState ; - # Class-level capacity: ALL members of this class can fly at Mach 2 - ies:eachHasCapacity ex:PerformerOfMach2Flight . - -# Another ClassOfState representing the capacity -ex:PerformerOfMach2Flight a ies:Capacity ; - rdfs:label "Performer of Mach 2 Flight"@en-gb ; - rdfs:comment "The capacity to perform flight at Mach 2 or greater."@en-gb ; - rdfs:subClassOf ies:EventParticipant . - -# ============================================================================ -# Instance-Level Example: A Specific Eurofighter -# ============================================================================ - -# The whole-life Entity: Fighter XYZ-123 -data:FighterXYZ123 a ies:Vehicle ; - rdfs:label "Fighter XYZ-123"@en-gb ; - rdfs:comment "A specific Eurofighter aircraft"@en-gb . - -# ============================================================================ -# A State of Fighter XYZ-123 in Operational Condition (2024) -# This State inherits the class-level capacity via eachHasCapacity -# ============================================================================ - -data:FighterXYZ123InOpsCondition2024 a ies:VehicleState, ex:EurofighterInOperationalCondition ; - rdfs:label "Fighter XYZ-123 in operational condition (2024)"@en-gb ; - rdfs:comment """A State of Fighter XYZ-123 during 2024 when it was in operational condition. - -Because this State is a member of ex:EurofighterInOperationalCondition, it inherits -the class-level capacity to perform Mach 2 flight via the eachHasCapacity relationship."""@en-gb ; - ies:isStateOf data:FighterXYZ123 ; - ies:inPeriod data:Period2024 . - -data:Period2024 a ies:ParticularPeriod ; - rdfs:label "2024"@en-gb ; - ies:iso8601PeriodRepresentation "2024"^^xsd:gYear . - -# ============================================================================ -# Alternative Pattern: Instance-Specific Capacity -# You can also attach capacities to specific States directly -# ============================================================================ - -# Another State of the same fighter, with instance-specific capacity -data:FighterXYZ123During2025 a ies:VehicleState ; - rdfs:label "Fighter XYZ-123 in 2025"@en-gb ; - rdfs:comment """A State of Fighter XYZ-123 during 2025. - -This State has an instance-specific capacity attached directly via hasCapacity."""@en-gb ; - ies:isStateOf data:FighterXYZ123 ; - ies:inPeriod data:Period2025 ; - # Instance-level capacity: THIS specific State can perform Mach 2 flight - ies:hasCapacity ex:PerformerOfMach2Flight . - -data:Period2025 a ies:ParticularPeriod ; - rdfs:label "2025"@en-gb ; - ies:iso8601PeriodRepresentation "2025"^^xsd:gYear . - -# ============================================================================ -# Actualising the Capacity: The Fighter Actually Flies at Mach 2 -# ============================================================================ - -# An Event: A specific Mach 2 flight -data:Mach2Flight20240717 a ies:Movement ; - rdfs:label "Mach 2 flight on 2024-07-17"@en-gb ; - rdfs:comment "A specific flight where Fighter XYZ-123 actually flew at Mach 2"@en-gb . - -data:FlightStart a ies:BoundingState ; - rdfs:label "Start of Mach 2 flight"@en-gb ; - ies:isStartOf data:Mach2Flight20240717 ; - ies:inPeriod data:Period20240717T0900 . - -data:FlightEnd a ies:BoundingState ; - rdfs:label "End of Mach 2 flight"@en-gb ; - ies:isEndOf data:Mach2Flight20240717 ; - ies:inPeriod data:Period20240717T0930 . - -data:Period20240717T0900 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-07-17T09:00:00Z"^^xsd:string . - -data:Period20240717T0930 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-07-17T09:30:00Z"^^xsd:string . - -# A State of the fighter actually performing Mach 2 flight -# This State is both an EventParticipant AND a member of the Capacity class -# This actualises the capacity that the fighter had -data:FighterXYZ123AtMach2 a ies:EventParticipant, ex:PerformerOfMach2Flight ; - rdfs:label "Fighter XYZ-123 performing Mach 2 flight"@en-gb ; - rdfs:comment """The fighter actually performing a Mach 2 flight - actualising its capacity. - -Note that this State is a member of ex:PerformerOfMach2Flight (via rdf:type), -which means the capacity has been actualised. The capacity itself was expressed -via hasCapacity or eachHasCapacity on other States."""@en-gb ; - ies:isParticipationOf data:FighterXYZ123 ; - ies:isParticipantIn data:Mach2Flight20240717 . - -# ============================================================================ -# Example: Person with Capacity for Leadership Role -# Demonstrates the pattern with InPost -# ============================================================================ - -# A Person -data:FredBloggs a ies:Person ; - rdfs:label "Fred Bloggs"@en-gb . - -# ClassOfState: Term as Captain of Medway Queen -ex:TermAsCaptainOfMedwayQueen a ies:ClassOfState ; - rdfs:label "Term as Captain of Medway Queen"@en-gb ; - rdfs:comment "A term of office as captain of the paddle steamer Medway Queen."@en-gb ; - rdfs:subClassOf ies:InPost . - -# A State of Fred in 2026 with the capacity to become captain -data:FredBloggsIn2026 a ies:PersonState ; - rdfs:label "Fred Bloggs in 2026"@en-gb ; - rdfs:comment """A State of Fred Bloggs during 2026, when he has the qualifications -and opportunity to become captain of the Medway Queen."""@en-gb ; - ies:isStateOf data:FredBloggs ; - ies:inPeriod data:Period2026 ; - # Fred in 2026 has the capacity to be captain - ies:hasCapacity ex:TermAsCaptainOfMedwayQueen . - -data:Period2026 a ies:ParticularPeriod ; - rdfs:label "2026"@en-gb ; - ies:iso8601PeriodRepresentation "2026"^^xsd:gYear . - -# If Fred actually becomes captain, that would be modelled as a different State -# which is both a member of ex:TermAsCaptainOfMedwayQueen AND an InPost -# (This actualises the capacity) diff --git a/docs/common/examples/sample-data/capacity-emergency-shelter.ttl b/docs/common/examples/sample-data/capacity-emergency-shelter.ttl deleted file mode 100644 index 920315d..0000000 --- a/docs/common/examples/sample-data/capacity-emergency-shelter.ttl +++ /dev/null @@ -1,172 +0,0 @@ -# Capacity Pattern Example: Emergency Shelter (REVISED for Enhancement) -# This example demonstrates the IES Capacity pattern using an emergency planning scenario, -# following the capacity-enhancement.md pattern where hasCapacity has domain ies:State. -# -# Key change: Capacities are now attached to States, not to whole-life Entities. - -@prefix rdf: . -@prefix rdfs: . -@prefix xsd: . -@prefix ies: . -@prefix ex: . -@prefix data: . - -# ============================================================================ -# Domain-Specific Capacity Taxonomy -# These are example Capacity instances for emergency planning scenarios. -# Each application domain should define its own taxonomy. -# ============================================================================ - -ex:OperateAsRecreationalSpace a ies:Capacity ; - rdfs:label "Operate as Recreational Space"@en-gb ; - rdfs:comment "The capacity to operate as a recreational or leisure venue."@en-gb ; - rdfs:subClassOf ies:EventParticipant . - -ex:ShelterDisplacedPersons a ies:Capacity ; - rdfs:label "Shelter Displaced Persons"@en-gb ; - rdfs:comment "The capacity to provide emergency shelter for displaced persons."@en-gb ; - rdfs:subClassOf ies:EventParticipant . - -ex:AssessLocationsForEmergencyPlanning a ies:Capacity ; - rdfs:label "Assess Locations for Emergency Planning"@en-gb ; - rdfs:comment "The capacity to conduct emergency planning assessments."@en-gb ; - rdfs:subClassOf ies:EventParticipant . - -# ============================================================================ -# The Location -# ============================================================================ - -data:SandownCommunityHall a ies:Location ; - rdfs:label "Sandown Community Hall"@en-gb ; - rdfs:comment "Community sports and events venue in Sandown"@en-gb . - -# ============================================================================ -# Planning Period State: Hall During Assessment (2024) -# This State has the capacities that were identified during planning -# ============================================================================ - -data:HallDuringPlanning a ies:LocationState ; - rdfs:label "Sandown Community Hall during planning period (2024)"@en-gb ; - rdfs:comment """A State of the community hall during the 2024 planning period, -when it was assessed as having multiple capacities for emergency use."""@en-gb ; - ies:isStateOf data:SandownCommunityHall ; - ies:inPeriod data:Period2024 ; - # These are the capacities identified during assessment - ies:hasCapacity ex:OperateAsRecreationalSpace ; - ies:hasCapacity ex:ShelterDisplacedPersons . - -data:Period2024 a ies:ParticularPeriod ; - rdfs:label "2024"@en-gb ; - ies:iso8601PeriodRepresentation "2024"^^xsd:gYear . - -# ============================================================================ -# The Organisation That Assesses Emergency Suitability -# ============================================================================ - -data:AcmeLtd a ies:Organisation ; - rdfs:label "Acme Ltd"@en-gb ; - rdfs:comment "A company that carries out emergency planning assessments"@en-gb . - -# State of Acme during the planning period -data:AcmeDuringPlanning a ies:OrganisationState ; - rdfs:label "Acme Ltd during 2024 planning work"@en-gb ; - ies:isStateOf data:AcmeLtd ; - ies:inPeriod data:Period2024 ; - ies:hasCapacity ex:AssessLocationsForEmergencyPlanning . - -# ============================================================================ -# The Emergency Planning Assessment -# ============================================================================ - -data:EmergencyPlanningAssessment a ies:Assessment ; - rdfs:label "Emergency Planning Assessment"@en-gb ; - rdfs:comment "An assessment of Sandown Community Hall for emergency use"@en-gb . - -data:AssessmentStart a ies:BoundingState ; - rdfs:label "Start of assessment"@en-gb ; - ies:isStartOf data:EmergencyPlanningAssessment ; - ies:inPeriod data:Period20240101 . - -data:AssessmentEnd a ies:BoundingState ; - rdfs:label "End of assessment"@en-gb ; - ies:isEndOf data:EmergencyPlanningAssessment ; - ies:inPeriod data:Period20240131 . - -data:Period20240101 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-01-01T12:00:00Z"^^xsd:string . - -data:Period20240131 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-01-31T12:00:00Z"^^xsd:string . - -# A State of Acme Ltd performing the assessment (actualising its capacity) -data:AcmeAssessing a ies:Assessor, ex:AssessLocationsForEmergencyPlanning ; - rdfs:label "Acme Ltd assessing"@en-gb ; - rdfs:comment "Acme actually performing an assessment - actualising its capacity"@en-gb ; - ies:isParticipationOf data:AcmeLtd ; - ies:isParticipantIn data:EmergencyPlanningAssessment . - -# ============================================================================ -# Normal Operations: Recreational Space (2024) -# The hall actualises its recreational capacity -# ============================================================================ - -data:RecreationalOperation a ies:Event ; - rdfs:label "Recreational Space Operation"@en-gb ; - rdfs:comment "Sandown Community Hall operating as a recreational space"@en-gb . - -data:RecreationalStart a ies:BoundingState ; - rdfs:label "Start of recreational operation"@en-gb ; - ies:isStartOf data:RecreationalOperation ; - ies:inPeriod data:Period20240101T1200 . - -data:RecreationalEnd a ies:BoundingState ; - rdfs:label "End of recreational operation"@en-gb ; - ies:isEndOf data:RecreationalOperation ; - ies:inPeriod data:Period20241231T1200 . - -data:Period20240101T1200 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-01-01T12:00:00"^^xsd:string . - -data:Period20241231T1200 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-12-31T12:00:00"^^xsd:string . - -# A State of the hall actually operating as a recreational centre -# This State is both an EventParticipant AND a member of the Capacity class -data:HallAsRecreationalSpace a ies:EventParticipant, ex:OperateAsRecreationalSpace ; - rdfs:label "Sandown Community Hall as recreational space"@en-gb ; - rdfs:comment "The hall actually operating as a recreational space - actualising its capacity"@en-gb ; - ies:isParticipationOf data:SandownCommunityHall ; - ies:isParticipantIn data:RecreationalOperation . - -# ============================================================================ -# Emergency Activation: Shelter (January 2025) -# The hall actualises its shelter capacity -# ============================================================================ - -data:EmergencyShelterOperation a ies:Event ; - rdfs:label "Emergency Shelter Operation"@en-gb ; - rdfs:comment "Sandown Community Hall operating as an emergency shelter"@en-gb . - -data:ShelterStart a ies:BoundingState ; - rdfs:label "Start of emergency shelter operation"@en-gb ; - ies:isStartOf data:EmergencyShelterOperation ; - ies:inPeriod data:Period20250101T1200 . - -data:ShelterEnd a ies:BoundingState ; - rdfs:label "End of emergency shelter operation"@en-gb ; - ies:isEndOf data:EmergencyShelterOperation ; - ies:inPeriod data:Period20250131T1200 . - -data:Period20250101T1200 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2025-01-01T12:00:00"^^xsd:string . - -data:Period20250131T1200 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2025-01-31T12:00:00"^^xsd:string . - -# A State of the hall actually operating as an emergency shelter -# This State is both an EventParticipant AND a member of the Capacity class -data:HallAsShelter a ies:EventParticipant, ex:ShelterDisplacedPersons ; - rdfs:label "Sandown Community Hall as emergency shelter"@en-gb ; - rdfs:comment "The hall actually operating as an emergency shelter - actualising its capacity"@en-gb ; - ies:isParticipationOf data:SandownCommunityHall ; - ies:isParticipantIn data:EmergencyShelterOperation . diff --git a/docs/common/examples/sample-data/capacity-water-distribution.ttl b/docs/common/examples/sample-data/capacity-water-distribution.ttl deleted file mode 100644 index b0bf5e4..0000000 --- a/docs/common/examples/sample-data/capacity-water-distribution.ttl +++ /dev/null @@ -1,172 +0,0 @@ -# Capacity Pattern Example: Water Distribution Point (REVISED for Enhancement) -# This example demonstrates a car park with multiple capacities: -# normal use as a car park, and emergency use as a water distribution point. -# -# Following the capacity-enhancement.md pattern where hasCapacity has domain ies:State. -# Key change: Capacities are now attached to States, not to whole-life Entities. - -@prefix rdf: . -@prefix rdfs: . -@prefix xsd: . -@prefix ies: . -@prefix ex: . -@prefix data: . - -# ============================================================================ -# Domain-Specific Capacity Taxonomy -# ============================================================================ - -ex:HoldParkedVehicles a ies:Capacity ; - rdfs:label "Hold Parked Vehicles"@en-gb ; - rdfs:comment "The capacity to operate as a car park."@en-gb ; - rdfs:subClassOf ies:EventParticipant . - -ex:DistributePotableWater a ies:Capacity ; - rdfs:label "Distribute Potable Water"@en-gb ; - rdfs:comment "The capacity to serve as a distribution point for potable water."@en-gb ; - rdfs:subClassOf ies:EventParticipant . - -ex:AssessLocationsForEmergencyPlanning a ies:Capacity ; - rdfs:label "Assess Locations for Emergency Planning"@en-gb ; - rdfs:comment "The capacity to conduct emergency planning assessments."@en-gb ; - rdfs:subClassOf ies:EventParticipant . - -# ============================================================================ -# The Location -# ============================================================================ - -data:SandownCarPark a ies:Location ; - rdfs:label "Sandown Town Centre Car Park"@en-gb ; - rdfs:comment "A car park normally used for vehicle parking"@en-gb . - -# ============================================================================ -# Planning Period State: Car Park During Assessment (2024) -# This State has the capacities that were identified during planning -# ============================================================================ - -data:CarParkDuringPlanning a ies:LocationState ; - rdfs:label "Sandown car park during planning period (2024)"@en-gb ; - rdfs:comment """A State of the car park during the 2024 planning period, -when it was assessed as having multiple capacities for both normal and emergency use."""@en-gb ; - ies:isStateOf data:SandownCarPark ; - ies:inPeriod data:Period2024 ; - # These are the capacities identified during assessment - ies:hasCapacity ex:HoldParkedVehicles ; - ies:hasCapacity ex:DistributePotableWater . - -data:Period2024 a ies:ParticularPeriod ; - rdfs:label "2024"@en-gb ; - ies:iso8601PeriodRepresentation "2024"^^xsd:gYear . - -# ============================================================================ -# The Organisation That Conducts Assessments -# ============================================================================ - -data:AcmeLtd a ies:Organisation ; - rdfs:label "Acme Ltd"@en-gb ; - rdfs:comment "A company that carries out emergency planning assessments"@en-gb . - -# State of Acme during the planning period -data:AcmeDuringPlanning a ies:OrganisationState ; - rdfs:label "Acme Ltd during 2024 planning work"@en-gb ; - ies:isStateOf data:AcmeLtd ; - ies:inPeriod data:Period2024 ; - ies:hasCapacity ex:AssessLocationsForEmergencyPlanning . - -# ============================================================================ -# The Emergency Planning Assessment -# ============================================================================ - -data:WaterDistributionAssessment a ies:Assessment ; - rdfs:label "Water Distribution Point Assessment"@en-gb ; - rdfs:comment "An assessment of the car park as a potential water distribution point"@en-gb . - -data:WaterAssessmentStart a ies:BoundingState ; - rdfs:label "Start of water distribution assessment"@en-gb ; - ies:isStartOf data:WaterDistributionAssessment ; - ies:inPeriod data:Period20240101 . - -data:WaterAssessmentEnd a ies:BoundingState ; - rdfs:label "End of water distribution assessment"@en-gb ; - ies:isEndOf data:WaterDistributionAssessment ; - ies:inPeriod data:Period20240131 . - -data:Period20240101 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-01-01T12:00:00Z"^^xsd:string . - -data:Period20240131 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-01-31T12:00:00Z"^^xsd:string . - -# A State of Acme Ltd performing the assessment (actualising its capacity) -data:AcmeAssessingWaterPoint a ies:Assessor, ex:AssessLocationsForEmergencyPlanning ; - rdfs:label "Acme Ltd assessing water distribution point"@en-gb ; - rdfs:comment "Acme actually performing an assessment - actualising its capacity"@en-gb ; - ies:isParticipationOf data:AcmeLtd ; - ies:isParticipantIn data:WaterDistributionAssessment . - -# ============================================================================ -# Normal Operations: Car Park (2024) -# The car park actualises its parking capacity -# ============================================================================ - -data:CarParkOperation a ies:Event ; - rdfs:label "Car Park Operation"@en-gb ; - rdfs:comment "Sandown Town Centre Car Park operating normally"@en-gb . - -data:CarParkOperationStart a ies:BoundingState ; - rdfs:label "Start of car park operation"@en-gb ; - ies:isStartOf data:CarParkOperation ; - ies:inPeriod data:Period20240101T1200 . - -data:CarParkOperationEnd a ies:BoundingState ; - rdfs:label "End of car park operation"@en-gb ; - ies:isEndOf data:CarParkOperation ; - ies:inPeriod data:Period20241231T1200 . - -data:Period20240101T1200 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-01-01T12:00:00"^^xsd:string . - -data:Period20241231T1200 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-12-31T12:00:00"^^xsd:string . - -# A State of the car park operating normally -# This State is both an EventParticipant AND a member of the Capacity class -data:CarParkNormalOperation a ies:EventParticipant, ex:HoldParkedVehicles ; - rdfs:label "Sandown Car Park as vehicle parking"@en-gb ; - rdfs:comment "The car park operating in its normal capacity - actualising its parking capacity"@en-gb ; - ies:isParticipationOf data:SandownCarPark ; - ies:isParticipantIn data:CarParkOperation . - -# ============================================================================ -# Emergency Activation: Water Distribution Point (January 2025) -# Following severe flooding that interrupted mains water supplies -# The car park actualises its water distribution capacity -# ============================================================================ - -data:WaterDistributionOperation a ies:Event ; - rdfs:label "Water Distribution Point Operation"@en-gb ; - rdfs:comment "Sandown Car Park operating as an emergency water distribution point"@en-gb . - -data:WaterDistributionStart a ies:BoundingState ; - rdfs:label "Start of water distribution operation"@en-gb ; - ies:isStartOf data:WaterDistributionOperation ; - ies:inPeriod data:Period20250101T1200 . - -data:WaterDistributionEnd a ies:BoundingState ; - rdfs:label "End of water distribution operation"@en-gb ; - ies:isEndOf data:WaterDistributionOperation ; - ies:inPeriod data:Period20250131T1200 . - -data:Period20250101T1200 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2025-01-01T12:00:00"^^xsd:string . - -data:Period20250131T1200 a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2025-01-31T12:00:00"^^xsd:string . - -# A State of the car park actually distributing water -# This State is both an EventParticipant AND a member of the Capacity class -data:CarParkAsWaterPoint a ies:EventParticipant, ex:DistributePotableWater ; - rdfs:label "Sandown Car Park as water distribution point"@en-gb ; - rdfs:comment "The car park operating as an emergency water distribution point - actualising its water distribution capacity"@en-gb ; - ies:isParticipationOf data:SandownCarPark ; - ies:isParticipantIn data:WaterDistributionOperation . diff --git a/docs/common/examples/sample-data/disposition-class-level.ttl b/docs/common/examples/sample-data/disposition-class-level.ttl new file mode 100644 index 0000000..cdbef2b --- /dev/null +++ b/docs/common/examples/sample-data/disposition-class-level.ttl @@ -0,0 +1,63 @@ +# Disposition Pattern Example: Class-Level Disposition +# +# Demonstrates ies:eachHasDisposition - asserting that every member of a +# ClassOfState has a particular disposition. +# +# Scenario: Early mission planning. The planning team has determined that +# all Eurofighters in operational condition can fly at Mach 2. At this +# stage no specific aircraft has been allocated; the assertion is made +# at the class level. +# +# Key properties demonstrated: +# ies:eachHasDisposition - domain: ies:ClassOfState, range: ies:ClassOfState +# +# Note: eachHasDisposition is a sub-property of ies:relationship only. +# It does NOT entail rdfs:subClassOf, so ex:EurofighterInOperationalCondition +# remains structurally separate from ex:FlyAtMach2. + +@prefix rdf: . +@prefix rdfs: . +@prefix xsd: . +@prefix ies: . +@prefix ex: . + +# ============================================================================= +# Domain vocabulary +# ============================================================================= + +# The disposition target - what "flying at Mach 2" means as a class of States. +# Typed as ies:Capability (a sub-class of ies:DispositionalClass). +# rdfs:subClassOf ies:VehicleState indicates that members of this class are +# States of vehicles. +ex:FlyAtMach2 a ies:Capability ; + rdfs:label "Fly at Mach 2"@en-GB ; + rdfs:comment "The disposition to perform flight at Mach 2 or greater."@en-GB ; + rdfs:subClassOf ies:VehicleState . + +# A ClassOfState representing Eurofighter aircraft in operational condition. +# The eachHasDisposition assertion below says: every member of this class +# (i.e. every State that is a Eurofighter in operational condition) has the +# disposition to fly at Mach 2. +ex:EurofighterInOperationalCondition a ies:ClassOfState ; + rdfs:label "Eurofighter in operational condition"@en-GB ; + rdfs:comment """A class whose members are States of Eurofighter aircraft +when in operational condition. The eachHasDisposition assertion records +that every such State has the disposition to fly at Mach 2."""@en-GB ; + rdfs:subClassOf ies:VehicleState ; + ies:eachHasDisposition ex:FlyAtMach2 . + +# ============================================================================= +# An anonymous planning asset class (§3.1 non-specific asset requirement) +# ============================================================================= + +# The planner needs an asset that can fly at Mach 2 but has not yet +# committed to a specific platform. A named class is a convenience - the +# Capability ex:FlyAtMach2 already implicitly defines the set of entities +# disposed to it. +ex:Mach2CapableAsset a ies:ClassOfState ; + rdfs:label "Mach 2 capable asset"@en-GB ; + rdfs:comment """A planning-level class representing any asset with the +disposition to fly at Mach 2, created before a specific platform is +selected."""@en-GB ; + rdfs:subClassOf ies:VehicleState ; + ies:eachHasDisposition ex:FlyAtMach2 . diff --git a/docs/common/examples/sample-data/disposition-conditional.ttl b/docs/common/examples/sample-data/disposition-conditional.ttl new file mode 100644 index 0000000..b28adba --- /dev/null +++ b/docs/common/examples/sample-data/disposition-conditional.ttl @@ -0,0 +1,150 @@ +# Disposition Pattern Example: Conditional Disposition +# +# Demonstrates combining ies:eachHasDisposition and ies:hasDisposition +# with a conditional ClassOfState - encoding the idea that a disposition +# is available only when an Entity is in a particular State. +# +# Scenario: Mach 2 flight is permitted only when a Eurofighter is in +# operational condition. A second aircraft (Fighter ABC-456) is present +# but currently in a degraded state - it retains its whole-life +# disposition but is not currently in the conditional class, so the +# class-level assertion does not apply to it in its present State. +# +# Pattern: +# 1. Define a conditional ClassOfState (ex:EurofighterInOperationalCondition) +# and attach eachHasDisposition to it. The disposition then applies to +# every State that is a member of that conditional class. +# 2. An individual State typed as the conditional class inherits the +# class-level disposition and may also carry an explicit hasDisposition +# assertion (e.g. from a maintenance assessment). +# 3. A degraded State is typed as a different ClassOfState; it does NOT +# inherit the class-level disposition, even though the whole-life +# Entity retains a whole-life hasDisposition assertion. +# +# Key properties demonstrated: +# ies:eachHasDisposition - domain: ies:ClassOfState, range: ies:ClassOfState +# ies:hasDisposition - domain: ies:State, range: ies:ClassOfState + +@prefix rdf: . +@prefix rdfs: . +@prefix xsd: . +@prefix ies: . +@prefix ex: . +@prefix data: . + +# ============================================================================= +# Domain vocabulary +# ============================================================================= + +ex:FlyAtMach2 a ies:Capability ; + rdfs:label "Fly at Mach 2"@en-GB ; + rdfs:comment "The disposition to perform flight at Mach 2 or greater."@en-GB ; + rdfs:subClassOf ies:VehicleState . + +# The conditional ClassOfState. Only States typed as members of this class +# inherit the eachHasDisposition assertion below. +# Encoding the precondition as a ClassOfState (rather than bundling it into +# the Capability label) keeps the Capability definition simple and the +# precondition machine-readable. +ex:EurofighterInOperationalCondition a ies:ClassOfState ; + rdfs:label "Eurofighter in operational condition"@en-GB ; + rdfs:comment """A class whose members are States of Eurofighter aircraft +confirmed as being in operational condition. Attaching eachHasDisposition +here (rather than to the Eurofighter class itself) encodes the precondition: +only aircraft in operational condition have this disposition."""@en-GB ; + rdfs:subClassOf ies:VehicleState ; + ies:eachHasDisposition ex:FlyAtMach2 . + +# A separate ClassOfState for degraded aircraft - not in operational condition. +# States typed as this class do NOT inherit the Mach 2 disposition. +ex:EurofighterInDegradedCondition a ies:ClassOfState ; + rdfs:label "Eurofighter in degraded condition"@en-GB ; + rdfs:comment """A class whose members are States of Eurofighter aircraft +whose operational readiness is degraded (e.g. an engine fault). Members of +this class do not inherit the eachHasDisposition for Mach 2 flight."""@en-GB ; + rdfs:subClassOf ies:VehicleState . + +# ============================================================================= +# Fighter XYZ-123: in operational condition (2024) +# ============================================================================= + +data:FighterXYZ-123 a ies:Aircraft ; + rdfs:label "Fighter XYZ-123"@en-GB . + +# A temporal State of the aircraft, confirmed as operational after maintenance. +# Typed as ex:EurofighterInOperationalCondition, so it: +# (a) inherits the class-level disposition via eachHasDisposition, AND +# (b) carries an explicit hasDisposition from the post-maintenance assessment. +# Both assertions express the same modal relationship; an implementation may +# rely on (a) alone or assert both for explicitness. +data:FighterXYZ-123-Operational-2024 a ex:EurofighterInOperationalCondition ; + rdfs:label "Fighter XYZ-123 in operational condition (2024)"@en-GB ; + rdfs:comment """Post-maintenance State of Fighter XYZ-123. Typed as the +conditional class, so it inherits the eachHasDisposition assertion. +The additional hasDisposition records the result of the specific maintenance +assessment."""@en-GB ; + ies:isStateOf data:FighterXYZ-123 ; + ies:inPeriod data:Period2024 ; + ies:hasDisposition ex:FlyAtMach2 . + +data:Period2024 a ies:ParticularPeriod ; + rdfs:label "2024"@en-GB ; + ies:iso8601PeriodRepresentation "2024"^^xsd:gYear . + +# ============================================================================= +# Fighter ABC-456: currently degraded (2024) +# ============================================================================= + +data:FighterABC-456 a ies:Aircraft ; + rdfs:label "Fighter ABC-456"@en-GB ; + rdfs:comment """A second Eurofighter. As a whole-life Entity instance, +it is also a State (via the Entity-as-State pattern) and retains a whole-life +hasDisposition for Mach 2 - but its current temporal State is degraded, so the +class-level eachHasDisposition from ex:EurofighterInOperationalCondition does +not apply to it in its present condition."""@en-GB ; + ies:hasDisposition ex:FlyAtMach2 . + +# Current State of ABC-456: degraded due to an engine fault. +# Typed as ex:EurofighterInDegradedCondition - NOT as +# ex:EurofighterInOperationalCondition, so the class-level disposition +# for Mach 2 flight does NOT apply to this State. +data:FighterABC-456-Degraded-2024 a ex:EurofighterInDegradedCondition ; + rdfs:label "Fighter ABC-456 in degraded condition (2024)"@en-GB ; + rdfs:comment """A State of Fighter ABC-456 during a period of engine fault. +Not typed as ex:EurofighterInOperationalCondition, so the class-level +eachHasDisposition for Mach 2 does not apply to this State, even though the +whole-life Entity retains a hasDisposition assertion."""@en-GB ; + ies:isStateOf data:FighterABC-456 ; + ies:inPeriod data:Period2024 . + +# ============================================================================= +# Actualisation: Fighter XYZ-123 flies at Mach 2 +# ============================================================================= + +data:Sortie20240717 a ies:Event ; + rdfs:label "Sortie 20240717"@en-GB . + +data:SortieStart a ies:BoundingState ; + ies:isStartOf data:Sortie20240717 ; + ies:inPeriod data:Period20240717T0900 . + +data:SortieEnd a ies:BoundingState ; + ies:isEndOf data:Sortie20240717 ; + ies:inPeriod data:Period20240717T1130 . + +data:Period20240717T0900 a ies:ParticularPeriod ; + ies:iso8601PeriodRepresentation "2024-07-17T09:00:00Z"^^xsd:string . + +data:Period20240717T1130 a ies:ParticularPeriod ; + ies:iso8601PeriodRepresentation "2024-07-17T11:30:00Z"^^xsd:string . + +# Actualisation: this State IS a member of ex:FlyAtMach2 (rdf:type), +# not merely disposed to it (hasDisposition). +data:FighterXYZ-123-Flying-20240717 a ex:FlyAtMach2 ; + rdfs:label "Fighter XYZ-123 flying at Mach 2 on 2024-07-17"@en-GB ; + rdfs:comment """Actualisation of the Mach 2 disposition. The State is typed +as ex:FlyAtMach2 (actual class membership) rather than connected via +hasDisposition (modal potential). Fighter ABC-456, whose current State lacks +the disposition, does not participate in this sortie."""@en-GB ; + ies:isParticipationOf data:FighterXYZ-123 ; + ies:isParticipantIn data:Sortie20240717 . diff --git a/docs/common/examples/sample-data/disposition-individual-level.ttl b/docs/common/examples/sample-data/disposition-individual-level.ttl new file mode 100644 index 0000000..14721d9 --- /dev/null +++ b/docs/common/examples/sample-data/disposition-individual-level.ttl @@ -0,0 +1,113 @@ +# Disposition Pattern Example: Individual-Level Disposition +# +# Demonstrates ies:hasDisposition - asserting that a specific State instance +# has a particular disposition. +# +# Scenario: Fighter XYZ-123 has completed a post-maintenance flight test +# and has been assessed as capable of Mach 2 flight. Two patterns are shown: +# +# (a) hasDisposition on the whole-life Entity instance - possible because +# ies:Aircraft is a sub-class of ies:VehicleState, which is a +# sub-class of ies:State, satisfying the domain of hasDisposition. +# +# (b) hasDisposition on an explicit temporal State - preferred when the +# disposition holds only during a bounded period (e.g. after a +# maintenance check confirms operational condition). +# +# Key properties demonstrated: +# ies:hasDisposition - domain: ies:State, range: ies:ClassOfState +# +# Note: hasDisposition is a sub-property of ies:relationship only. +# It does NOT entail rdf:type, so the aircraft is not inferred to BE a +# member of ex:FlyAtMach2 - only that it CAN be. + +@prefix rdf: . +@prefix rdfs: . +@prefix xsd: . +@prefix ies: . +@prefix ex: . +@prefix data: . + +# ============================================================================= +# Domain vocabulary +# ============================================================================= + +ex:FlyAtMach2 a ies:Capability ; + rdfs:label "Fly at Mach 2"@en-GB ; + rdfs:comment "The disposition to perform flight at Mach 2 or greater."@en-GB ; + rdfs:subClassOf ies:VehicleState . + +# ============================================================================= +# Pattern (a): Disposition on the whole-life Entity +# ============================================================================= + +# The aircraft as a whole-life Entity. Because ies:Aircraft is a sub-class +# of ies:VehicleState (which is a sub-class of ies:State), this instance +# satisfies the domain of hasDisposition directly. +# Use this pattern when the disposition applies throughout the aircraft's +# existence and no temporal qualification is needed. +data:FighterXYZ-123 a ies:Aircraft ; + rdfs:label "Fighter XYZ-123"@en-GB ; + rdfs:comment "A specific Eurofighter Typhoon airframe."@en-GB ; + ies:hasDisposition ex:FlyAtMach2 . + +# ============================================================================= +# Pattern (b): Disposition on an explicit temporal State +# ============================================================================= + +# A State of Fighter XYZ-123 following a post-maintenance check in 2024. +# The disposition is scoped to this period - the aircraft was assessed as +# being in operational condition during this State. +data:FighterXYZ-123-Operational-2024 a ies:VehicleState ; + rdfs:label "Fighter XYZ-123 in operational condition (2024)"@en-GB ; + rdfs:comment """A State of Fighter XYZ-123 following post-maintenance +assessment in 2024. The hasDisposition assertion records the result of +that assessment: the aircraft, in this State, has the disposition to fly +at Mach 2."""@en-GB ; + ies:isStateOf data:FighterXYZ-123 ; + ies:inPeriod data:Period2024 ; + ies:hasDisposition ex:FlyAtMach2 . + +data:Period2024 a ies:ParticularPeriod ; + rdfs:label "2024"@en-GB ; + ies:iso8601PeriodRepresentation "2024"^^xsd:gYear . + +# ============================================================================= +# Actualisation: Fighter XYZ-123 actually flies at Mach 2 +# ============================================================================= + +# Having a disposition is distinct from using it. When the aircraft +# actually flies at Mach 2, a State is created that IS a member of +# ex:FlyAtMach2 (via rdf:type). This is the actualisation of the disposition. + +data:Sortie20240717 a ies:Event ; + rdfs:label "Sortie 20240717"@en-GB ; + rdfs:comment "A training sortie on 17 July 2024."@en-GB . + +data:SortieStart a ies:BoundingState ; + rdfs:label "Start of Sortie 20240717"@en-GB ; + ies:isStartOf data:Sortie20240717 ; + ies:inPeriod data:Period20240717T0900 . + +data:SortieEnd a ies:BoundingState ; + rdfs:label "End of Sortie 20240717"@en-GB ; + ies:isEndOf data:Sortie20240717 ; + ies:inPeriod data:Period20240717T1130 . + +data:Period20240717T0900 a ies:ParticularPeriod ; + ies:iso8601PeriodRepresentation "2024-07-17T09:00:00Z"^^xsd:string . + +data:Period20240717T1130 a ies:ParticularPeriod ; + ies:iso8601PeriodRepresentation "2024-07-17T11:30:00Z"^^xsd:string . + +# A State of the aircraft during the sortie - this is the actualisation. +# Note: typed as ex:FlyAtMach2 via rdf:type (actual membership of the class), +# NOT via hasDisposition (which would only record the potential). +data:FighterXYZ-123-Flying-20240717 a ex:FlyAtMach2 ; + rdfs:label "Fighter XYZ-123 flying at Mach 2 on 2024-07-17"@en-GB ; + rdfs:comment """Fighter XYZ-123 actualising its Mach 2 disposition during +Sortie 20240717. This State is typed as ex:FlyAtMach2 (membership of the +class), distinguishing actuality from the modal potential recorded via +hasDisposition on data:FighterXYZ-123-Operational-2024."""@en-GB ; + ies:isParticipationOf data:FighterXYZ-123 ; + ies:isParticipantIn data:Sortie20240717 . diff --git a/docs/common/glossary.md b/docs/common/glossary.md index c699142..080b635 100644 --- a/docs/common/glossary.md +++ b/docs/common/glossary.md @@ -23,9 +23,6 @@ A `State` that marks the beginning or end of another `State` or `Event`. For exa ## C -### Capacity -A `ClassOfState` representing what a `State` of an Entity *can* do in some possible world (modal possibility). A Capacity expresses potential rather than actuality—a State can have a Capacity without ever actualising it. For example, a State of "Fighter XYZ-123 in operational condition" can have the Capacity "Performer of Mach 2 flight" even if that aircraft has never actually flown at Mach 2. Having a Capacity (`hasCapacity`) is distinct from actualising it (`rdf:type`). See also [Capacity user guide](user-guides/capacity.md). - ### Characteristic A qualitative property of an `Element`. Unlike `Measures`, characteristics are not quantifiable on a numeric scale. Examples include colour, disposition, or accent. @@ -70,8 +67,8 @@ A `Characteristic` describing an `Element`'s capability or tendency to do someth ## E -### eachHasCapacity -A relationship that asserts all members of a `ClassOfState` can have (be members of) a particular `ClassOfState` (Capacity). This is the class-level equivalent of `hasCapacity`. For example, "Every Eurofighter in operational condition can fly at Mach 2" uses `eachHasCapacity` to assert this capability at the class level, whereas `hasCapacity` would be used for a specific aircraft State. Domain: `ies:ClassOfState`. Range: `ies:ClassOfState`. See [Capacity](user-guides/capacity.md). +### eachHasDisposition +A relationship that asserts all members of a `ClassOfState` can have (be members of) a particular `ClassOfState`. This is the class-level equivalent of `hasDisposition`. For example, "Every Eurofighter in operational condition can fly at Mach 2" uses `eachHasDisposition` to assert this capability at the class level, whereas `hasDisposition` would be used for a specific aircraft State. Domain: `ies:ClassOfState`. Range: `ies:ClassOfState`. See [Disposition](user-guides/disposition.md). ### Element Anything with spatio-temporal extent—things that occupy space and time. The fundamental class in IES from which `Entity`, `State`, `Event`, and `PeriodOfTime` all descend. Informally: "things you can kick." @@ -117,8 +114,8 @@ An ontological approach that treats time the same way as space. Things exist as ## H -### hasCapacity -A relationship that asserts a `State` can have (be a member of) a particular `ClassOfState` (Capacity). This expresses modal possibility: the State, in some possible world, can be a member of the specified ClassOfState. This is distinct from actually being a member (`rdf:type`). For example, "Sandown Hall during 2024 has the capacity to shelter displaced persons" means that State *can* be a member of the "Shelter displaced persons" ClassOfState, whether or not it ever actualises that capacity. Domain: `ies:State`. Range: `ies:ClassOfState`. See also [Capacity user guide](user-guides/capacity.md). +### hasDisposition +A relationship that asserts a `State` can have (be a member of) a particular `ClassOfState`. This expresses modal possibility: the State, in some possible world, can be a member of the specified ClassOfState. This is distinct from actually being a member (`rdf:type`). For example, "Sandown Hall during 2024 has the disposition (capability) to shelter displaced persons" means that State *can* be a member of the "Shelter displaced persons" ClassOfState, whether or not it ever actualises it. Domain: `ies:State`. Range: `ies:ClassOfState`. See also [Dispoisition user guide](user-guides/disposition.md). --- @@ -294,7 +291,7 @@ For more detailed explanations of these concepts, see: - [What is an Ontology?](user-guides/what-is-an-ontology.md) - Fundamental ontology concepts - [4D Ontology Approach](user-guides/4d-ontology.md) - Understanding the four-dimensional approach - [BORO Methodology](user-guides/boro-methodology.md) - The BORO method and extent-based identity -- [Capacity](user-guides/capacity.md) - Guide to the Capacity pattern +- [Disposition](user-guides/disposition.md) - Guide to the Disposition pattern - [Networks Overview](user-guides/networks/index.md) - Guide to network-related concepts - [IES Specification](specification/) - Complete technical specification diff --git a/docs/common/specification/ies-common.ttl b/docs/common/specification/ies-common.ttl index 4a7ed08..5779a6b 100644 --- a/docs/common/specification/ies-common.ttl +++ b/docs/common/specification/ies-common.ttl @@ -502,17 +502,6 @@ ies:Capability rdfs:label "Capability"@en-GB ; rdfs:subClassOf ies:DispositionalClass . -ies:Capacity - a rdfs:Class ; - dcterms:identifier "{existing-UUID}" ; - rdfs:label "Capacity"@en-GB ; - rdfs:comment """A ClassOfState representing what an Entity can do (in some possible world). - -Note: Typing a ClassOfState as Capacity is optional. The ies:hasCapacity and ies:eachHasCapacity -properties accept any ClassOfState as their range. Typing as Capacity simply provides semantic -clarity that this ClassOfState represents a capacity."""@en-GB ; - rdfs:subClassOf ies:ClassOfState . - ies:CarTravel a rdfs:Class ; dcterms:identifier "{F5E2BCD3-4529-42f2-9ED9-95801B42ED3F}" ; @@ -4146,16 +4135,47 @@ ies:documentedBy rdfs:range ies:WorkOfDocumentation ; rdfs:subPropertyOf ies:isRepresentedAs . -ies:eachHasCapacity +ies:eachHasDisposition a owl:ObjectProperty ; dcterms:identifier "{F4C6B093-874D-4e4f-9A7C-6B3E1D8C2A91}" ; - rdfs:comment """A relationship that asserts all members of a ClassOfState can have (be members of) another ClassOfState (Capacity). + rdfs:comment """ + A relationship that asserts all members of a ClassOfState can have (be members of) another ClassOfState. + This is the class-level equivalent of `hasDisposition`. + For example, "Eurofighter in operational condition" (a ClassOfState) `eachHasDisposition` "Performer of Mach 2 flight" + (another ClassOfState) means that every member of the first class can be a member of the second class. + + See also: `hasDisposition` for the instance-level equivalent. + """@en-GB ; + rdfs:domain ies:ClassOfState ; + rdfs:label "each Has Disposition"@en-GB ; + rdfs:range ies:ClassOfState ; + rdfs:subPropertyOf ies:relationship . -This is the class-level equivalent of hasCapacity. For example, "Eurofighter in operational condition" (a ClassOfState) eachHasCapacity "Performer of Mach 2 flight" (another ClassOfState) means that every member of the first class can, in some possible world, be a member of the second class. +ies:eachRequires + a owl:ObjectProperty ; + dcterms:identifier "{22117AB4-5F04-4E95-A2B1-D8E9B5064F1A}" ; + rdfs:comment """ + Asserts that every member of the domain ClassOfState + requires the temporal co-occurrence of at least one member of the + range ClassOfState. This is the class-level cross-entity dependency + assertion. + """@en-GB ; + rdfs:domain ies:ClassOfState ; + rdfs:label "each Requires"@en-GB ; + rdfs:range ies:ClassOfState ; + rdfs:subPropertyOf ies:relationship . -See also: hasCapacity for the instance-level equivalent."""@en-GB ; +ies:eachRequiresPart + a owl:ObjectProperty ; + dcterms:identifier "{D9E14D76-6790-4D3F-A719-5560F9947560}" ; + rdfs:comment """ + Asserts that a particular State requires, as a + mereological part, at least one member of the specified ClassOfState. + This is the individual-level whole-part dependency + assertion. + """@en-GB ; rdfs:domain ies:ClassOfState ; - rdfs:label "each Has Capacity"@en-GB ; + rdfs:label "each Requires Part"@en-GB ; rdfs:range ies:ClassOfState ; rdfs:subPropertyOf ies:relationship . @@ -4288,18 +4308,20 @@ ies:hasAuthor rdfs:range ies:ResponsibleActor ; rdfs:subPropertyOf ies:relationship . -ies:hasCapacity +ies:hasDisposition a owl:ObjectProperty ; dcterms:identifier "{862E873D-B64A-41AD-9D3D-27F108FA159F}" ; - rdfs:comment """A relationship that asserts a State can have (be a member of) a particular ClassOfState (Capacity). - -This expresses modal possibility: the State, in some possible world, can be a member of the specified ClassOfState. For example, "Fred Bloggs in 2026" (a PersonState) can be a member of "Term as Captain of Medway Queen" (a ClassOfState subclass of InPost). - -This is distinct from actually being a member of that ClassOfState - actual membership is expressed via rdf:type. A State may have a Capacity that is never actualised. - -See also: eachHasCapacity for the class-level equivalent."""@en-GB ; + rdfs:comment """ + A relationship that asserts a State can have (be a member of) a particular ClassOfState. + This expresses modal possibility: the State can be a member of the specified ClassOfState. + For example, "Fred Bloggs in 2026" (a PersonState) can be a member of "Term as Captain of Medway Queen" (a ClassOfState subclass of InPost). + This is distinct from actually being a member of that ClassOfState - actual membership is expressed via rdf:type. + A State may have a Disposition that is never actualised. + + See also: eachHasDisposition for the class-level equivalent. + """@en-GB ; rdfs:domain ies:State ; - rdfs:label "has Capacity"@en-GB ; + rdfs:label "has Disposition"@en-GB ; rdfs:range ies:ClassOfState ; rdfs:subPropertyOf ies:relationship . @@ -5117,6 +5139,32 @@ ies:relationship rdfs:label "relationship"@en-GB ; rdfs:range ies:Thing . +ies:requires a owl:ObjectProperty ; + rdfs:label "requires"@en-GB ; + rdfs:comment """ + Asserts that for a particular State to exercise a + disposition, it requires the temporal co-occurrence of at least one + member of the specified ClassOfState. This is the individual-level + cross-entity dependency assertion. + """@en-GB ; + rdfs:domain ies:State ; + rdfs:range ies:ClassOfState ; + rdfs:subPropertyOf ies:relationship . + +ies:requiresPart + a owl:ObjectProperty ; + dcterms:identifier "{160A6FD8-999D-444B-8804-B7479641FB24}" ; + rdfs:comment """ + Asserts that a particular State requires, as a + mereological part, at least one member of the specified ClassOfState. + This is the individual-level whole-part dependency + assertion. + """@en-GB ; + rdfs:domain ies:State ; + rdfs:label "requires Part"@en-GB ; + rdfs:range ies:ClassOfState ; + rdfs:subPropertyOf ies:relationship . + ies:residesIn a owl:ObjectProperty ; dcterms:identifier "{6BC3DDD8-477E-4c8a-B85D-E637CF9DB6DF}" ; diff --git a/docs/common/specification/ies.md b/docs/common/specification/ies.md index 6405acf..7fae99c 100644 --- a/docs/common/specification/ies.md +++ b/docs/common/specification/ies.md @@ -9,7 +9,7 @@ description: Comprehensive visual documentation of IES concepts, relationships, # The Information Exchange Standard (IES) Model Specification -![IES Logo](../assets/images/logos/IES-logo-dark.png) +![IES Logo](../../assets/images/logos/IES-logo-dark.png) ## Abstract @@ -595,9 +595,11 @@ Dispositions are managed in IES using `DispositionalClass` - something that was * [ClassOfEvent](#4ea194c6-bbf9-45ab-85de-5802d8c3a531) * [ClassOfState](#0358ddab-d22c-4ee5-8f9a-cf18f3e432bd) * [Capability](#91d62f08-ed05-4558-9321-368712a34a30) -* [isDisposedTo](#b093f8da-ae08-4819-8e1c-f119ef212566) * [Tendency](#2b451601-ec1d-4bd4-a782-6e0b7e0d416d) +* [isDisposedTo](#b093f8da-ae08-4819-8e1c-f119ef212566) * [allHaveDisposition](#6f8504e0-e03c-43fa-aa81-c3341ca551e3) +* [hasDisposition](#d1c8e5b7-9a0c-4f2b-9e3c-1a0e5c8d6f1a) +* [eachHasDisposition](#d9e5c8b7-1a0c-4f2b-9e3c-1a0e5c8d6f1a) --- @@ -3430,6 +3432,9 @@ An Iden ### Duration The Measure of an Element's temporal extent +### eachHasDisposition +A relationship that asserts all members of a ClassOfState can have (be members of) another ClassOfState. + ### Easting The GeoIdentity that is a representation of the eastward componrnent of cartesian point on a map - i.e. on a 2D projection of the globe such as a mercator projection. @@ -3699,6 +3704,9 @@ An rdf: ### hasCountryOfIssue The country in which the respective IdentityDocument or PaymentArtefact was issued. +### hasDisposition +A relationship that asserts a State can have (be a member of) a particular ClassOfState. + ### hasEmergencyContactAddress The address of an emergency contact as printed on the IdentityDocument diff --git a/docs/common/user-guides/capacity.md b/docs/common/user-guides/capacity.md deleted file mode 100644 index f98c432..0000000 --- a/docs/common/user-guides/capacity.md +++ /dev/null @@ -1,408 +0,0 @@ -# Capacity - -A **Capacity** is a `ClassOfState` representing what a State of an Entity *can* do (in some possible world), whether or not it has ever actually done it. - -The key insight is that a Capacity represents modal possibility: a State *can* be a member of a particular `ClassOfState` in some possible world. For example, a State of "Fighter XYZ-123 in operational condition" can be a member of "Performer of Mach 2 flight" even if that specific aircraft has never actually flown at Mach 2. - -## The hasCapacity Relationship - -The `hasCapacity` relationship asserts that a **State** can have (be a member of) a particular `ClassOfState` (Capacity). This is a "has a" relationship rather than an "is a" relationship, making it intuitive to express statements like "this building, during the emergency planning period, has the capacity to serve as an emergency shelter." - -**Property signature:** -- **Domain:** `ies:State` -- **Range:** `ies:ClassOfState` - -```turtle -@prefix ies: . -@prefix ex: . -@prefix data: . - -# The whole-life Entity -data:SandownCommunityHall a ies:Location ; - rdfs:label "Sandown Community Hall"@en-gb . - -# A State of that Location during the planning period -data:HallDuringPlanning a ies:LocationState ; - rdfs:label "Hall during 2024 planning"@en-gb ; - ies:isStateOf data:SandownCommunityHall ; - ies:inPeriod data:Period2024 ; - # This State has two capacities - ies:hasCapacity ex:OperateAsRecreationalSpace ; - ies:hasCapacity ex:ShelterDisplacedPersons . -``` - -## The eachHasCapacity Relationship - -While `hasCapacity` asserts that a specific State instance has a Capacity, `eachHasCapacity` asserts that all members of a `ClassOfState` can have a particular Capacity. This is useful for defining class-level capabilities in domain ontologies. - -**Property signature:** -- **Domain:** `ies:ClassOfState` -- **Range:** `ies:ClassOfState` -```turtle -@prefix ies: . -@prefix ex: . -@prefix data: . - -# Class-level assertion: ALL Eurofighters in operational condition can fly at Mach 2 -ex:EurofighterInOperationalCondition a ies:ClassOfState ; - rdfs:subClassOf ies:VehicleState ; - ies:eachHasCapacity ex:PerformerOfMach2Flight . - -# Instance-level assertion: THIS specific Eurofighter State can fly at Mach 2 -# (inherits the capacity from its class via eachHasCapacity) -data:FighterXYZ123InOpsCondition2024 a ies:VehicleState, ex:EurofighterInOperationalCondition ; - rdfs:label "Fighter XYZ-123 in operational condition (2024)"@en-gb ; - ies:isStateOf data:FighterXYZ123 ; - ies:inPeriod data:Period2024 . - # Inherits the Mach 2 capacity from ex:EurofighterInOperationalCondition -``` - -### When to Use Each Property - -| Property | Use When... | Example | -|----------|-------------|---------| -| `hasCapacity` | A specific State instance has been assessed or designated as having a Capacity | "Fighter XYZ-123 in operational condition during 2024 has the capacity to fly at Mach 2" | -| `eachHasCapacity` | All members of a ClassOfState have a Capacity | "Every Eurofighter in operational condition has the capacity to fly at Mach 2" | - -### Combining Class and Instance Capacities - -States can have both inherited class-level Capacities (via `eachHasCapacity` on their class) and additional instance-specific Capacities (via `hasCapacity` on the State): -```turtle -# Define a class-level capacity: ALL community halls can operate as recreational spaces -ex:CommunityHallInOperation a ies:ClassOfState ; - rdfs:subClassOf ies:LocationState ; - ies:eachHasCapacity ex:OperateAsRecreationalSpace . - -# A specific State inherits the class capacity AND has an additional one -data:SandownHallDuring2024 a ies:LocationState, ex:CommunityHallInOperation ; - rdfs:label "Sandown Community Hall during 2024"@en-gb ; - ies:isStateOf data:SandownCommunityHall ; - ies:inPeriod data:Period2024 ; - # Inherits OperateAsRecreationalSpace from ex:CommunityHallInOperation - # Plus has an instance-specific capacity (assessed for this specific hall): - ies:hasCapacity ex:ShelterDisplacedPersons . -``` - -## Modelling Whole-Life vs Temporal Capacities - -**Important:** Even when a capacity appears to persist throughout an Entity's existence, it is still modelled as a State having the capacity, not the Entity directly. - -### Temporal Capacity (capacity during specific period) - -```turtle -# A car park assessed in 2024 as having water distribution capacity -data:CarParkDuringPlanning a ies:LocationState ; - ies:isStateOf data:SandownCarPark ; - ies:inPeriod data:Period2024 ; - ies:hasCapacity ex:DistributePotableWater . -``` - -### Whole-Life Capacity (capacity throughout Entity's existence) - -For capacities that persist throughout an Entity's existence, IES provides a convenient pattern: Entity subclasses are also subclasses of their corresponding State subclass (e.g., `ies:Person rdfs:subClassOf ies:PersonState`, `ies:Location rdfs:subClassOf ies:LocationState`). - -**Exception:** `ies:Entity` itself is NOT a subclass of `ies:State`. - -This means when you instantiate a specific Entity subclass (like Person or Location), that instance is automatically both an Entity and a State representing its whole life: -```turtle -# A fire station that has always been able to house emergency vehicles -# Because Location is a subclass of LocationState, this instance is BOTH -data:PortsmouthFireStation a ies:Location ; # Therefore also a LocationState - rdfs:label "Portsmouth Fire Station"@en-gb ; - # Can attach capacity directly - no need for separate State instance - ies:hasCapacity ex:HouseEmergencyVehicles . -``` - -This pattern works for: -- `ies:Person` instances (also `PersonState`) -- `ies:Location` instances (also `LocationState`) -- `ies:Vehicle` instances (also `VehicleState`) -- And other Entity subclasses that follow this pattern - -For temporal capacities (capacities during specific periods), you still create explicit State instances with temporal bounds as shown in the previous section. - -## Relationship to Existing Patterns - -IES has existing concepts for modelling capabilities and tendencies through `DispositionalClass`, `Capability`, and `Tendency`. These use an "is a" pattern via `rdf:type`. - -The Capacity pattern provides an alternative "has a" approach using `hasCapacity`. Both patterns remain valid in IES: - -- The existing `DispositionalClass` pattern is **retained for backwards compatibility** -- The new `Capacity` pattern is **additive and non-breaking** -- Implementers may choose whichever pattern better fits their data and use cases - -The Capacity pattern is recommended for new implementations because: - -- It aligns more naturally with how we describe capabilities in everyday language -- It provides clearer spatio-temporal semantics (via `State` and `ClassOfState`) -- It separates the concept of having a Capacity from actually using it in Event participation -- It supports conditional capacities (e.g., "can fly at Mach 2 *only* when in an operational state") - -## Creating Domain-Specific Capacity Taxonomies - -The core IES ontology defines `ies:Capacity`, `ies:hasCapacity`, and `ies:eachHasCapacity`. Domain-specific applications should create their own taxonomies of Capacity instances relevant to their use cases. - -**Note:** Typing a `ClassOfState` as `ies:Capacity` is optional but recommended for semantic clarity. The properties accept any `ClassOfState` as their range. - -For example, an emergency planning domain might define: - -```turtle -@prefix rdfs: . -@prefix ies: . -@prefix ex: . - -# Domain-specific Capacity instances (subclasses of both ClassOfState and Capacity) -ex:ShelterDisplacedPersons a ies:Capacity ; - rdfs:label "Shelter Displaced Persons"@en-gb ; - rdfs:comment "The capacity to provide emergency shelter for displaced persons."@en-gb ; - rdfs:subClassOf ies:EventParticipant . - -ex:DistributePotableWater a ies:Capacity ; - rdfs:label "Distribute Potable Water"@en-gb ; - rdfs:comment "The capacity to serve as a distribution point for potable water."@en-gb ; - rdfs:subClassOf ies:EventParticipant . - -ex:AssessLocationsForEmergencyPlanning a ies:Capacity ; - rdfs:label "Assess Locations for Emergency Planning"@en-gb ; - rdfs:comment "The capacity to conduct emergency planning assessments of locations."@en-gb ; - rdfs:subClassOf ies:EventParticipant . -``` - -## Capacities and Actualisation - -Having a Capacity is distinct from *using* that Capacity. When a State actually uses its Capacity, this is modelled as that State participating in an Event and being a member (via `rdf:type`) of the Capacity class. - -```turtle -# A State of the car park during planning - HAS the capacity (potential) -data:CarParkDuringPlanning a ies:LocationState ; - ies:isStateOf data:SandownCarPark ; - ies:inPeriod data:Period2024 ; - ies:hasCapacity ex:DistributePotableWater . - -# An Event where water is being distributed -data:WaterDistributionOperation a ies:Event ; - rdfs:label "Water Distribution Operation"@en-gb . - -# A State of the car park actually distributing water - USES the capacity (actual) -data:CarParkDistributingWater a ies:EventParticipant, ex:DistributePotableWater ; - rdfs:comment "The car park actualising its capacity"@en-gb ; - ies:isParticipationOf data:SandownCarPark ; - ies:isParticipantIn data:WaterDistributionOperation . -``` - -**Key distinction:** -- `ies:hasCapacity` = "can be a member of this ClassOfState" (modal possibility) -- `rdf:type` = "is a member of this ClassOfState" (actuality) - -This separation enables queries like: -- "Which Locations **have the Capacity** to serve as emergency shelters?" (potential resources) -- "Which Locations **have actually served** as emergency shelters?" (actual usage) - -## Worked Example: Emergency Shelter - -This example demonstrates a community hall that has the Capacity to serve as an emergency shelter. It shows: - -1. The building being assessed as having this Capacity -2. The building operating normally as a recreational space -3. The building being activated as an emergency shelter during an incident - -### The Location and Its Assessed Capacities - -```turtle -@prefix ies: . -@prefix ex: . -@prefix data: . - -# The whole-life Entity -data:SandownCommunityHall a ies:Location ; - rdfs:label "Sandown Community Hall"@en-gb ; - rdfs:comment "Community sports and events venue in Sandown"@en-gb . - -# A State of the hall during the 2024 planning period -data:HallDuringPlanning a ies:LocationState ; - rdfs:label "Hall during 2024 planning period"@en-gb ; - ies:isStateOf data:SandownCommunityHall ; - ies:inPeriod data:Period2024 ; - # These are the capacities identified during assessment - ies:hasCapacity ex:OperateAsRecreationalSpace ; - ies:hasCapacity ex:ShelterDisplacedPersons . -``` - -### The Assessment - -An organisation assesses the building's suitability as an emergency shelter: - -```turtle -# An organisation that carries out assessments -data:AcmeLtd a ies:Organisation ; - rdfs:label "Acme Ltd"@en-gb . - -# A State of Acme during the planning period -data:AcmeDuringPlanning a ies:OrganisationState ; - ies:isStateOf data:AcmeLtd ; - ies:inPeriod data:Period2024 ; - ies:hasCapacity ex:AssessLocationsForEmergencyPlanning . - -# The emergency planning assessment -data:EmergencyPlanningAssessment a ies:Assessment ; - rdfs:label "Emergency Planning Assessment"@en-gb . - -# Bounding states for the assessment -data:AssessmentStart a ies:BoundingState ; - ies:isStartOf data:EmergencyPlanningAssessment ; - ies:inPeriod [ a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-01-01T12:00:00Z"^^xsd:string ] . - -data:AssessmentEnd a ies:BoundingState ; - ies:isEndOf data:EmergencyPlanningAssessment ; - ies:inPeriod [ a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-01-31T12:00:00Z"^^xsd:string ] . - -# A State of Acme actually performing the assessment (actualising its capacity) -data:AcmeAssessing a ies:Assessor, ex:AssessLocationsForEmergencyPlanning ; - rdfs:comment "Acme actualising its assessment capacity"@en-gb ; - ies:isParticipationOf data:AcmeLtd ; - ies:isParticipantIn data:EmergencyPlanningAssessment . -``` - -### Normal Operations - -The building operates as a recreational space during normal times: - -```turtle -# An event where the hall is operating as a recreational space -data:RecreationalOperation a ies:Event ; - rdfs:label "Recreational Space Operation"@en-gb . - -# Bounding states for normal operation -data:RecreationalStart a ies:BoundingState ; - ies:isStartOf data:RecreationalOperation ; - ies:inPeriod [ a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-01-01T12:00:00"^^xsd:string ] . - -data:RecreationalEnd a ies:BoundingState ; - ies:isEndOf data:RecreationalOperation ; - ies:inPeriod [ a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2024-12-31T12:00:00"^^xsd:string ] . - -# A State of the hall actually operating as a recreational centre (actualising capacity) -data:HallAsRecreationalSpace a ies:EventParticipant, ex:OperateAsRecreationalSpace ; - rdfs:comment "Hall actualising its recreational capacity"@en-gb ; - ies:isParticipationOf data:SandownCommunityHall ; - ies:isParticipantIn data:RecreationalOperation . -``` - -### Emergency Activation - -When an incident occurs, the building is activated as an emergency shelter: - -```turtle -# An event where the hall is operating as an emergency shelter -data:EmergencyShelterOperation a ies:Event ; - rdfs:label "Emergency Shelter Operation"@en-gb . - -# Bounding states for emergency operation -data:ShelterStart a ies:BoundingState ; - ies:isStartOf data:EmergencyShelterOperation ; - ies:inPeriod [ a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2025-01-01T12:00:00"^^xsd:string ] . - -data:ShelterEnd a ies:BoundingState ; - ies:isEndOf data:EmergencyShelterOperation ; - ies:inPeriod [ a ies:ParticularPeriod ; - ies:iso8601PeriodRepresentation "2025-01-31T12:00:00"^^xsd:string ] . - -# A State of the hall actually operating as an emergency shelter (actualising capacity) -data:HallAsShelter a ies:EventParticipant, ex:ShelterDisplacedPersons ; - rdfs:comment "Hall actualising its emergency shelter capacity"@en-gb ; - ies:isParticipationOf data:SandownCommunityHall ; - ies:isParticipantIn data:EmergencyShelterOperation . -``` - -## Querying Capacities - -The Capacity pattern enables useful queries. Here are some examples using SPARQL: - -### Finding Entities with States That Have a Specific Capacity - -```sparql -PREFIX ies: -PREFIX ex: - -SELECT ?entity ?entityLabel ?state -WHERE { - ?state ies:hasCapacity ex:ShelterDisplacedPersons ; - ies:isStateOf ?entity . - ?entity rdfs:label ?entityLabel . -} -``` - -### Finding When a Capacity Was Actually Used - -```sparql -PREFIX ies: -PREFIX ex: - -SELECT ?entity ?event ?startTime -WHERE { - # Find States that are members of the Capacity class (actualisation) - ?state a ex:ShelterDisplacedPersons ; - ies:isParticipationOf ?entity ; - ies:isParticipantIn ?event . - ?startBound ies:isStartOf ?event ; - ies:inPeriod ?period . - ?period ies:iso8601PeriodRepresentation ?startTime . -} -``` - -### Finding Unused Capacities - -```sparql -PREFIX ies: -PREFIX ex: - -SELECT ?entity ?entityLabel -WHERE { - # States that HAVE the capacity - ?state ies:hasCapacity ex:ShelterDisplacedPersons ; - ies:isStateOf ?entity . - ?entity rdfs:label ?entityLabel . - - # But have never actualised it - FILTER NOT EXISTS { - ?actualState a ex:ShelterDisplacedPersons ; - ies:isParticipationOf ?entity . - } -} -``` - -## Summary - -The Capacity pattern in IES provides: - -- A clear way to express what a State of an Entity *can* do (modal possibility) -- Separation between having a Capacity and actualising it -- Support for assessments of Capacities -- Temporal tracking of when Capacities are activated -- A foundation for domain-specific Capacity taxonomies - -### Key Principles - -1. **Capacity is modal possibility** — a State can have a Capacity without ever actualising it -2. **hasCapacity domain is State** — capacities attach to temporal parts -3. **Actualisation via rdf:type** — when a Capacity is actually employed, the State is a member of the Capacity class -4. **Whole-life capacities use Entity instances** — Entity subclass instances (Person, Location, etc.) are also States representing their whole life -5. **Domain taxonomies expected** — IES provides the framework; applications define specific Capacities -6. **Optional typing as ies:Capacity** — provides semantic clarity but is not mandatory - ---- - -## Related Documentation - -- [Instantiation Patterns](instantiation-patterns.md) — Standard patterns for creating IES data -- [4D Ontology Approach](4d-ontology.md) — Understanding States and temporal parts -- [Extending IES](extending-ies.md) — How to create domain-specific extensions - ---- - -*© Crown Copyright 2020-2026* diff --git a/docs/common/user-guides/disposition-pattern.pdf b/docs/common/user-guides/disposition-pattern.pdf new file mode 100644 index 0000000..5a1f338 Binary files /dev/null and b/docs/common/user-guides/disposition-pattern.pdf differ diff --git a/docs/common/user-guides/disposition.md b/docs/common/user-guides/disposition.md new file mode 100644 index 0000000..365ec3b --- /dev/null +++ b/docs/common/user-guides/disposition.md @@ -0,0 +1,321 @@ +# Dispositions + +A **disposition** is what a State of an Entity *can* do — its potential — in some possible world, whether or not it has ever actually done it. + +The key insight is that a disposition represents modal possibility: a State *can* be a member of a particular `ClassOfState` in some possible world. For example, a State of "Fighter XYZ-123 in operational condition" can be a member of "Performer of Mach 2 flight" even if that specific aircraft has never actually flown at Mach 2. + +Dispositions in IES are expressed by asserting that a State (or a class of States) is related to a `ClassOfState` — the class representing the potential behaviour or role. The `ClassOfState` used as a disposition target is typically an instance of `ies:DispositionalClass`, or one of its sub-classes `ies:Capability` (a shared capability) or `ies:Tendency` (a shared tendency). + +## The Existing Encoding: `allHaveDisposition` and `isDisposedTo` + +IES has two existing properties for recording dispositions. + +`ies:allHaveDisposition` asserts that all instances of a `ClassOfElement` share a disposition. It is a sub-property of `rdfs:subClassOf`, so it carries a structural inference: if `ex:Eurofighter ies:allHaveDisposition ex:FlyAtMach2`, a reasoner infers `ex:Eurofighter rdfs:subClassOf ex:FlyAtMach2` — placing the Entity class *within* the Capability hierarchy. + +`ies:isDisposedTo` asserts that an individual `Element` is a member of a `DispositionalClass`. It is a sub-property of `rdf:type`, so it carries a type inference: if `data:FighterXYZ-123 ies:isDisposedTo ex:FlyAtMach2`, a reasoner infers `data:FighterXYZ-123 rdf:type ex:FlyAtMach2`. + +Both properties remain valid in IES v5 and are retained for backwards compatibility. + +## Two New Properties: `hasDisposition` and `eachHasDisposition` + +IES v5.1 introduces two complementary properties that express disposition without the sub-class and type inferences of the existing properties. + +**Property signatures:** + +| Property | Domain | Range | Level | +|---|---|---|---| +| `ies:hasDisposition` | `ies:State` | `ies:ClassOfState` | Individual State | +| `ies:eachHasDisposition` | `ies:ClassOfState` | `ies:ClassOfState` | Class of States | + +These properties are sub-properties of `ies:relationship` (not of `rdf:type` or `rdfs:subClassOf`), so they record the modal relationship directly without altering the type hierarchy. + +### `ies:hasDisposition` + +`hasDisposition` asserts that a specific State instance can have (be a member of) a particular `ClassOfState`. This expresses modal possibility: the State *can* be a member of the specified class, but need not actually be one. + +The domain is `ies:State`. In practice, this covers: + +- **Explicit temporal States**, such as `data:FighterXYZ-123-Operational-2024 a ies:VehicleState` +- **Whole-life Entity instances**, such as `data:FighterXYZ-123 a ies:Aircraft`, because every IES Entity subclass (Aircraft, Person, Location, Organisation, etc.) is also a sub-class of its corresponding State subclass through the Entity-as-State pattern + +```turtle +@prefix ies: . +@prefix ex: . +@prefix data: . + +# Individual-level assertion on a temporal State +data:FighterXYZ-123-Operational-2024 a ies:VehicleState ; + rdfs:label "Fighter XYZ-123 in operational condition (2024)"@en-GB ; + ies:isStateOf data:FighterXYZ-123 ; + ies:inPeriod data:Period2024 ; + ies:hasDisposition ex:FlyAtMach2 . +``` + +The range is `ies:ClassOfState`. The target class is typically an instance of `ies:Capability` or `ies:Tendency`: + +```turtle +ex:FlyAtMach2 a ies:Capability ; + rdfs:label "Fly at Mach 2"@en-GB ; + rdfs:subClassOf ies:VehicleState . +``` + +### `ies:eachHasDisposition` + +`eachHasDisposition` asserts that *every member* of a `ClassOfState` can have (be a member of) another `ClassOfState`. This is a universal assertion over a class rather than a statement about any individual. + +```turtle +# Class-level assertion: ALL Eurofighters in operational condition can fly at Mach 2 +ex:EurofighterInOperationalCondition a ies:ClassOfState ; + rdfs:label "Eurofighter in operational condition"@en-GB ; + rdfs:subClassOf ies:VehicleState ; + ies:eachHasDisposition ex:FlyAtMach2 . +``` + +Because `eachHasDisposition` is not a sub-property of `rdfs:subClassOf`, the class `ex:EurofighterInOperationalCondition` is **not** placed within the Capability hierarchy. The asset class and the Capability remain structurally separate, connected only by the `eachHasDisposition` arc. A reasoner will not infer that every member of `ex:EurofighterInOperationalCondition` is a member of `ex:FlyAtMach2` — only that they *can* be. + +### When to Use Each Property + +| Property | Use When… | Example | +|---|---|---| +| `hasDisposition` | A specific State instance can have a particular disposition | "Fighter XYZ-123 in operational condition during 2024 can fly at Mach 2" | +| `eachHasDisposition` | Every member of a `ClassOfState` can have a particular disposition | "Every Eurofighter in operational condition can fly at Mach 2" | +| `isDisposedTo` | An Element is asserted to be a member of a `DispositionalClass` (type inference intended) | Existing data using the original pattern | +| `allHaveDisposition` | All instances of a `ClassOfElement` share a disposition (subclass inference intended) | Existing data using the original pattern | + +### Choosing Between the Old and New Properties + +The key structural difference is the presence or absence of type and subclass inferences: + +- `isDisposedTo` and `allHaveDisposition` place subjects *within* the `DispositionalClass` hierarchy via `rdf:type` and `rdfs:subClassOf` inferences respectively. +- `hasDisposition` and `eachHasDisposition` record the modal relationship without altering the type hierarchy — the subject and the disposition target remain structurally separate. + +For new implementations, `hasDisposition` and `eachHasDisposition` are recommended because: + +- The modal commitment (the State *can* be a member of the class) sits in the property, not in an incidental type inference +- The `ClassOfState` domain/range aligns naturally with 4D extensional modelling, where whole-life Entities and explicit temporal States are uniformly treated as States +- Asset classes and Capability classes remain compositionally independent + +The existing `isDisposedTo` and `allHaveDisposition` properties are retained for backwards compatibility and remain valid for data that intentionally uses the type/subclass encoding. + +## Conditional Dispositions + +Dispositions are often conditional: an asset may be capable of something only when in a particular state (e.g., Mach 2 flight only when in operational condition). The recommended approach is to define a conditional `ClassOfState` representing the subset of interest, and attach the disposition to that class: + +```turtle +# The disposition target +ex:FlyAtMach2 a ies:Capability ; + rdfs:label "Fly at Mach 2"@en-GB ; + rdfs:subClassOf ies:VehicleState . + +# A conditional ClassOfState: Eurofighters in operational condition +ex:EurofighterInOperationalCondition a ies:ClassOfState ; + rdfs:label "Eurofighter in operational condition"@en-GB ; + rdfs:subClassOf ies:VehicleState ; + ies:eachHasDisposition ex:FlyAtMach2 . + +# A temporal State of the specific aircraft, typed as that conditional class +data:FighterXYZ-123-Operational-2024 a ex:EurofighterInOperationalCondition ; + rdfs:label "Fighter XYZ-123 in operational condition (2024)"@en-GB ; + ies:isStateOf data:FighterXYZ-123 ; + ies:inPeriod data:Period2024 ; + ies:hasDisposition ex:FlyAtMach2 . +``` + +This approach keeps Capabilities compositional: the Capability, the precondition, and their relationship are all machine-readable. A Eurofighter with a failed engine remains a member of the class `ex:Eurofighter` but is not currently a member of `ex:EurofighterInOperationalCondition` — and therefore does not inherit the Mach 2 disposition from the class-level assertion, while still retaining any individual-level `hasDisposition` assertions made about it. + +## Modelling Whole-Life vs Temporal Dispositions + +Because every Entity subclass (e.g. `ies:Aircraft`, `ies:Person`, `ies:Location`) is also a sub-class of its corresponding State subclass (e.g. `ies:VehicleState`, `ies:PersonState`, `ies:LocationState`), a whole-life Entity instance satisfies the `ies:State` domain of `hasDisposition` directly. No separate State instance is needed for dispositions that apply throughout an Entity's existence: + +```turtle +# Whole-life disposition — no separate State instance needed +data:FighterXYZ-123 a ies:Aircraft ; + rdfs:label "Fighter XYZ-123"@en-GB ; + ies:hasDisposition ex:FlyAtMach2 . +``` + +For dispositions that hold only during a specific period, create an explicit State instance with temporal bounds: + +```turtle +# Temporal disposition — State instance with period +data:FighterXYZ-123-PostMaint-2024 a ies:VehicleState ; + rdfs:label "Fighter XYZ-123 post-maintenance (2024)"@en-GB ; + ies:isStateOf data:FighterXYZ-123 ; + ies:inPeriod data:Period2024 ; + ies:hasDisposition ex:FlyAtMach2 . +``` + +> **Note.** `ies:Entity` itself is **not** a sub-class of `ies:State`, so the pattern applies only to concrete Entity subclasses (Aircraft, Person, Location, Organisation, etc.), not to bare `ies:Entity` instances. + +## Disposition and Actualisation + +Having a disposition is distinct from *using* it. When a State actually exercises its disposition, this is modelled as that State participating in an Event and being typed as a member of the disposition's `ClassOfState`: + +```turtle +# A State of the aircraft — HAS the disposition (potential) +data:FighterXYZ-123-Operational-2024 a ies:VehicleState ; + ies:isStateOf data:FighterXYZ-123 ; + ies:inPeriod data:Period2024 ; + ies:hasDisposition ex:FlyAtMach2 . + +# An Event of Mach 2 flight +data:Sortie20240717 a ies:Event ; + rdfs:label "Sortie 20240717"@en-GB . + +# A State of the aircraft during the sortie — IS a member of the class (actuality) +data:FighterXYZ-123-Flying-20240717 a ex:FlyAtMach2 ; + rdfs:comment "Fighter XYZ-123 actualising its Mach 2 disposition"@en-GB ; + ies:isParticipationOf data:FighterXYZ-123 ; + ies:isParticipantIn data:Sortie20240717 . +``` + +**Key distinction:** + +- `ies:hasDisposition` = "can be a member of this `ClassOfState`" (modal possibility) +- `rdf:type` = "is a member of this `ClassOfState`" (actuality) + +This separation enables queries such as: + +- "Which aircraft **have the disposition** to fly at Mach 2?" (potential — readiness assessment) +- "Which aircraft **have actually flown** at Mach 2?" (actuality — operational record) + +## Querying Dispositions + +### Finding all States with a given disposition + +```sparql +PREFIX ies: +PREFIX ex: + +SELECT ?state ?entity +WHERE { + ?state ies:hasDisposition ex:FlyAtMach2 . + OPTIONAL { ?state ies:isStateOf ?entity } +} +``` + +### Finding all classes whose members have a given disposition + +```sparql +PREFIX ies: +PREFIX ex: + +SELECT ?class ?classLabel +WHERE { + ?class ies:eachHasDisposition ex:FlyAtMach2 ; + rdfs:label ?classLabel . +} +``` + +### Finding assets with a disposition that have never actualised it + +```sparql +PREFIX ies: +PREFIX ex: + +SELECT ?entity ?entityLabel +WHERE { + ?state ies:hasDisposition ex:FlyAtMach2 ; + ies:isStateOf ?entity . + ?entity rdfs:label ?entityLabel . + FILTER NOT EXISTS { + ?actualState a ex:FlyAtMach2 ; + ies:isParticipationOf ?entity . + } +} +``` + +## Worked Example: Fighter XYZ-123 + +This example brings together class-level and individual-level dispositions for a Eurofighter, showing how the two properties interact and how a disposition is later actualised. + +### Domain Vocabulary + +```turtle +@prefix ies: . +@prefix ex: . +@prefix data: . + +# Disposition target +ex:FlyAtMach2 a ies:Capability ; + rdfs:label "Fly at Mach 2"@en-GB ; + rdfs:subClassOf ies:VehicleState . + +# Conditional ClassOfState — only Eurofighters in operational condition +ex:EurofighterInOperationalCondition a ies:ClassOfState ; + rdfs:label "Eurofighter in operational condition"@en-GB ; + rdfs:subClassOf ies:VehicleState ; + ies:eachHasDisposition ex:FlyAtMach2 . # class-level assertion +``` + +### Individual Aircraft and Temporal State + +```turtle +# The whole-life aircraft Entity +data:FighterXYZ-123 a ies:Aircraft ; + rdfs:label "Fighter XYZ-123"@en-GB . + +# A post-maintenance State — the aircraft has been assessed in operational condition +data:FighterXYZ-123-Operational-2024 a ex:EurofighterInOperationalCondition ; + rdfs:label "Fighter XYZ-123 in operational condition (2024)"@en-GB ; + ies:isStateOf data:FighterXYZ-123 ; + ies:inPeriod data:Period2024 ; + ies:hasDisposition ex:FlyAtMach2 . # individual-level assertion +``` + +Here `data:FighterXYZ-123-Operational-2024` has the disposition both by direct `hasDisposition` assertion *and* by virtue of being a member of `ex:EurofighterInOperationalCondition` (which carries `eachHasDisposition ex:FlyAtMach2`). An implementation may rely on the class-level assertion alone, or assert both for clarity. + +### Actualisation + +```turtle +# A sortie in which Mach 2 is actually achieved +data:Sortie20240717 a ies:Event ; + rdfs:label "Sortie 20240717"@en-GB . + +data:SortieStart a ies:BoundingState ; + ies:isStartOf data:Sortie20240717 ; + ies:inPeriod [ a ies:ParticularPeriod ; + ies:iso8601PeriodRepresentation "2024-07-17T09:00:00Z"^^xsd:string ] . + +data:SortieEnd a ies:BoundingState ; + ies:isEndOf data:Sortie20240717 ; + ies:inPeriod [ a ies:ParticularPeriod ; + ies:iso8601PeriodRepresentation "2024-07-17T11:30:00Z"^^xsd:string ] . + +# The aircraft actualising the Mach 2 disposition +data:FighterXYZ-123-Flying-20240717 a ex:FlyAtMach2 ; + rdfs:comment "Fighter XYZ-123 flying at Mach 2 during Sortie 20240717"@en-GB ; + ies:isParticipationOf data:FighterXYZ-123 ; + ies:isParticipantIn data:Sortie20240717 . +``` + +## Summary + +The disposition properties in IES provide a way to record what States *can* do — their potential — separately from what they *actually* do. + +| Property | Pattern | Inference | +|---|---|---| +| `ies:hasDisposition` | State → ClassOfState (modal) | None — modal possibility only | +| `ies:eachHasDisposition` | ClassOfState → ClassOfState (modal) | None — modal possibility only | +| `ies:isDisposedTo` | Element → DispositionalClass | Entails `rdf:type` (existing pattern) | +| `ies:allHaveDisposition` | ClassOfElement → DispositionalClass | Entails `rdfs:subClassOf` (existing pattern) | + +**Key principles:** + +1. **Dispositions are modal** — a State can have a disposition without ever actualising it +2. **`hasDisposition` domain is `State`** — dispositions attach to temporal parts (or whole-life Entity instances, which are also States) +3. **Actualisation via `rdf:type`** — when a disposition is actually exercised, the State is typed as a member of the disposition's `ClassOfState` +4. **Conditional dispositions use conditional classes** — preconditions are encoded by defining a restricted `ClassOfState` and attaching `eachHasDisposition` to it +5. **`hasDisposition` and `eachHasDisposition` do not alter the type hierarchy** — the subject and the disposition target remain structurally separate + +--- + +## Related Documentation + +- [Instantiation Patterns](instantiation-patterns.md) — Standard patterns for creating IES data +- [4D Ontology Approach](4d-ontology.md) — Understanding States and temporal parts +- [Extending IES](extending-ies.md) — How to create domain-specific extensions + +--- + +*© Crown Copyright 2020-2026* diff --git a/docs/common/user-guides/index.md b/docs/common/user-guides/index.md index 3593bea..5efb2e5 100644 --- a/docs/common/user-guides/index.md +++ b/docs/common/user-guides/index.md @@ -1,6 +1,6 @@ # User Guides -Welcome to the IES Common User Guides. This section provides comprehensive guidance for understanding, implementing, and extending the Information Exchange Standard (IES). +Welcome to the IES Common User Guides. This section provides guidance for understanding, implementing, and extending the Information Exchange Standard (IES). --- @@ -33,6 +33,7 @@ Put your knowledge into practice: - **[Instantiation Patterns](instantiation-patterns.md)** - Learn standard patterns for creating IES data - **[Extending IES](extending-ies.md)** - Discover how to extend IES for your specific needs +- **[Disposition](disposition.md)** - Model what Elements can do (potential vs. actuality) ### 4. Network Concepts Learn how to model interconnected systems: @@ -128,6 +129,17 @@ Guidance on how to extend IES for domain-specific or organisation-specific needs --- +### [Disposition](disposition.md) +Guide to modelling what Elements can do using the Disposition pattern, which expresses potential capabilities that may or may not be actualised. + +**Topics covered:** + +- The hasDisposition and eachHasDisposition relationships +- Relationship to existing patterns (DispositionalClass, Capability) +- Distinguishing potential from actuality + +--- + ### Network Concepts The network documentation provides guidance on modelling interconnected systems such as road networks, utility networks, and other infrastructure. @@ -196,58 +208,6 @@ Discussion of the relationship between the existing `inLocation` relationship an --- -## Audience-Specific Pathways - -### For Implementers -Building systems that consume or produce IES data: - -1. [Introduction to IES](introduction.md) -2. [4D Ontology Approach](4d-ontology.md) - focus on practical implications -3. [Instantiation Patterns](instantiation-patterns.md) -4. [Network Concepts](networks/network.md) - if working with network data -5. Review [Examples](../examples/index.md) - -### For Information Architects -Designing information exchanges or mapping schemas: - -1. [What is an Ontology?](what-is-an-ontology.md) -2. [Introduction to IES](introduction.md) -3. [4D Ontology Approach](4d-ontology.md) -4. [BORO Methodology](boro-methodology.md) -5. [Network Concepts](networks/network.md) - for infrastructure domains -6. [Extending IES](extending-ies.md) - -### For Data Modellers -Mapping existing schemas to/from IES: - -1. [Introduction to IES](introduction.md) -2. [What is an Ontology?](what-is-an-ontology.md) -3. [Instantiation Patterns](instantiation-patterns.md) -4. [Connection](networks/connection.md) - for relationship mapping -5. [Extending IES](extending-ies.md) - -### For Ontology Engineers -Working on IES itself or advanced extensions: - -1. [BORO Methodology](boro-methodology.md) -2. [4D Ontology Approach](4d-ontology.md) -3. [Network Concepts](networks/network.md) - understanding the network extension -4. [Location and Containment](networks/location-and-containment.md) - semantic distinctions -5. [Extending IES](extending-ies.md) -6. Review [Specification](../specification/index.md) - -### For Infrastructure Domain Specialists -Working with road, rail, utility, or other network-based domains: - -1. [Introduction to IES](introduction.md) -2. [4D Ontology Approach](4d-ontology.md) -3. [Network Concepts](networks/network.md) -4. [Connection](networks/connection.md) -5. [Flow](networks/flow.md) -6. [Containment](networks/containment.md) - ---- - ## Additional Resources ### Related Documentation @@ -303,7 +263,7 @@ Please [open an issue](https://github.com/IES-Org/ies-common/issues) on our GitH ## Version Information **Documentation Version:** 5.1.0 -**Last Updated:** 06 January 2026 +**Last Updated:** 07 January 2026 **Applies to:** IES Common 5.x releases ---