curie

README

curie

The library defines identity types curie ("Compact URI") as defined by the W3C and urn as defined by RFC8141. These datatype supports type safe identity within domain driven design.

Inspiration

Linked-Data are used widely by Semantic Web to publish structured data so that it can be interlinked by applications. Internationalized Resource Identifiers (IRIs) are key elements to cross-link data structure and establish global references (pointers) to data elements. These IRIs may be written as relative, absolute or compact IRIs. The curie type is just a formal definition of compact IRI (superset of XML QNames, with the modification that the format of the strings after the colon is looser).

Another challenge solved by curie is a formal mechanism to permit the use of the concept of scoping, where identities are created within a unique scope, and that scope's collection is managed by the group that defines it. All-in-all CURIEs expand to any IRI.

urn is an alternative for curie following same principles.

Getting started

The latest version of the library is available at main branch of this repository. All development, including new features and bug fixes, take place on the main branch using forking and pull requests as described in contribution guidelines. The stable version is available via Golang modules.

import "github.com/fogfish/curie/v2"

//
// creates compacts URI to wiki article about CURIE data type
compact := curie.New("wikipedia", "CURIE")

//
// expands compact URI to absolute one
//   ⟿ http://en.wikipedia.org/wiki/CURIE
prefixes := curie.Prefixes{
  "wikipedia": "http://en.wikipedia.org/wiki/",
}
url := curie.URI(prefixes, compact)

The type specification is available at go doc.

CURIE format

Compact URI is superset of XML QNames, with the modification that the format of the strings after the colon is looser. It is comprised of two components: a prefix and a reference, separated by :. Omit prefix to declare a relative IRI; omit suffix to declare namespace only. See W3C CURIE Syntax 1.0

safe_curie  :=   '[' curie ']'
curie       :=   [ [ prefix ] ':' ] reference
prefix      :=   NCName
reference   :=   irelative-ref (as defined in IRI, RFC 3987)

CURIE "algebra"

The type defines a simple algebra for manipulating instances of compact URI:

// zero: empty compact URI
z := curie.Empty

// transform: string ⟼ CURIE
a := curie.New("wiki", "CURIE")

// unary decompose: CURIE ⟼ string
curie.Schema(a)
curie.Reference(b)

// binary compose: CURIE × String ⟼ CURIE
curie.Join(a, "#Example")

// binary compose: CURIE × Int ⟼ CURIE
curie.Disjoin(a, 1)

URI compatibility

The datatype is compatible with traditional URIs

// any absolute URIs are parsable to CURIE
compact := curie.New("https://example.com/a/b/c")

// cast to string, it is an equivalent to input
//   ⟿ https://example.com/a/b/c
string(compact)

//
// expands compact URI to absolute one
//   ⟿ https://example.com/a/b/c
url, err := curie.URI("https://example.com/a/b/c")

Linked-data

Cross-linking of structured data is an essential part of type safe domain driven design. The library helps developers to model relations between data instances using familiar data type:

type Person struct {
  ID      curie.IRI
  Social  *curie.IRI
  Father  *curie.IRI
  Mother  *curie.IRI
  Friends []curie.IRI
}

This example uses CURIE data type. ID is a primary key, all other IRI is a "pointer" to linked-data.

URN

URN is equivalent presentation or CURIE.

import "github.com/fogfish/curie/v2/urn"

// zero: empty URN
z := urn.Empty

//
// creates URN to wiki article about CURIE data type
a := urn.New("wikipedia", "CURIE")

// unary decompose: CURIE ⟼ string
curie.Schema(a)
curie.Reference(a)

// binary compose: CURIE × String ⟼ CURIE
curie.Join(a, "example")

// binary compose: CURIE × Int ⟼ CURIE
curie.Disjoin(a, 1)

How To Contribute

The library is MIT licensed and accepts contributions via GitHub pull requests:

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

The build and testing process requires Go version 1.13 or later.

build and test library.

git clone https://github.com/fogfish/curie
cd curie
go test

commit message

The commit message helps us to write a good release note, speed-up review process. The message should address two question what changed and why. The project follows the template defined by chapter Contributing to a Project of Git book.

bugs

If you experience any issues with the library, please let us know via GitHub issues. We appreciate detailed and accurate reports that help us to identity and replicate the issue.

License

Documentation

Overview

Package curie implements the type for compact URI. It defines a generic syntax for expressing URIs by abbreviated literal as defined by the W3C. https://www.w3.org/TR/2010/NOTE-curie-20101216/

Package curie The type `curie` ("Compact URI") defines a generic syntax for expressing URIs by abbreviated literal as defined by the W3C. https://www.w3.org/TR/2010/NOTE-curie-20101216/.

The type supports type safe domain driven design using aspects of hierarchical linked-data.

Inspiration

Linked-Data are used widely by Semantic Web to publish structured data so that it can be interlinked by applications. Internationalized Resource Identifiers (IRIs) are key elements to cross-link data structure and establish references (pointers) to data elements. These IRIs may be written as relative, absolute or compact IRIs. The `curie` type is just a formal definition of compact IRI (superset of XML QNames). Another challenge solved by `curie` is a formal mechanism to permit the use of hierarchical extensible name collections and its serialization. All-in-all CURIEs expand to any IRI.

CURIE format

Compact URI is superset of XML QNames. It is comprised of two components: a prefix and a suffix, separated by `:`. Omit prefix to declare a relative URI; omit suffix to declare namespace only; omit both components to declare empty URI. See W3C CURIE Syntax 1.0 https://www.w3.org/TR/2010/NOTE-curie-20101216/

safe_curie  :=   '[' curie ']'
curie       :=   [ [ prefix ] ':' ] reference
prefix      :=   NCName
reference   :=   irelative-ref (as defined in IRI)

CURIE algebra

The type defines a simple algebra for manipulating instances of compact URI

↣ zero: empty compact URI

↣ transform: string ⟼ CURIE

↣ binary compose: CURIE × CURIE ⟼ CURIE

↣ unary decompose: CURIE ⟼ CURIE

↣ rank: |CURIE| ⟼ Int

↣ binary ordering: CURIE ≼ CURIE ⟼ bool

Linked data

Cross-linking of structured data is an essential part of type safe domain driven design. The library helps developers to model relations between data instances using familiar data type:

type Person struct {
  curie.ID
  Father  *curie.IRI
  Mother  *curie.IRI
  Friends []curie.IRI
}

`curie.ID` and `curie.IRI` are sibling, equivalent CURIE data type. `ID` is only used as primary key, `IRI` is a "pointer" to linked-data.

CURIE type is core type to organize hierarchies. An application declares `A ⟼ B` hierarchical relation using path at suffix. For example, the root is `curie.New("some:a")`, 2nd rank node `curie.New("some:a/b")` and so on `curie.New("some:a/b/c/e/f")`.

Index

• Constants
• func Decode(uri string) string
• func IsEmpty(iri IRI) bool
• func Reference(iri IRI) string
• func Schema(iri IRI) string
• func Split(iri IRI) (string, string)
• func URI(prefixes Prefixes, iri IRI) string
• func URL(prefixes Prefixes, iri IRI) (*url.URL, error)
• type IRI
  • func Disjoin(iri IRI, n int) IRI
  • func FromURI(prefixes Prefixes, uri string) IRI
  • func Join(iri IRI, segments ...string) IRI
  • func New(schema, ref string, args ...interface{}) IRI
  • func (iri IRI) Disjoin(n int) IRI
  • func (iri IRI) IsEmpty() bool
  • func (iri IRI) Join(segments ...string) IRI
  • func (iri IRI) MarshalJSON() ([]byte, error)
  • func (iri IRI) Reference() string
  • func (iri IRI) Safe() string
  • func (iri IRI) Schema() string
  • func (iri IRI) Split() (string, string)
  • func (iri *IRI) UnmarshalJSON(b []byte) error
• type Namespaces
  • func (ns Namespaces) Create(uri string) IRI
  • func (ns Namespaces) Lookup(prefix string) (string, bool)
• type Prefixes

Constants

const Empty = IRI("")

Empty IRI

Functions

func Decode

func Decode(uri string) string

Decode converts URIs to IRIs as defined by RFC 3987 https://www.rfc-editor.org/rfc/rfc3987#section-3.2

func IsEmpty

func IsEmpty(iri IRI) bool

IsEmpty is an alias to len(iri) == 0

func Reference

func Reference(iri IRI) string

Return URN Reference

func Schema

func Schema(iri IRI) string

Return CURIE Schema (prefix)

func Split

func Split(iri IRI) (string, string)

Split CURIE

a: ⟼ [ a ]
b ⟼ [ , b ]
a:b ⟼ [a, b]
a:b/c/d ⟼ [a, b/c/d ]

func URI

func URI(prefixes Prefixes, iri IRI) string

URI converts CURIE to fully qualified URL

wikipedia:CURIE ⟼ http://en.wikipedia.org/wiki/CURIE

func URL

func URL(prefixes Prefixes, iri IRI) (*url.URL, error)

URL converts CURIE to fully qualified url.URL type

wikipedia:CURIE ⟼ http://en.wikipedia.org/wiki/CURIE

Types

type IRI

type IRI string

IRI is compact URI, defined as superset of XML QNames, with the modification that the format of the strings after the colon is looser.

safe_curie := '[' curie ']' curie := [ [ prefix ] ':' ] reference prefix := NCName reference := irelative-ref (as defined in IRI, RFC 3987)

func Disjoin

func Disjoin(iri IRI, n int) IRI

Disjoin decomposes CURIE.

func FromURI

func FromURI(prefixes Prefixes, uri string) IRI

URI converts fully qualified URL to CURIE

http://en.wikipedia.org/wiki/CURIE ⟼ wikipedia:CURIE

func Join

func Join(iri IRI, segments ...string) IRI

Join composes segments into new descendant URN.

a:b × [c, d, e] ⟼ a:b/c/d/e

func New

func New(schema, ref string, args ...interface{}) IRI

New transform category of strings to IRI. It expects UTF-8 string according to RFC 3987.

func (IRI) Disjoin

func (iri IRI) Disjoin(n int) IRI

Disjoin decomposes CURIE.

func (IRI) IsEmpty

func (iri IRI) IsEmpty() bool

IsEmpty is an alias to len(iri) == 0

func (IRI) Join

func (iri IRI) Join(segments ...string) IRI

Join composes segments into new descendant CURIE.

func (IRI) MarshalJSON

func (iri IRI) MarshalJSON() ([]byte, error)

MarshalJSON `IRI ⟼ "[prefix:suffix]"`

func (IRI) Reference

func (iri IRI) Reference() string

Return CURIE Reference

func (IRI) Safe

func (iri IRI) Safe() string

Safe transforms CURIE to safe string

func (IRI) Schema

func (iri IRI) Schema() string

Return CURIE Schema (prefix)

func (IRI) Split

func (iri IRI) Split() (string, string)

Split URN into NID and NSS

func (*IRI) UnmarshalJSON

func (iri *IRI) UnmarshalJSON(b []byte) error

UnmarshalJSON `"[prefix:suffix]" ⟼ IRI`

type Namespaces

type Namespaces map[string]string

Namespaces is constant in-memory collection of prefixes defined by the application

func (Namespaces) Create

func (ns Namespaces) Create(uri string) IRI

Create new URI using prefix table

func (Namespaces) Lookup

func (ns Namespaces) Lookup(prefix string) (string, bool)

Lookup prefix in the map

type Prefixes

type Prefixes interface {
	Create(string) IRI
	Lookup(string) (string, bool)
}

Prefixes is a collection of prefixes defined by the application