curie

README

curie

The type curie ("Compact URI") defines a generic syntax for expressing URIs by abbreviated literal as defined by the W3C. This 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.

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"

//
// 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.New("")

// transform: string ⟼ CURIE
a := curie.New(/* ... */)
b := curie.New(/* ... */)

// rank: |CURIE| ⟼ EMPTY, PREFIX, REFERENCE
curie.Rank(a)

// unary decompose: CURIE ⟼ string
curie.Prefix(c)
curie.Reference(c)

// binary ordering: CURIE ≼ CURIE ⟼ bool 
curie.Eq(a, b)
curie.Lt(a, b)

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

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.

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 Eq(a, b IRI) bool
• func IsEmpty(iri IRI) bool
• func Lt(a, b IRI) bool
• func Prefix(iri IRI) string
• func Rank(iri IRI) int
• func Reference(iri IRI) string
• func Seq(iri IRI) (string, string)
• func URI(prefixes Prefixes, iri IRI) string
• func URL(prefixes Prefixes, iri IRI) (*url.URL, error)
• type IRI
  • func FromURI(prefixes Prefixes, uri string) IRI
  • func Join(iri IRI, segments ...string) IRI
  • func New(iri string, args ...interface{}) IRI
  • func (iri IRI) MarshalJSON() ([]byte, error)
  • func (iri IRI) Safe() 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 = iota
	PREFIX
	REFERENCE
)

Built-in CURIE ranks

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 Eq

func Eq(a, b IRI) bool

Eq compares two CURIEs, return true if they are equal.

func IsEmpty

func IsEmpty(iri IRI) bool

IsEmpty is an alias to curie.Rank(iri) == 0

func Lt

func Lt(a, b IRI) bool

Lt compares two CURIEs, return true if left element is less than supplied one.

func Prefix

func Prefix(iri IRI) string

Prefix decomposes CURIE and return its prefix CURIE as string value.

func Rank

func Rank(iri IRI) int

Rank of CURIE, number of elements Rank is an alias of len(curie.Seq(iri))

func Reference

func Reference(iri IRI) string

Reference decomposes CURIE and return its reference as string value.

func Seq

func Seq(iri IRI) (string, string)

Seq Returns CURIE segments

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 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 CURIE.

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

func New

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

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

func (IRI) MarshalJSON

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

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

func (IRI) Safe

func (iri IRI) Safe() string

Safe transforms CURIE to safe string

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