README.md in json-ld-3.1.4 vs README.md in json-ld-3.1.5

- old
+ new

@@ -23,25 +23,29 @@ This gem implements an optimized streaming reader used for generating RDF from large dataset dumps formatted as JSON-LD. Such documents must correspond to the [JSON-LD Streaming Profile](https://w3c.github.io/json-ld-streaming/): * Keys in JSON objects must be ordered with any of `@context`, and/or `@type` coming before any other keys, in that order. This includes aliases of those keys. It is strongly encouraged that `@id` be present, and come immediately after. * JSON-LD documents can be signaled or requested in [streaming document form](https://w3c.github.io/json-ld-streaming/#dfn-streaming-document-form). The profile URI identifying the [streaming document form](https://w3c.github.io/json-ld-streaming/#dfn-streaming-document-form) is `http://www.w3.org/ns/json-ld#streaming`. -### MultiJson parser -The [MultiJson](https://rubygems.org/gems/multi_json) gem is used for parsing JSON; this defaults to the native JSON parser, but will use a more performant parser if one is available. A specific parser can be specified by adding the `:adapter` option to any API call. See [MultiJson](https://rubygems.org/gems/multi_json) for more information. +This gem also implements an optimized streaming writer used for generating JSON-LD from large repositories. Such documents result in the JSON-LD Streaming Profile: -### JSON-LD Streaming Profile -This gem implements an optimized streaming writer used for generating JSON-LD from large repositories. Such documents result in the JSON-LD Streaming Profile: - * Each statement written as a separate node in expanded/flattened form. -* RDF Lists are written as separate nodes using `rdf:first` and `rdf:rest` properties. +* `RDF List`s are written as separate nodes using `rdf:first` and `rdf:rest` properties. +The order of triples retrieved from the `RDF::Enumerable` dataset determines the way that JSON-LD node objects are written; for best results, statements should be ordered by _graph name_, _subect_, _predicate_ and _object_. + +### MultiJson parser +The [MultiJson](https://rubygems.org/gems/multi_json) gem is used for parsing JSON; this defaults to the native JSON parser, but will use a more performant parser if one is available. A specific parser can be specified by adding the `:adapter` option to any API call. See [MultiJson](https://rubygems.org/gems/multi_json) for more information. + ## Examples + ```ruby require 'rubygems' require 'json/ld' ``` + ### Expand a Document + ```ruby input = JSON.parse %({ "@context": { "name": "http://xmlns.com/foaf/0.1/name", "homepage": "http://xmlns.com/foaf/0.1/homepage", @@ -57,12 +61,13 @@ "http://xmlns.com/foaf/0.1/name": [{"@value"=>"Manu Sporny"}], "http://xmlns.com/foaf/0.1/homepage": [{"@value"=>"https://manu.sporny.org/"}], "http://xmlns.com/foaf/0.1/avatar": [{"@value": "https://twitter.com/account/profile_image/manusporny"}] }] ``` + ### Compact a Document -```ruby + input = JSON.parse %([{ "http://xmlns.com/foaf/0.1/name": ["Manu Sporny"], "http://xmlns.com/foaf/0.1/homepage": [{"@id": "https://manu.sporny.org/"}], "http://xmlns.com/foaf/0.1/avatar": [{"@id": "https://twitter.com/account/profile_image/manusporny"}] }]) @@ -84,13 +89,13 @@ }, "avatar": "https://twitter.com/account/profile_image/manusporny", "homepage": "https://manu.sporny.org/", "name": "Manu Sporny" } -``` + ### Frame a Document -```ruby + input = JSON.parse %({ "@context": { "Book": "http://example.org/vocab#Book", "Chapter": "http://example.org/vocab#Chapter", "contains": {"@id": "http://example.org/vocab#contains", "@type": "@id"}, @@ -167,13 +172,13 @@ "title": "The Republic" } } ] } -``` + ### Turn JSON-LD into RDF (Turtle) -```ruby + input = JSON.parse %({ "@context": { "": "https://manu.sporny.org/", "foaf": "http://xmlns.com/foaf/0.1/" }, @@ -190,13 +195,13 @@ @prefix foaf: <http://xmlns.com/foaf/0.1/> . <http://example.org/people#joebob> a foaf:Person; foaf:name "Joe Bob"; foaf:nick ("joe" "bob" "jaybe") . -``` + ### Turn RDF into JSON-LD -```ruby + require 'rdf/turtle' input = RDF::Graph.new << RDF::Turtle::Reader.new(%( @prefix foaf: <http://xmlns.com/foaf/0.1/> . <https://manu.sporny.org/#me> a foaf:Person; @@ -228,56 +233,63 @@ "@type": ["http://xmlns.com/foaf/0.1/Person"], "http://xmlns.com/foaf/0.1/knows": [{"@id": "_:g70265766605380"}], "http://xmlns.com/foaf/0.1/name": [{"@value": "Manu Sporny"}] } ] -``` + ## Use a custom Document Loader In some cases, the built-in document loader {JSON::LD::API.documentLoader} is inadequate; for example, when using `http://schema.org` as a remote context, it will be re-loaded every time (however, see [json-ld-preloaded](https://rubygems.org/gems/json-ld-preloaded)). All entries into the {JSON::LD::API} accept a `:documentLoader` option, which can be used to provide an alternative method to use when loading remote documents. For example: + ```ruby load_document_local = Proc.new do |url, **options, &block| if RDF::URI(url, canonicalize: true) == RDF::URI('http://schema.org/') remote_document = JSON::LD::API::RemoteDocument.new(url, File.read("etc/schema.org.jsonld")) return block_given? ? yield(remote_document) : remote_document else JSON::LD::API.documentLoader(url, options, &block) end end + ``` Then, when performing something like expansion: + ```ruby JSON::LD::API.expand(input, documentLoader: load_document_local) ``` ## Preloading contexts In many cases, for small documents, processing time can be dominated by loading and parsing remote contexts. In particular, a small schema.org example may need to download a large context and turn it into an internal representation, before the actual document can be expanded for processing. Using {JSON::LD::Context.add_preloaded}, an implementation can perform this loading up-front, and make it available to the processor. + ```ruby ctx = JSON::LD::Context.new().parse('http://schema.org/') JSON::LD::Context.add_preloaded('http://schema.org/', ctx) ``` + On lookup, URIs with an `https` prefix are normalized to `http`. A context may be serialized to Ruby to speed this process using `Context#to_rb`. When loaded, this generated file will add entries to the {JSON::LD::Context::PRELOADED}. ## RDF Reader and Writer {JSON::LD} also acts as a normal RDF reader and writer, using the standard RDF.rb reader/writer interfaces: + ```ruby graph = RDF::Graph.load("etc/doap.jsonld", format: :jsonld) graph.dump(:jsonld, standard_prefixes: true) ``` + `RDF::GRAPH#dump` can also take a `:context` option to use a separately defined context As JSON-LD may come from many different sources, included as an embedded script tag within an HTML document, the RDF Reader will strip input before the leading `{` or `[` and after the trailing `}` or `]`. ## Extensions from JSON-LD 1.0 This implementation is being used as a test-bed for features planned for an upcoming JSON-LD 1.1 Community release. ### Scoped Contexts A term definition can include `@context`, which is applied to values of that object. This is also used when compacting. Taken together, this allows framing to effectively include context definitions more deeply within the framed structure. -```ruby + { "@context": { "ex": "http://example.com/", "foo": { "@id": "ex:foo", @@ -288,108 +300,108 @@ } } }, "foo": "Bar" } -``` + ### @id and @type maps The value of `@container` in a term definition can include `@id` or `@type`, in addition to `@set`, `@list`, `@language`, and `@index`. This allows value indexing based on either the `@id` or `@type` of associated objects. -```ruby + { "@context": { "@vocab": "http://example/", "idmap": {"@container": "@id"} }, "idmap": { "http://example.org/foo": {"label": "Object with @id <foo>"}, "_:bar": {"label": "Object with @id _:bar"} } } -``` + ### @graph containers and maps A term can have `@container` set to include `@graph` optionally including `@id` or `@index` and `@set`. In the first form, with `@container` set to `@graph`, the value of a property is treated as a _simple graph object_, meaning that values treated as if they were contained in an object with `@graph`, creating _named graph_ with an anonymous name. -```ruby + { "@context": { "@vocab": "http://example.org/", "input": {"@container": "@graph"} }, "input": { "value": "x" } } -``` + which expands to the following: -```ruby + [{ "http://example.org/input": [{ "@graph": [{ "http://example.org/value": [{"@value": "x"}] }] }] }] -``` + Compaction reverses this process, optionally ensuring that a single value is contained within an array of `@container` also includes `@set`: -```ruby + { "@context": { "@vocab": "http://example.org/", "input": {"@container": ["@graph", "@set"]} } } -``` + A graph map uses the map form already existing for `@index`, `@language`, `@type`, and `@id` where the index is either an index value or an id. -```ruby + { "@context": { "@vocab": "http://example.org/", "input": {"@container": ["@graph", "@index"]} }, "input": { "g1": {"value": "x"} } } -``` + treats "g1" as an index, and expands to the following: -```ruby + [{ "http://example.org/input": [{ "@index": "g1", "@graph": [{ "http://example.org/value": [{"@value": "x"}] }] }] }]) -``` + This can also include `@set` to ensure that, when compacting, a single value of an index will be in array form. The _id_ version is similar: -```ruby + { "@context": { "@vocab": "http://example.org/", "input": {"@container": ["@graph", "@id"]} }, "input": { "http://example.com/g1": {"value": "x"} } } -``` + which expands to: -```ruby + [{ "http://example.org/input": [{ "@id": "http://example.com/g1", "@graph": [{ "http://example.org/value": [{"@value": "x"}] }] }] }]) -``` + ### Transparent Nesting Many JSON APIs separate properties from their entities using an intermediate object. For example, a set of possible labels may be grouped under a common property: -```json + { "@context": { "skos": "http://www.w3.org/2004/02/skos/core#", "labels": "@nest", "main_label": {"@id": "skos:prefLabel"}, @@ -401,13 +413,13 @@ "labels": { "main_label": "This is the main label for my resource", "other_label": "This is the other label" } } - ``` + In this case, the `labels` property is semantically meaningless. Defining it as equivalent to `@nest` causes it to be ignored when expanding, making it equivalent to the following: -```json + { "@context": { "skos": "http://www.w3.org/2004/02/skos/core#", "labels": "@nest", "main_label": {"@id": "skos:prefLabel"}, @@ -417,13 +429,13 @@ "@id":"http://example.org/myresource", "homepage": "http://example.org", "main_label": "This is the main label for my resource", "other_label": "This is the other label" } - ``` + Similarly, properties may be marked with "@nest": "nest-term", to cause them to be nested. Note that the `@nest` keyword can also be aliased in the context. -```json + { "@context": { "skos": "http://www.w3.org/2004/02/skos/core#", "labels": "@nest", "main_label": {"@id": "skos:prefLabel", "@nest": "labels"}, @@ -435,11 +447,11 @@ "labels": { "main_label": "This is the main label for my resource", "other_label": "This is the other label" } } -``` + In this way, nesting survives round-tripping through expansion, and framed output can include nested properties. ## Sinatra/Rack support JSON-LD 1.1 describes support for the _profile_ parameter to a media type in an HTTP ACCEPT header. This allows an HTTP request to specify the format (expanded/compacted/flattened/framed) along with a reference to a context or frame to use to format the returned document. @@ -513,18 +525,18 @@ * [JSON](https://rubygems.org/gems/json) (>= 2.2) ## Installation The recommended installation method is via [RubyGems](https://rubygems.org/). To install the latest official release of the `JSON-LD` gem, do: -```bash - % [sudo] gem install json-ld -``` + + % [sudo] gem install json-ld + ## Download To get a local working copy of the development repository, do: -```bash - % git clone git://github.com/ruby-rdf/json-ld.git -``` + + % git clone git://github.com/ruby-rdf/json-ld.git + ## Mailing List * <https://lists.w3.org/Archives/Public/public-rdf-ruby/> ## Author * [Gregg Kellogg](https://github.com/gkellogg) - <https://greggkellogg.net/> @@ -538,11 +550,13 @@ change them, do so on your private branch only. * Do feel free to add yourself to the `CREDITS` file and the corresponding list in the the `README`. Alphabetical order applies. * Do note that in order for us to merge any non-trivial changes (as a rule of thumb, additions larger than about 15 lines of code), we need an - explicit [public domain dedication][PDD] on record from you. + explicit [public domain dedication][PDD] on record from you, + which you will be asked to agree to on the first commit to a repo within the organization. + Note that the agreement applies to all repos in the [Ruby RDF](https://github.com/ruby-rdf/) organization. License ------- This is free and unencumbered public domain software. For more information, @@ -550,10 +564,10 @@ [Ruby]: https://ruby-lang.org/ [RDF]: https://www.w3.org/RDF/ [YARD]: https://yardoc.org/ [YARD-GS]: https://rubydoc.info/docs/yard/file/docs/GettingStarted.md -[PDD]: https://lists.w3.org/Archives/Public/public-rdf-ruby/2010May/0013.html +[PDD]: https://unlicense.org/#unlicensing-contributions [RDF.rb]: https://rubygems.org/gems/rdf [Rack::LinkedData]: https://rubygems.org/gems/rack-linkeddata [Backports]: https://rubygems.org/gems/backports [JSON-LD]: https://www.w3.org/TR/json-ld11/ "JSON-LD 1.1" [JSON-LD API]: https://www.w3.org/TR/json-ld11-api/ "JSON-LD 1.1 Processing Algorithms and API"