Adding facility location to user guide

documentation/user-guides/design-patterns/Design Pattern 1/facility location/README.md

@@ -0,0 +1,110 @@
+# Pattern Name
+Facility Location
+
+# Intent
+
+To represent location relationships where material entities (e.g., facilities, equipment, infrastructure) are situated within progressively larger geographic regions or sites (e.g., building → campus → city → state → country), enabling multi-level location queries and reasoning. The specific entity types and site hierarchies shown are examples. This pattern generalizes to any material entity that can be located at sites, and any hierarchical organization of sites.
+
+# Competency Questions
+
+1. Where is a specific facility located?
+2. What bigger site is this facility located in, and are there smaller sites that the facility is located in that are also located in the bigger site?
+3. What are all the facilities located within a particular site?
+
+# Structure
+
+Represents locations as sites and use of the located_in relation.
+
+Helps with show how non-transitive relation can be used to do a query that acts transitively.
+
+Visual model through mermaid and png.
+
+*Note: Entity types and location hierarchies shown are illustrative examples. This pattern applies to any material entities and site taxonomies relevant to your domain.*
+```mermaid
+flowchart BT
+    A@{ label: "<font color=\"#000000\">Facility 1</font>" } -- LocatedIn<br>BFO_0000171 --> B@{ label: "<font color=\"#000000\">City 1</font>" }
+    B -- LocatedIn<br>BFO_0000171 --> C@{ label: "<font color=\"#000000\">State 1</font>" }
+    A -- rdf:type --> D@{ label: "<span style=\"color:black\"><b>Facility<br>ont00000192</b></span><br>" }
+    B -- rdf:type --> E@{ label: "<span style=\"color:black\"><b>Site<br>BFO_0000029</b></span><br>" }
+    C -- rdf:type --> E
+    A -. rdfs:label .-> F["<i>&quot;Building 1&quot;</i>"]
+    B -. rdfs:label .-> G["<i>&quot;NY City&quot;</i>"]
+    C -. rdfs:label .-> H["<i>&quot;NY State&quot;</i>"]
+
+    subgraph Legend[" "]
+    direction LR
+    LL[ ] --> |relation| LL2[ ]
+    LD[ ] -.-> |data property| LD2[ ]
+        AA["Individual"]
+    BB["<b>Class</b>"]
+    CC["<i>&quot;literal&quot;</i>"]
+    end
+
+    A ~~~ Legend
+
+    A@{ shape: rect}
+    B@{ shape: rect}
+    C@{ shape: rect}
+    D@{ shape: rect}
+    E@{ shape: rect}
+    F@{ shape: rect}
+    G@{ shape: rect}
+    H@{ shape: rect}
+    A:::purple
+    B:::purple
+    C:::purple
+    D:::yellow
+    E:::yellow
+    F:::literal
+    G:::literal
+    H:::literal
+    AA:::purple
+    BB:::yellow
+    CC:::literal
+    LL:::invisible
+    LL2:::invisible
+    LD:::invisible
+    LD2:::invisible
+    classDef yellow fill:#ffe680,color:#7a6000,stroke:#c8a800
+    classDef purple fill:#dbc9ef,color:#000000,stroke:#9b7fc7
+    classDef literal fill:none,stroke:none,color:#555555,font-style:italic
+    classDef invisible fill:none,stroke:none,color:none,width:0px
+
+```
+
+# File Structure
+```
+facility-location/
+├── README.md
+├── mermaid/
+│   ├── FacilityLocation.md        # Mermaid source file
+│   └── FacilityLocation.png        # Exported PNG diagram
+└── sparql/
+    ├── CQ1.sparql     # Where is a specific facility located?
+    ├── CQ2.sparql        # What larger/smaller sites contain this facility?
+    ├── CQ3.sparql    # What facilities are within a particular site?
+    └── example.ttl                  # Test data for SPARQL queries
+```
+
+## File Descriptions
+
+### mermaid/
+| File | Description |
+|------|-------------|
+| `FacilityLocation.md` | Mermaid diagram source showing the pattern structure |
+| `FacilityLocation.png` | PNG export of the diagram for documentation |
+
+### sparql/
+| File | Competency Question |
+|------|---------------------|
+| `CQ1.sparql` | Where is a specific facility located? |
+| `CQ2.sparql` | What bigger site is this facility located in, and are there smaller sites that the facility is located in that are also located in the bigger site? |
+| `CQ3.sparql` | What are all the facilities located within a particular site? |
+| `example.ttl` | Turtle file with test instances (states, cities, campuses, buildings, facilities) |
+
+# Additional Notes
+
+- Related pattern: Geospatial Coordinate Pattern
+- Key classes: `obo:BFO_0000029` (Site), `cco:ont00000192` (Facility)
+- Key property: `obo:BFO_0000171` (located in)
+

documentation/user-guides/design-patterns/Design Pattern 1/facility location/mermaid/FacilityLocation.md

@@ -0,0 +1,49 @@
+flowchart BT
+    A@{ label: "<font color=\"#000000\">Facility 1</font>" } -- LocatedIn<br>BFO_0000171 --> B@{ label: "<font color=\"#000000\">City 1</font>" }
+    B -- LocatedIn<br>BFO_0000171 --> C@{ label: "<font color=\"#000000\">State 1</font>" }
+    A -- rdf:type --> D@{ label: "<span style=\"color:black\"><b>Facility<br>ont00000192</b></span><br>" }
+    B -- rdf:type --> E@{ label: "<span style=\"color:black\"><b>Site<br>BFO_0000029</b></span><br>" }
+    C -- rdf:type --> E
+    A -. rdfs:label .-> F["<i>&quot;Building 1&quot;</i>"]
+    B -. rdfs:label .-> G["<i>&quot;NY City&quot;</i>"]
+    C -. rdfs:label .-> H["<i>&quot;NY State&quot;</i>"]
+
+    subgraph Legend[" "]
+    direction LR
+    LL[ ] --> |relation| LL2[ ]
+    LD[ ] -.-> |data property| LD2[ ]
+        AA["Individual"]
+    BB["<b>Class</b>"]
+    CC["<i>&quot;literal&quot;</i>"]
+    end
+
+    A ~~~ Legend
+
+    A@{ shape: rect}
+    B@{ shape: rect}
+    C@{ shape: rect}
+    D@{ shape: rect}
+    E@{ shape: rect}
+    F@{ shape: rect}
+    G@{ shape: rect}
+    H@{ shape: rect}
+    A:::purple
+    B:::purple
+    C:::purple
+    D:::yellow
+    E:::yellow
+    F:::literal
+    G:::literal
+    H:::literal
+    AA:::purple
+    BB:::yellow
+    CC:::literal
+    LL:::invisible
+    LL2:::invisible
+    LD:::invisible
+    LD2:::invisible
+    classDef yellow fill:#ffe680,color:#7a6000,stroke:#c8a800
+    classDef purple fill:#dbc9ef,color:#000000,stroke:#9b7fc7
+    classDef literal fill:none,stroke:none,color:#555555,font-style:italic
+    classDef invisible fill:none,stroke:none,color:none,width:0px
+

documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ1.sparql

@@ -0,0 +1,22 @@
+# CQ1: Where is a facility located?
+# Returns the immediate site(s) where a given facility is located
+
+PREFIX rdfs:       <http://www.w3.org/2000/01/rdf-schema#>
+PREFIX cco:        <https://www.commoncoreontologies.org/>
+PREFIX obo:        <http://purl.obolibrary.org/obo/>
+PREFIX facility:   <https://www.commoncoreontologies.org/ont00000192>
+PREFIX located_in: <http://purl.obolibrary.org/obo/BFO_0000171>
+
+SELECT ?facility ?facilityLabel ?site ?siteLabel
+WHERE {
+
+    # ── Parameter: bind the facility IRI you want to query ──────────────────
+    #BIND(<YOUR_FACILITY_IRI_HERE> AS ?facility)
+
+    BIND(<https://www.commoncoreontologies.org/CommonCoreOntologiesMerged/facility_warehouse_nyc> AS ?facility)
+
+    ?facility a facility: ;
+              rdfs:label ?facilityLabel ;
+              located_in: ?site .
+    ?site rdfs:label ?siteLabel .
+}

documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ2.sparql

@@ -0,0 +1,33 @@
+# CQ2: What bigger site is this facility located in, and are there smaller sites 
+# that the facility is also located in that are within the bigger site?
+# Uses property paths to find the full location hierarchy
+
+PREFIX rdfs:       <http://www.w3.org/2000/01/rdf-schema#>
+PREFIX cco:        <https://www.commoncoreontologies.org/>
+PREFIX obo:        <http://purl.obolibrary.org/obo/>
+PREFIX facility:   <https://www.commoncoreontologies.org/ont00000192>
+PREFIX located_in: <http://purl.obolibrary.org/obo/BFO_0000171>
+
+SELECT ?site ?siteLabel ?parentSite ?parentSiteLabel
+       (COUNT(?intermediate) AS ?depth)
+WHERE {
+
+    # ── Parameter: bind the facility IRI you want to query ──────────────────
+    #BIND(<YOUR_FACILITY_IRI_HERE> AS ?facility)
+
+    BIND(<https://www.commoncoreontologies.org/CommonCoreOntologiesMerged/facility_warehouse_nyc> AS ?facility)
+
+    ?facility located_in: ?site .
+
+    ?site        located_in: ?parentSite .
+    ?site        rdfs:label  ?siteLabel .
+    ?parentSite  rdfs:label  ?parentSiteLabel .
+
+    OPTIONAL {
+        ?site         located_in:+ ?intermediate .
+        ?intermediate located_in:+ ?parentSite .
+    }
+
+}
+GROUP BY ?site ?siteLabel ?parentSite ?parentSiteLabel
+ORDER BY ASC(?depth) ASC(?siteLabel)

documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/CQ3.sparql

@@ -0,0 +1,27 @@
+# CQ3: What are all the facilities located within a site?
+# Finds facilities directly or transitively located within a site
+
+PREFIX rdfs:       <http://www.w3.org/2000/01/rdf-schema#>
+PREFIX cco:        <https://www.commoncoreontologies.org/>
+PREFIX obo:        <http://purl.obolibrary.org/obo/>
+PREFIX site:       <http://purl.obolibrary.org/obo/BFO_0000029>
+PREFIX facility:   <https://www.commoncoreontologies.org/ont00000192>
+PREFIX located_in: <http://purl.obolibrary.org/obo/BFO_0000171>
+
+SELECT ?targetSite ?targetSiteLabel ?facility ?facilityLabel
+WHERE {
+
+    # ── Parameter: bind the site IRI you want to query ──────────────────────
+    #BIND(<YOUR_SITE_IRI_HERE> AS ?targetSite)
+
+    BIND(<https://www.commoncoreontologies.org/CommonCoreOntologiesMerged/campus_manhattan> AS ?targetSite)
+
+    ?targetSite rdfs:label ?targetSiteLabel .
+
+    ?facility a facility: ;
+              rdfs:label ?facilityLabel ;
+              located_in:+ ?targetSite .
+
+}
+ORDER BY ASC(?facilityLabel)
+

documentation/user-guides/design-patterns/Design Pattern 1/facility location/sparql/example.ttl

@@ -0,0 +1,101 @@
+# Test data for CQ1–CQ3
+# Imports CCO (which in turn imports BFO), so no need to restate definitions here.
+# For reference, the key classes and properties used are:
+#   - obo:BFO_0000029  (site)       — a three-dimensional immaterial entity
+#   - cco:ont00000192  (Facility)   — a Material Artifact dedicated to a specific purpose
+#   - obo:BFO_0000171  (located in) — occupies a spatial region that is part of another's region
+# Full definitions are in the imported ontologies.
+
+@prefix :     <https://www.commoncoreontologies.org/CommonCoreOntologiesMerged/> .
+@prefix cco:  <https://www.commoncoreontologies.org/> .
+@prefix obo:  <http://purl.obolibrary.org/obo/> .
+@prefix owl:  <http://www.w3.org/2002/07/owl#> .
+@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
+
+<https://www.commoncoreontologies.org/CommonCoreOntologiesMerged/>
+    rdf:type owl:Ontology ;
+    owl:imports <https://www.commoncoreontologies.org/> .
+
+#################################################################
+#    Sites — location hierarchy (largest → smallest)
+#
+#    NY State
+#      └── New York City       (located_in NY State)
+#      │     └── Manhattan Campus  (located_in NYC)
+#      │           ├── Tower 1     (located_in Manhattan Campus)
+#      │           └── Tower 2     (located_in Manhattan Campus)
+#      └── Buffalo             (located_in NY State)
+#    California
+#      └── Los Angeles         (located_in California)
+#            └── Downtown LA Campus  (located_in LA)
+#    Texas
+#      └── Houston             (located_in Texas)
+#################################################################
+
+# States
+:state_ny       rdf:type obo:BFO_0000029 ; rdfs:label "NY State" .
+:state_ca       rdf:type obo:BFO_0000029 ; rdfs:label "California" .
+:state_tx       rdf:type obo:BFO_0000029 ; rdfs:label "Texas" .
+
+# Cities
+:city_nyc       rdf:type obo:BFO_0000029 ; rdfs:label "New York City" ;
+                obo:BFO_0000171 :state_ny .              # NYC located_in NY State
+
+:city_buffalo   rdf:type obo:BFO_0000029 ; rdfs:label "Buffalo" ;
+                obo:BFO_0000171 :state_ny .              # Buffalo located_in NY State
+
+:city_la        rdf:type obo:BFO_0000029 ; rdfs:label "Los Angeles" ;
+                obo:BFO_0000171 :state_ca .              # LA located_in California
+
+:city_houston   rdf:type obo:BFO_0000029 ; rdfs:label "Houston" ;
+                obo:BFO_0000171 :state_tx .              # Houston located_in Texas
+
+# Campuses
+:campus_manhattan    rdf:type obo:BFO_0000029 ; rdfs:label "Manhattan Campus" ;
+                     obo:BFO_0000171 :city_nyc .         # Manhattan Campus located_in NYC
+
+:campus_downtown_la  rdf:type obo:BFO_0000029 ; rdfs:label "Downtown LA Campus" ;
+                     obo:BFO_0000171 :city_la .          # Downtown LA Campus located_in LA
+
+# Buildings
+:building_tower1  rdf:type obo:BFO_0000029 ; rdfs:label "Tower 1" ;
+                  obo:BFO_0000171 :campus_manhattan .    # Tower 1 located_in Manhattan Campus
+
+:building_tower2  rdf:type obo:BFO_0000029 ; rdfs:label "Tower 2" ;
+                  obo:BFO_0000171 :campus_manhattan .    # Tower 2 located_in Manhattan Campus
+
+#################################################################
+#    Facilities
+#
+#    NYC Main Warehouse        located_in Tower 1
+#    NYC Corporate Office      located_in Tower 2
+#    NYC Research Lab          located_in Manhattan Campus
+#    Buffalo Distribution Ctr  located_in Buffalo
+#    LA Warehouse              located_in Downtown LA Campus
+#    LA Regional Office        located_in Los Angeles
+#    Houston Manufacturing     located_in Houston
+#################################################################
+
+:facility_warehouse_nyc     rdf:type cco:ont00000192 ; rdfs:label "NYC Main Warehouse" ;
+                            obo:BFO_0000171 :building_tower1 .       # NYC Main Warehouse located_in Tower 1
+
+:facility_office_nyc        rdf:type cco:ont00000192 ; rdfs:label "NYC Corporate Office" ;
+                            obo:BFO_0000171 :building_tower2 .       # NYC Corporate Office located_in Tower 2
+
+:facility_lab_nyc           rdf:type cco:ont00000192 ; rdfs:label "NYC Research Lab" ;
+                            obo:BFO_0000171 :campus_manhattan .      # NYC Research Lab located_in Manhattan Campus
+
+:facility_warehouse_buffalo  rdf:type cco:ont00000192 ; rdfs:label "Buffalo Distribution Center" ;
+                             obo:BFO_0000171 :city_buffalo .         # Buffalo Distribution Center located_in Buffalo
+
+:facility_warehouse_la      rdf:type cco:ont00000192 ; rdfs:label "LA Warehouse" ;
+                            obo:BFO_0000171 :campus_downtown_la .    # LA Warehouse located_in Downtown LA Campus
+
+:facility_office_la         rdf:type cco:ont00000192 ; rdfs:label "LA Regional Office" ;
+                            obo:BFO_0000171 :city_la .               # LA Regional Office located_in Los Angeles
+
+:facility_plant_houston     rdf:type cco:ont00000192 ; rdfs:label "Houston Manufacturing Plant" ;
+                            obo:BFO_0000171 :city_houston .          # Houston Manufacturing Plant located_in Houston
+

documentation/user-guides/design-patterns/README.md

@@ -3,3 +3,10 @@ This folder contains common CCO design patterns.
 Each entry includes a mermaid graph, a visualization of that graph, a description of competency questions answered, and a sparql query to support the competency questions.
 
 Users are encouraged to reuse these design patterns in their knowledge graphs to speed up data mapping and querying while ensuring greater consistency and interoperability across knowledge graphs.
+
+## Folder Directory
+
+| Folder Name     | Description                                |
+|------------------|--------------------------------------------|
+| Design Pattern 1           | facility location         |
+