yog_io/json

JSON format export and import for graph data exchange.

This module provides comprehensive JSON import/export capabilities for graph data, supporting multiple formats used by popular visualization libraries.

Features

Generic types for nodes and edges (not just Strings)
Multiple JSON formats (D3.js, Cytoscape.js, vis.js, etc.)
File I/O operations (read/write JSON files directly)
Rich metadata support (graph properties, rendering hints)
Format validation and error reporting

Quick Start

import yog_io/json
import yog/model

pub fn main() {
  let graph =
    model.new(model.Directed)
    |> model.add_node(1, "Alice")
    |> model.add_node(2, "Bob")
    |> model.add_edge(from: 1, to: 2, with: "follows")

  // Export to file
  let assert Ok(_) = json.to_json_file(
    graph,
    "graph.json",
    json.default_export_options(),
  )
}

Format Support

Generic: Full metadata with type preservation
D3Force: D3.js force-directed graphs
Cytoscape: Cytoscape.js network visualization
VisJs: vis.js network format
NetworkX: Python NetworkX compatibility

References

Types

JsonError

</>

Errors that can occur during JSON operations

pub type JsonError {
  FileNotFound(path: String)
  InvalidJson(error: String)
  WriteError(path: String, error: String)
  ReadError(path: String, error: String)
  UnsupportedFormat(format: String)
}

Constructors

```
FileNotFound(path: String)
```
File not found
```
InvalidJson(error: String)
```
Invalid JSON syntax
```
WriteError(path: String, error: String)
```
File write error
```
ReadError(path: String, error: String)
```
File read error
```
UnsupportedFormat(format: String)
```
Unsupported format

JsonExportOptions

</>

Options for JSON export

pub type JsonExportOptions(n, e) {
  JsonExportOptions(
    format: JsonFormat,
    include_metadata: Bool,
    node_serializer: option.Option(fn(n) -> json.Json),
    edge_serializer: option.Option(fn(e) -> json.Json),
    pretty: Bool,
    metadata: option.Option(dict.Dict(String, json.Json)),
  )
}

Constructors

JsonExportOptions(
  format: JsonFormat,
  include_metadata: Bool,
  node_serializer: option.Option(fn(n) -> json.Json),
  edge_serializer: option.Option(fn(e) -> json.Json),
  pretty: Bool,
  metadata: option.Option(dict.Dict(String, json.Json)),
)

Arguments

format: Output format (default: Generic)
include_metadata: Include graph metadata (default: True)
node_serializer: Custom node data serializer
edge_serializer: Custom edge data serializer
pretty: Pretty print output (default: True)
metadata: Custom metadata fields

JsonFormat

</>

Format presets for popular graph visualization libraries

pub type JsonFormat {
  Generic
  D3Force
  Cytoscape
  VisJs
  NetworkX
}

Constructors

```
Generic
```
Generic format with full metadata
```
D3Force
```
D3.js force-directed graph format
```
Cytoscape
```
Cytoscape.js elements format
```
VisJs
```
vis.js network format
```
NetworkX
```
NetworkX node-link format (Python compatibility)

Values

default_export_options

</>

pub fn default_export_options() -> JsonExportOptions(
  String,
  String,
)

Creates default export options for String node and edge data.

Default Settings

Format: Generic
Include metadata: True
Pretty print: True
Node serializer: Converts strings to JSON strings
Edge serializer: Converts strings to JSON strings

Example

let options = json.default_export_options()
json.to_json(graph, options)

error_to_string

</>

pub fn error_to_string(error: JsonError) -> String

Converts a JsonError to a human-readable string.

Example

case json.to_json_file(graph, "output.json", options) {
  Ok(_) -> "Success!"
  Error(e) -> json.error_to_string(e)
}

export_options_with

</>

pub fn export_options_with(
  node_serializer: fn(n) -> json.Json,
  edge_serializer: fn(e) -> json.Json,
) -> JsonExportOptions(n, e)

Creates export options with custom serializers for generic types.

Use this when your graph contains custom data types that need special conversion to JSON.

Example

pub type Person {
  Person(name: String, age: Int)
}

let options = json.export_options_with(
  node_serializer: fn(person) {
    json.object([
      #("name", json.string(person.name)),
      #("age", json.int(person.age)),
    ])
  },
  edge_serializer: fn(weight) { json.int(weight) },
)

to_cytoscape_json

</>

pub fn to_cytoscape_json(
  graph: model.Graph(n, e),
  node_serializer: fn(n) -> json.Json,
  edge_serializer: fn(e) -> json.Json,
) -> String

Quick export for Cytoscape.js with default settings.

to_d3_json

</>

pub fn to_d3_json(
  graph: model.Graph(n, e),
  node_serializer: fn(n) -> json.Json,
  edge_serializer: fn(e) -> json.Json,
) -> String

Quick export for D3.js force-directed graphs with default settings.

This is a convenience function that exports graphs in D3.js format with sensible defaults.

Example

let d3_json = json.to_d3_json(graph, json.string, json.string)

to_json

</>

pub fn to_json(
  graph: model.Graph(n, e),
  options: JsonExportOptions(n, e),
) -> String

Converts a graph to a JSON string.

This function serializes a graph to JSON format according to the specified options and format preset.

Time Complexity: O(V + E)

Example

import yog/model
import yog_io/json

pub fn main() {
  let graph =
    model.new(model.Directed)
    |> model.add_node(1, "Alice")
    |> model.add_node(2, "Bob")
    |> model.add_edge(from: 1, to: 2, with: "follows")

  let json_string = json.to_json(graph, json.default_export_options())
  // Returns JSON string representation
}

to_json_file

</>

pub fn to_json_file(
  graph: model.Graph(n, e),
  path: String,
  options: JsonExportOptions(n, e),
) -> Result(Nil, JsonError)

Exports a graph to a JSON file.

This function writes the graph to a file in the specified JSON format. The file will be created if it doesn’t exist, or overwritten if it does.

Example

case json.to_json_file(graph, "output.json", json.default_export_options()) {
  Ok(_) -> io.println("Graph saved successfully")
  Error(json.WriteError(path, error)) -> {
    io.println("Failed to write to " <> path <> ": " <> error)
  }
  Error(_) -> io.println("Unknown error")
}

to_json_file_multi

</>

pub fn to_json_file_multi(
  graph: model.MultiGraph(n, e),
  path: String,
  options: JsonExportOptions(n, e),
) -> Result(Nil, JsonError)

Exports a multigraph to a JSON file.

This function writes the multigraph to a file in the specified JSON format. The file will be created if it doesn’t exist, or overwritten if it does.

Example

case json.to_json_file_multi(graph, "output.json", json.default_export_options()) {
  Ok(_) -> io.println("Multigraph saved successfully")
  Error(json.WriteError(path, error)) -> {
    io.println("Failed to write to " <> path <> ": " <> error)
  }
  Error(_) -> io.println("Unknown error")
}

to_json_multi

</>

pub fn to_json_multi(
  graph: model.MultiGraph(n, e),
  options: JsonExportOptions(n, e),
) -> String

Converts a multigraph to a JSON string.

This function serializes a multigraph to JSON format with edge IDs to preserve parallel edges. All formats include unique edge identifiers.

Time Complexity: O(V + E)

Example

import yog/multi/model as multi
import yog_io/json

pub fn main() {
  let graph =
    multi.new(multi.Directed)
    |> multi.add_node(1, "Alice")
    |> multi.add_node(2, "Bob")
    |> multi.add_edge(from: 1, to: 2, with: "follows")
    |> multi.add_edge(from: 1, to: 2, with: "mentions")

  let json_string = json.to_json_multi(graph, json.default_export_options())
  // Returns JSON with edge IDs for parallel edges
}

to_visjs_json

</>

pub fn to_visjs_json(
  graph: model.Graph(n, e),
  node_serializer: fn(n) -> json.Json,
  edge_serializer: fn(e) -> json.Json,
) -> String

Quick export for vis.js networks with default settings.