Class: JSON::LD::API

Inherits:
Object
  • Object
show all
Includes:
Compact, Expand, Flatten, Frame, FromRDF, ToRDF
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.

See Also:

Author:

Constant Summary collapse

OPEN_OPTS =

Options used for open_file

{
  :headers => {"Accept" => "application/ld+json, application/json"}
}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

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

#from_statements

Methods included from Flatten

#generate_node_map

Methods included from ToRDF

#graph_to_rdf, #node, #parse_list, #parse_object

Methods included from Compact

#compact

Methods included from Expand

#expand

Constructor Details

#initialize(input, context, options = {}) {|api| ... } ⇒ API

Initialize the API, reading in any document and setting global options

Parameters:

  • input (String, #read, Hash, Array)
  • context (String, #read, , Hash, Array, JSON::LD::Context) —

    An external context to use additionally to the context embedded in input when expanding the input.

  • options (Hash{Symbol => Object}) (defaults to: {})

Options Hash (options):

  • :base (Boolean) —

    The Base IRI to use when expanding the document. This overrides the value of ‘input` if it is a IRI. If not specified and `input` is not an IRI, the base IRI defaults to the current document IRI if in a browser context, or the empty string if there is no document context.

  • :compactArrays (Boolean) — default: true —

    If set to ‘true`, the JSON-LD processor replaces arrays with just one element with that element during compaction. If set to `false`, all arrays will remain arrays even if they have just one element.

  • :flatten (Boolean, String, RDF::URI) —

    If set to a value that is not ‘false`, the JSON-LD processor must modify the output of the Compaction Algorithm or the Expansion Algorithm by coalescing all properties associated with each subject via the Flattening Algorithm. The value of `flatten must` be either an IRI value representing the name of the graph to flatten, or `true`. If the value is `true`, then the first graph encountered in the input document is selected and flattened.

  • :optimize (Boolean) — default: false —

    If set to ‘true`, the JSON-LD processor is allowed to optimize the output of the Compaction Algorithm to produce even compacter representations. The algorithm for compaction optimization is beyond the scope of this specification and thus not defined. Consequently, different implementations MAY implement different optimization algorithms. (Presently, this is a noop).

  • :useNativeTypes (Boolean) — default: true —

    If set to ‘true`, the JSON-LD processor will use native datatypes for expression xsd:integer, xsd:boolean, and xsd:double values, otherwise, it will use the expanded form.

  • :useRdfType (Boolean) — default: false —

    If set to ‘true`, the JSON-LD processor will try to convert datatyped literals to JSON native types instead of using the expanded object form when converting from RDF. `xsd:boolean` values will be converted to `true` or `false`. `xsd:integer` and `xsd:double` values will be converted to JSON numbers.

  • :rename_bnodes (Boolean) — default: true —

    Rename bnodes as part of expansion, or keep them the same.

Yields:

  • (api)

Yield Parameters:



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, options = {}, &block)
  @options = {:compactArrays => true}.merge(options)
  options = {:rename_bnodes => true}.merge(options)
  @namer = options[: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

Returns:



40
41
42
 
# File 'lib/json/ld/api.rb', line 40

def context
  @context
end

#input ⇒ String, ...

Current input

Returns:



35
 
# File 'lib/json/ld/api.rb', line 35

attr_accessor :value

#namer ⇒ JSON::LD::BlankNodeNamer (readonly)

Current Blank Node Namer

Returns:



45
46
47
 
# File 'lib/json/ld/api.rb', line 45

def namer
  @namer
end

#value ⇒ String, ...

Current input

Returns:



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.

Parameters:

  • input (String, #read, Hash, Array) —

    The JSON-LD object to copy and perform the compaction upon.

  • context (String, #read, Hash, Array, JSON::LD::Context) —

    The base context to use when compacting the input.

  • options (Hash{Symbol => Object}) (defaults to: {}) —

    See options in #initialize Other options passed to expand

Yields:

  • jsonld

Yield Parameters:

  • jsonld (Hash) —

    The compacted JSON-LD document

Returns:

  • (Hash) —

    The compacted JSON-LD document

Raises:

See Also:



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, options = {})
  expanded = 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 = API.expand(input, nil, options.merge(:debug => nil))

  API.new(expanded, context, options) do
    debug(".compact") {"expanded input: #{expanded.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

Parameters:

  • input (String, #read, Hash, Array) —

    The JSON-LD object to copy and perform the expansion upon.

  • context (String, #read, Hash, Array, JSON::LD::Context) (defaults to: nil) —

    An external context to use additionally to the context embedded in input when expanding the input.

  • options (Hash{Symbol => Object}) (defaults to: {}) —

    See options in #initialize

Yields:

  • jsonld

Yield Parameters:

  • jsonld (Array<Hash>) —

    The expanded JSON-LD document

Returns:

  • (Array<Hash>) —

    The expanded JSON-LD document

Raises:

See Also:



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.expand(input, context = nil, options = {})
  result = nil
  API.new(input, context, options) do |api|
    result = api.expand(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.

Parameters:

  • input (String, #read, Hash, Array) —

    The JSON-LD object or array of JSON-LD objects to flatten or an IRI referencing the JSON-LD document to flatten.

  • context (String, #read, Hash, Array, JSON::LD::EvaluationContext) —

    An optional external context to use additionally to the context embedded in input when expanding the input.

  • options (Hash{Symbol => Object}) (defaults to: {}) —

    See options in #initialize Other options passed to expand

Yields:

  • jsonld

Yield Parameters:

  • jsonld (Hash) —

    The framed JSON-LD document

Returns:

  • (Array<Hash>) —

    The framed JSON-LD document

Raises:

See Also:



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, options = {})
  flattened = []

  # Expand input to simplify processing
  expanded_input = API.expand(input, nil, options)

  # Initialize input using frame as context
  API.new(expanded_input, nil, options) 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] 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, 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.

Parameters:

  • input (String, #read, Hash, Array) —

    The JSON-LD object to copy and perform the framing on.

  • frame (String, #read, Hash, Array) —

    The frame to use when re-arranging the data.

  • options (Hash{Symbol => Object}) (defaults to: {}) —

    See options in #initialize Other options passed to expand

Options Hash (options):

  • :embed (Boolean) — default: true —

    a flag specifying that objects should be directly embedded in the output, instead of being referred to by their IRI.

  • :explicit (Boolean) — default: false —

    a flag specifying that for properties to be included in the output, they must be explicitly declared in the framing context.

  • :omitDefault (Boolean) — default: false —

    a flag specifying that properties that are missing from the JSON-LD input should be omitted from the output.

Yields:

  • jsonld

Yield Parameters:

  • jsonld (Hash) —

    The framed JSON-LD document

Returns:

  • (Array<Hash>) —

    The framed JSON-LD document

Raises:

See Also:



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, options = {})
  result = nil
  match_limit = 0
  framing_state = {
    :embed       => true,
    :explicit    => false,
    :omitDefault => false,
    :embeds      => nil,
  }
  framing_state[:embed] = options[:embed] if options.has_key?(:embed)
  framing_state[:explicit] = options[:explicit] if options.has_key?(:explicit)
  framing_state[:omitDefault] = options[:omitDefault] if options.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
  expanded_frame = API.expand(frame)
  
  # Expand input to simplify processing
  expanded_input = API.expand(input)

  # Initialize input using frame as context
  API.new(expanded_input, nil, options) do
    #debug(".frame") {"context from frame: #{context.inspect}"}
    debug(".frame") {"raw frame: #{frame.to_json(JSON_STATE)}"}
    debug(".frame") {"expanded 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)
    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, (expanded_frame.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.

Parameters:

  • input (Array<RDF::Statement>)
  • options (Hash{Symbol => Object}) (defaults to: {}) —

    See options in #initialize

Yields:

  • jsonld

Yield Parameters:

  • jsonld (Hash) —

    The JSON-LD document in expanded form

Returns:

  • (Array<Hash>) —

    The JSON-LD document in expanded form



397
398
399
400
401
402
403
404
405
406
407
 
# File 'lib/json/ld/api.rb', line 397

def self.fromRDF(input, options = {}, &block)
  options = {:useNativeTypes => true}.merge(options)
  result = nil

  API.new(nil, nil, options) 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.

Parameters:

  • input (String, #read, Hash, Array) —

    The JSON-LD object to process when outputting statements.

  • context (String, #read, Hash, Array, JSON::LD::Context) (defaults to: nil) —

    An external context to use additionally to the context embedded in input when expanding the input.

  • options ({Symbol,String => Object}) (defaults to: {}) —

    See options in #initialize Options passed to expand

Options Hash (options):

  • :produceGeneralizedRDF (Boolean) — default: false —

    If true, output will include statements having blank node predicates, otherwise they are dropped.

Yields:

  • statement

Yield Parameters:

  • statement (RDF::Statement)

Returns:

  • (Array<RDF::Statement>) —

    if no block given

Raises:



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
 
# File 'lib/json/ld/api.rb', line 348

def self.toRDF(input, context = nil, options = {}, &block)
  results = []
  results.extend(RDF::Enumerable)

  # Expand input to simplify processing
  expanded_input = API.expand(input, context, options)

  API.new(expanded_input, context, options) 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: #{expanded_input.to_json(JSON_STATE)}"}

    # Generate _nodeMap_
    node_map = Hash.ordered
    node_map['@default'] = Hash.ordered
    generate_node_map(expanded_input, 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|
        next if statement.predicate.node? && !options[:produceGeneralizedRDF]
        statement.context = context if context
        if block_given?
          yield statement
        else
          results << statement
        end
      end
    end
  end
  results
end