README
¶
Type-safe Linked Data identities for Golang
Linked Data applications require careful handling of identifiers (IRIs, URNs) and relationships between entities. Manual string manipulation is error-prone and lacks compile-time guarantees. The gold library solves this by providing type-safe Linked Data identities that leverage Go's type system to prevent schema mismatches and ensure correct identifier usage at compile time.
go get github.com/fogfish/gold
Quick Start
package main
import (
"fmt"
"github.com/fogfish/gold"
)
// Define domain types
type User struct {
ID gold.IRI[User] `json:"id"`
}
type Blog struct {
ID gold.IRI[Blog] `json:"id"`
Creator gold.IRI[User] `json:"creator"`
}
func main() {
// Create type-safe IRIs - schema is derived from type
userID := gold.ToIRI[User]("alice") // "user:alice"
blogID := gold.ToIRI[Blog]("my-blog") // "blog:my-blog"
user := User{ID: userID}
blog := Blog{ID: blogID, Creator: userID}
// Compile-time safety: this would fail at compile time
// blog.Creator = blogID // ❌ Cannot assign blog ID to user field
}
Core Concepts
Type-Safe IRIs
IRIs are structured as {schema}:{id} where the schema is automatically derived from the Go type name:
type Person struct{}
personID := gold.ToIRI[Person]("john") // "person:john"
validID, err := gold.AsIRI[Person]("person:jane") // ✅ Valid
invalidID, err := gold.AsIRI[Person]("user:bob") // ❌ Error: wrong schema
Hierarchical URNs
For hierarchical identifiers with namespace support:
type MyApp struct{}
type Document struct{}
// Creates "urn:myapp:document:folder:subfolder:file"
urn := gold.ToURN[MyApp, Document]("folder", "subfolder", "file")
iri := urn.ToIRI() // "document:folder/subfolder/file"
Relationship Modeling
Model relationships between entities using compound types:
// Relationship between User and Blog for compound database keys
type UserBlog = gold.Imply[User, Blog]
relationship := gold.ImplyFrom(
gold.ToIRI[User]("alice"),
gold.ToIRI[Blog]("tech-blog")
)
Schema Registry
Schemas are derived automatically, but can be customized:
// For complex types, register custom schemas
gold.Register[[]MyType]("my-type-collection")
Type-Safe URL Templates
URL templates provide compile-time safety for building URLs with typed parameters:
type AccountID = gold.IRI[Account]
type StoryID = gold.IRI[Story]
// Define type-safe URL template
type StoryUrl = gold.Url2[string, AccountID, StoryID]
// Create URL template constants
const CatalogStoryUrl = StoryUrl("/catalog/authors/%s/stories/%s")
// Build URLs with type safety
accountID := gold.ToIRI[Account]("alice")
storyID := gold.ToIRI[Story]("my-story")
url := CatalogStoryUrl.Build(accountID, storyID)
// Result: "/catalog/authors/account:alice/stories/story:my-story"
The library provides Url1 through Url4 for templates with 1-4 parameters respectively.
License
See LICENSE file for details.
Documentation
¶
Overview ¶
Package gold provides a typesafe Linked Data support for Golang. It defines algebra for declaring identity and hierarchical relationships between data types.
Index ¶
- func DecodeJSON(b []byte) (string, error)
- func EncodeJSON(s string, err error) ([]byte, error)
- func Register[T any](schema string) string
- func Schema[T any]() string
- type Codec
- type Decoder
- type Encoder
- type IRI
- type Imply
- type URN
- func (urn *URN[N, T]) FromIRI(iri IRI[T])
- func (urn URN[N, T]) IsEmpty() bool
- func (urn *URN[N, T]) IsValid() bool
- func (urn URN[N, T]) Join(other URN[N, T]) URN[N, T]
- func (urn URN[N, T]) MarshalJSON() ([]byte, error)
- func (urn URN[N, T]) Norm() URN[N, T]
- func (urn URN[N, T]) Reference() string
- func (urn URN[N, T]) Split() (URN[N, T], URN[N, T])
- func (urn URN[N, T]) ToIRI() IRI[T]
- func (urn *URN[N, T]) UnmarshalJSON(b []byte) (err error)
- func (urn *URN[N, T]) Validate() (err error)
- type Url1
- type Url2
- type Url3
- type Url4
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeJSON ¶
Types ¶
type IRI ¶
Compact IRI (CURIE) is universal identifier for a resource, defined as
{schema}:{id}
where schema is a namespace prefix and id is a local identifier. The schema is always derived from the type of the resource T, making it safe at compiletime.
It is recommended to derive schema from the class itself:
type MyClass struct {
ID gold.IRI[MyClass] `json:"id"`
}
IRIs are not hierarchical in the linked-data sense. They are flat, typed identifiers structured as {schema}:{id}.
func AsIRI ¶
IRI parser, converts a string into a compact IRI type. Input string is expected to be a compact IRI of the form {schema}:{id}. It returns an error if the schema prefix is different than one associated with type T.
func ToIRI ¶
IRI type constructor, creates a new IRI from the string. It returns a valid compact IRI annotated with a schema.
If input string is compact IRI of other kind, it is still annotated with a schema.
func (IRI[T]) MarshalJSON ¶
Encodes IRI into JSON as a CURIE string.
func (IRI[T]) Norm ¶
Normalize IRI to a compact IRI type. Use it as constructor for IRI types aliases.
type MyID = gold.IRI[MyClass]
var id = MyID("foo").Norm()
func (*IRI[T]) UnmarshalJSON ¶
Decodes IRI from JSON as a CURIE string.
type Imply ¶
IRIs are not hierarchical in the linked-data sense. They are flat, typed identifiers structured as {schema}:{id}. IRI assumes hierarchical identifiers but they are not hierarchical in this context {id} is a "flat" identity of the class. Conveniently, it is possible to use IRIs as hierarchical identifiers but it is not reflected in the type system and should be managed by the application itself.
Relations between concepts are not implied by IRI structure itself. Instead, They are modeled explicitly as product of IRIs or using predicate statements:
image:Selfie schema:creator user:Alice
Application models predicate statements as attributes of the IRI type
type Image struct {
ID gold.IRI[Image] `json:"id"`
Creator gold.IRI[User] `json:"creator"`
}
Statements are not flexible enough to model convolution of statements into composite keys, which are essential for persisting linked-data.
Generic Imply type is used to explicitly model relationships between two types A and B as composite structure.
user:Alice/schema:creator/image:Selfie type Creator gold.Imply[Image, User]
type URN ¶
Uniform Resource Name (URN) is a type-safe identifier for hierarchical identity, it is defined as
urn:{namespace}:{schema}:{id⁰}:{id¹}:...:{idⁿ}
where namespace is a unique identifier for the application, schema is a type-safe identifier for the resource, and id is a local identifier.
URNs supports convenient hierarchical identity. It is not reflected in the type system and should be managed by the application itself.
func AsURN ¶
URN parser, converts a string into a URN type. Input string is expected to be a compact URN of the form urn:{namespace}:{schema}. It returns an error if the schema prefix is different than one associated with type T.
func ToURN ¶
URN type constructor, creates a new URN from the string. It returns a valid compact URN annotated with a urn:{namespace}:{schema}.
If input segment is compact URN of other kind, it panic.
func (URN[N, T]) Join ¶
Join combines two URNs into one, where the second URN is appended to the first.
func (URN[N, T]) MarshalJSON ¶
Encodes IRI into JSON as a CURIE string.
func (URN[N, T]) Norm ¶
Normalize URN to a URN type. Use it as constructor for URN types aliases.
type MyID = gold.URN[MyNamespace, MyClass]
var id = MyID("foo").Norm()
func (URN[N, T]) Reference ¶
Reference returns a local identifier of the URN, without schema prefix.
func (URN[N, T]) Split ¶
Split splits URN into two parts: base and reference.
urn:{namespace}:{schema}:{id⁰}:{id¹}:...:{idⁿ} ⇒
urn:{namespace}:{schema}:{id⁰}:{id¹}:...:{idⁿ⁻¹}
urn:{namespace}:{schema}:{idⁿ}
func (*URN[N, T]) UnmarshalJSON ¶
Decodes IRI from JSON as a CURIE string.
type Url1 ¶
Url1 is a type-safe URL template with one parameter. T is the target string type, A is the type of the parameter.
Example:
type UserUrl = gold.Url1[string, UserID]
const UserProfile = UserUrl("/users/%s")
url := UserProfile.Build(userID)
type Url2 ¶
Url2 is a type-safe URL template with two parameters. T is the target string type, A and B are the types of the parameters.
Example:
type StoryUrl = gold.Url2[string, AccountID, StoryID]
const CatalogStoryUrl = StoryUrl("/catalog/authors/%s/stories/%s")
url := CatalogStoryUrl.Build(accountID, storyID)
type Url3 ¶
Url3 is a type-safe URL template with three parameters. T is the target string type, A, B, and C are the types of the parameters.
Example:
type CommentUrl = gold.Url3[string, AccountID, StoryID, CommentID]
const StoryCommentUrl = CommentUrl("/catalog/authors/%s/stories/%s/comments/%s")
url := StoryCommentUrl.Build(accountID, storyID, commentID)
type Url4 ¶
Url4 is a type-safe URL template with four parameters. T is the target string type, A, B, C, and D are the types of the parameters.
Example:
type ThreadUrl = gold.Url4[string, AccountID, StoryID, CommentID, ThreadID]
const CommentThreadUrl = ThreadUrl("/catalog/authors/%s/stories/%s/comments/%s/threads/%s")
url := CommentThreadUrl.Build(accountID, storyID, commentID, threadID)
Source Files
Directories