did

README

did

did is a Go package that provides tools to work with Decentralized Identifiers (DIDs).

This repository is a fork of ockam-network/did.

Install

go get github.com/nuts-foundation/did-ockam

Example

package main

import (
	"fmt"
	"log"

	"github.com/nuts-foundation/did-ockam"
)

func main() {
	d, err := did.Parse("did:example:q7ckgxeq1lxmra0r")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%#v", d)
}

The above example parses the input string according to the rules defined in the DID Grammar and prints the following value of DID type.

&did.DID{
	Method:"example",
	ID:"q7ckgxeq1lxmra0r",
	IDStrings:[]string{"q7ckgxeq1lxmra0r"},
	Path:"",
	PathSegments:[]string(nil),
	Query:"",
	Fragment:""
}

The input string may also be a DID Reference with a DID Path:

d, err := did.Parse("did:example:q7ckgxeq1lxmra0r/abc/pqr")

which would result in:

&did.DID{
	Method:"example",
	ID:"q7ckgxeq1lxmra0r",
	IDStrings:[]string{"q7ckgxeq1lxmra0r"},
	Path:"abc/pqr",
	PathSegments:[]string{"abc", "pqr"},
	Query:"",
	Fragment:""
}

or a DID Reference with a DID Path and a DID Query:

d, err := did.Parse("did:example:q7ckgxeq1lxmra0r/abc/pqr?xyz")
fmt.Println(d.Query)
// Output: xyz

or a DID Reference with a DID Fragment:

d, err := did.Parse("did:example:q7ckgxeq1lxmra0r#keys-1")
fmt.Println(d.Fragment)
// Output: keys-1

This package also implements the Stringer interface for the DID type. It is easy to convert DID type structures into valid DID strings:

d := &did.DID{Method: "example", ID: "q7ckgxeq1lxmra0r"}
fmt.Println(d.String())
// Output: did:example:q7ckgxeq1lxmra0r

or with a refence with a fragment:

d := &did.DID{Method: "example", ID: "q7ckgxeq1lxmra0r", Fragment: "keys-1"}
fmt.Println(d.String())
// Output: did:example:q7ckgxeq1lxmra0r#keys-1

For more documentation and examples, please see godoc.

Build

To compile the code in this repository, run:

go build

Test

This repository includes a comprehensive suite of tests that check for various edge cases within the DID Grammar.

To run the tests, run:

go test -v -cover

Benchmark

We haven't spent any time tuning the performance of the parser, however this repository includes some benchmarks that compare the speed of did.Parse against Go's url.Parse with inputs of similar length, this is intended as a sanity check to ensure that did.Parse is at least comparable in performance to url.Parse

go test -bench=.

did.Parse included in this package:

BenchmarkParse-8                  	 5000000	       365 ns/op
BenchmarkParseWithPath-8          	 3000000	       500 ns/op
BenchmarkParseWithQuery-8         	 3000000	       558 ns/op
BenchmarkParseWithFragment-8      	 3000000	       552 ns/op

Go's url.Parse:

BenchmarkUrlParse-8               	 3000000	       475 ns/op
BenchmarkUrlParseWithPath-8       	 3000000	       505 ns/op
BenchmarkUrlParseWithQuery-8      	 5000000	       294 ns/op
BenchmarkUrlParseWithFragment-8   	 5000000	       369 ns/op

Contributing

This package is early in its development and we welcome all contributions from the DID community. Please open issues and send pull requests.

We follow the conventions specified in Conventional Commits for our commit messages.

License

This package is licensed under Apache License 2.0.

Documentation

Overview

Package did is a set of tools to work with Decentralized Identifiers (DIDs) as described in the DID spec https://w3c.github.io/did-core/

Index

• type DID
  • func Parse(input string) (*DID, error)
  • func (d *DID) IsURL() bool
  • func (d *DID) String() string
• type Param
  • func (p *Param) String() string

Examples

• DID.IsURL (NoPathOrFragment)
• DID.IsURL (WithFragment)
• DID.IsURL (WithPath)
• DID.String
• DID.String (WithFragment)
• DID.String (WithPath)
• DID.String (WithPathSegments)
• DID.String (WithQuery)
• Parse
• Parse (WithFragment)
• Parse (WithPath)
• Parse (WithQuery)

Types

type DID

type DID struct {
	// DID Method
	// https://w3c.github.io/did-core/#method-specific-syntax
	Method string

	// The method-specific-id component of a DID
	// method-specific-id = *idchar *( ":" *idchar )
	ID string

	// method-specific-id may be composed of multiple `:` separated idstrings
	IDStrings []string

	// DID URL
	// did-url = did *( ";" param ) path-abempty [ "?" query ] [ "#" fragment ]
	// did-url may contain multiple params, a path, query, and fragment
	Params []Param

	// DID Path, the portion of a DID reference that follows the first forward slash character.
	// https://w3c.github.io/did-core/#path
	Path string

	// Path may be composed of multiple `/` separated segments
	// path-abempty  = *( "/" segment )
	PathSegments []string

	// DID Query
	// https://w3c.github.io/did-core/#query
	// query = *( pchar / "/" / "?" )
	Query string

	// DID Fragment, the portion of a DID reference that follows the first hash sign character ("#")
	// https://w3c.github.io/did-core/#fragment
	Fragment string
}

A DID represents a parsed DID or a DID URL

func Parse

func Parse(input string) (*DID, error)

Parse parses the input string into a DID structure.

Example

d, err := did.Parse("did:example:q7ckgxeq1lxmra0r")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Method - %s, ID - %s", d.Method, d.ID)

Output:

Method - example, ID - q7ckgxeq1lxmra0r

Example (WithFragment)

d, err := did.Parse("did:example:q7ckgxeq1lxmra0r#keys-1")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Method - %s, ID - %s, Fragment - %s", d.Method, d.ID, d.Fragment)

Output:

Method - example, ID - q7ckgxeq1lxmra0r, Fragment - keys-1

Example (WithPath)

d, err := did.Parse("did:example:q7ckgxeq1lxmra0r/a/b")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Method - %s, ID - %s, Path - %s", d.Method, d.ID, d.Path)

Output:

Method - example, ID - q7ckgxeq1lxmra0r, Path - a/b

Example (WithQuery)

d, err := did.Parse("did:example:q7ckgxeq1lxmra0r?dskjsdjj")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Method - %s, ID - %s, Query - %s", d.Method, d.ID, d.Query)

Output:

Method - example, ID - q7ckgxeq1lxmra0r, Query - dskjsdjj

func (*DID) IsURL

func (d *DID) IsURL() bool

IsURL returns true if a DID has a Path, a Query or a Fragment https://w3c-ccg.github.io/did-spec/#dfn-did-reference

Example (NoPathOrFragment)

d := &did.DID{Method: "example", ID: "q7ckgxeq1lxmra0r"}
fmt.Println(d.IsURL())

Output:

false

Example (WithFragment)

d := &did.DID{Method: "example", ID: "q7ckgxeq1lxmra0r", Fragment: "keys-1"}
fmt.Println(d.IsURL())

Output:

true

Example (WithPath)

d := &did.DID{Method: "example", ID: "q7ckgxeq1lxmra0r", Path: "a/b"}
fmt.Println(d.IsURL())

Output:

true

func (*DID) String

func (d *DID) String() string

String encodes a DID struct into a valid DID string. nolint: gocyclo

Example

d := &did.DID{Method: "example", ID: "q7ckgxeq1lxmra0r"}
fmt.Println(d.String())

Output:

did:example:q7ckgxeq1lxmra0r

Example (WithFragment)

d := &did.DID{Method: "example", ID: "q7ckgxeq1lxmra0r", Fragment: "keys-1"}
fmt.Println(d.String())

Output:

did:example:q7ckgxeq1lxmra0r#keys-1

Example (WithPath)

d := &did.DID{Method: "example", ID: "q7ckgxeq1lxmra0r", Path: "a/b"}
fmt.Println(d.String())

Output:

did:example:q7ckgxeq1lxmra0r/a/b

Example (WithPathSegments)

d := &did.DID{Method: "example", ID: "q7ckgxeq1lxmra0r", PathSegments: []string{"a", "b"}}
fmt.Println(d.String())

Output:

did:example:q7ckgxeq1lxmra0r/a/b

Example (WithQuery)

d := &did.DID{Method: "example", ID: "q7ckgxeq1lxmra0r", Query: "abc"}
fmt.Println(d.String())

Output:

did:example:q7ckgxeq1lxmra0r?abc

type Param

type Param struct {
	// param-name = 1*param-char
	// Name may include a method name and param name separated by a colon
	Name string
	// param-value = *param-char
	Value string
}

Param represents a parsed DID param, which contains a name and value. A generic param is defined as a param name and value separated by a colon. generic-param-name:param-value A param may also be method specific, which requires the method name to prefix the param name separated by a colon method-name:param-name. param = param-name [ "=" param-value ] https://w3c.github.io/did-core/#generic-did-parameter-names https://w3c.github.io/did-core/#method-specific-did-parameter-names

func (*Param) String

func (p *Param) String() string

String encodes a Param struct into a valid Param string. Name is required by the grammar. Value is optional