json_ld/lib.rs
1//! This crate is a Rust implementation of the
2//! [JSON-LD](https://www.w3.org/TR/json-ld/)
3//! data interchange format.
4//!
5//! [Linked Data (LD)](https://www.w3.org/standards/semanticweb/data)
6//! is a [World Wide Web Consortium (W3C)](https://www.w3.org/)
7//! initiative built upon standard Web technologies to create an
8//! interrelated network of datasets across the Web.
9//! The [JavaScript Object Notation (JSON)](https://tools.ietf.org/html/rfc7159) is
10//! a widely used, simple, unstructured data serialization format to describe
11//! data objects in a human readable way.
12//! JSON-LD brings these two technologies together, adding semantics to JSON
13//! to create a lightweight data serialization format that can organize data and
14//! help Web applications to inter-operate at a large scale.
15//!
16//! # Usage
17//!
18//! The entry point for this library is the [`JsonLdProcessor`] trait
19//! that provides an access to all the JSON-LD transformation algorithms
20//! (context processing, expansion, compaction, etc.).
21//! If you want to explore and/or transform [`JsonLdExpandedDocument`]s, you may
22//! also want to check out the [`JsonLdObject`] type representing a JSON object.
23//!
24//! [`JsonLdProcessor`]: crate::JsonLdProcessor
25//!
26//! ## Expansion
27//!
28//! If you want to expand a JSON-LD document, first describe the document to
29//! be expanded using either [`JsonLdDocument`] or [`RemoteJsonLdDocument`]:
30//! - [`JsonLdDocument`] wraps the JSON representation of the document
31//! alongside its remote URL.
32//! - [`RemoteJsonLdDocument`] may represent only an URL, letting
33//! some loader fetching the remote document by dereferencing the URL.
34//!
35//! After that, you can simply use the [`JsonLdProcessor::expand`] function on
36//! the remote document.
37//!
38//! [`JsonLdDocument`]: crate::JsonLdDocument
39//! [`RemoteJsonLdDocument`]: crate::RemoteJsonLdDocument
40//! [`JsonLdProcessor::expand`]: JsonLdProcessor::expand
41//!
42//! ### Example
43//!
44//! ```
45//! use rdf_syntax::iri;
46//! use json_ld::{JsonLdProcessor, JsonLdDocument, json_syntax::{JsonValue, JsonParse}};
47//!
48//! // Parse a JSON-LD document.
49//! let (value, _) = JsonValue::parse_str(r#"{
50//! "@context": { "name": "http://xmlns.com/foaf/0.1/name" },
51//! "@id": "https://www.rust-lang.org",
52//! "name": "Rust Programming Language"
53//! }"#).expect("unable to parse file");
54//!
55//! let input = JsonLdDocument::new(
56//! Some(iri!("https://example.com/sample.jsonld").to_owned()),
57//! None,
58//! value,
59//! );
60//!
61//! // Use `NoJsonLdLoader` as we won't need to load any remote document.
62//! let expanded = input.expand(json_ld::NoJsonLdLoader).expect("expansion failed");
63//!
64//! assert!(!expanded.is_empty());
65//! ```
66//!
67//! Here is another example using a file-system loader.
68//!
69//! ```no_run
70//! use rdf_syntax::iri;
71//! use json_ld::{JsonLdProcessor, JsonLdLoader};
72//!
73//! let mut loader = json_ld::JsonLdFsLoader::default();
74//! loader.mount(iri!("https://example.com/").to_owned(), "examples");
75//!
76//! let input = loader.load(iri!("https://example.com/sample.jsonld")).expect("loading failed");
77//! let expanded = input.expand(&loader).expect("expansion failed");
78//! ```
79//!
80//! ## Compaction
81//!
82//! The JSON-LD Compaction is a transformation that consists in applying a
83//! context to a given JSON-LD document reducing its size.
84//! There are two ways to get a compact JSON-LD document with this library
85//! depending on your starting point:
86//! - If you want to get a compact representation for an arbitrary remote
87//! document, simply use the [`JsonLdProcessor::compact`]
88//! (or [`JsonLdProcessor::compact_with`]) method.
89//! - Otherwise to compact a [`JsonLdExpandedDocument`] you can use the
90//! [`JsonLdExpandedDocument::compact`] method.
91//!
92//! [`JsonLdProcessor::compact`]: crate::JsonLdProcessor::compact
93//! [`JsonLdProcessor::compact_with`]: crate::JsonLdProcessor::compact_with
94//! [`JsonLdExpandedDocument`]: crate::JsonLdExpandedDocument
95//! [`JsonLdExpandedDocument::compact`]: crate::JsonLdExpandedDocument::compact
96//!
97//! ### Example
98//!
99//! Here is an example compacting an arbitrary document using [`JsonLdProcessor::compact`].
100//!
101//! ```no_run
102//! use rdf_syntax::iri;
103//! use json_ld::{JsonLdProcessor, JsonLdLoader, RemoteJsonLdContext, json_syntax::JsonPrint};
104//!
105//! let mut loader = json_ld::JsonLdFsLoader::default();
106//! loader.mount(iri!("https://example.com/").to_owned(), "examples");
107//!
108//! let input = loader.load(iri!("https://example.com/sample.jsonld")).expect("loading failed");
109//! let context = RemoteJsonLdContext::iri(iri!("https://example.com/context.jsonld").to_owned());
110//!
111//! let compact = input.compact(context, &loader).expect("compaction failed");
112//!
113//! println!("output: {}", compact.pretty_print());
114//! ```
115//!
116//! ## Flattening
117//!
118//! The JSON-LD Flattening is a transformation that consists in moving nested
119//! nodes out. The result is a list of all the nodes declared in the document.
120//! There are two ways to flatten JSON-LD document with this library
121//! depending on your starting point:
122//! - If you want to flatten an arbitrary remote document, use
123//! [`JsonLdProcessor::flatten`] (or [`JsonLdProcessor::flatten_with`]).
124//! This returns a compacted JSON-LD document.
125//! - To flatten an already-expanded [`JsonLdExpandedDocument`], use the
126//! [`JsonLdExpandedDocument::flatten`] (or
127//! [`JsonLdExpandedDocument::flatten_unordered`]) method, which returns a
128//! [`JsonLdFlattenedDocument`].
129//!
130//! [`JsonLdProcessor::flatten`]: crate::JsonLdProcessor::flatten
131//! [`JsonLdProcessor::flatten_with`]: crate::JsonLdProcessor::flatten_with
132//! [`JsonLdExpandedDocument::flatten`]: crate::JsonLdExpandedDocument::flatten
133//! [`JsonLdExpandedDocument::flatten_unordered`]: crate::JsonLdExpandedDocument::flatten_unordered
134//! [`JsonLdFlattenedDocument`]: crate::JsonLdFlattenedDocument
135//!
136//! ### Example
137//!
138//! Here is an example flattening an arbitrary document using [`JsonLdProcessor::flatten`].
139//!
140//! ```no_run
141//! use rdf_syntax::iri;
142//! use json_ld::{JsonLdProcessor, JsonLdLoader, json_syntax::JsonPrint};
143//!
144//! let mut loader = json_ld::JsonLdFsLoader::default();
145//! loader.mount(iri!("https://example.com/").to_owned(), "examples");
146//!
147//! let input = loader.load(iri!("https://example.com/sample.jsonld")).expect("loading failed");
148//! let flattened = input.flatten(None, &loader).expect("flattening failed");
149//!
150//! println!("output: {}", flattened.pretty_print());
151//! ```
152pub use json_syntax;
153
154#[cfg(feature = "algorithms")]
155pub mod algorithms;
156mod core;
157pub mod ext;
158#[cfg(feature = "algorithms")]
159mod processor;
160pub mod syntax;
161mod tracing;
162
163#[cfg(feature = "algorithms")]
164pub use algorithms::RdfSerializationOptions;
165pub use core::*;
166pub use linked_data;
167#[cfg(feature = "algorithms")]
168pub use processor::*;
169pub use syntax::{JsonLdContext, JsonLdContextEntry};
170pub use tracing::*;