We are early in developing the GeoDID spec. For now, we are focused on storing
geojsonvector spatial data structures, andgeotiffraster data. The GeoDID specification is designed to be flexible and identify any spatial dataset in any format - even ones that haven't been developed yet.
Geographic decentralized identifiers, or GeoDIDs, are DIDs designed to identify spatial data assets and to be compatible with any distributed ledger or network. Spatial data has unique properties that require special treatment - the GeoDID Method Specification defines an approach in creating, reading, updating and deleting identifiers for these assets using DIDs. In creating a GeoDID, data controllers permissionlessly create irrevocable, cryptographically-verifiable identities for spatial data assets that can be useful in decentralized applications
The objective of the GeoDID is to encourage contribution to the DID specification and Linked Data Signatures to identify and ensure trustable spatial data. This will allow rapid development of extensions to these without requiring the usage of trustless infrastructures such as blockchains or other distributed systems.
The GeoDID is inspired by the SpatioTemporal Asset Catalog (STAC) specification and utilizes a similar linked data structure. The structure alleviates a handful of problems associated with traversing large datasets, and allows for ease of use for the end user. Spatial data assets are identified in the service endpoints of the GeoDID document. These service endpoints can be classed as either Collections or Items. Each "Collection" contains a number of child Collections or Items; and each "Item" will contain several service endpoints that dereference to geospatial data assets. This hierarchy of encapsulating linked data within the GeoDIDs will allow for user's to find or create the data/datasets that they need easily.
This data model is based on the STAC specification, which was designed for cataloging spatiotemporal data assets including satellite images, UAV imagery, LIDAR scans etc.
For the alpha version of the specification we did not consider the OGC API - Features specification, which is better optimized for representing vector spatial data. Future versions of the GeoDID Method Specification should evolve so that vector and raster data assets are identified according to the most appropriate specification - work to be done.
The namestring that shall identify this DID method is: geo.
A DID that uses this method MUST begin with the following prefix: did:geo. Per the DID specification, this string MUST be in lowercase. The remainder of the DID after the prefix, is specified below.
did:geo:<geo-specific-identifier>
All GeoDIDs are base58 encoded using the Bitcoin / IPFS alphabets of a 16-byte UUID.
geo-did = "did:geo:" + geo-specific-identifier
geo-specific-identifier = new CID(0, 'dag-pb', hash, 'base58btc')
hash = multihash(byte, sha2-256)
byte = new TextEncoder().encode(ethereum address + UNIX Time)
For the draft version of this specification, <geo-specific-identifier> referenced above is created by computing a sha2-256 multihash on the byte representation of the DID controller's ethereum address + Unix time: multihash(ethAddress + time, sha2-256). Then we create a new CID Block by encoding the multihash with a base58 encoding. This will return a cid that will act as the identifier for the GeoDID.
This <geo-specific-identifier> generation procedure achieves our design goals of enabling one Ethereum address to control multiple GeoDIDs. However, in future versions of the specification we intend to investigate the potential of encoding more information into the identifier, including a hash or checksum of the spatial data assets identified, similar to the Ocean Protocol DID Method.
We also could encode some segment of the identifier to indicate which blockchain the GeoDID is registered on, a possible approach to achieve our design goal of platform agnosticism.
Fundamentally, the GeoDID identifier should not change even if GeoDID Document contents are subsequently updated by the GeoDID controller.
The service array in the GeoDID will contain several references to other GeoDIDs and/or assets. The idea is that if the GeoDID is the root DID in the hierarchy, regardless of its type, then it has the base DID identifier. If the GeoDID is a sub-collection or sub-item then it is referenced via path, and if it is an asset within the sub-item's service array, then it is referenced via fragment.
Standalone or Root GeoDIDs using the Base DID Identifier:
did:geo:9H8WRbfd4K3kQ2NTxT6L2wTNyMj1ARCaVVsT5GJ87Jw2
Paths reference other GeoDID sub-Collections or sub-Items:
did:geo:9H8WRbfd4K3kQ2NTxT6L2wTNyMj1ARCaVVsT5GJ87Jw2/sub-collection-A/sub-item-1
Fragments reference assets within the GeoDID sub-Items:
did:geo:9H8WRbfd4K3kQ2NTxT6L2wTNyMj1ARCaVVsT5GJ87Jw2/sub-collection-A/sub-item-1#raster-image-1
did:geo:9H8WRbfd4K3kQ2NTxT6L2wTNyMj1ARCaVVsT5GJ87Jw2/sub-collection-A/sub-item-1#thumbnail
In future versions of the specification we hope to incorporate spatial, temporal and other query parameter capabilities in the GeoDID fragment, so we could retrieve matching features. By incorporating this querying, filtering and masking capability many advanced spatial decentralized applications would be enabled - though technical feasibility has not be assessed.
In order to create a GeoDID, a method specific identifier must be created, which will be used to build the document. After the method specific identifier is created, the user will need to select the type of Document they would like to create, Collection or Item.
ECDSA keypair. (for the alpha version of the specification - future versions may be agnostic to which digital signature algorithm is used).
Spatial data asset(s), or URI(s) resolving to spatial data asset(s), along with relevant metadata / attribution.
If GeoDID Collection, some information about the relationships between the spatial data assets being identified.
Create Method Specific Identifier described in (2), above.
User chooses which type of GeoDID they want to create (Collection or standalone Item).
If the user decides to create a standalone Item then they just upload the assets, did-metadata information, and item-metadata they want in the DID. The GeoDID will be built, pinned on IPFS, and anchored on the Ropsten Testnet.
If the user decides to create a Collection then the client will build a collection GeoDID and return the GeoDID ID. The GeoDID will be built, pinned on IPFS, and anchored on the Ropsten Testnet.
The user will save this GeoDID ID to append children sub-collections or sub-items as children.
If the user decides to add children to the sub-collection, they repeat step 4, and use the returned GeoDID ID + Collection path to append more leaf nodes.
If the user decides to add items to the collection, they repeat step 3, until they finish adding all items.
In the near future, we will also create automation features to create trees, by uploading folders with files in it. We hope this will kill two birds with one stone, so the user will only need to prepare the data once, and upload it in bulk.
In the alpha implementation of the specification a GeoDID document can be resolved by invoking the resolve(<GeoDID ID>) method at contract address <0x___TBD___> on Ethereum's Ropsten testnet. This contract method will first verify that the user has access to this GeoDID by checking to make sure that his address registered the GeoDID via the create method. The contract will store a mapping from the user's address to GeoDID IDs.
Once the user has been authenticated, the contract will trigger an event that the astral-protocol-core package will be listening for. From there the geo-did-resolver will handle the rest, and dereference to the proper GeoDID Document.
The GeoDID Document can then be parsed and analyzed by the client, or spatial data assets can be fetched from their respective service endpoints. Do note that sometimes data assets will be identified by CIDs and stored on the IPFS network, while other service endpoints may be HTTP URLs - appropriate resolution methods will be required.
Controller Address
Each identity always has a controller address. To check the read only contract function identityOwner(address identity) on the deployed version of the ERC1056 contract.
The identity controller will always have a publicKey with the id set as the DID with the fragment #key appended.
An entry is also added to the authentication array of the DID document with type Secp256k1SignatureAuthentication2018.
Service Endpoints are relevant in both GeoDID Controllers **<Collections?>**¸ and Items. It exists to list relevant relationships to and from itself. <?Each object in the> service array will contain a required link field and several that contain the GeoDID ID, its relationship to the DID ID, and a reference link if the controller needs to dereference it. The purpose of the link field is to enables browsers and crawlers to access the sets of Items, in an organized and straightforward way. These service endpoints can also contain references to assets that are related to a specific item.
The GeoDID Document identified by the CID can the be resolved using a browser with native IPFS support (ipfs://<CID>), or by resolving via a gateway, like ipfs.io/ipfs/<GeoDID Document CID>
The DID Document may be updated by invoking the update(<GeoDID ID>) method at contract address <0x_____> on the Ropsten testnet.
Once the address has been verified as the DID controller, an oracle function will be invoked and will trigger an off chain event to open the GeoDID Document for the user to update. When user is done updating, they can submit the update, which will compute the CID of the GeoDID Document and compare the block to the previous CID version.
If the CIDs differ, the client will append the timestamp of the update within the GeoDID Document, recalculate the finalized CID, and will append a new Record in the astral-core-package. The updated CID will be returned via the oracle, and appends to the end of the array of GeoDID Document CIDs, meaning users can fetchVersionHistory(<GeoDID fragment>) and retrieve all the CIDs of historical GeoDID documents.
A GeoDID Controller can revoke access to a GeoDID by invoking the deactivate(<GeoDID fragment>) method. This simply sets that GeoDID's GeoDIDActive record to false - it does not remove information from the smart contract about the historical versions of the GeoDID. It does, however, mean that future attempts to resolve that GeoDID will not succeed.
Once we develop it, we will store code at https://github.com/AstralProtocol as a reference implementation of this DID method.\
The Collection Specification of the GeoDID; includes the collection's fields for specification.
As of right now, the Collection extends the default GeoDID Specification without any added fields. It is up to the user to add what they deem necessary,. However, the collection must function as a DID that will reference other DID documents or URL links. The metadata added to it must reflect that.
The Core Specification of the GeoDID; includes default fields for specification.
There are two "types" of GeoDID Specifications under the Astral Protocol, that work together to enable structure between resources. At their core, they are both extensions of the DID and default GeoDID specification. However, they differ in their functionality and purpose, in order to enable a better user experience for all users.
The GeoDID Collection - A GeoDID Collection is a simple, flexible JSON file of service endpoints that provides a structure to organize and browse GeoDID Items. The collection is responsible for bundling a set of items or sub collections, by utilizing links to reference other child Collections or Items . The division of sub-collections is up to the implementor, but is generally done in order to make the end user's UX easier.
The GeoDID Item - A GeoDID Item is an extension of the Default GeoDID Structure. Unlike its counterpart, the GeoDID Item is responsible for identifying a particular resources and referencing relative assets, through the service endpoints. GeoDID Items can only act as the leaves of the tree and cannot link to other items or collections. It can only reference assets like raster imagery, videos, geojson and reference linked parent DID Documents.
id
string
REQUIRED The identifier for the DID Document. It can be the root DID ID or it can be a DID URL with a specific path or fragment. The id must be of the following format: did:<method>:<specific identifier>. The path(.../path), query(...?query), and fragment(...#fragment) are optional but will be used later as identifiers for the children collections and items.
authentication
[Authentication Object]
did_metadata
did_metadata Object
REQUIRED The did_metadata object contains relative metadata pertaining to the particular GeoDID. For example, timestamps for the CRUD operations, the type of GeoDID, descriptions, etc.
service
Service Object
REQUIRED The service object contains several sub fields used to reference metadata, other GeoDIDs, and/or assets.
The publicKey verification relationship is used to specify how the DID subject is expected to be authenticated, for purposes such as performing CRUD operations on the DID Document. However, the PublicKey Object is OPTIONAL by default as stated by the W3C working groups' DID specification.
id
string
The GeoDID ID + key fragment which will be used to reference the controllers public key.
type
string
The type of Verification method being used. (ex. Ed25519VerificationKey2018, Secp256k1VerificationKey2018)
controller
string
The GeoDID ID which will be used to reference the controllers.
ethereumAddress
string
The Ethereum address of the controller.
Note: Do not worry about this field as it will automatically be populated with the user's Ethereum address.
type
string
REQUIRED The type can either be a Collection or Item. ****
subtype
string
REQUIRED The subtype can either be a GeoJSON or Raster.
created
string
REQUIRED UPON CREATION The GeoDID package will automatically timestamp the GeoDID upon creation.
updated
string
REQUIRED UPON UPDATE The GeoDID package will automatically timestamp the GeoDID upon an update. If the GeoDID Document never updates then there will not be a
description
string
OPTIONAL A description describing the GeoDID Document. It can be anything but most likely the description will address the DID subject.
The Metadata Object array will contain an array of Metadata related to the assets or links within the GeoDID. (ex. List of Spatial Data Providers who provided the data, GeoJSON Feature)object list contains all the assets the GeoDID Item will need to reference.The Assets Object array will contain a list of references to assets relative to the GeoDID Item.
id
string
REQUIRED The DID URL that dereferences to the entity's metadata. [#metadata]
type
string
REQUIRED The type of metadata (ex. collection-metadata, item-metadata), or the type of the asset. (ex. GeoTIFF, geoJSON, JSON, CSV)
serviceEndpoint
string
REQUIRED The actual link in the format of an URL or CID. Relative and absolute links are both allowed.
This object list describes the one-to-many relationships with other GeoDIDs. These entities can be sub-collection or sub-item GeoDIDs. This object field will come in handy when a user needs to traverse or scrape a data collection.
As of right now, The Graph, is persisting the relationships between the different DID Documents and their respective CIDs. We still need to figure out how to properly update the links within the GeoDID in a scalable way. For large trees of GeoDID Collection, updates to the relations might take too long, so as a work around we are maintaining all the relationships on The Graph. And the GeoDID will only contain a reference to itself, the root Document, and its' parent.
id
string
REQUIRED The DID URL that dereferences to the entity's GeoDID Document. This field is required if you want to create a hierarchy of GeoDID Documents (ex. GeoDID collection is parent to GeoDID Items or Collections).
type
string
REQUIRED See chapter "Endpoint types" for more information.
rel
string
REQUIRED Relationship between the current document and the linked document. See chapter "Relation types" for more information.
OPTIONAL BY DEFAULT Authentication is a process (typically some type of protocol) by which an entity can prove it has a specific attribute or controls a specific secret using one or more . With , a common example would be proving control of the private key associated with a public key published in a .