From 00c05effbe2c4c22afbc25845958b84abb282fa7 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Sun, 5 Jul 2020 10:41:42 +0100 Subject: [PATCH 01/19] Updated README file --- README.md | 600 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 582 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index df0f99c..751f777 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,39 @@ # json-ld.net -A [JSON-LD][jsonld] processor for .NET. - [![NuGet][nuget-badge]][nuget] ![Build Status][gha-badge] [![codecov][codecov-badge]][codecov] -This project has adopted the [Microsoft Open Source Code of Conduct][coc]. -For more information see the [Code of Conduct FAQ][coc-faq] or contact -[opencode@microsoft.com][ms-mail] with any additional questions or comments. +## Introduction +This library is an implementation of the JSON-LD specification in C#. + +JSON, as specified in RFC7159, is a simple language for representing objects on the Web. Linked Data is a way of describing content across different documents or Web sites. Web resources are described using IRIs, and typically are dereferencable entities that may be used to find more information, creating a "Web of Knowledge". JSON-LD is intended to be a simple publishing method for expressing not only Linked Data in JSON, but for adding semantics to existing JSON. + +JSON-LD is designed as a light-weight syntax that can be used to express Linked Data. It is primarily intended to be a way to express Linked Data in JavaScript and other Web-based programming environments. It is also useful when building interoperable Web Services and when storing Linked Data in JSON-based document storage engines. It is practical and designed to be as simple as possible, utilizing the large number of JSON parsers and existing code that is in use today. It is designed to be able to express key-value pairs, RDF data, RDFa data, Microformats data, and Microdata. That is, it supports every major Web-based structured data model in use today. + +The syntax does not require many applications to change their JSON, but easily add meaning by adding context in a way that is either in-band or out-of-band. The syntax is designed to not disturb already deployed systems running on JSON, but provide a smooth migration path from JSON to JSON with added semantics. Finally, the format is intended to be fast to parse, fast to generate, stream-based and document-based processing compatible, and require a very small memory footprint in order to operate. + +You can read more about JSON-LD on the [JSON-LD website](jsonld). + +## Conformance + +This library aims to conform with the following: + +* [JSON-LD 1.0][JSON-LD 1.0], W3C Recommendation, 2014-01-16, and any [errata][errata] +* [JSON-LD 1.0 Processing Algorithms and API][JSON-LD 1.0 API], W3C Recommendation, 2014-01-16, and any [errata][errata] +* [JSON-LD 1.0 Framing][JSON-LD 1.0 Framing], Unofficial Draft, 2012-08-30 +* Working Group [test suite][WG test suite] + +The [JSON-LD Working Group][JSON-LD WG] is now developing JSON-LD 1.1. Library +updates to conform with newer specifications will happen as features stabilize +and development time and resources permit. + +* [JSON-LD 1.1][JSON-LD WG 1.1], W3C Working Draft, 2018-12-14 or [newer][JSON-LD WG latest] +* [JSON-LD 1.1 Processing Algorithms and API][JSON-LD WG 1.1 API], W3C Working Draft, 2018-12-14 or [newer][JSON-LD WG API latest] +* [JSON-LD 1.1 Framing][JSON-LD WG 1.1 Framing], W3C Working Draft, 2018-12-14 or [newer][JSON-LD WG Framing latest] + +The [test runner][] is often updated to note or skip newer tests that are not +yet supported. ## Supported frameworks @@ -16,14 +41,530 @@ For more information see the [Code of Conduct FAQ][coc-faq] or contact * .NET Standard 1.3 and 2.0 * Portable .NET 4.5, Windows 8 +## Installation + +### dotnet CLI + +```sh +dotnet new console +dotnet add package json-ld.net +``` + +```csharp +using JsonLD.Core; +using Newtonsoft.Json.Linq; +using System; + +namespace JsonLD.Demo +{ + internal class Program + { + private static void Main() + { + var json = "{'@context':{'test':'http://www.test.com/'},'test:hello':'world'}"; + var document = JObject.Parse(json); + var expanded = JsonLdProcessor.Expand(document); + Console.WriteLine(expanded); + } + } +} + +``` + +## Examples +-------- + +Example data and context used throughout examples below: + +#### doc.json +```json +{ + "@id": "http://example.org/ld-experts", + "http://schema.org/name": "LD Experts", + "http://schema.org/member": [{ + "@type": "http://schema.org/Person", + "http://schema.org/name": "Manu Sporny", + "http://schema.org/url": {"@id": "http://manu.sporny.org/"}, + "http://schema.org/image": {"@id": "http://manu.sporny.org/images/manu.png"} + }] +} +``` + +#### context.json +```json +{ + "name": "http://schema.org/name", + "member": "http://schema.org/member", + "homepage": {"@id": "http://schema.org/url", "@type": "@id"}, + "image": {"@id": "http://schema.org/image", "@type": "@id"}, + "Person": "http://schema.org/Person", + "@vocab": "http://example.org/", + "@base": "http://example.org/" +} +``` + + +### [compact](http://json-ld.org/spec/latest/json-ld/#compacted-document-form) + +```csharp +var doc = JObject.Parse(_docJson); +var context = JObject.Parse(_contextJson); +var opts = new JsonLdOptions(); +var compacted = JsonLdProcessor.Compact(doc, context, opts); +Console.WriteLine(compacted); + +/* + +Output: +{ + "@id": "ld-experts", + "member": { + "@type": "Person", + "image": "http://manu.sporny.org/images/manu.png", + "name": "Manu Sporny", + "homepage": "http://manu.sporny.org/" + }, + "name": "LD Experts", + "@context": . . . +} + +*/ +``` + + +### [expand](http://json-ld.org/spec/latest/json-ld/#expanded-document-form) + +```csharp +var expanded = JsonLdProcessor.Expand(compacted); +Console.WriteLine(expanded); + +/* + +Output: +[ + { + "@id": "http://test.com/ld-experts", + "http://schema.org/member": [ + { + "http://schema.org/url": [ + { + "@id": "http://manu.sporny.org/" + } + ], + "http://schema.org/image": [ + { + "@id": "http://manu.sporny.org/images/manu.png" + } + ], + "http://schema.org/name": [ + { + "@value": "Manu Sporny" + } + ] + } + ], + "http://schema.org/name": [ + { + "@value": "LD Experts" + } + ] + } +] + +*/ + + +*/ +``` + + +### [flatten](http://json-ld.org/spec/latest/json-ld/#flattened-document-form) + +```csharp +var doc = JObject.Parse(_docJson); +var context = JObject.Parse(_contextJson); +var opts = new JsonLdOptions(); +var flattened = JsonLdProcessor.Flatten(doc, context, opts); +Console.WriteLine(flattened); + +/* + +Output: +{ + "@context": . . ., + "@graph": [ + { + "@id": "_:b0", + "@type": "Person", + "image": "http://manu.sporny.org/images/manu.png", + "name": "Manu Sporny", + "homepage": "http://manu.sporny.org/" + }, + { + "@id": "ld-experts", + "member": { + "@id": "_:b0" + }, + "name": "LD Experts" + } + ] +} + +*/ + +``` + + +### [frame](http://json-ld.org/spec/latest/json-ld-framing/#introduction) + +For the framing example below, the framing document is defined as follows: + +```json +{ + "@context": { + "name": "http://schema.org/name", + "member": {"@id": "http://schema.org/member", "@type": "@id"}, + "homepage": {"@id": "http://schema.org/url", "@type": "@id"}, + "image": {"@id": "http://schema.org/image", "@type": "@id"}, + "Person": "http://schema.org/Person" + }, + "@type": "Person" +} +``` + +And we use it like this: +```csharp +var doc = JObject.Parse(_docJson); +var frame = JObject.Parse(_frameJson); +var opts = new JsonLdOptions(); +var flattened = JsonLdProcessor.Frame(doc, frame, opts); +Console.WriteLine(flattened); + +/* + +Output: +{ + "@context": . . ., + "@graph": [ + { + "@id": "_:b0", + "@type": "Person", + "image": "http://manu.sporny.org/images/manu.png", + "name": "Manu Sporny", + "homepage": "http://manu.sporny.org/" + } + ] +} + +*/ +``` + + +### [normalize](http://json-ld.github.io/normalization/spec/) (aka canonize) + +Normalized is a graph of objects that is a canonical representation of the document that can be used for hashing, comparison, etc. + +```csharp +var doc = JObject.Parse(_docJson); +var opts = new JsonLdOptions(); +var normalized = (RDFDataset)JsonLdProcessor.Normalize(doc, opts); +Console.WriteLine(normalized.Dump()); + +/* + +Output: +@default + subject + type blank node + value _:c14n0 + predicate + type IRI + value http://schema.org/image + object + type IRI + value http://manu.sporny.org/images/manu.png + --- + subject + type blank node + value _:c14n0 + predicate + type IRI + value http://schema.org/name + object + type literal + value Manu Sporny + datatype http://www.w3.org/2001/XMLSchema#string + --- + subject + type blank node + value _:c14n0 + predicate + type IRI + value http://schema.org/url + object + type IRI + value http://manu.sporny.org/ + --- + subject + type blank node + value _:c14n0 + predicate + type IRI + value http://www.w3.org/1999/02/22-rdf-syntax-ns#type + object + type IRI + value http://schema.org/Person + --- + subject + type IRI + value http://example.org/ld-experts + predicate + type IRI + value http://schema.org/member + object + type blank node + value _:c14n0 + --- + subject + type IRI + value http://example.org/ld-experts + predicate + type IRI + value http://schema.org/name + object + type literal + value LD Experts + datatype http://www.w3.org/2001/XMLSchema#string + --- + +*/ +``` + + +### ToRDF (N-Quads) + +```csharp +var doc = JObject.Parse(_docJson); +var opts = new JsonLdOptions(); +var rdf = (RDFDataset)JsonLdProcessor.ToRDF(doc, opts); + +var serialized = RDFDatasetUtils.ToNQuads(rdf); // serialize RDF to string +Console.WriteLine(serialized); + +/* + +Output: + _:b0 . + "LD Experts" . +_:b0 . +_:b0 "Manu Sporny" . +_:b0 . +_:b0 . + +*/ +``` + +_or_ using a custom RDF renderer object + +```csharp +private class JSONLDTripleCallback : IJSONLDTripleCallback +{ + public object Call(RDFDataset dataset) => + RDFDatasetUtils.ToNQuads(dataset); // serialize the RDF dataset as NQuads +} + +internal static void Run() +{ + var doc = JObject.Parse(_docJson); + var callback = new JSONLDTripleCallback(); + var serialized = JsonLdProcessor.ToRDF(doc, callback); + Console.WriteLine(serialized); + + /* + + Output: + _:b0 . + "LD Experts" . + _:b0 . + _:b0 "Manu Sporny" . + _:b0 . + _:b0 . + + */ +} +``` + +### fromRDF (N-Quads) + +```csharp +var opts = new JsonLdOptions(); +var jsonld = JsonLdProcessor.FromRDF(serialized, opts); +Console.WriteLine(jsonld); + +/* + +Output: +[ + { + "@id": "_:b0", + "http://schema.org/image": [ + { + "@id": "http://manu.sporny.org/images/manu.png" + } + ], + "http://schema.org/name": [ + { + "@value": "Manu Sporny" + } + ], + "http://schema.org/url": [ + { + "@id": "http://manu.sporny.org/" + } + ], + "@type": [ + "http://schema.org/Person" + ] + }, + { + "@id": "http://example.org/ld-experts", + "http://schema.org/member": [ + { + "@id": "_:b0" + } + ], + "http://schema.org/name": [ + { + "@value": "LD Experts" + } + ] + } +] +*/ +``` + +_or_ using a custom RDF parser + +```csharp +private class CustomRDFParser : IRDFParser +{ + public RDFDataset Parse(JToken input) + { + // by public decree, references to example.org are normalized to https going forward... + var converted = ((string)input).Replace("http://example.org/", "https://example.org/"); + return RDFDatasetUtils.ParseNQuads(converted); + } +} + +internal static void Run() +{ + var parser = new CustomRDFParser(); + var jsonld = JsonLdProcessor.FromRDF(_serialized, parser); + Console.WriteLine(jsonld); + + /* + + Output: + [ + { + "@id": "_:b0", + "http://schema.org/image": [ + { + "@id": "http://manu.sporny.org/images/manu.png" + } + ], + "http://schema.org/name": [ + { + "@value": "Manu Sporny" + } + ], + "http://schema.org/url": [ + { + "@id": "http://manu.sporny.org/" + } + ], + "@type": [ + "http://schema.org/Person" + ] + }, + { + "@id": "https://example.org/ld-experts", + "http://schema.org/member": [ + { + "@id": "_:b0" + } + ], + "http://schema.org/name": [ + { + "@value": "LD Experts" + } + ] + } + ] + */ +} +``` + + +### Custom documentLoader + +```csharp +public class CustomDocumentLoader : DocumentLoader +{ + private static readonly string _cachedExampleOrgContext = Res.ReadString("context.json"); + + public override RemoteDocument LoadDocument(string url) + { + if (url == "http://example.org/context.jsonld") // we have this cached locally + { + var doc = new JObject(new JProperty("@context", JObject.Parse(_cachedExampleOrgContext))); + return new RemoteDocument(url, doc); + } + else + { + return base.LoadDocument(url); + } + } +} + +public static void Run() +{ + var doc = JObject.Parse(_docJson); + var remoteContext = JObject.Parse("{'@context':'http://example.org/context.jsonld'}"); + var opts = new JsonLdOptions { documentLoader = new CustomDocumentLoader() }; + var compacted = JsonLdProcessor.Compact(doc, remoteContext, opts); + Console.WriteLine(compacted); + + /* + + Output: + { + "@id": "http://example.org/ld-experts", + "member": { + "@type": "Person", + "image": "http://manu.sporny.org/images/manu.png", + "name": "Manu Sporny", + "homepage": "http://manu.sporny.org/" + }, + "name": "LD Experts" + } + + */ +} +``` + + ## Contributing +This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc-faq] or contact [opencode@microsoft.com][ms-mail] with any additional questions or comments. + Pull requests for json-ld.net are welcome, to get started install the latest tools for .NET Core: * [.NET Core][dnc] * [.NET Core tutorial][dnc-tutorial] + ### Build and Tests On Windows, you can execute `build.ps1`, which will create a nupkg and run @@ -32,21 +573,44 @@ tests for both .NET desktop and .NET Core. On both Windows and all other supported operating systems, you can run `dotnet build` to build and `dotnet test` to run the tests. + ## Origin This project began life as a [Sharpen][sharpen]-based auto-port from [jsonld-java][jsonld-java]. - [jsonld]: https://json-ld.org/ - [sharpen]: http://community.versant.com/Projects/html/projectspaces/db4o_product_design/sharpen.html - [jsonld-java]: https://github.com/jsonld-java/jsonld-java - [nuget]: https://www.nuget.org/packages/json-ld.net/ - [nuget-badge]: https://img.shields.io/nuget/v/json-ld.net.svg - [coc]: https://opensource.microsoft.com/codeofconduct/ - [coc-faq]: https://opensource.microsoft.com/codeofconduct/faq/ - [ms-mail]: mailto:opencode@microsoft.com - [dnc]: https://dot.net - [dnc-tutorial]: https://www.microsoft.com/net/core - [codecov]: https://codecov.io/gh/linked-data-dotnet/json-ld.net - [codecov-badge]: https://img.shields.io/codecov/c/github/linked-data-dotnet/json-ld.net/master.svg - [gha-badge]: https://github.com/linked-data-dotnet/json-ld.net/workflows/dotnet/badge.svg +Documentation for this library is in part drawn from https://github.com/linked-data-dotnet/json-ld.net + + [coc]: https://opensource.microsoft.com/codeofconduct/ + [coc-faq]: https://opensource.microsoft.com/codeofconduct/faq/ + [codecov]: https://codecov.io/gh/linked-data-dotnet/json-ld.net + [codecov-badge]: https://img.shields.io/codecov/c/github/linked-data-dotnet/json-ld.net/master.svg + + [ms-mail]: mailto:opencode@microsoft.com + [dnc]: https://dot.net + [dnc-tutorial]: https://www.microsoft.com/net/core + + [gha-badge]: https://github.com/linked-data-dotnet/json-ld.net/workflows/dotnet/badge.svg + + [jsonld]: https://json-ld.org/ + [jsonld-java]: https://github.com/jsonld-java/jsonld-java + + [JSON-LD 1.0]: http://www.w3.org/TR/2014/REC-json-ld-20140116/ + [JSON-LD 1.0 API]: http://www.w3.org/TR/2014/REC-json-ld-api-20140116/ + [JSON-LD 1.0 Framing]: https://json-ld.org/spec/ED/json-ld-framing/20120830/ + + [JSON-LD WG 1.1]: https://www.w3.org/TR/json-ld11/ + [JSON-LD WG 1.1 API]: https://www.w3.org/TR/json-ld11-api/ + [JSON-LD WG 1.1 Framing]: https://www.w3.org/TR/json-ld11-framing/ + + [JSON-LD WG latest]: https://w3c.github.io/json-ld-syntax/ + [JSON-LD WG API latest]: https://w3c.github.io/json-ld-api/ + [JSON-LD WG Framing latest]: https://w3c.github.io/json-ld-framing/ + + [nuget]: https://www.nuget.org/packages/json-ld.net/ + [nuget-badge]: https://img.shields.io/nuget/v/json-ld.net.svg + + [sharpen]: http://community.versant.com/Projects/html/projectspaces/db4o_product_design/sharpen.html + + [test runner]: https://github.com/linked-data-dotnet/json-ld.net/tree/master/test/json-ld.net.tests + [WG test suite]: https://github.com/w3c/json-ld-api/tree/master/tests From e2e7c884b2102d4cb1af01eedb61738d3d8a3c34 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 21:47:54 +0100 Subject: [PATCH 02/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 751f777..f34a99d 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,7 @@ namespace JsonLD.Demo Example data and context used throughout examples below: #### doc.json + ```json { "@id": "http://example.org/ld-experts", From 7b4dfe014aa5aa97044011dad699d75c07a85906 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 21:49:55 +0100 Subject: [PATCH 03/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f34a99d..190b76e 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ JSON, as specified in RFC7159, is a simple language for representing objects on JSON-LD is designed as a light-weight syntax that can be used to express Linked Data. It is primarily intended to be a way to express Linked Data in JavaScript and other Web-based programming environments. It is also useful when building interoperable Web Services and when storing Linked Data in JSON-based document storage engines. It is practical and designed to be as simple as possible, utilizing the large number of JSON parsers and existing code that is in use today. It is designed to be able to express key-value pairs, RDF data, RDFa data, Microformats data, and Microdata. That is, it supports every major Web-based structured data model in use today. -The syntax does not require many applications to change their JSON, but easily add meaning by adding context in a way that is either in-band or out-of-band. The syntax is designed to not disturb already deployed systems running on JSON, but provide a smooth migration path from JSON to JSON with added semantics. Finally, the format is intended to be fast to parse, fast to generate, stream-based and document-based processing compatible, and require a very small memory footprint in order to operate. +The syntax does not require many applications to change their JSON, but easily add meaning by adding context in a way that is either in-band or out-of-band. The syntax is designed to not disturb already deployed systems running on JSON, but provide a smooth migration path from plain JSON to semantically enhanced JSON. Finally, the format is intended to be fast to parse, fast to generate, stream-based and document-based processing compatible, and require a very small memory footprint in order to operate. You can read more about JSON-LD on the [JSON-LD website](jsonld). From cafb911a24d6f303d4ebec6a0fa7d51362709220 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 21:50:05 +0100 Subject: [PATCH 04/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 190b76e..f3248dd 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ JSON-LD is designed as a light-weight syntax that can be used to express Linked The syntax does not require many applications to change their JSON, but easily add meaning by adding context in a way that is either in-band or out-of-band. The syntax is designed to not disturb already deployed systems running on JSON, but provide a smooth migration path from plain JSON to semantically enhanced JSON. Finally, the format is intended to be fast to parse, fast to generate, stream-based and document-based processing compatible, and require a very small memory footprint in order to operate. -You can read more about JSON-LD on the [JSON-LD website](jsonld). +You can read more about JSON-LD on the [JSON-LD website][jsonld]. ## Conformance From 4401d535ab54ae282f811f655b71ada19711ad77 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 21:54:00 +0100 Subject: [PATCH 05/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f3248dd..a8b34a9 100644 --- a/README.md +++ b/README.md @@ -596,7 +596,7 @@ Documentation for this library is in part drawn from https://github.com/linked-d [jsonld]: https://json-ld.org/ [jsonld-java]: https://github.com/jsonld-java/jsonld-java - [JSON-LD 1.0]: http://www.w3.org/TR/2014/REC-json-ld-20140116/ + [json-ld-1.0]: http://www.w3.org/TR/2014/REC-json-ld-20140116/ [JSON-LD 1.0 API]: http://www.w3.org/TR/2014/REC-json-ld-api-20140116/ [JSON-LD 1.0 Framing]: https://json-ld.org/spec/ED/json-ld-framing/20120830/ From 3b73f3688fe997d6af12561e7051d9a3d1df3ae2 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 21:54:31 +0100 Subject: [PATCH 06/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index a8b34a9..933218f 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,7 @@ Example data and context used throughout examples below: ``` #### context.json + ```json { "name": "http://schema.org/name", From ca934be80f8346965d021dbc4a63acec37d90398 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 21:54:54 +0100 Subject: [PATCH 07/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 933218f..0f62c4c 100644 --- a/README.md +++ b/README.md @@ -261,10 +261,9 @@ Output: */ ``` +### Normalize -### [normalize](http://json-ld.github.io/normalization/spec/) (aka canonize) - -Normalized is a graph of objects that is a canonical representation of the document that can be used for hashing, comparison, etc. +[Normalization](http://json-ld.github.io/normalization/spec/) (aka. canonicalization) converts the document into a graph of objects that is a canonical representation of the document that can be used for hashing, comparison, etc. ```csharp var doc = JObject.Parse(_docJson); From ef015dfbc0835f312af6c8dfe6574a66c293728f Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 21:55:50 +0100 Subject: [PATCH 08/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0f62c4c..c01e3f7 100644 --- a/README.md +++ b/README.md @@ -341,8 +341,9 @@ Output: */ ``` +### ToRDF -### ToRDF (N-Quads) + (N-Quads) ```csharp var doc = JObject.Parse(_docJson); From 78e4d49f5d33bfabea684ea109376c167a6b1aa4 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 21:55:59 +0100 Subject: [PATCH 09/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c01e3f7..7738d58 100644 --- a/README.md +++ b/README.md @@ -396,7 +396,9 @@ internal static void Run() } ``` -### fromRDF (N-Quads) +### FromRDF + + (N-Quads) ```csharp var opts = new JsonLdOptions(); From 90ce90a11a720488010d76e0016e059a04b03de1 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 21:56:09 +0100 Subject: [PATCH 10/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7738d58..5fedd4f 100644 --- a/README.md +++ b/README.md @@ -447,7 +447,7 @@ Output: */ ``` -_or_ using a custom RDF parser +_or_ using a custom RDF parser: ```csharp private class CustomRDFParser : IRDFParser From 405d0d62209c10efe27326a2755e86020f829098 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 21:59:47 +0100 Subject: [PATCH 11/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 5fedd4f..cbc2df7 100644 --- a/README.md +++ b/README.md @@ -509,8 +509,7 @@ internal static void Run() } ``` - -### Custom documentLoader +### Custom DocumentLoader ```csharp public class CustomDocumentLoader : DocumentLoader From fe6f0b77243526c575784831abed11cd15c72cd3 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 22:09:46 +0100 Subject: [PATCH 12/19] lines broken into 80 characters or less (except where for code samples or URLs) --- README.md | 61 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index cbc2df7..8708147 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,31 @@ ## Introduction This library is an implementation of the JSON-LD specification in C#. -JSON, as specified in RFC7159, is a simple language for representing objects on the Web. Linked Data is a way of describing content across different documents or Web sites. Web resources are described using IRIs, and typically are dereferencable entities that may be used to find more information, creating a "Web of Knowledge". JSON-LD is intended to be a simple publishing method for expressing not only Linked Data in JSON, but for adding semantics to existing JSON. - -JSON-LD is designed as a light-weight syntax that can be used to express Linked Data. It is primarily intended to be a way to express Linked Data in JavaScript and other Web-based programming environments. It is also useful when building interoperable Web Services and when storing Linked Data in JSON-based document storage engines. It is practical and designed to be as simple as possible, utilizing the large number of JSON parsers and existing code that is in use today. It is designed to be able to express key-value pairs, RDF data, RDFa data, Microformats data, and Microdata. That is, it supports every major Web-based structured data model in use today. - -The syntax does not require many applications to change their JSON, but easily add meaning by adding context in a way that is either in-band or out-of-band. The syntax is designed to not disturb already deployed systems running on JSON, but provide a smooth migration path from plain JSON to semantically enhanced JSON. Finally, the format is intended to be fast to parse, fast to generate, stream-based and document-based processing compatible, and require a very small memory footprint in order to operate. +JSON, as specified in RFC7159, is a simple language for representing objects on +the Web. Linked Data is a way of describing content across different documents +or Web sites. Web resources are described using IRIs, and typically are +dereferencable entities that may be used to find more information, creating a +"Web of Knowledge". JSON-LD is intended to be a simple publishing method for +expressing not only Linked Data in JSON, but for adding semantics to existing +JSON. + +JSON-LD is designed as a light-weight syntax that can be used to express Linked +Data. It is primarily intended to be a way to express Linked Data in JavaScript +and other Web-based programming environments. It is also useful when building +interoperable Web Services and when storing Linked Data in JSON-based document +storage engines. It is practical and designed to be as simple as possible, +utilizing the large number of JSON parsers and existing code that is in use +today. It is designed to be able to express key-value pairs, RDF data, RDFa +data, Microformats data, and Microdata. That is, it supports every major +Web-based structured data model in use today. + +The syntax does not require many applications to change their JSON, but easily +add meaning by adding context in a way that is either in-band or out-of-band. +The syntax is designed to not disturb already deployed systems running on JSON, +but provide a smooth migration path from plain JSON to semantically enhanced +JSON. Finally, the format is intended to be fast to parse, fast to generate, +stream-based and document-based processing compatible, and require a very small +memory footprint in order to operate. You can read more about JSON-LD on the [JSON-LD website][jsonld]. @@ -19,8 +39,10 @@ You can read more about JSON-LD on the [JSON-LD website][jsonld]. This library aims to conform with the following: -* [JSON-LD 1.0][JSON-LD 1.0], W3C Recommendation, 2014-01-16, and any [errata][errata] -* [JSON-LD 1.0 Processing Algorithms and API][JSON-LD 1.0 API], W3C Recommendation, 2014-01-16, and any [errata][errata] +* [JSON-LD 1.0][JSON-LD 1.0], W3C Recommendation, 2014-01-16, and any +[errata][errata] +* [JSON-LD 1.0 Processing Algorithms and API][JSON-LD 1.0 API], W3C +Recommendation, 2014-01-16, and any [errata][errata] * [JSON-LD 1.0 Framing][JSON-LD 1.0 Framing], Unofficial Draft, 2012-08-30 * Working Group [test suite][WG test suite] @@ -28,12 +50,15 @@ The [JSON-LD Working Group][JSON-LD WG] is now developing JSON-LD 1.1. Library updates to conform with newer specifications will happen as features stabilize and development time and resources permit. -* [JSON-LD 1.1][JSON-LD WG 1.1], W3C Working Draft, 2018-12-14 or [newer][JSON-LD WG latest] -* [JSON-LD 1.1 Processing Algorithms and API][JSON-LD WG 1.1 API], W3C Working Draft, 2018-12-14 or [newer][JSON-LD WG API latest] -* [JSON-LD 1.1 Framing][JSON-LD WG 1.1 Framing], W3C Working Draft, 2018-12-14 or [newer][JSON-LD WG Framing latest] +* [JSON-LD 1.1][JSON-LD WG 1.1], W3C Working Draft, 2018-12-14 or +[newer][JSON-LD WG latest] +* [JSON-LD 1.1 Processing Algorithms and API][JSON-LD WG 1.1 API], W3C Working +Draft, 2018-12-14 or [newer][JSON-LD WG API latest] +* [JSON-LD 1.1 Framing][JSON-LD WG 1.1 Framing], W3C Working Draft, 2018-12-14 +or [newer][JSON-LD WG Framing latest] -The [test runner][] is often updated to note or skip newer tests that are not -yet supported. +The [test runner][test runner] is often updated to note or skip newer tests that +are not yet supported. ## Supported frameworks @@ -263,7 +288,10 @@ Output: ### Normalize -[Normalization](http://json-ld.github.io/normalization/spec/) (aka. canonicalization) converts the document into a graph of objects that is a canonical representation of the document that can be used for hashing, comparison, etc. +[Normalization](http://json-ld.github.io/normalization/spec/) (aka. +canonicalization) converts the document into a graph of objects that is a +canonical representation of the document that can be used for hashing, +comparison, etc. ```csharp var doc = JObject.Parse(_docJson); @@ -559,7 +587,9 @@ public static void Run() ## Contributing -This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc-faq] or contact [opencode@microsoft.com][ms-mail] with any additional questions or comments. +This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For +more information see the [Code of Conduct FAQ][coc-faq] or contact +[opencode@microsoft.com][ms-mail] with any additional questions or comments. Pull requests for json-ld.net are welcome, to get started install the latest tools for .NET Core: @@ -582,7 +612,8 @@ On both Windows and all other supported operating systems, you can run This project began life as a [Sharpen][sharpen]-based auto-port from [jsonld-java][jsonld-java]. -Documentation for this library is in part drawn from https://github.com/linked-data-dotnet/json-ld.net +Documentation for this library is in part drawn from +https://github.com/linked-data-dotnet/json-ld.net [coc]: https://opensource.microsoft.com/codeofconduct/ [coc-faq]: https://opensource.microsoft.com/codeofconduct/faq/ From 5bb50937f3ef3c197e5c7c1b0d9da8cb54e8fc84 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 22:24:58 +0100 Subject: [PATCH 13/19] fixed link bugs and normalised to use kebab-case for link references --- README.md | 48 +++++++++++++++++++++++++----------------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 8708147..ad2f4c5 100644 --- a/README.md +++ b/README.md @@ -39,25 +39,25 @@ You can read more about JSON-LD on the [JSON-LD website][jsonld]. This library aims to conform with the following: -* [JSON-LD 1.0][JSON-LD 1.0], W3C Recommendation, 2014-01-16, and any +* [JSON-LD 1.0][json-ld-10], W3C Recommendation, 2014-01-16, and any [errata][errata] -* [JSON-LD 1.0 Processing Algorithms and API][JSON-LD 1.0 API], W3C +* [JSON-LD 1.0 Processing Algorithms and API][json-ld-10-api], W3C Recommendation, 2014-01-16, and any [errata][errata] -* [JSON-LD 1.0 Framing][JSON-LD 1.0 Framing], Unofficial Draft, 2012-08-30 -* Working Group [test suite][WG test suite] +* [JSON-LD 1.0 Framing][json-ld-10-framing], Unofficial Draft, 2012-08-30 +* Working Group [test suite][wg-test-suite] -The [JSON-LD Working Group][JSON-LD WG] is now developing JSON-LD 1.1. Library +The [JSON-LD Working Group][json-ld-wg] is now developing JSON-LD 1.1. Library updates to conform with newer specifications will happen as features stabilize and development time and resources permit. -* [JSON-LD 1.1][JSON-LD WG 1.1], W3C Working Draft, 2018-12-14 or -[newer][JSON-LD WG latest] -* [JSON-LD 1.1 Processing Algorithms and API][JSON-LD WG 1.1 API], W3C Working -Draft, 2018-12-14 or [newer][JSON-LD WG API latest] -* [JSON-LD 1.1 Framing][JSON-LD WG 1.1 Framing], W3C Working Draft, 2018-12-14 -or [newer][JSON-LD WG Framing latest] +* [JSON-LD 1.1][json-ld-wg-11], W3C Working Draft, 2018-12-14 or +[newer][json-ld-wg-latest] +* [JSON-LD 1.1 Processing Algorithms and API][json-ld-wg-11-api], W3C Working +Draft, 2018-12-14 or [newer][json-ld-wg-api-latest] +* [JSON-LD 1.1 Framing][json-ld-wg-11-framing], W3C Working Draft, 2018-12-14 +or [newer][json-ld-wg-framing-latest] -The [test runner][test runner] is often updated to note or skip newer tests that +The [test runner][test-runner] is often updated to note or skip newer tests that are not yet supported. ## Supported frameworks @@ -620,6 +620,8 @@ https://github.com/linked-data-dotnet/json-ld.net [codecov]: https://codecov.io/gh/linked-data-dotnet/json-ld.net [codecov-badge]: https://img.shields.io/codecov/c/github/linked-data-dotnet/json-ld.net/master.svg + [errata]: http://www.w3.org/2014/json-ld-errata + [ms-mail]: mailto:opencode@microsoft.com [dnc]: https://dot.net [dnc-tutorial]: https://www.microsoft.com/net/core @@ -629,22 +631,22 @@ https://github.com/linked-data-dotnet/json-ld.net [jsonld]: https://json-ld.org/ [jsonld-java]: https://github.com/jsonld-java/jsonld-java - [json-ld-1.0]: http://www.w3.org/TR/2014/REC-json-ld-20140116/ - [JSON-LD 1.0 API]: http://www.w3.org/TR/2014/REC-json-ld-api-20140116/ - [JSON-LD 1.0 Framing]: https://json-ld.org/spec/ED/json-ld-framing/20120830/ + [json-ld-10]: http://www.w3.org/TR/2014/REC-json-ld-20140116/ + [json-ld-10-api]: http://www.w3.org/TR/2014/REC-json-ld-api-20140116/ + [json-ld-10-framing]: https://json-ld.org/spec/ED/json-ld-framing/20120830/ - [JSON-LD WG 1.1]: https://www.w3.org/TR/json-ld11/ - [JSON-LD WG 1.1 API]: https://www.w3.org/TR/json-ld11-api/ - [JSON-LD WG 1.1 Framing]: https://www.w3.org/TR/json-ld11-framing/ + [json-ld-wg-11]: https://www.w3.org/TR/json-ld11/ + [json-ld-wg-11-api]: https://www.w3.org/TR/json-ld11-api/ + [json-ld-wg-11-framing]: https://www.w3.org/TR/json-ld11-framing/ - [JSON-LD WG latest]: https://w3c.github.io/json-ld-syntax/ - [JSON-LD WG API latest]: https://w3c.github.io/json-ld-api/ - [JSON-LD WG Framing latest]: https://w3c.github.io/json-ld-framing/ + [json-ld-wg-latest]: https://w3c.github.io/json-ld-syntax/ + [json-ld-wg-api-latest]: https://w3c.github.io/json-ld-api/ + [json-ld-wg-framing-latest]: https://w3c.github.io/json-ld-framing/ [nuget]: https://www.nuget.org/packages/json-ld.net/ [nuget-badge]: https://img.shields.io/nuget/v/json-ld.net.svg [sharpen]: http://community.versant.com/Projects/html/projectspaces/db4o_product_design/sharpen.html - [test runner]: https://github.com/linked-data-dotnet/json-ld.net/tree/master/test/json-ld.net.tests - [WG test suite]: https://github.com/w3c/json-ld-api/tree/master/tests + [test-runner]: https://github.com/linked-data-dotnet/json-ld.net/tree/master/test/json-ld.net.tests + [wg-test-suite]: https://github.com/w3c/json-ld-api/tree/master/tests From ae58f1ddce33d3c127b17d26d1bda35368e58deb Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 22:26:50 +0100 Subject: [PATCH 14/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ad2f4c5..ceb4e5e 100644 --- a/README.md +++ b/README.md @@ -241,8 +241,9 @@ Output: ``` +### Frame -### [frame](http://json-ld.org/spec/latest/json-ld-framing/#introduction) +[Frame](http://json-ld.org/spec/latest/json-ld-framing/#introduction). For the framing example below, the framing document is defined as follows: From a90cd39d642135476c57a823345b6d6c313ce1d6 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 22:27:09 +0100 Subject: [PATCH 15/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ceb4e5e..97ff5ac 100644 --- a/README.md +++ b/README.md @@ -204,8 +204,9 @@ Output: */ ``` +### Flatten -### [flatten](http://json-ld.org/spec/latest/json-ld/#flattened-document-form) +[Flatten](http://json-ld.org/spec/latest/json-ld/#flattened-document-form). ```csharp var doc = JObject.Parse(_docJson); From 5c673382a9ba0f369f0248bebd105ab5d8c0d645 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 22:27:23 +0100 Subject: [PATCH 16/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 97ff5ac..cb62385 100644 --- a/README.md +++ b/README.md @@ -158,8 +158,9 @@ Output: */ ``` +### Expand -### [expand](http://json-ld.org/spec/latest/json-ld/#expanded-document-form) +[Expand](http://json-ld.org/spec/latest/json-ld/#expanded-document-form). ```csharp var expanded = JsonLdProcessor.Expand(compacted); From 6ea46a58d46f6fd59b9208a8caf27dfe60b0da0f Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 22:31:11 +0100 Subject: [PATCH 17/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index cb62385..c766a6e 100644 --- a/README.md +++ b/README.md @@ -263,6 +263,7 @@ For the framing example below, the framing document is defined as follows: ``` And we use it like this: + ```csharp var doc = JObject.Parse(_docJson); var frame = JObject.Parse(_frameJson); From 536400796ec12b261d1e0fd34c11f372b4d53888 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 22:31:25 +0100 Subject: [PATCH 18/19] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Asbjørn Ulsberg --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c766a6e..3ea8f25 100644 --- a/README.md +++ b/README.md @@ -130,8 +130,9 @@ Example data and context used throughout examples below: } ``` +### Compact -### [compact](http://json-ld.org/spec/latest/json-ld/#compacted-document-form) +[Compact](http://json-ld.org/spec/latest/json-ld/#compacted-document-form). ```csharp var doc = JObject.Parse(_docJson); From 70ab9c68e5dfed51069c5a3cd90f2b75873f5415 Mon Sep 17 00:00:00 2001 From: Andrew Stewart Gibson Date: Tue, 7 Jul 2020 23:10:21 +0100 Subject: [PATCH 19/19] descriptions of various algorithms and utility methods added --- README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 61 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 3ea8f25..39870e7 100644 --- a/README.md +++ b/README.md @@ -132,7 +132,12 @@ Example data and context used throughout examples below: ### Compact -[Compact](http://json-ld.org/spec/latest/json-ld/#compacted-document-form). +[Compaction](http://json-ld.org/spec/latest/json-ld/#compacted-document-form) is +the process of applying a developer-supplied context to shorten IRIs to terms or +compact IRIs, and JSON-LD values expressed in expanded form to simple values +such as strings or numbers. Often this makes it simpler to work with a document +as the data is expressed in application-specific terms. Compacted documents are +also typically easier to read for humans. ```csharp var doc = JObject.Parse(_docJson); @@ -161,7 +166,11 @@ Output: ### Expand -[Expand](http://json-ld.org/spec/latest/json-ld/#expanded-document-form). + +[Exapansion](http://json-ld.org/spec/latest/json-ld/#expanded-document-form) is +the process of taking a JSON-LD document and applying a @context such that all +IRIs, types, and values are expanded so that the @context is no longer +necessary. ```csharp var expanded = JsonLdProcessor.Expand(compacted); @@ -208,7 +217,11 @@ Output: ### Flatten -[Flatten](http://json-ld.org/spec/latest/json-ld/#flattened-document-form). +[Flattening](http://json-ld.org/spec/latest/json-ld/#flattened-document-form) +collects all properties of a node in a single JSON object and labels all blank +nodes with blank node identifiers. This ensures a shape of the data and +consequently may drastically simplify the code required to process JSON-LD in +certain applications. ```csharp var doc = JObject.Parse(_docJson); @@ -246,7 +259,17 @@ Output: ### Frame -[Frame](http://json-ld.org/spec/latest/json-ld-framing/#introduction). +[Framing](http://json-ld.org/spec/latest/json-ld-framing/#introduction) is used +to shape the data in a JSON-LD document, using an example frame document which +is used to both match the flattened data and show an example of how the +resulting data should be shaped. Matching is performed by using properties +present in the frame to find objects in the data that share common values. +Matching can be done either using all properties present in the frame, or any +property in the frame. By chaining together objects using matched property +values, objects can be embedded within one another. + +A frame also includes a context, which is used for compacting the resulting +framed output. For the framing example below, the framing document is defined as follows: @@ -376,7 +399,20 @@ Output: ### ToRDF - (N-Quads) +JSON-LD is a concrete RDF syntax as described in [RDF 1.1 Concepts and Abstract +Syntax][rdf-11-concepts]. Hence, a JSON-LD document is both an RDF document and a +JSON document and correspondingly represents an instance of an RDF data model. +The procedure to deserialize a JSON-LD document to an +[RDF dataset][rdf-11-dataset] (and, optionally, to [RDF N-Quads][n-quads]) +involves the following steps: + +1. Expand the JSON-LD document, removing any context; this ensures that +properties, types, and values are given their full representation as IRIs and +expanded values. +1. Flatten the document, which turns the document into an array of node objects. +1. Turn each node object into a series of RDF N-Quads. + +The processor's `ToRDF` method carries out these steps for you, like this: ```csharp var doc = JObject.Parse(_docJson); @@ -399,7 +435,7 @@ _:b0