Root Index

[michaelsena]

cip: 12
title: Root Index
author: Michael Sena (@michaelsena), Joel Thorstensson (@oed)
status: Draft
category: Standards
type: RFC
created: 2020-05-22
requires: Tile Doctype (CIP-8), DocId Map (CIP-10)

Simple Summary

Root Index is a document that acts as the root directory for a DID's resources.

Abstract

In an identity-centric model of development, users carry their identifier and resources with them across various contexts. Applications then use with these resources to provide service to the user. However in order to access resources, applications need an easy way to find them.

Currently, there is no standard and decentralized way of associating various resources, such as keys, accounts, profiles, social graphs, data, settings, and more to a DID. Because of this, there is no single location or interface for applications to query when discovering or interacting with a DID's resources, which restricts the adoption and potential use cases for decentralized identities.

The Root Index is a document that acts as an extensible top-level root directory for a DID's resources. It does not store the resources itself, but rather stores an index of subdirectories which in turn store pointers to resources. By standardizing how resources are associated to a DID, the Root Index is the foundational component needed to enable identity-centric resource discoverability.

Root Index is the top-level directory of the Identity Index (IDX) (CIP-11), and is used to store links to subdirectories such as the Profiles Index (CIP-13), Keychains Index (CIP-15), Accounts Index (CIP-14), Connections Index (CIP-18), Collections Index (CIP-16), Services Index (CIP-17), Settings Index (CIP-24), and more.

Motivation

Complete Decentralized Identities: Decentralized identifiers (DIDs) are the foundational requirement for interoperable, platform-agnostic identities. However, in practice "identity" is much more than just an identifier. Identity is the complete set of keys, accounts, data, resources, and capabilities that are associated with a DID. Since DIDs only provide an identifier, they are alone insufficient as identity. The Root Index provides a standardized core structure for associating resources to a DID that is infinitely extensible.

Identity-Centric Resource Indexing, Discoverability, and Routing: In a user-centric model of application development, when a user logs-in to a site, the site needs to discover and access the many resources associated with that user's DID to provide them service. However, these resources are likely scattered across the web on servers, distributed networks, etc. By supplying the logical, top-level routing information to all of these resources, the Root Index makes resources discoverable to any application.

DID-agnostic Standards: Given the number of DID providers only continues to increase, standardization around resource mappings is paramount; failing to do this will result in each DID method implementing their own system for resource routing which would limit the interoperability and utility of DIDs. The Root Index is compatible with any DID.

Specification

The Root Index specification includes a doctype, schema, table, and tag.

Doctype

Root Index is a Tile Doctype (CIP-8).

Schema

The Root Index utilizes the DocId Map (CIP-10) schema, which simply stores a list of strings which map to Ceramic DocIds. A reference to this schema should be included in your Root Index document when it is created.

Table

Root Index Table contains the standard set of properties that may be contained in any given Root Index. New properties can be added to the table by following the steps below. Additional properties not found in this table may be stored in any Root Index, however they may be less interoperable since others may not know what they represent. Here are some common examples of properties stored in Root Index:

• profiles: a link to the Profiles Index (CIP-13), a subdirectory for a DID's profiles
• keychains: a link to the Keychains Index (CIP-15), a subdirectory for a DID's keychains
• accounts: a link to the Accounts Index (CIP-14), a subdirectory for a DID's linked accounts (i.e. crypto & Oauth)
• connections: a link to the Connections Index (CIP-18), a subdirectory for a DID's social connections (i.e. follows)
• collections: a link to the Collections Index (CIP-16), a subdirectory for a DID's data collections (i.e. app data)
• services: a link to the Services Index (CIP-17), a subdirectory for a DID's services (i.e. notifications or backup)
• settings: a link to the Settings Index (CIP-24), a subdirectory for a DID's global settings (i.e. internationalization)

How to add a new property to the Root Index Table

1. Choose a unique, descriptive property name.
2. Add a description for your property.
3. Submit a PR to the CIP repository updating the Root Index Table with your property.
4. Mention the authors of this CIP in the comments of your PR.

Tags

When creating a Root Index document, add RootIndex to the tags field.

Example

An example Root Index document.

"doctype": "tile"
"schema": "<insert canonical schema for DocId Map>"
"tags": ["RootIndex", "DocIdMap"],
"content": {
  "profiles": "ceramic://bafyljsdf1",
  "accounts": "ceramic://bafysdfoijwe2",
  "keychains": "ceramic://bafysdfoijwe3",
  "services": "ceramic://bafysdfoijwe4",
  "collections": "ceramic://bafysdfoijwe5",
  "connections": "ceramic://bafysdfoijwe6",
  "settings": "ceramic://bafysdfoijwe7"
}

Suggested Usage

DIDs: Root Index can be used with any DID. A link to the DocId of the Root Index should be stored in the DID document, ideally under an index property to make it discoverable by simply resolving the DID document. The 3ID DID (CIP-6) native to Ceramic provides an optional index property and is fully compatible with Root Index.

Content: It is recommended that the Root Index be used as a root directory which only stores links to subdirectories which contain links to categorical subsets of resources. This keeps the Root Index minimal and provides a logical structure for information. The properties profiles, accounts, keychains, etc found in the Root Index Table above are examples of documents that act as subdirectories. For more information on how directories should be constructed for a DID, see the Identity Index (IDX) (CIP-11).

Rationale

Extensibility & Flexibility: It is impossible to predict all of the types of resources that need to be associated with any particular DID. Therefore the Root Index was designed to be infinitely extensible to support the indexing any kind of resource category or type.

Decentralization & Trust: Resource routing information is mission-critical data that needs to be globally-available, censorship-resistant, and live permissionlessly in the public domain (not on any single server). Additionally this information should be owned by a DID and will need to be updated from time to time. These requirements make Ceramic the most appropriate platform for publishing this content.

Implementation

DocId Map Schema: Find the DocID Map schema here.

Root index Table: Find the table containing standard Root Index properties here.

Libraries: Not yet available.

Copyright

Copyright and related rights waived via CC0.

[oed]

Suggested schema:

{
  "$schema": "http://json-schema.org/draft-06/schema#",
  "$ref": "#/definitions/IdentityRouter",
  "definitions": {
    "IdentityRouter": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "pattern": "^ceramic:\/\/.+"
      },
      "title": "IdentityRouter"
    }
  }
}

[michaelsena]

@oed as discussed, updated this document to reflect the DocId Map schema, instead of the one you mentioned above. Also added the RootIndex tag. Mind checking the schemas and details above now? Thx! 🚀

[oed]

Looks good. I don't think we need the DocIdMap tag if schemas are also able to be indexed?

[oed]

Stale, closing.