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.
Constant Summary collapse
- OPEN_OPTS =
Options used for open_file
{ :headers => %w(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.
-
.expand(input, context = nil, 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>
Take an ordered list of RDF::Statements and turn them into a JSON-LD document.
-
.toRDF(input, context = nil, options = {}) {|statement| ... } ⇒ Array<RDF::Statement>
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
#add_quad, #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
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 |
# File 'lib/json/ld/api.rb', line 71 def initialize(input, context, = {}, &block) @options = {:compactArrays => true}.merge() = {:rename_bnodes => true}.merge() @namer = [:rename_bnodes] ? BlankNodeNamer.new("b") : BlankNodeMapper.new @value = case input when Array, Hash then input.dup when IO, StringIO then JSON.parse(input.read) when String content = nil @options = {:base => input}.merge(@options) RDF::Util::File.open_file(input, OPEN_OPTS) {|f| content = JSON.parse(f.read)} content end @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.
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 |
# File 'lib/json/ld/api.rb', line 152 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, nil, .merge(:debug => nil)) 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 |
.expand(input, context = nil, 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
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 |
# File 'lib/json/ld/api.rb', line 114 def self.(input, context = nil, = {}) result = nil API.new(input, context, ) 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.
194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 |
# File 'lib/json/ld/api.rb', line 194 def self.flatten(input, context, = {}) flattened = [] # Expand input to simplify processing = API.(input, nil, ) # Initialize input using frame as context API.new(, nil, ) 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 = Hash.ordered node_map['@default'] = Hash.ordered 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] end end default_graph.keys.kw_sort.each do |id| flattened << 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, 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.
265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 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 |
# File 'lib/json/ld/api.rb', line 265 def self.frame(input, frame, = {}) result = nil match_limit = 0 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) # 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 content = nil RDF::Util::File.open_file(frame, OPEN_OPTS) {|f| content = JSON.parse(f.read)} content end # Expand frame to simplify processing = API.(frame) # Expand input to simplify processing = API.(input) # 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 = Hash.ordered old_dbg, @options[:debug] = @options[:debug], nil depth do generate_node_map(value, all_nodes, '@merged') end @options[:debug] = old_dbg @node_map = all_nodes['@merged'] debug(".frame") {"node_map: #{@node_map.to_json(JSON_STATE)}"} result = [] frame(framing_state, @node_map, (.first || {}), result, nil) 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>
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.
394 395 396 397 398 399 400 401 402 403 404 |
# File 'lib/json/ld/api.rb', line 394 def self.fromRDF(input, = {}, &block) = {:useNativeTypes => true}.merge() result = nil API.new(nil, nil, ) do |api| result = api.from_statements(input) end yield result if block_given? result end |
.toRDF(input, context = nil, options = {}) {|statement| ... } ⇒ Array<RDF::Statement>
Processes the input according to the RDF Conversion Algorithm, calling the provided callback for each triple generated.
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 |
# File 'lib/json/ld/api.rb', line 346 def self.toRDF(input, context = nil, = {}, &block) results = [] results.extend(RDF::Enumerable) # Expand input to simplify processing = API.(input, context, ) API.new(, context, ) 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 = Hash.ordered node_map['@default'] = Hash.ordered 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'}"} graph_to_rdf(graph).each do |statement| statement.context = context if context if block_given? yield statement else results << statement end end end end results end |