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| ... } ⇒ Object, Hash
Compacts the given input according to the steps in the Compaction Algorithm.
-
.documentLoader(url, options = {}) {|remote_document| ... } ⇒ Object, RemoteDocument
Default document loader.
-
.expand(input, options = {}) {|jsonld| ... } ⇒ Object, Array<Hash>
Expands the given input according to the steps in the Expansion Algorithm.
-
.flatten(input, context, options = {}) {|jsonld| ... } ⇒ Object, 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| ... } ⇒ Object, Hash
Frames the given input using the frame according to the steps in the Framing Algorithm.
-
.fromRdf(input, options = {}) {|jsonld| ... } ⇒ Object, Hash
(also: fromRDF)
Take an ordered list of RDF::Statements and turn them into a JSON-LD document.
-
.toRdf(input, options = {}) {|statement| ... } ⇒ RDF::Enumerable
(also: toRDF)
Processes the input according to the RDF Conversion Algorithm, calling the provided callback for each triple generated.
Methods included from Frame
#cleanup_preserve, #count_blank_node_identifiers, #frame, #remove_dependents
Methods included from Utils
#add_value, #as_resource, #blank_node?, #compare_values, #has_property, #has_value, #index?, #list?, #node?, #node_or_ref?, #node_reference?, #value?
Methods included from FromRDF
Methods included from Flatten
Methods included from ToRDF
#item_to_rdf, #node, #parse_list
Methods included from Compact
Methods included from Expand
Instance Attribute Details
#context ⇒ JSON::LD::Context
Input evaluation context
48 49 50 |
# File 'lib/json/ld/api.rb', line 48 def context @context end |
#input ⇒ String, ...
Current input
43 |
# File 'lib/json/ld/api.rb', line 43 attr_accessor :value |
#namer ⇒ JSON::LD::BlankNodeNamer (readonly)
Current Blank Node Namer
53 54 55 |
# File 'lib/json/ld/api.rb', line 53 def namer @namer end |
#value ⇒ String, ...
Current input
43 44 45 |
# File 'lib/json/ld/api.rb', line 43 def value @value end |
Class Method Details
.compact(input, context, options = {}) {|jsonld| ... } ⇒ Object, 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.
206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 |
# File 'lib/json/ld/api.rb', line 206 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. = [:expanded] ? input : API.(input, ) API.new(, context, ) do log_debug(".compact") {"expanded input: #{.to_json(JSON_STATE) rescue 'malformed json'}"} result = compact(value) # 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 block_given? ? yield(result) : result end |
.documentLoader(url, options = {}) {|remote_document| ... } ⇒ Object, RemoteDocument
Default document loader.
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 |
# File 'lib/json/ld/api.rb', line 495 def self.documentLoader(url, = {}) = OPEN_OPTS.merge() RDF::Util::File.open_file(url, ) do |remote_doc| content_type = remote_doc.content_type if remote_doc.respond_to?(:content_type) # 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, "url: #{url}, content_type: #{content_type}" if main != 'application' || sub !~ /^(.*\+)?json$/ end # 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. contextUrl = unless content_type.nil? || content_type.start_with?("application/ld+json") # Get context link(s) # Note, we can't simply use #find_link, as we need to detect multiple links = remote_doc.links.links.select do |link| link.attr_pairs.include?(%w(rel http://www.w3.org/ns/json-ld#context)) end raise JSON::LD::JsonLdError::MultipleContextLinkHeaders, "expected at most 1 Link header with rel=jsonld:context, got #{links.length}" if links.length > 1 Array(links.first).first end doc_uri = remote_doc.base_uri rescue url doc = RemoteDocument.new(doc_uri, remote_doc.read, contextUrl) block_given? ? yield(doc) : doc end rescue IOError => e raise JSON::LD::JsonLdError::LoadingDocumentFailed, e. end |
.expand(input, options = {}) {|jsonld| ... } ⇒ Object, 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
170 171 172 173 174 175 176 177 178 179 180 181 182 |
# File 'lib/json/ld/api.rb', line 170 def self.(input, = {}) result = nil API.new(input, [:expandContext], ) do |api| result = api.(api.value, nil, api.context, ordered: .fetch(:ordered, true)) 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) block_given? ? yield(result) : result end |
.flatten(input, context, options = {}) {|jsonld| ... } ⇒ Object, 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.
247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 |
# File 'lib/json/ld/api.rb', line 247 def self.flatten(input, context, = {}) flattened = [] # Expand input to simplify processing = [:expanded] ? input : API.(input, ) # Initialize input using API.new(, context, ) do log_debug(".flatten") {"expanded input: #{value.to_json(JSON_STATE) rescue 'malformed json'}"} # Initialize node map to a JSON object consisting of a single member whose key is @default and whose value is an empty JSON object. graph_maps = {'@default' => {}} create_node_map(value, graph_maps) default_graph = graph_maps['@default'] graph_maps.keys.kw_sort.reject {|k| k == '@default'}.each do |graph_name| graph = graph_maps[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 = compact(flattened) compacted = [compacted] unless compacted.is_a?(Array) kwgraph = self.context.compact_iri('@graph', quiet: true) flattened = self.context.serialize.merge(kwgraph => compacted) end end block_given? ? yield(flattened) : flattened end |
.frame(input, frame, options = {}) {|jsonld| ... } ⇒ Object, 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.
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 352 353 354 355 356 357 358 359 360 361 362 363 364 365 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 |
# File 'lib/json/ld/api.rb', line 314 def self.frame(input, frame, = {}) result = nil = { base: (input if input.is_a?(String)), compactArrays: true, embed: '@last', explicit: false, requireAll: true, omitDefault: false, pruneBlankNodeIdentifiers: true, documentLoader: method(:documentLoader) }.merge!() framing_state = { graphMap: {}, graphStack: [], subjectStack: [], link: {}, } # de-reference frame to create the framing object frame = case frame when Hash then frame.dup when IO, StringIO then MultiJson.load(frame.read) when String remote_doc = [:documentLoader].call(frame) case remote_doc.document when String then MultiJson.load(remote_doc.document) else remote_doc.document end end # Expand input to simplify processing = [:expanded] ? input : API.(input, ) # Expand frame to simplify processing = API.(frame, .merge(processingMode: "json-ld-1.1-expand-frame")) # Initialize input using frame as context API.new(, nil, ) do log_debug(".frame") {"expanded frame: #{.to_json(JSON_STATE) rescue 'malformed json'}"} # Get framing nodes from expanded input, replacing Blank Node identifiers as necessary create_node_map(value, framing_state[:graphMap], graph: '@default') frame_keys = frame.keys.map {|k| context.(k, vocab: true, quiet: true)} if frame_keys.include?('@graph') # If frame contains @graph, it matches the default graph. framing_state[:graph] = '@default' else # If frame does not contain @graph used the merged graph. framing_state[:graph] = '@merged' framing_state[:link]['@merged'] = {} framing_state[:graphMap]['@merged'] = merge_node_map_graphs(framing_state[:graphMap]) end framing_state[:subjects] = framing_state[:graphMap][framing_state[:graph]] result = [] frame(framing_state, framing_state[:subjects].keys.sort, (.first || {}), .merge(parent: result)) # Count blank node identifiers used in the document, if pruning bnodes_to_clear = if [:pruneBlankNodeIdentifiers] count_blank_node_identifiers(result).collect {|k, v| k if v == 1}.compact end # Initalize context from frame @context = @context.parse(frame['@context']) # Compact result compacted = compact(result) 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}) log_debug(".frame") {"after compact: #{result.to_json(JSON_STATE) rescue 'malformed json'}"} result = cleanup_preserve(result, bnodes_to_clear || []) end block_given? ? yield(result) : result end |
.fromRdf(input, options = {}) {|jsonld| ... } ⇒ Object, 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.
471 472 473 474 475 476 477 478 479 480 481 |
# File 'lib/json/ld/api.rb', line 471 def self.fromRdf(input, = {}, &block) useRdfType = .fetch(:useRdfType, false) useNativeTypes = .fetch(:useNativeTypes, false) result = nil API.new(nil, nil, ) do |api| result = api.from_statements(input, useRdfType: useRdfType, useNativeTypes: useNativeTypes) end block_given? ? yield(result) : result end |
.toRdf(input, options = {}) {|statement| ... } ⇒ RDF::Enumerable Also known as: toRDF
Processes the input according to the RDF Conversion Algorithm, calling the provided callback for each triple generated.
409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 |
# File 'lib/json/ld/api.rb', line 409 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 = [:expanded] ? input : 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. log_debug(".toRdf") {"expanded input: #{.to_json(JSON_STATE) rescue 'malformed json'}"} # Recurse through input .each do |node| item_to_rdf(node) 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 log_debug(".toRdf") {"drop statement with relative IRIs: #{statement.to_ntriples}"} next end yield statement end end end end |