Documentation
¶
Overview ¶
Package rdf is a small, fast, dependency-free RDF toolkit. It provides the RDF triple model (Term, Triple, Graph), parsers and serializers for the four common serializations — RDF/XML, JSON-LD, Turtle and N-Triples — and a streaming decoder for the line-based formats.
Two reading modes:
- Whole document: ParseRDFXML, ParseJSONLD, ParseTurtle and ParseNTriples take a []byte and return a *Graph. Fast and convenient for inputs that fit in memory.
- Streaming: NewDecoder reads N-Triples, N-Quads, RDF/XML or Turtle from an io.Reader one triple at a time in constant memory, for inputs too large to materialize (e.g. the multi-gigabyte Library of Congress authority dumps). JSON-LD is whole-document only.
The parsers target the constructs real-world RDF uses rather than the whole of each specification; see each parser's documentation for what is and isn't handled (notably, relative-IRI resolution against a document base is not performed). There are no third-party dependencies.
Index ¶
- Constants
- Variables
- func LocalName(iri string) string
- func TurtleHeader(prefixes map[string]string) []byte
- type Dataset
- type Decoder
- type Encoder
- type Format
- type Graph
- func (g *Graph) Add(s, p, o Term)
- func (g *Graph) Canonical() ([]byte, error)
- func (g *Graph) HasType(subject Term, typeIRI string) bool
- func (g *Graph) Literal(subject Term, predicate string) (string, bool)
- func (g *Graph) NQuads(graph Term) []byte
- func (g *Graph) NTriples() []byte
- func (g *Graph) Object(subject Term, predicate string) (Term, bool)
- func (g *Graph) Objects(subject Term, predicate string) []Term
- func (g *Graph) SubjectsOfType(typeIRI string) []Term
- func (g *Graph) Turtle(prefixes map[string]string) []byte
- func (g *Graph) TurtleBody(prefixes map[string]string) []byte
- type Kind
- type Quad
- type Term
- type Triple
Constants ¶
const ( NS = "http://www.w3.org/1999/02/22-rdf-syntax-ns#" TypeIRI = NS + "type" FirstIRI = NS + "first" RestIRI = NS + "rest" NilIRI = NS + "nil" XSDString = "http://www.w3.org/2001/XMLSchema#string" )
Well-known IRIs.
Variables ¶
var ErrCanonComplexity = errors.New("rdf: canonicalization exceeded complexity budget")
ErrCanonComplexity is returned by the canonicalization functions when a graph's blank-node structure would require more work than maxCanonWork permits — the guard against the algorithm's exponential worst case on adversarial "poison" datasets. Well-formed data never approaches the limit.
Functions ¶
func LocalName ¶
LocalName returns the fragment or last path segment of an IRI (the part after the final '#' or '/').
func TurtleHeader ¶
TurtleHeader returns the @prefix declaration block for the given prefixes, terminated by a blank line. Collection writers emit it once.
Types ¶
type Dataset ¶ added in v0.4.0
type Dataset struct {
Quads []Quad
}
Dataset is a set of quads — RDF statements each tagged with the graph they belong to. It is the quad-level analogue of Graph and what ParseNQuads returns; it is how provenance (which source a statement came from) is carried.
func Canonicalize ¶ added in v0.5.0
Canonicalize returns a new Dataset with blank nodes relabeled to their canonical _:c14nN identifiers and quads in canonical order, leaving d untouched.
func ParseNQuads ¶ added in v0.4.0
ParseNQuads parses an N-Quads document into a Dataset, preserving each statement's graph term; lines carrying only three terms fall in the default graph. It shares the N-Triples term reader, so the same escaping and leniency apply — blank, comment and malformed lines are skipped.
func (*Dataset) Canonical ¶ added in v0.5.0
Canonical returns the dataset serialized as canonical N-Quads per the W3C RDF Dataset Canonicalization algorithm RDFC-1.0 (URDNA2015): blank nodes are relabeled to isomorphism-invariant _:c14nN identifiers and the quads are sorted, so two datasets that differ only in statement order or blank-node labels produce byte-identical output. It returns ErrCanonComplexity for a graph whose symmetry exceeds the work budget.
func (*Dataset) Graph ¶ added in v0.4.0
Graph returns the triples belonging to the given graph term as a Graph; pass a zero-value term for the default graph.
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder streams RDF statements from an io.Reader one triple at a time, in constant memory — for inputs far too large to materialize into a Graph (multi-gigabyte dumps such as the LC authority files). Each returned triple owns its strings, so it is safe to retain after the next call.
JSON-LD is not streamable here (its document must be materialized); use ParseJSONLD for that.
func NewDecoder ¶
NewDecoder returns a streaming Decoder reading the given format from r.
func (*Decoder) All ¶
All returns an iterator over the remaining triples, ending at the first error (io.EOF, the normal end, is not surfaced). Breaking out of the loop stops the producer:
for tr := range dec.All() { ... }
Use Decode directly when a non-EOF read error must be observed.
func (*Decoder) AllQuads ¶ added in v0.4.0
AllQuads returns an iterator over the remaining statements as quads, preserving N-Quads graph terms. Like All, it ends at the first error and breaking out of the loop stops the producer:
for q := range dec.AllQuads() { ... }
func (*Decoder) Close ¶
Close stops a streaming decoder early, releasing its producer goroutine. It is a no-op for the line-based formats and after the stream is exhausted.
func (*Decoder) Decode ¶
Decode returns the next triple, or io.EOF when the input is exhausted. Any fourth (graph) term on an N-Quads line is dropped; use DecodeQuad to keep it. Blank, comment and malformed lines/statements are skipped, so a stray line never aborts a large stream.
func (*Decoder) DecodeQuad ¶ added in v0.4.0
DecodeQuad returns the next statement as a quad, preserving the graph term of an N-Quads line; the triple-only formats (N-Triples, RDF/XML, Turtle) yield a zero-value graph term (the default graph). It returns io.EOF at end of input.
type Encoder ¶ added in v0.4.0
type Encoder struct {
// contains filtered or unexported fields
}
Encoder serializes a sequence of graphs into one document — N-Triples, N-Quads or Turtle — keeping blank-node labels unique across the graphs it writes. Blank-node labels are scoped to the whole document, so a single Encoder must be reused for every graph written to one stream; a fresh encoder per graph would let graphs that each number their blanks from scratch (such as one BIBFRAME graph per record) collide and merge. It is the serialization counterpart to Decoder; the whole-graph Graph.NTriples, Graph.NQuads and Graph.Turtle methods each use a fresh Encoder internally.
func (*Encoder) AppendNQuads ¶ added in v0.4.0
AppendNQuads appends every triple of g to b as N-Quads tagged with the graph term — g's named graph / provenance. A zero-value graph term writes the default graph (plain N-Triples). Each call is a fresh blank-node scope, so graphs that label their blanks from scratch never merge, while their output labels stay unique across the whole document.
func (*Encoder) AppendNTriples ¶ added in v0.4.0
AppendNTriples appends g's triples to b as N-Triples in a fresh blank-node scope — N-Triples being N-Quads restricted to the default graph.
func (*Encoder) AppendQuad ¶ added in v0.4.0
AppendQuad appends one quad to b as an N-Quads line. A default-graph quad (zero-value G) is written as a three-term N-Triples line.
func (*Encoder) AppendTurtle ¶ added in v0.4.0
AppendTurtle appends g's triples to b as a Turtle body (no @prefix header), grouped by subject, in a fresh blank-node scope. It groups without a per-subject map: subjects are ranked by first appearance, then a stable sort of triple indices by that rank makes each subject's triples contiguous in document order — turning thousands of small allocations into a handful.
type Format ¶
type Format int
Format identifies a serialization the streaming Decoder reads.
const ( // NTriples is the line-based N-Triples format. NTriples Format = iota // NQuads is N-Quads; the optional graph label on each line is ignored, so each // statement still yields a triple. NQuads // RDFXML is RDF/XML; triples stream as each node element is parsed. RDFXML // Turtle streams '.'-terminated statements; @prefix/@base carry forward. // SPARQL-style PREFIX/BASE directives (no '.') are not supported when streaming. Turtle )
type Graph ¶
type Graph struct {
Triples []Triple
// contains filtered or unexported fields
}
Graph is a set of triples with simple lookup helpers built on first use. Term is comparable, so it indexes by subject term directly — no key strings.
func ParseJSONLD ¶
ParseJSONLD parses a JSON-LD document into a Graph. It expands compact IRIs and terms against an inline @context (prefix maps and term definitions, including "@type":"@id" coercion), and handles @graph, @id, @type, @value/@language/@type literals, @list, nested node objects, and arrays of any of these. It does not fetch remote @context documents or run full JSON-LD 1.1 framing.
func ParseNTriples ¶
ParseNTriples parses an N-Triples document (one "subject predicate object ." statement per line) into a Graph. It also accepts N-Quads, ignoring any fourth (graph) term. Blank, comment and malformed lines are skipped, so it is robust to the trailing noise real-world dumps carry.
func ParseRDFXML ¶
ParseRDFXML parses an RDF/XML document into a Graph. It supports the striped syntax real bibliographic RDF uses: typed node elements and rdf:Description, rdf:about / rdf:nodeID / rdf:ID subjects, rdf:resource and rdf:nodeID object references, nested node elements, literal property values with rdf:datatype and xml:lang, property attributes, and rdf:parseType="Resource". It does not handle RDF containers, reification, or rdf:parseType="Literal"/"Collection".
func ParseTurtle ¶
ParseTurtle parses a Turtle document into a Graph. It supports the constructs real RDF uses: @prefix/@base and SPARQL-style PREFIX/BASE, prefixed names and IRIs, the `a` keyword, predicate-object lists (`;`) and object lists (`,`), blank-node labels, `[ … ]` blank-node property lists, `( … )` collections, and string (including triple-quoted), language-tagged, datatyped, numeric and boolean literals. Local names are read as the common identifier subset.
func (*Graph) Canonical ¶ added in v0.5.0
Canonical returns the graph as canonical N-Quads (its triples in the default graph), per RDFC-1.0. See Dataset.Canonical.
func (*Graph) HasType ¶
HasType reports whether the subject has rdf:type typeIRI. It scans the index without allocating.
func (*Graph) Literal ¶
Literal returns the value of the subject's first literal object for the predicate, or false. It scans the index without allocating an intermediate slice, serving the frequent single-value field reads.
func (*Graph) NQuads ¶ added in v0.4.0
NQuads serializes the graph's triples as N-Quads, each tagged with the given graph term (its named graph / provenance). A zero-value graph term produces plain N-Triples.
func (*Graph) Object ¶
Object returns the first object for (subject, predicate), or false. It scans the index without allocating an intermediate slice.
func (*Graph) Objects ¶
Objects returns the objects of every triple with the given subject and predicate IRI, in document order.
func (*Graph) SubjectsOfType ¶
SubjectsOfType returns every subject with rdf:type typeIRI, in document order (deduplicated).
type Quad ¶ added in v0.4.0
type Quad struct {
S, P, O, G Term
}
Quad is an RDF statement in a named graph: a triple plus the graph it belongs to. A zero-value graph term (G) denotes the default graph, so a Quad is a strict superset of a Triple.
type Term ¶
type Term struct {
Kind Kind
Value string // IRI, blank-node identifier, or a literal's lexical form
Lang string // literal language tag (Literal only)
Datatype string // literal datatype IRI (Literal only)
}
Term is an RDF term: an IRI, a blank node, or a literal.
func NewLiteral ¶
NewLiteral makes a literal; an empty datatype defaults per RDF (xsd:string, or rdf:langString when a language tag is present).
Source Files