NIP-115 Yet Another Geo Tag (ISO-3166-1/2/3)

115.md

@@ -0,0 +1,103 @@
+# NIP-115: Yet Another Geo Tag
+
+`draft` `optional`
+
+This NIP adds a new indexable tag `G`. 
+
+## Motivation
+The core aim of this NIP is to establish a unified and efficient method for geocoded events. While attempting to implement `ISO-3166` with NIP-32, it became evident that more specific guidelines were needed for geocoding events. This NIP is designed to provide a clear and standardized format for geocoded events, promoting uniformity and effectiveness of geodata across nostr.
+
+## Rationale
+Developing a dedicated geotagging NIP offers several advantages over the general application of NIP-32 for geographical data:
+
+- **Full ISO-3166 support** NIP-115 is an objective, non-opinionated complete implementation of ISO-3166 that is compatible with nostr filters with no known collisions.
+- **Lean** Value types are implicit and have a significantly smaller footprint compared to explicit value typing.
+- **Intuitive** Enables shallow usage of standard without ISO-3166 domain knowledge.
+- **Handles ISO-3166-3 "changes":** The complexity added by ISO-3166-3 country code changes when using NIP-32 is streamlined in this NIP by simply labeling the channge as countryCode, thus making both publishing and filtering more straightforward.
+- **Significance of Geodata:** Given its ubiquity, importance and diversity, geodata warrants its own specific letter designations and detailed specifications within nostr.
+- **Backwards compatibility** In the event a country has a code change, events from both before and after the change are discoverable
+
+## Schema 
+```
+["G", value, marker]
+```
+
+## Value Types 
+_`x` axis is ISO-3166 value type, and `y` axis is draft_
+| draft      | alpha-2 | alpha-3 | alpha-4 | numeric |
+|------------|---------|---------|---------|---------|
+| ISO-3166-1 | ✓       | ✓       |         | ✓       |
+| ISO-3166-2 | ✓       |         |         | ✓       |
+| ISO-3166-3 | ✓       | ✓       |  ✓      | ✓       |
+
+
+## Markers
+Standards are assigned to human readable markers instead explicit standard-specific language, which simplifies both publishing, filtering and readability.
+_See above table for draft/value type compatiblity_
+| marker      | alpha-2 | alpha-3 | alpha-4 | numeric |
+|-------------|---------|---------|---------|---------|
+| countryCode | ✓       | ✓       | ✓       | ✓       |
+| regionCode  | ✓       |         |         | ✓       |
+
+## Collisions 
+Filter collisions have been mitigated as much as possible.
+- `ISO-3166-1/2/3:numeric` codes have no collisions. 
+- `ISO-3166-1/3` and `ISO-3166-2` [subdivisions] collisions are inconsequential.
+
+# Best Practices
+- `alpha-2` codes take prominence, other codes **MAY** optionally be included for system compatiblity.
+- When publishing, if a country has an `ISO-3166-3` "change", `ISO-3166-3:alpha-4` **SHOULD** be included (hint for parsing case)
+- When publishing, if a country has an `ISO-3166-3` "change", the `ISO-3166-1` **SHOULD NOT** be included 
+- When filtering, if a country has an `ISO-3166-3` "change", both the `ISO-3166-1` and `ISO-3166-3` code(s) **SHOULD** be included for most complete results.
+
+# ISO-3166 Library Support
+
+ISO-3166 is widely supported, existing libraries help with publishing, filtering and parsing.
+
+_Many languages have multiple library options, only a single library is linked for each language_
+|                                                                    | drafts | alpha-2 | alpha-3 | alpha-4    | numeric |
+|--------------------------------------------------------------------|--------|---------|---------|------------|---------|
+| [JS/TS](https://www.npmjs.com/package/iso-3166)                    | 1/2/3  | ✓       | ✓       | composable | ✓       |
+| [GO](https://github.com/biter777/countries)                        | 1/2/3  | ✓       | ✓       | composable | ✓       |
+| [Rust](https://github.com/rust-iso/rust_iso3166)                   | 1/2/3  | ✓       | ✓       | composable | ✓       |
+| [Swift](https://github.com/funky-monkey/IsoCountryCodes)           | 1      | ✓       | ✓       |            | ✓       |
+| [Java](https://github.com/TakahikoKawasaki/CountryCode)            | 1      | ✓       | ✓       |            | ✓       |
+| [Clojure](https://github.com/totakke/clj-iso3166)                  | 1      | ✓       | ✓       |            | ✓       |
+| [Ruby](https://github.com/countries/countries/)                    | 1      | ✓       | ✓       |            | ✓       |
+
+## Examples
+
+### Minimal Example 
+```json
+{ tags:
+  [
+    [ "G", "countryCode", "US" ]
+  ]
+}
+```
+
+### Robust Example
+_Note: Antiquated ISO-3166-1 codes are included for example purposes_
+```json
+{ tags:
+  [
+    [ "G",  "AI",   "countryCode"     ], //ISO-3166-1 alpha-2
+    [ "G",  "AIA",  "countryCode"     ], //ISO-3166-1 alpha-3
+    [ "G",  "262",  "countryCode"     ], //ISO-3166-1 numeric
+    [ "G",  "DJ",   "countryCode"     ], //ISO-3166-3 alpha-2 "change" 
+    [ "G",  "DJI",  "countryCode"     ], //ISO-3166-3 alpha-3 "change" 
+    [ "G",  "AIDJ", "countryCode"     ], //ISO-3166-3 alpha-4 change hint
+    [ "G",  "AI",   "regionCode"      ], //ISO-3166-2 regionCode alpha-2 (subdivision)
+    [ "G",  "019",  "regionCode"      ], //ISO-3166-2 regionCode numeric (subdivision)
+    [ "G",  "419",  "subRegionCode"   ], //ISO-3166-2 subRegionCode numeric (subdivision)
+    [ "G",  "029",  "interRegionCode" ], //ISO-3166-2 intermediate region code numeric (subdivision)
+  ]
+}
+```
+
+### Filter
+_Effective for events where **countryCode** `G` is either `AI` (antiquated `ISO-3166-1`) or `DJ` (`ISO-3166-3` change)_
+
+```
+{ "#G": ["AI", "DJ"] }
+```

README.md

@@ -81,6 +81,7 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos
 - [NIP-96: HTTP File Storage Integration](96.md)
 - [NIP-98: HTTP Auth](98.md)
 - [NIP-99: Classified Listings](99.md)
+- [NIP-115: ISO-3166 Geotags](115.md)
 
 ## Event Kinds
 | kind          | description                | NIP                      |
@@ -214,12 +215,13 @@ Please update these lists when proposing NIPs introducing new event kinds.
 | `a`               | coordinates to an event              | relay URL            | [01](01.md)                           |
 | `d`               | identifier                           | --                   | [01](01.md)                           |
 | `g`               | geohash                              | --                   | [52](52.md)                           |
+| `G`               | ISO-3166 (alpha-2/3/4, numeric)      | --                   | [115](115.md)                         |
 | `i`               | identity                             | proof                | [39](39.md)                           |
 | `k`               | kind number (string)                 | --                   | [18](18.md), [25](25.md), [72](72.md) |
 | `l`               | label, label namespace               | annotations          | [32](32.md)                           |
 | `L`               | label namespace                      | --                   | [32](32.md)                           |
 | `m`               | MIME type                            | --                   | [94](94.md)                           |
-| `q`               | event id (hex)                       | relay URL    | [18](18.md)                           |
+| `q`               | event id (hex)                       | relay URL            | [18](18.md)                           |
 | `r`               | a reference (URL, etc)               | petname              |                                       |
 | `r`               | relay url                            | marker               | [65](65.md)                           |
 | `t`               | hashtag                              | --                   |                                       |