The highest tagged major version is
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).
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.
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.
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
url, err := curie.URI("http://en.wikipedia.org/wiki/", compact)
The type specification is available at go doc.
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
safe_curie := '[' curie ']'
curie := [ [ scheme ] ':' ] reference
scheme := NCName
reference := irelative-ref (as defined in IRI)
reference := prefix [ # suffix ]
prefix := irelative-part
suffix := ifragment
Formally, CURIE is a triple: ⟨𝒔𝒉𝒆𝒎𝒆, 𝒑𝒓𝒆𝒇𝒊𝒙, 𝒔𝒖𝒇𝒇𝒊𝒙⟩
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| ⟼ Int
curie.Rank(a)
// binary compose: CURIE × CURIE ⟼ CURIE
curie.Heir(a, b)
// unary decompose: CURIE ⟼ CURIE
curie.Parent(c)
// unary decompose: CURIE ⟼ string
curie.Prefix(c)
curie.Suffix(c)
// binary ordering: CURIE ≼ CURIE ⟼ bool
curie.Eq(a, b)
curie.Lt(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")
// String is an identity function
// ⟿ https://example.com/a/b/c
compact.String()
//
// expands compact URI to absolute one
// ⟿ https://example.com/a/b/c
url, err := compact.URI("https://example.com/a/b/c")
Hierarchy
CURIE type is core type to organize hierarchies. An application declares A ⟼ B hierarchical relation using paths, prefixes and suffixes.
root := curie.New("some:a")
// construct 2nd rank curie using one of those functions
rank2 := curie.New("some:a#b")
rank2 := curie.Join(root, "b")
rank2 := curie.Heir(root, curie.New("b"))
//
// parent and prefix of rank2 node is root
// ⟿ some:a
curie.Parent(rank2)
curie.Prefix(rank2)
//
// suffix of rank2 node is
// ⟿ b
curie.Suffix(rank2)
//
// and so on
curie.New("some:a/b/c#e/f")
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.String
Father *curie.IRI
Mother *curie.IRI
Friends []curie.IRI
}
This example uses CURIE data type. ID is only used as primary key, IRI is a "pointer" to linked-data. curie.String is an alternative approach to defined IRI using safe notation.
How To Contribute
The library is MIT licensed and accepts contributions via GitHub pull requests:
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Added some feature') - Push to the branch (
git push origin my-new-feature) - 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 ¶
- func Eq(a, b IRI) bool
- func IsEmpty(iri IRI) bool
- func Lt(a, b IRI) bool
- func Path(iri IRI) string
- func Prefix(iri IRI) string
- func Rank(iri IRI) int
- func Scheme(iri IRI) string
- func Seq(iri IRI) []string
- func Suffix(iri IRI) string
- func URI(prefix string, iri IRI) (*url.URL, error)
- type IRI
- type String
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Lt ¶ added in v1.2.0
Lt compares two CURIEs, return true if left element is less than supplied one.
func Path ¶ added in v1.2.0
Path converts CURIE to relative file system path.
a: ⟼ a a:b/c ⟼ a/b/c a:b/c#d/e ⟼ a/b/c/d/e
func Rank ¶ added in v1.2.0
Rank of CURIE, number of segments Rank is an alias of len(curie.Seq(iri))
func Seq ¶ added in v1.2.0
Seq Returns CURIE segments
a: ⟼ [ a ] a:b/c ⟼ [a, b, c] a:b/c#d/e ⟼ [a, b, c, d, e]
Types ¶
type IRI ¶
type IRI struct {
// contains filtered or unexported fields
}
IRI is compact URI, defined as superset of XML QNames.
safe_curie := '[' curie ']' curie := [ [ scheme ] ':' ] reference scheme := NCName reference := irelative-ref (as defined in IRI) reference := prefix [ # suffix ] prefix := irelative-part suffix := ifragment
func Heir ¶ added in v1.2.0
Heir composes two CURIEs into new descendant CURIE.
a:b × c/d/e ⟼ a:b#c/d/e a:b × c:d/e ⟼ a:b#c/d/e
func Join ¶ added in v1.2.0
Join composes segments into new descendant CURIE.
a:b × [c, d, e] ⟼ a:b#c/d/e
func Split ¶ added in v1.2.0
Split IRI defining a new suffix rank, defining behavior of splitters such as Parent, Prefix Suffix. Every new IRI has suffix rank 1
a:b/c/d/e ⟼⁰ a:b/c/d/e # a:b/c/d/e ⟼¹ a:b/c/d # e a:b/c/d/e ⟼² a:b/c # d/e a:b/c/d/e ⟼³ a:b # c/d/e ... a:b/c/d/e ⟼ⁿ⁻² a:b # c/d/e a:b/c/d/e ⟼ⁿ⁻¹ a:b # c/d/e a:b/c/d/e ⟼ⁿ a:b # c/d/e
func (IRI) MarshalJSON ¶
MarshalJSON `IRI ⟼ "[prefix:suffix]"`
func (*IRI) UnmarshalJSON ¶
UnmarshalJSON `"[prefix:suffix]" ⟼ IRI`
Source Files