jsonldGraph top-level property

Global convenience variable for working with JSON-LD format

This variable provides direct access to the JSON-LD codec for easy encoding and decoding of RDF data in JSON-LD format. It uses the default configuration of JsonLdGraphCodec with standard namespace mappings and default encoder/decoder options.

Using this global instance is recommended for most common JSON-LD operations where custom configuration is not needed.

Dataset and Named Graph Handling

JSON-LD provides native support for RDF datasets through the @graph keyword. When converting between JSON-LD and RDF Graphs:

• Decoding: When a JSON-LD document contains a top-level @graph property, all triples from the named graphs are imported into a single RdfGraph, losing the graph names but preserving the triple data.

• Encoding: When an RdfGraph contains multiple independent subjects, it is serialized as a JSON-LD document with a top-level @graph array, which groups the data for better readability but doesn't create separate named graphs in the RDF sense.

Note that the full RDF Dataset support (with multiple named graphs) is planned for a future release.

Configuration

Parameters:

• Uses default RdfNamespaceMappings for standard namespace prefixes
• Uses default JsonLdEncoderOptions for serialization
• Uses default JsonLdDecoderOptions for parsing

Examples

Basic usage:

// Decode JSON-LD string into an RDF graph
final jsonLdString = '''
{
  "@context": {
    "name": "http://xmlns.com/foaf/0.1/name"
  },
  "@id": "http://example.org/person/1",
  "name": "John Smith"
}
''';
final graph = jsonldGraph.decode(jsonLdString);

// Encode an RDF graph to JSON-LD string
final serialized = jsonldGraph.encode(graph);

Working with @graph:

// JSON-LD with @graph containing multiple subjects
final jsonWithGraph = '''
{
  "@context": {
    "name": "http://xmlns.com/foaf/0.1/name"
  },
  "@graph": [
    {
      "@id": "http://example.org/person/1",
      "name": "Alice"
    },
    {
      "@id": "http://example.org/person/2",
      "name": "Bob"
    }
  ]
}
''';

// Decodes into a single RDF graph with multiple subjects
final multiSubjectGraph = jsonldGraph.decode(jsonWithGraph);

For custom JSON-LD processing options, create a specific instance of JsonLdGraphCodec with the desired configuration.