From caa989e345567c0fa3b35130a5fb1b8033eae601 Mon Sep 17 00:00:00 2001 From: John X Date: Tue, 16 Dec 2025 12:59:57 +0000 Subject: [PATCH 1/5] docs: Clarify locationType and location attribute relationship MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses feedback from Philipp via Adam Spiers regarding confusion about the locationType attribute structure: - Changed "included in" to clearly state that locationType IS the Location Format Identifier, not a container that includes it - Added new "How It Works" section explicitly explaining the relationship between locationType and location attributes - Added three concrete examples showing both locationType and location values together for different formats (coordinate, GeoJSON, WKT) - Reorganized content to present the two-attribute structure upfront before diving into identifier naming conventions - Minor whitespace cleanup (trailing space removal) This improves navigation and clarity by making it immediately clear which content applies to locationType (the identifier) vs location (the payload). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/location-protocol/location-types.md | 39 ++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/docs/location-protocol/location-types.md b/docs/location-protocol/location-types.md index 80dbe4f..7fd3ce6 100644 --- a/docs/location-protocol/location-types.md +++ b/docs/location-protocol/location-types.md @@ -10,7 +10,40 @@ The Location Format Extensions Library is a core component of Astral's Location ## Overview -Each location format is defined by a unique identifier (the Location Format Identifier — a `string` value included in the `locationType` attribute). In the `location` attribute, a payload can be found that contains the geospatial data formatted according to that identifier. This approach enables: +The Location Protocol uses two complementary attributes to represent geospatial data: + +- **`locationType`**: Contains the Location Format Identifier — a standardized string that defines how the location data is structured (e.g., `coordinate-decimal+lon-lat`, `geojson-point`, `wkt-polygon`) +- **`location`**: Contains the actual geospatial data payload, formatted according to the identifier specified in `locationType` + +### How It Works + +The `locationType` attribute **is** the Location Format Identifier. It's not a container that includes the identifier — it is the identifier itself. The `location` attribute then contains the corresponding geospatial data formatted according to that identifier. + +**Example 1: Coordinate format** +```json +{ + "locationType": "coordinate-decimal+lon-lat", + "location": "-73.935242, 40.730610" +} +``` + +**Example 2: GeoJSON format** +```json +{ + "locationType": "geojson-point", + "location": "{\"type\":\"Point\",\"coordinates\":[-73.935242,40.730610]}" +} +``` + +**Example 3: WKT format** +```json +{ + "locationType": "wkt-polygon", + "location": "POLYGON((-122.4 37.8, -122.4 37.7, -122.3 37.7, -122.3 37.8, -122.4 37.8))" +} +``` + +This two-attribute approach enables: - **Extensibility:** New location formats can be added easily without impacting existing functionality. - **Interoperability:** A standardized interface allows different systems and proof strategies to work together seamlessly. @@ -21,7 +54,7 @@ In v0.1 of the Astral SDK, all location formats are eventually converted to GeoJ ## Location Format Identifier Naming Convention The **Location Format Identifier** is a string that uniquely defines how the location data is structured. It is designed to be: - + - **All lower case** - **Dot-separated**, with each segment conveying a specific piece of information - **Kebab-case** for multi-word segments @@ -79,7 +112,7 @@ Note that for v0.1, the only spatial reference system (`srs`) supported is WGS84 ### Additional Considerations -The Location Protocol is intended to be as interoperable with the rest of the geospatial web as possible. One way to think about location proofs is as a wrapper around a geospatial data artifact that includes digital signatures and evidence about its truthfulness or authenticity. +The Location Protocol is intended to be as interoperable with the rest of the geospatial web as possible. One way to think about location proofs is as a wrapper around a geospatial data artifact that includes digital signatures and evidence about its truthfulness or authenticity. In that sense, location proofs are spatio-temporal assets. We are considering how to integrate / harmonize the Location Proof Protocol with the STAC spec — weigh in [here](https://github.com/DecentralizedGeo/location-proofs/issues/2). From c9b6bcf6b766b8960a04ff63fad6e5ee51a07a54 Mon Sep 17 00:00:00 2001 From: John X Date: Tue, 16 Dec 2025 13:02:32 +0000 Subject: [PATCH 2/5] docs: Clarify distinction between location attestations and proofs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Location attestations are consistently-formatted verifiable location records that can optionally carry location proofs (cryptographic/cryptoeconomic evidence). Updated terminology to accurately reflect this distinction. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/location-protocol/location-types.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/location-protocol/location-types.md b/docs/location-protocol/location-types.md index 7fd3ce6..4b91390 100644 --- a/docs/location-protocol/location-types.md +++ b/docs/location-protocol/location-types.md @@ -112,9 +112,9 @@ Note that for v0.1, the only spatial reference system (`srs`) supported is WGS84 ### Additional Considerations -The Location Protocol is intended to be as interoperable with the rest of the geospatial web as possible. One way to think about location proofs is as a wrapper around a geospatial data artifact that includes digital signatures and evidence about its truthfulness or authenticity. +The Location Protocol is intended to be as interoperable with the rest of the geospatial web as possible. Location attestations are consistently-formatted verifiable location records that wrap geospatial data artifacts with digital signatures and metadata. They can optionally carry location proofs — cryptographic or cryptoeconomic evidence that corroborates the claims being made by the attestation. -In that sense, location proofs are spatio-temporal assets. We are considering how to integrate / harmonize the Location Proof Protocol with the STAC spec — weigh in [here](https://github.com/DecentralizedGeo/location-proofs/issues/2). +In that sense, location attestations are spatio-temporal assets. We are considering how to integrate / harmonize the Location Attestation Protocol with the STAC spec — weigh in [here](https://github.com/DecentralizedGeo/location-proofs/issues/2). ## Conclusion From 093362018529eefb41c563f5468103b929115078 Mon Sep 17 00:00:00 2001 From: John X Date: Tue, 16 Dec 2025 13:18:29 +0000 Subject: [PATCH 3/5] fix: Update GitHub links to point to correct docs repository MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changed GitHub links in navbar and footer from AstralProtocol/astralprotocol to AstralProtocol/docs to correctly reference the documentation repository. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docusaurus.config.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 84375aa..db079d9 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -75,7 +75,7 @@ const config: Config = { }, // {to: '/blog', label: 'Blog', position: 'left'}, { - href: 'https://github.com/AstralProtocol/astralprotocol', + href: 'https://github.com/AstralProtocol/docs', label: 'GitHub', position: 'right', }, @@ -119,7 +119,7 @@ const config: Config = { // }, { label: 'GitHub', - href: 'https://github.com/AstralProtocol/astralprotocol', + href: 'https://github.com/AstralProtocol/docs', }, ], }, From be650f58dd9d4fd3b9e66148d1789cac2892893c Mon Sep 17 00:00:00 2001 From: John X Date: Tue, 16 Dec 2025 13:24:31 +0000 Subject: [PATCH 4/5] docs: Add rationale for locationType and clarify location payload options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added comprehensive explanation of why locationType is included and clarified that the location payload can be either direct data or a pointer: - Clarified that location can contain actual data OR pointers (CID, DID, URL) - Added "Why Include locationType?" section explaining: - Efficiency: Avoids blind downloads of large files - Clarity: Resolves ambiguities like coordinate ordering - Interoperability: Enables system coordination without inspecting payloads - Added Example 4 showing pointer usage with IPFS CID for raster data - Updated existing examples to distinguish "Direct data" vs "Pointer" patterns - Noted that verifiable storage (like IPFS) is recommended but not required 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/location-protocol/location-types.md | 34 ++++++++++++++++++++---- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/docs/location-protocol/location-types.md b/docs/location-protocol/location-types.md index 4b91390..6984744 100644 --- a/docs/location-protocol/location-types.md +++ b/docs/location-protocol/location-types.md @@ -13,13 +13,29 @@ The Location Format Extensions Library is a core component of Astral's Location The Location Protocol uses two complementary attributes to represent geospatial data: - **`locationType`**: Contains the Location Format Identifier — a standardized string that defines how the location data is structured (e.g., `coordinate-decimal+lon-lat`, `geojson-point`, `wkt-polygon`) -- **`location`**: Contains the actual geospatial data payload, formatted according to the identifier specified in `locationType` +- **`location`**: Contains either the actual geospatial data or a pointer to it (such as a CID, DID, or URL), formatted according to the identifier specified in `locationType` ### How It Works -The `locationType` attribute **is** the Location Format Identifier. It's not a container that includes the identifier — it is the identifier itself. The `location` attribute then contains the corresponding geospatial data formatted according to that identifier. +The `locationType` attribute **is** the Location Format Identifier. It's not a container that includes the identifier — it is the identifier itself. The `location` attribute then contains the corresponding geospatial data (or a pointer to it) formatted according to that identifier. -**Example 1: Coordinate format** +The `location` payload can be: +- **Direct data**: The actual geospatial data embedded in the attestation (e.g., coordinate pairs, GeoJSON strings, WKT strings) +- **Pointer/reference**: A link to external data storage (e.g., IPFS CID, DID, or URL pointing to larger files) + +While we recommend using verifiable storage systems like IPFS for data integrity, regular URLs are also supported. + +### Why Include locationType? + +The `locationType` attribute serves several important purposes: + +1. **Efficiency**: Location attestations often point to large files. Knowing the data type upfront allows systems to make informed decisions about whether to download and parse a file, rather than fetching it blindly just to discover its geometry types. + +2. **Clarity**: It resolves ambiguities that are common in geospatial data, such as coordinate ordering (lon-lat vs lat-lon), which can otherwise lead to errors where locations appear in the wrong place. + +3. **Interoperability**: It provides a standardized interface that allows different systems and proof strategies to work together seamlessly without needing to inspect the data payload first. + +**Example 1: Direct data - Coordinate format** ```json { "locationType": "coordinate-decimal+lon-lat", @@ -27,7 +43,7 @@ The `locationType` attribute **is** the Location Format Identifier. It's not a c } ``` -**Example 2: GeoJSON format** +**Example 2: Direct data - GeoJSON format** ```json { "locationType": "geojson-point", @@ -35,7 +51,7 @@ The `locationType` attribute **is** the Location Format Identifier. It's not a c } ``` -**Example 3: WKT format** +**Example 3: Direct data - WKT format** ```json { "locationType": "wkt-polygon", @@ -43,6 +59,14 @@ The `locationType` attribute **is** the Location Format Identifier. It's not a c } ``` +**Example 4: Pointer - GeoTIFF via IPFS CID** +```json +{ + "locationType": "raster-geotiff", + "location": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi" +} +``` + This two-attribute approach enables: - **Extensibility:** New location formats can be added easily without impacting existing functionality. From 04031160317329613573204586cf1f9733dfb4cf Mon Sep 17 00:00:00 2001 From: John R Hoopes <41551283+johnx25bd@users.noreply.github.com> Date: Tue, 16 Dec 2025 13:26:31 +0000 Subject: [PATCH 5/5] Update location-types.md --- docs/location-protocol/location-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/location-protocol/location-types.md b/docs/location-protocol/location-types.md index 6984744..68cc502 100644 --- a/docs/location-protocol/location-types.md +++ b/docs/location-protocol/location-types.md @@ -138,7 +138,7 @@ Note that for v0.1, the only spatial reference system (`srs`) supported is WGS84 The Location Protocol is intended to be as interoperable with the rest of the geospatial web as possible. Location attestations are consistently-formatted verifiable location records that wrap geospatial data artifacts with digital signatures and metadata. They can optionally carry location proofs — cryptographic or cryptoeconomic evidence that corroborates the claims being made by the attestation. -In that sense, location attestations are spatio-temporal assets. We are considering how to integrate / harmonize the Location Attestation Protocol with the STAC spec — weigh in [here](https://github.com/DecentralizedGeo/location-proofs/issues/2). +In that sense, location attestations are spatio-temporal assets. We are considering how to integrate / harmonize the Location Protocol with the STAC spec — weigh in [here](https://github.com/DecentralizedGeo/location-proofs/issues/2). ## Conclusion