Class: JSON::LD::API
- Inherits:
-
Object
- Object
- JSON::LD::API
- Defined in:
- lib/json/ld/api.rb
Overview
A JSON-LD processor based on the JsonLdProcessor interface.
This API provides a clean mechanism that enables developers to convert JSON-LD data into a a variety of output formats that are easier to work with in various programming languages. If a JSON-LD API is provided in a programming environment, the entirety of the following API must be implemented.
Note that the API method signatures are somewhat different than what is specified, as the use of Futures and explicit callback parameters is not as relevant for Ruby-based interfaces.
Defined Under Namespace
Classes: RemoteDocument
Constant Summary collapse
- OPEN_OPTS =
Options used for open_file
{ :headers => {"Accept" => "application/ld+json, application/json"} }
Instance Attribute Summary collapse
-
#context ⇒ JSON::LD::Context
Input evaluation context.
-
#input ⇒ String, ...
Current input.
-
#namer ⇒ JSON::LD::BlankNodeNamer
readonly
Current Blank Node Namer.
-
#value ⇒ String, ...
Current input.
Class Method Summary collapse
-
.compact(input, context, options = {}) {|jsonld| ... } ⇒ Hash
Compacts the given input according to the steps in the Compaction Algorithm.
-
.documentLoader(url, options = {}) {|remote_document| ... } ⇒ RemoteDocument
Default document loader.
-
.expand(input, options = {}) {|jsonld| ... } ⇒ Array<Hash>
Expands the given input according to the steps in the Expansion Algorithm.
-
.flatten(input, context, options = {}) {|jsonld| ... } ⇒ Array<Hash>
This algorithm flattens an expanded JSON-LD document by collecting all properties of a node in a single JSON object and labeling all blank nodes with blank node identifiers.
-
.frame(input, frame, options = {}) {|jsonld| ... } ⇒ Array<Hash>
Frames the given input using the frame according to the steps in the Framing Algorithm.
-
.fromRdf(input, options = {}) {|jsonld| ... } ⇒ Array<Hash>
(also: fromRDF)
Take an ordered list of RDF::Statements and turn them into a JSON-LD document.
-
.toRdf(input, options = {}) {|statement| ... } ⇒ Object
(also: toRDF)
Processes the input according to the RDF Conversion Algorithm, calling the provided callback for each triple generated.
Instance Method Summary collapse
-
#initialize(input, context, options = {}) {|api| ... } ⇒ API
constructor
Initialize the API, reading in any document and setting global options.
Methods included from Frame
#cleanup_preserve, #frame, #remove_dependents
Methods included from Utils
#as_resource, #blank_node?, #index?, #list?, #node?, #node_reference?, #value?
Methods included from FromRDF
Methods included from Flatten
Methods included from ToRDF
#graph_to_rdf, #node, #parse_list, #parse_object
Methods included from Compact
Methods included from Expand
Constructor Details
#initialize(input, context, options = {}) {|api| ... } ⇒ API
Initialize the API, reading in any document and setting global options
81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 |
# File 'lib/json/ld/api.rb', line 81 def initialize(input, context, = {}, &block) @options = {:compactArrays => true}.merge() @options[:validate] = true if @options[:processingMode] == "json-ld-1.0" @options[:documentLoader] ||= self.class.method(:documentLoader) [:rename_bnodes] ||= true @namer = [:unique_bnodes] ? BlankNodeUniqer.new : ([:rename_bnodes] ? BlankNodeNamer.new("b") : BlankNodeMapper.new) @value = case input when Array, Hash then input.dup when IO, StringIO @options = {:base => input.base_uri}.merge(@options) if input.respond_to?(:base_uri) JSON.parse(input.read) when String remote_doc = @options[:documentLoader].call(input, @options) @options = {:base => remote_doc.documentUrl}.merge(@options) context = context ? [context, remote_doc.contextUrl].compact : remote_doc.contextUrl case remote_doc.document when String then JSON.parse(remote_doc.document) else remote_doc.document end end # Update calling context :base option, if not defined [:base] ||= @options[:base] if @options[:base] @context = Context.new(@options) @context = @context.parse(context) if context if block_given? case block.arity when 0, -1 then instance_eval(&block) else block.call(self) end end end |
Instance Attribute Details
#context ⇒ JSON::LD::Context
Input evaluation context
40 41 42 |
# File 'lib/json/ld/api.rb', line 40 def context @context end |
#input ⇒ String, ...
Current input
35 |
# File 'lib/json/ld/api.rb', line 35 attr_accessor :value |
#namer ⇒ JSON::LD::BlankNodeNamer (readonly)
Current Blank Node Namer
45 46 47 |
# File 'lib/json/ld/api.rb', line 45 def namer @namer end |
#value ⇒ String, ...
Current input
35 36 37 |
# File 'lib/json/ld/api.rb', line 35 def value @value end |
Class Method Details
.compact(input, context, options = {}) {|jsonld| ... } ⇒ Hash
Compacts the given input according to the steps in the Compaction Algorithm. The input must be copied, compacted and returned if there are no errors. If the compaction fails, an appropirate exception must be thrown.
If no context is provided, the input document is compacted using the top-level context of the document
The resulting ‘Hash` is either returned or yielded, if a block is given.
172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 |
# File 'lib/json/ld/api.rb', line 172 def self.compact(input, context, = {}) = result = nil # 1) Perform the Expansion Algorithm on the JSON-LD input. # This removes any existing context to allow the given context to be cleanly applied. = API.(input, ) API.new(, context, ) do debug(".compact") {"expanded input: #{.to_json(JSON_STATE)}"} result = compact(value, nil) # xxx) Add the given context to the output ctx = self.context.serialize if result.is_a?(Array) kwgraph = self.context.compact_iri('@graph', :vocab => true, :quiet => true) result = result.empty? ? {} : {kwgraph => result} end result = ctx.merge(result) unless ctx.empty? end yield result if block_given? result end |
.documentLoader(url, options = {}) {|remote_document| ... } ⇒ RemoteDocument
Default document loader.
463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 |
# File 'lib/json/ld/api.rb', line 463 def self.documentLoader(url, = {}) require 'net/http' unless defined?(Net::HTTP) remote_document = nil [:headers] ||= OPEN_OPTS[:headers] url = url.to_s[5..-1] if url.to_s.start_with?("file:") case url.to_s when /^http/ parsed_url = ::URI.parse(url.to_s) until remote_document do Net::HTTP::start(parsed_url.host, parsed_url.port, open_timeout: 60 * 1000, use_ssl: parsed_url.scheme == 'https', verify_mode: OpenSSL::SSL::VERIFY_NONE ) do |http| request = Net::HTTP::Get.new(parsed_url.request_uri, [:headers]) http.request(request) do |response| case response when Net::HTTPSuccess # found object content_type, ct_param = response.content_type.to_s.downcase.split(";") # If the passed input is a DOMString representing the IRI of a remote document, dereference it. If the retrieved document's content type is neither application/json, nor application/ld+json, nor any other media type using a +json suffix as defined in [RFC6839], reject the promise passing an loading document failed error. if content_type && [:validate] main, sub = content_type.split("/") raise JSON::LD::JsonLdError::LoadingDocumentFailed, "content_type: #{content_type}" if main != 'application' || sub !~ /^(.*\+)?json$/ end remote_document = RemoteDocument.new(parsed_url.to_s, response.body) # If the input has been retrieved, the response has an HTTP Link Header [RFC5988] using the http://www.w3.org/ns/json-ld#context link relation and a content type of application/json or any media type with a +json suffix as defined in [RFC6839] except application/ld+json, update the active context using the Context Processing algorithm, passing the context referenced in the HTTP Link Header as local context. The HTTP Link Header is ignored for documents served as application/ld+json If multiple HTTP Link Headers using the http://www.w3.org/ns/json-ld#context link relation are found, the promise is rejected with a JsonLdError whose code is set to multiple context link headers and processing is terminated. unless content_type.start_with?("application/ld+json") links = response["link"].to_s. split(","). map(&:strip). select {|h| h =~ %r{rel=\"http://www.w3.org/ns/json-ld#context\"}} case links.length when 0 then #nothing to do when 1 remote_document.contextUrl = links.first.match(/<([^>]*)>/) && $1 else raise JSON::LD::JsonLdError::MultipleContextLinkHeaders, "expected at most 1 Link header with rel=jsonld:context, got #{links.length}" end end return block_given? ? yield(remote_document) : remote_document when Net::HTTPRedirection # Follow redirection parsed_url = ::URI.parse(response["Location"]) else raise JSON::LD::JsonLdError::LoadingDocumentFailed, "<#{parsed_url}>: #{response.msg}(#{response.code})" end end end end else # Use regular open RDF::Util::File.open_file(url, ) do |f| remote_document = RemoteDocument.new(url, f.read) content_type, ct_param = f.content_type.to_s.downcase.split(";") if f.respond_to?(:content_type) if content_type && [:validate] main, sub = content_type.split("/") raise JSON::LD::JsonLdError::LoadingDocumentFailed, "content_type: #{content_type}" if main != 'application' || sub !~ /^(.*\+)?json$/ end return block_given? ? yield(remote_document) : remote_document end end end |
.expand(input, options = {}) {|jsonld| ... } ⇒ Array<Hash>
Expands the given input according to the steps in the Expansion Algorithm. The input must be copied, expanded and returned if there are no errors. If the expansion fails, an appropriate exception must be thrown.
The resulting ‘Array` either returned or yielded
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 |
# File 'lib/json/ld/api.rb', line 134 def self.(input, = {}) result = nil API.new(input, [:expandContext], ) do |api| result = api.(api.value, nil, api.context) end # If, after the algorithm outlined above is run, the resulting element is an # JSON object with just a @graph property, element is set to the value of @graph's value. result = result['@graph'] if result.is_a?(Hash) && result.keys == %w(@graph) # Finally, if element is a JSON object, it is wrapped into an array. result = [result].compact unless result.is_a?(Array) yield result if block_given? result end |
.flatten(input, context, options = {}) {|jsonld| ... } ⇒ Array<Hash>
This algorithm flattens an expanded JSON-LD document by collecting all properties of a node in a single JSON object and labeling all blank nodes with blank node identifiers. This resulting uniform shape of the document, may drastically simplify the code required to process JSON-LD data in certain applications.
The resulting ‘Array` is either returned, or yielded if a block is given.
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 |
# File 'lib/json/ld/api.rb', line 214 def self.flatten(input, context, = {}) flattened = [] # Expand input to simplify processing = API.(input, ) # Initialize input using frame as context API.new(, context, ) do debug(".flatten") {"expanded input: #{value.to_json(JSON_STATE)}"} # Initialize node map to a JSON object consisting of a single member whose key is @default and whose value is an empty JSON object. node_map = {'@default' => {}} self.generate_node_map(value, node_map) default_graph = node_map['@default'] node_map.keys.kw_sort.reject {|k| k == '@default'}.each do |graph_name| graph = node_map[graph_name] entry = default_graph[graph_name] ||= {'@id' => graph_name} nodes = entry['@graph'] ||= [] graph.keys.kw_sort.each do |id| nodes << graph[id] unless node_reference?(graph[id]) end end default_graph.keys.kw_sort.each do |id| flattened << default_graph[id] unless node_reference?(default_graph[id]) end if context && !flattened.empty? # Otherwise, return the result of compacting flattened according the Compaction algorithm passing context ensuring that the compaction result uses the @graph keyword (or its alias) at the top-level, even if the context is empty or if there is only one element to put in the @graph array. This ensures that the returned document has a deterministic structure. compacted = depth {compact(flattened, nil)} compacted = [compacted] unless compacted.is_a?(Array) kwgraph = self.context.compact_iri('@graph', :quiet => true) flattened = self.context.serialize.merge(kwgraph => compacted) end end yield flattened if block_given? flattened end |
.frame(input, frame, options = {}) {|jsonld| ... } ⇒ Array<Hash>
Frames the given input using the frame according to the steps in the Framing Algorithm. The input is used to build the framed output and is returned if there are no errors. If there are no matches for the frame, null must be returned. Exceptions must be thrown if there are errors.
The resulting ‘Array` is either returned, or yielded if a block is given.
284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 |
# File 'lib/json/ld/api.rb', line 284 def self.frame(input, frame, = {}) result = nil framing_state = { :embed => true, :explicit => false, :omitDefault => false, :embeds => nil, } framing_state[:embed] = [:embed] if .has_key?(:embed) framing_state[:explicit] = [:explicit] if .has_key?(:explicit) framing_state[:omitDefault] = [:omitDefault] if .has_key?(:omitDefault) [:documentLoader] ||= method(:documentLoader) # de-reference frame to create the framing object frame = case frame when Hash then frame.dup when IO, StringIO then JSON.parse(frame.read) when String remote_doc = [:documentLoader].call(frame) case remote_doc.document when String then JSON.parse(remote_doc.document) else remote_doc.document end end # Expand input to simplify processing = API.(input, ) # Expand frame to simplify processing = API.(frame, ) # Initialize input using frame as context API.new(, nil, ) do #debug(".frame") {"context from frame: #{context.inspect}"} debug(".frame") {"raw frame: #{frame.to_json(JSON_STATE)}"} debug(".frame") {"expanded frame: #{.to_json(JSON_STATE)}"} debug(".frame") {"expanded input: #{value.to_json(JSON_STATE)}"} # Get framing nodes from expanded input, replacing Blank Node identifiers as necessary all_nodes = {} old_dbg, @options[:debug] = @options[:debug], nil depth do generate_node_map(value, all_nodes) end @options[:debug] = old_dbg @node_map = all_nodes['@default'] debug(".frame") {"node_map: #{@node_map.to_json(JSON_STATE)}"} result = [] frame(framing_state, @node_map, (.first || {}), parent: result) debug(".frame") {"after frame: #{result.to_json(JSON_STATE)}"} # Initalize context from frame @context = depth {@context.parse(frame['@context'])} # Compact result compacted = depth {compact(result, nil)} compacted = [compacted] unless compacted.is_a?(Array) # Add the given context to the output kwgraph = context.compact_iri('@graph', :quiet => true) result = context.serialize.merge({kwgraph => compacted}) debug(".frame") {"after compact: #{result.to_json(JSON_STATE)}"} result = cleanup_preserve(result) end yield result if block_given? result end |
.fromRdf(input, options = {}) {|jsonld| ... } ⇒ Array<Hash> Also known as: fromRDF
Take an ordered list of RDF::Statements and turn them into a JSON-LD document.
The resulting ‘Array` is either returned or yielded, if a block is given.
441 442 443 444 445 446 447 448 449 450 451 |
# File 'lib/json/ld/api.rb', line 441 def self.fromRdf(input, = {}, &block) = {:useNativeTypes => false}.merge() result = nil API.new(nil, nil, ) do |api| result = api.from_statements(input) end yield result if block_given? result end |
.toRdf(input, options = {}) {|statement| ... } ⇒ Object Also known as: toRDF
Processes the input according to the RDF Conversion Algorithm, calling the provided callback for each triple generated.
366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 |
# File 'lib/json/ld/api.rb', line 366 def self.toRdf(input, = {}, &block) unless block_given? results = [] results.extend(RDF::Enumerable) self.toRdf(input, ) do |stmt| results << stmt end return results end # Expand input to simplify processing = API.(input, .merge(:ordered => false)) API.new(, nil, ) do # 1) Perform the Expansion Algorithm on the JSON-LD input. # This removes any existing context to allow the given context to be cleanly applied. debug(".toRdf") {"expanded input: #{.to_json(JSON_STATE)}"} # Generate _nodeMap_ node_map = {'@default' => {}} generate_node_map(, node_map) debug(".toRdf") {"node map: #{node_map.to_json(JSON_STATE)}"} # Start generating statements node_map.each do |graph_name, graph| context = as_resource(graph_name) unless graph_name == '@default' debug(".toRdf") {"context: #{context ? context.to_ntriples : 'null'}"} # Drop results for graphs which are named with relative IRIs if graph_name.is_a?(RDF::URI) && !graph_name.absolute debug(".toRdf") {"drop relative graph_name: #{statement.to_ntriples}"} next end graph_to_rdf(graph) do |statement| next if statement.predicate.node? && ![:produceGeneralizedRdf] # Drop results with relative IRIs relative = statement.to_a.any? do |r| case r when RDF::URI r.relative? when RDF::Literal r.has_datatype? && r.datatype.relative? else false end end if relative debug(".toRdf") {"drop statement with relative IRIs: #{statement.to_ntriples}"} next end statement.context = context if context if block_given? yield statement else results << statement end end end end results end |