docs: Clarify locationType and location attribute relationship

docs/location-protocol/location-types.md

@@ -10,7 +10,64 @@ 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 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 (or a pointer to it) formatted according to that identifier.
+
+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",
+  "location": "-73.935242, 40.730610"
+}
+```
+
+**Example 2: Direct data - GeoJSON format**
+```json
+{
+  "locationType": "geojson-point",
+  "location": "{\"type\":\"Point\",\"coordinates\":[-73.935242,40.730610]}"
+}
+```
+
+**Example 3: Direct data - 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))"
+}
+```
+
+**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.
 - **Interoperability:** A standardized interface allows different systems and proof strategies to work together seamlessly.
@@ -21,7 +78,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,9 +136,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 Protocol with the STAC spec — weigh in [here](https://github.com/DecentralizedGeo/location-proofs/issues/2).
 
 ## Conclusion
 

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',
             },
           ],
         },