Class: JSON::LD::API

Inherits:
Object
  • Object
show all
Includes:
Compact, Expand, Flatten, Frame, FromTriples, Triples
Defined in:
lib/json/ld/api.rb

Overview

A JSON-LD processor implementing 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.

See Also:

Author:

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

#blank_node?, #list?, #node?, #node_reference?, #value?

Methods included from FromTriples

#from_statements

Methods included from Flatten

#generate_node_map

Methods included from Triples

#add_quad, #node, #parse_list, #statements

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) —

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

  • options (Hash) (defaults to: {})

Yields:

  • (api)

Yield Parameters:



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/json/ld/api.rb', line 39

def initialize(input, context, options = {}, &block)
  @options = options
  @value = case input
  when Array, Hash then input.dup
  when IO, StringIO then JSON.parse(input.read)
  when String
    content = nil
    RDF::Util::File.open_file(input) {|f| content = JSON.parse(f.read)}
    content
  end
  @context = EvaluationContext.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 ⇒ Object

Returns the value of attribute context.



28
29
30
 
# File 'lib/json/ld/api.rb', line 28

def context
  @context
end

#value ⇒ Object

Returns the value of attribute value.



27
28
29
 
# File 'lib/json/ld/api.rb', line 27

def value
  @value
end

Class Method Details

.compact(input, context, callback = nil, 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 returned via the provided callback.

Note that for Ruby, if the callback is not provided and a block is given, it will be yielded

Parameters:

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

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

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

    The base context to use when compacting the input.

  • callback (Proc) (defaults to: nil) —

    (&block) Alternative to using block, with same parameters.

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

    Other options passed to Expand#expand

Options Hash (options):

  • :optimize (Boolean) — default: false —

    Perform further optimmization of the compacted output. (Presently, this is a noop).

Yields:

  • jsonld

Yield Parameters:

  • jsonld (Hash) —

    The compacted JSON-LD document

Returns:

  • (Hash) —

    The compacted JSON-LD document

Raises:

See Also:



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/json/ld/api.rb', line 129

def self.compact(input, context, callback = nil, 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, 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
    result = case result
    when Hash then self.context.serialize.merge(result)
    when Array
      kwgraph = self.context.compact_iri('@graph', :quiet => true)
      self.context.serialize.merge(kwgraph => result)
    when String
      kwid = self.context.compact_iri('@id', :quiet => true)
      self.context.serialize.merge(kwid => result)
    end
  end
  callback.call(result) if callback
  yield result if block_given?
  result
end

.expand(input, context = nil, callback = 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` is returned via the provided callback.

Note that for Ruby, if the callback is not provided and a block is given, it will be yielded

Parameters:

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

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

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

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

  • callback (Proc) (defaults to: nil) —

    (&block) Alternative to using block, with same parameters.

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

Options Hash (options):

  • :base (Boolean) —

    Base IRI to use when processing relative IRIs.

Yields:

  • jsonld

Yield Parameters:

  • jsonld (Array<Hash>) —

    The expanded JSON-LD document

Returns:

  • (Array<Hash>) —

    The expanded JSON-LD document

Raises:

See Also:



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/json/ld/api.rb', line 84

def self.expand(input, context = nil, callback = 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] unless result.is_a?(Array)
  callback.call(result) if callback
  yield result if block_given?
  result
end

.flatten(input, graph, context, callback = nil, options = {}) {|jsonld| ... } ⇒ Array<Hash>

Flattens the given input according to the steps in the Flattening Algorithm. The input must be flattened and returned if there are no errors. If the flattening fails, an appropriate exception must be thrown.

The resulting ‘Array` is returned via the provided callback.

Note that for Ruby, if the callback is not provided and a block is given, it will be yielded. If there is no block, the value will be returned.

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.

  • graph (String, RDF::URI) —

    The graph in the document that should be flattened. To return the default graph @default has to be passed, for the merged graph @merged and for any other graph the IRI identifying the graph has to be passed. The default value is @merged.

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

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

  • callback (Proc) (defaults to: nil) —

    (&block) Alternative to using block, with same parameters.

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

    Other options passed to Expand#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:



189
190
191
192
193
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
 
# File 'lib/json/ld/api.rb', line 189

def self.flatten(input, graph, context, callback = nil, options = {})
  result = nil
  graph ||= '@merged'

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

  # Initialize input using frame as context
  API.new(expanded_input, nil, options) do
    debug(".flatten") {"expanded input: #{value.to_json(JSON_STATE)}"}

    # Generate _nodeMap_
    node_map = Hash.ordered
    self.generate_node_map(value,
      node_map,
      (graph.to_s == '@merged' ? '@merged' : '@default'),
      nil,
      BlankNodeNamer.new("t"))
    
    result = []

    # If nodeMap has no property graph, return result, otherwise set definitions to its value.
    definitions = node_map.fetch(graph.to_s, {})
    
    # Foreach property and valud of definitions
    definitions.keys.sort.each do |prop|
      value = definitions[prop]
      result << value
    end
    
    result
  end

  callback.call(result) if callback
  yield result if block_given?
  result
end

.frame(input, frame, callback = nil, 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 returned via the provided callback.

Note that for Ruby, if the callback is not provided and a block is given, it will be yielded

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.

  • callback (Proc) (defaults to: nil) —

    (&block) Alternative to using block, with same parameters.

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

    Other options passed to Expand#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:



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

def self.frame(input, frame, callback = nil, 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) {|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") {"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
    depth do
      generate_node_map(value,
        all_nodes,
        '@merged',
        nil,
        BlankNodeNamer.new("t"))
    end
    @node_map = all_nodes['@merged']
    debug(".frame") {"node_map: #{@node_map.to_json(JSON_STATE)}"}

    result = []
    frame(framing_state, @node_map, expanded_frame[0], 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

  callback.call(result) if callback
  yield result if block_given?
  result
end

.fromRDF(input, callback = nil, options = {}) {|jsonld| ... } ⇒ Array<Hash>

Take an ordered list of RDF::Statements and turn them into a JSON-LD document.

The resulting ‘Array` is returned via the provided callback.

Note that for Ruby, if the callback is not provided and a block is given, it will be yielded

Parameters:

  • input (Array<RDF::Statement>)
  • callback (Proc) (defaults to: nil) —

    (&block) Alternative to using block, with same parameteres.

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

Options Hash (options):

  • :notType (Boolean) —

    don’t use @type for rdf:type

Yields:

  • jsonld

Yield Parameters:

  • jsonld (Hash) —

    The JSON-LD document in expanded form

Returns:

  • (Array<Hash>) —

    The JSON-LD document in expanded form



377
378
379
380
381
382
383
384
385
386
387
 
# File 'lib/json/ld/api.rb', line 377

def self.fromRDF(input, callback = nil, options = {})
  result = nil

  API.new(nil, nil, options) do |api|
    result = api.from_statements(input)
  end

  callback.call(result) if callback
  yield result if block_given?
  result
end

.toRDF(input, context = nil, callback = nil, options = {}) {|statement| ... } ⇒ Object

Processes the input according to the RDF Conversion Algorithm, calling the provided callback for each triple generated.

Note that for Ruby, if the callback is not provided and a block is given, it will be yielded

Parameters:

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

    The JSON-LD object to process when outputting statements.

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

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

  • callback (Proc) (defaults to: nil) —

    (&block) Alternative to using block, with same parameteres.

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

    Options passed to Expand#expand

Yields:

  • statement

Yield Parameters:

  • statement (RDF::Statement)

Raises:



345
346
347
348
349
350
351
352
353
354
355
356
357
358
 
# File 'lib/json/ld/api.rb', line 345

def self.toRDF(input, context = nil, callback = nil, options = {})
  # 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 = expand(input, context, nil, options)

  API.new(expanded, nil, options) do
    debug(".expand") {"expanded input: #{value.to_json(JSON_STATE)}"}
    # Start generating statements
    statements("", value, nil, nil, nil) do |statement|
      callback.call(statement) if callback
      yield statement if block_given?
    end
  end
end