# Valueflows Location Proposal

After reviewing [all the schemas and formats for geospatial](https://github.com/Cuauhtlatoatzin/open-source-gis/blob/master/formats_and_schemas.md), plus a few other schemas for non-geo data.

## A Potential Solution

We really need a object that allows a level of combination between these different ideas.

We need an object that allows:
* `dcterms:title` — The name of the location. This is probably the minimum amount of data we need.
* `uri` — to enable URIs, [URNs](https://en.wikipedia.org/wiki/Uniform_Resource_Name#Examples), [Magnet URIs](https://en.wikipedia.org/wiki/Magnet_URI_scheme), or [DIDs](https://w3c.github.io/did-core/#a-simple-example).
* [`xal:AddressDetails`](https://www.web3d.org/specifications/kml2.2/documentation/xAL_AddressDetails.html#Link1)
* This also has it's own `AddressLatitude` and `AddressLongitude` that can be used instead of `geo:Feature`.
* [`geo:Feature`](https://github.com/opengeospatial/ogc-geosparql/blob/master/1.1/geo.ttl#L946)
* [example](https://github.com/opengeospatial/ogc-geosparql/blob/master/1.1/examples/demo-dataset.ttl#L91)
* [`payIdAddress`](https://github.com/PayString/rfcs/blob/master/dist/spec/self-sov-verifiable-payid-protocol.txt#L341-L354) — should we include the full set of signatures and verification parameters?
* `expTime` — a time at which point the crypto address will no longer be valid.
* `paymentNetwork` — The network that should be used, like XRPL. Most likely the name of the network on the exchange.
* `environment` — An indicator for which network environment should be used, for instance TESTNET.
* `addressDetailsType: "CryptoAddressDetails"`
* `addressDetails`
* `address` — The actual wallet adress.
* `tag` — Often times additional data needs to be used besides the address.

Then we have all the features any of the groups we've interacted with wanted, but we still don't expose RDF data, so SPARQL queries will have to wait until we do (unless we write our own engine on Holochain).

## Schema Changes

@base              <https://w3id.org/valueflows> .
@prefix vf:        <#> .
@prefix rdf:       <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix owl:       <http://www.w3.org/2002/07/owl#> .
@prefix rdfs:      <http://www.w3.org/2000/01/rdf-schema#> .
@prefix foaf:      <http://xmlns.com/foaf/0.1/> .
@prefix org:       <http://www.w3.org/ns/org#> .
@prefix dcterms:   <http://purl.org/dc/terms/> .
@prefix om2:       <http://www.ontology-of-units-of-measure.org/resource/om-2/> .
@prefix xsd:       <http://www.w3.org/2001/XMLSchema#> .
@prefix time:      <http://www.w3.org/2006/time#> .
@prefix wgs84_pos: <http://www.w3.org/2003/01/geo/wgs84_pos#> .
@prefix geosparql: <http://www.opengis.net/ont/geosparql#> .
# Not the schema, there's no RDF schema to match the xAL xml schema.
@prefix xal:       <http://docs.oasis-open.org/election/external/xAL.xsd> .
@prefix vs:        <http://www.w3.org/2003/06/sw-vocab-status/ns#> .
@prefix dtype:     <http://www.linkedmodel.org/schema/dtype#> .
@prefix dfc:       <http://www.virtual-assembly.org/DataFoodConsortium/BusinessOntology#> .
@prefix skos:      <http://www.w3.org/2004/02/skos/core#> .

vf:Location a               geosparql:Feature ;
        rdfs:label          "location object"@en ;
        vs:term_status      "unstable" ;
        rdfs:description    "A location that supports both physical and logical locations, for instance a specific drawer, a building, a bank account address, a crypto-address, or a p2p DHT hash."@en ;
        .

vf:address a                owl:ObjectProperty ;
        rdfs:label          "an address string"@en ;
        rdfs:domain         vf:Location ;
        rdfs:range          xsd:string ;
        vs:term_status      "unstable" ;
        rdfs:comment        "A simple address as a string"@en ;
        .

vf:addressDetails a         owl:ObjectProperty ;
        rdfs:label          "a structures address object"@en ;
        rdfs:domain         vf:Location ;
        rdfs:range          xal:AddressDetails ;
        vs:term_status      "unstable" ;
        rdfs:comment        "An address as a structured object conforming to xAL:AddressDetails."@en ;
        .

vf:uri a                    owl:ObjectProperty ;
        rdfs:label          "a virtual location"@en ;
        rdfs:domain         vf:Location ;
        rdfs:range          xsd:anyURI ;
        vs:term_status      "unstable" ;
        rdfs:comment        "A virtual address. Can be a document on the web, a magnet URI, a DID, etc."@en ;

vf:hasPoint a               owl:ObjectProperty ;
        rdfs:label          "geo point"@en ;
        rdfs:domain         vf:Location ;
        rdfs:range          wgs84_pos:Point ;
        vs:term_status      "unstable" ;
        rdfs:comment        "A simple geo point object with lat, long, alt."@en ;
        .
        
vf:hasPayIdAddress a        owl:ObjectProperty ;
        rdfs:label          "PayId Address"@en ;
        rdfs:domain         vf:Location ;
        rdfs:range          owl:Thing ;
        vs:term_status      "unstable" ;
        rdfs:comment        "A JSON object encoding all the data for a crypto currency payment."@en ;
        .

vf:currentLocation a        owl:ObjectProperty ;
        rdfs:label          "current location"@en ;
        rdfs:domain         vf:EconomicResource ;
        rdfs:range          vf:Location ;
        vs:term_status      "unstable" ;
        rdfs:comment        "The current place an economic resource is located.  Could be at any level of granularity, from a town to an address to a warehouse location.  Usually mappable."@en ;
        .

vf:primaryLocation a        owl:ObjectProperty ;
        rdfs:label          "primary location"@en ;
        rdfs:domain         foaf:Agent ;
        rdfs:range          vf:Location ;
        vs:term_status      "unstable" ;
        rdfs:comment        "The main place an agent is located, often an address where activities occur and mail can be sent. This is usually a mappable geographic location.  It also could be a website address, as in the case of agents who have no physical location."@en ;
        .

vf:eligibleLocation a       owl:ObjectProperty ;
        rdfs:label          "eligible location"@en ;
        rdfs:domain         vf:Proposal ;
        rdfs:range          vf:Location ;
        vs:term_status      "unstable" ;
        rdfs:comment        "Location or area where the proposal is valid."@en ;
        .

vf:atLocation a             owl:ObjectProperty ;
        rdfs:label          "at location"@en ;
        rdfs:domain         [ owl:unionOf (vf:EconomicEvent vf:Commitment vf:Intent) ] ;
        rdfs:range          vf:Location ;
        vs:term_status      "unstable" ;
        rdfs:comment        "The place where an intent, commitment, or economic event occurs.  Usually mappable."@en ;
        .

vf:toLocation a             owl:ObjectProperty ;
        rdfs:label          "to location"@en ;
        rdfs:domain         vf:EconomicEvent ;
        rdfs:range          vf:Location ;
        vs:term_status      "unstable" ;
        rdfs:comment        "The new location of the receiver resource."@en ;
        .
        
# Change vf:name and skos:note domain
        
# We should delete vf:mappableAddress (this is essentially a rename from vf:mappableAddress -> vf:address)

## Examples

Any of the following types of locations can actually be blended together (so long as the combination makes sense).

### Simple Address

{
  "id": "google-main",
  "name": "Google",
  "address": "1600 Amphitheatre Parkway Mountain View, CA 94043 United States"
}

### Virtual Location

{
  "id": "repo-0",
  "name": "REA Playspace Repo",
  "uri": "[e-mail]:lightningrodlabs/rea-playspace.git"
}

### DID

{
  "id": "did-0",
  "name": "Example DID",
  "uri": "did:example:123456/path"
}

### AddressDetails

{
  "id": "DEBY_LOD2_5744682",
  "name": "Random Place in Germany",
  "AddressDetails": {
    "AddressType": "Business",
    "Country": {
      "Name": "Germany"
    },
    "Locality": {
      "Type": "Town",
      "Name": "Moosach",
    "Thoroughfare": {
      "Type": "Street",
      "NameAndType": "Am Hang",
      "Number": "15"
    },
    "PostCode": {
      "Identifier": "85665"
    }
  }
}

### Simple Point

{
  "name": "Apple Park",
  "hasPoint": {
    "lat": 37.334797309504935,
    "long": -122.00893980918558,
    "alt": 0
  }
}

### PayID Address

{
  "id": "test",
  "name": "Test XRP Address",
  "hasPayIdAddress": {
    "expTime": 34874613475,
    "paymentNetwork": "XRPL",
    "environment": "TESTNET",
    "addressDetailsType": "CryptoAddressDetails",
    "addressDetails": {
      "address": "rnzBSt9ZCJSh4RxC9f1v6oS9WZtEYJa8B9",
      "tag": "12345"
     }
  }
}

### Geometry

Since this includes WKT, GML, KML, and GeoJSON, we can include even more complex geometries.

{
  "id": "shorncliffe-point-2",
  "name": "Shorncliffe Point 2",
  "hasGeometry": {
    "asWKT": "POINT (153.0880008 -27.3283533)",
    "asGeoJSON": "{\"type\": \"Point\", \"coordinates\": [153.0880008, -27.3283533]}"
  }
}