json-ld 3.1.0 → 3.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9fcb46a6c6bf33bfed92adcc8a751598cec5d6511e0450d38c9920bfdb696ce
-  data.tar.gz: 6fec905be8d5e0335149da757fef899d6e3fa948e852f74e9c88d0bff45801ae
+  metadata.gz: 65b570568511427e573b9ffecdc5eedfee1b708c62e88ffc24dce4ffa8d62c2f
+  data.tar.gz: a3255398de49dd88c3d4b3beb918857c8939de6eed4cf92c2aa1f61764455b59
 SHA512:
-  metadata.gz: 1a7d07de17bc462f2f38fc24ae7c2a04a2c1ffd24d0a431626771259d59ffd6fe4b33b4ea8501add71d710e3c4501897454aada60ff6054fa9a12ef69cf488f3
-  data.tar.gz: 48da4933e6660ccd7cffe9cdcb08b576d883f1c744a889867b5e8619f9c3908fad00af02a739bc9af5c1abd7495d3cb9517d914ee12f7ac4f48acf94b5b9b637
+  metadata.gz: 6f84d29c4d742ffe07dbdc585f8d51e612b7426dc3a58d21061d959587ebdfff0801bc02d3c7edf11426d03d6b9d500a54bdd172afc34b460bd5957fc0f9e4c5
+  data.tar.gz: ee8b915d0fb258e909e751c668ea31750b255d5d7e0276123439a149eece298284324fb63a8d13df9b23109f0662dcbcd0db41f56e23e22f745da17f50f7b75b

data/README.md

@@ -19,21 +19,31 @@ JSON::LD can now be used to create a _context_ from an RDFS/OWL definition, and
 
 Install with `gem install json-ld`
 
-### 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.
-
 ### 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:
+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`.
+
+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:
 
 * 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": {
@@ -53,8 +63,9 @@ require 'json/ld'
         "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/"}],
@@ -80,9 +91,9 @@ require 'json/ld'
         "homepage": "https://manu.sporny.org/",
         "name": "Manu Sporny"
     }
-```
+
 ### Frame a Document
-```ruby
+
     input = JSON.parse %({
       "@context": {
         "Book":         "http://example.org/vocab#Book",
@@ -163,9 +174,9 @@ require 'json/ld'
         }
       ]
     }
-```
+
 ### Turn JSON-LD into RDF (Turtle)
-```ruby
+
     input = JSON.parse %({
       "@context": {
         "":       "https://manu.sporny.org/",
@@ -186,9 +197,9 @@ require 'json/ld'
     <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/> .
@@ -224,13 +235,14 @@ require 'json/ld'
           "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
-def load_document_local(url, options={}, &block)
+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
@@ -238,28 +250,34 @@ def load_document_local(url, options={}, &block)
     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 `]`.
@@ -269,7 +287,7 @@ This implementation is being used as a test-bed for features planned for an upco
 
 ### 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/",
@@ -284,10 +302,10 @@ A term definition can include `@context`, which is applied to values of that obj
       },
       "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/",
@@ -298,10 +316,10 @@ The value of `@container` in a term definition can include `@id` or `@type`, in
         "_: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/",
@@ -311,9 +329,9 @@ A term can have `@container` set to include `@graph` optionally including `@id`
         "value": "x"
       }
     }
-```
+
 which expands to the following:
-```ruby
+
     [{
       "http://example.org/input": [{
         "@graph": [{
@@ -321,18 +339,18 @@ which expands to the following:
         }]
       }]
     }]
-```
+
 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/",
@@ -342,9 +360,9 @@ A graph map uses the map form already existing for `@index`, `@language`, `@type
         "g1": {"value": "x"}
       }
     }
-```
+
 treats "g1" as an index, and expands to the following:
-```ruby
+
     [{
       "http://example.org/input": [{
         "@index": "g1",
@@ -353,11 +371,11 @@ treats "g1" as an index, and expands to the following:
         }]
       }]
     }])
-```
+
 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/",
@@ -367,9 +385,9 @@ The _id_ version is similar:
         "http://example.com/g1": {"value": "x"}
       }
     }
-```
+
 which expands to:
-```ruby
+
     [{
       "http://example.org/input": [{
         "@id": "http://example.com/g1",
@@ -378,10 +396,10 @@ which expands to:
         }]
       }]
     }])
-```
+
 ### 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#",
@@ -397,9 +415,9 @@ Many JSON APIs separate properties from their entities using an intermediate obj
          "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#",
@@ -413,9 +431,9 @@ Many JSON APIs separate properties from their entities using an intermediate obj
       "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#",
@@ -431,7 +449,7 @@ Many JSON APIs separate properties from their entities using an intermediate obj
           "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
@@ -509,14 +527,14 @@ Note, the API method signatures differed in versions before 1.0, in that they al
 ## 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/>
 
@@ -534,7 +552,9 @@ To get a local working copy of the development repository, do:
   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
 -------
@@ -546,7 +566,7 @@ see <https://unlicense.org/> or the accompanying {file:UNLICENSE} file.
 [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

data/VERSION

@@ -1 +1 @@
-3.1.0
+3.1.5

data/bin/jsonld

@@ -10,7 +10,7 @@ require 'getoptlong'
 require 'open-uri'
 require 'logger'
 
-def run(input, options)
+def run(input, options, parser_options)
   reader_class = RDF::Reader.for(options[:input_format].to_sym)
   raise "Reader not found for #{options[:input_format]}" unless reader_class
 
@@ -19,38 +19,38 @@ def run(input, options)
 
   # If input format is not JSON-LD, transform input to JSON-LD first
   reader = if options[:input_format] != :jsonld
-    reader_class.new(input, options[:parser_options])
+    reader_class.new(input, parser_options)
   end
 
   start = Time.new
   if options[:expand]
-    options = options.merge(expandContext: options.delete(:context)) if options.has_key?(:context)
+    parser_options = parser_options.merge(expandContext: parser_options.delete(:context)) if parser_options.has_key?(:context)
     input = JSON::LD::API.fromRdf(reader) if reader
-    output = JSON::LD::API.expand(input, options)
+    output = JSON::LD::API.expand(input, parser_options)
     secs = Time.new - start
     options[:output].puts output.to_json(JSON::LD::JSON_STATE)
     STDERR.puts "Expanded in #{secs} seconds." unless options[:quiet]
   elsif options[:compact]
     input = JSON::LD::API.fromRdf(reader) if reader
-    output = JSON::LD::API.compact(input, options[:context], options)
+    output = JSON::LD::API.compact(input, parser_options[:context], parser_options)
     secs = Time.new - start
     options[:output].puts output.to_json(JSON::LD::JSON_STATE)
     STDERR.puts "Compacted in #{secs} seconds." unless options[:quiet]
   elsif options[:flatten]
     input = JSON::LD::API.fromRdf(reader) if reader
-    output = JSON::LD::API.flatten(input, options[:context], options)
+    output = JSON::LD::API.flatten(input, parser_options[:context], parser_options)
     secs = Time.new - start
     options[:output].puts output.to_json(JSON::LD::JSON_STATE)
     STDERR.puts "Flattened in #{secs} seconds." unless options[:quiet]
   elsif options[:frame]
     input = JSON::LD::API.fromRdf(reader) if reader
-    output = JSON::LD::API.frame(input, options[:frame], options)
+    output = JSON::LD::API.frame(input, parser_options[:frame], parser_options)
     secs = Time.new - start
     options[:output].puts output.to_json(JSON::LD::JSON_STATE)
     STDERR.puts "Framed in #{secs} seconds." unless options[:quiet]
   else
-    options = options.merge(expandContext: options.delete(:context)) if options.has_key?(:context)
-    parser_options = options[:parser_options].merge(standard_prefixes: true)
+    parser_options = parser_options.merge(expandContext: parser_options.delete(:context)) if parser_options.has_key?(:context)
+    parser_options[:standard_prefixes] = true
     reader ||= JSON::LD::Reader.new(input, parser_options)
     num = 0
     RDF::Writer.for(options[:output_format]).new(options[:output], parser_options) do |w|
@@ -86,7 +86,6 @@ parser_options = {
 }
 
 options = {
-  parser_options: parser_options,
   output:         STDOUT,
   output_format:  :jsonld,
   input_format:   :jsonld,
@@ -141,49 +140,47 @@ opts = GetoptLong.new(*OPT_ARGS.map {|o| o[0..-2]})
 opts.each do |opt, arg|
   case opt
   when '--debug'          then logger.level = Logger::DEBUG
-  when '--compact'        then options[:compact] = true
-  when "--compactArrays"  then options[:compactArrays] = (arg || 'true') == 'true'
-  when '--context'        then options[:context] = arg
+  when '--compact'        then parser_options[:compact] = true
+  when "--compactArrays"  then parser_options[:compactArrays] = (arg || 'true') == 'true'
+  when '--context'        then parser_options[:context] = RDF::URI(arg).absolute? ? arg : File.open(arg)
   when '--evaluate'       then input = arg
   when '--expand'         then options[:expand] = true
-  when "--expanded"       then options[:expanded] = (arg || 'true') == 'true'
-  when "--explicit"       then options[:compactArrays] = (arg || 'true') == 'true'
+  when "--expanded"       then parser_options[:expanded] = (arg || 'true') == 'true'
+  when "--explicit"       then parser_options[:compactArrays] = (arg || 'true') == 'true'
   when '--format'         then options[:output_format] = arg.to_sym
   when '--flatten'        then options[:flatten] = arg
-  when '--frame'          then options[:frame] = arg
+  when '--frame'          then options[:frame] = parser_otpions[:frame] = RDF::URI(arg).absolute? ? arg : File.open(arg)
   when '--input-format'   then options[:input_format] = arg.to_sym
-  when "--omitDefault"    then options[:omitDefault] = (arg || 'true') == 'true'
+  when "--omitDefault"    then parser_options[:omitDefault] = (arg || 'true') == 'true'
   when '--output'         then options[:output] = File.open(arg, "w")
   when '--parse-only'     then options[:parse_only] = true
-  when '--processingMode' then options[:processingMode] = arg
+  when '--processingMode' then parser_options[:processingMode] = arg
   when '--quiet'
     options[:quiet] = true
     logger.level = Logger::FATAL
-  when "--rename_bnodes"  then options[:rename_bnodes] = (arg || 'true') == 'true'
-  when "--requireAll"     then options[:requireAll] = (arg || 'true') == 'true'
+  when "--rename_bnodes"  then parser_options[:rename_bnodes] = (arg || 'true') == 'true'
+  when "--requireAll"     then parser_options[:requireAll] = (arg || 'true') == 'true'
   when '--stream'         then parser_options[:stream] = true
-  when "--unique_bnodes"  then options[:unique_bnodes] = (arg || 'true') == 'true'
+  when "--unique_bnodes"  then parser_options[:unique_bnodes] = (arg || 'true') == 'true'
   when '--uri'            then parser_options[:base] = arg
   when '--validate'       then parser_options[:validate] = true
   when '--help'           then usage
   when '--embed'
     case arg
-    when '@always', '@never', '@link', '@last', '@first'
-      options[:embed] = arg
+    when '@always', '@never', '@link', '@once'
+      parser_options[:embed] = arg
     when 'true'
-      options[:embed] = '@never'
+      parser_options[:embed] = '@never'
     when 'false'
-      options[:embed] = '@first'
+      parser_options[:embed] = '@first'
     else
-      STDERR.puts "--embed option takes one of @always, @never, @link, @first, or @last"
+      STDERR.puts "--embed option takes one of @always, @never, @link, or @once"
       exit(1)
     end
   end
 end
 
 # Hack
-options[:parser_options][:context] = options[:context] if parser_options[:stream]
-
 if !(options.keys & [:expand, :compact, :flatten, :frame]).empty? &&
    (parser_options[:stream] || options[:output_format] != :jsonld)
    STDERR.puts "Incompatible options"
@@ -192,11 +189,11 @@ end
 
 if ARGV.empty?
   s = input ? input : $stdin.read
-  run(StringIO.new(s), options)
+  run(StringIO.new(s), options, parser_options)
 else
   ARGV.each do |file|
     # Call with opened files
-    RDF::Util::File.open_file(file, options) {|f| run(f, options)}
+    RDF::Util::File.open_file(file, options) {|f| run(f, options, parser_options)}
   end
 end
 puts