Swift DynamicJSON

All JSON values in the framework are represented using the JSON enumeration. This enum covers all standard JSON types including null, boolean, integer, float, string, array, and object.

You can construct JSON values in several ways:

1. Swift Literal Syntax: Use Swift's native dictionary and array literals to create JSON objects directly.
2. String/Data Initializers: Initialize JSON from a JSON-encoded String or Data object.
3. Encodable Initializer: Convert any Codable Swift type into a JSON value using init(encodable:) or the generic init() which coerces basic types.

// 1. Using Swift literal syntax
let json0: JSON = [
  "foo": true,
  "str": "one two",
  "object": [
    "value": nil,
    "arr": [1, 2, 3],
    "obj": [ "x" : 17.6 ]
  ]
]

// 2. Initializing from a JSON String
let json1 = try JSON(string: """
  {
    "foo": true,
    "str": "one two",
    "object": {
      "value": null,
      "arr": [1, 2, 3],
      "obj": { "x" : 17.6 }
    }
  }
""")

// 3. Converting a Codable type to JSON
struct Person: Codable {
  let name: String
  let age: Int
  let children: [Person]
}
let person = Person(name: "John", age: 34, children: [])
let json2 = try JSON(encodable: person)

To avoid the performance overhead of copying large JSON structures during mutation, DynamicJSON provides two primary mutate patterns. These methods use closures that operate on inout references.

1. Generic Mutation

Use this when you want to perform a custom set of operations on a specific location.

mutating func mutate(_ ref: JSONReference, with proc: (inout JSON) throws -> Void) throws

2. Type-Specific Mutation

Use this when you know the target type (Array or Object) and want to use specialized closures for those types. If the target is neither an array nor an object, the other closure is called.

mutating func mutate(_ ref: JSONReference, 
                     array arrProc: ((inout [JSON]) throws -> Void)? = nil, 
                     object objProc: ((inout [String : JSON]) throws -> Void)? = nil, 
                     other proc: ((inout JSON) throws -> Void)? = nil) throws

// Using the specialized mutate method to update an object
try json.mutate("/user/profile" as JSONReference, object: { obj in
    obj["last_login"] = .string("2025-01-01")
})

A JSONReference is an abstraction used to identify, retrieve, set, or mutate a specific value within a larger JSON document. The library provides two primary protocols for these references:

1. JSONReference: The base protocol for navigating and modifying values. It defines methods for selecting members/indices, retrieving values (get), replacing values (set), and performing in-place mutations (mutate).
2. SegmentableJSONReference: An extension of JSONReference that represents a reference as a sequence of segments. This allows for decomposing a path into its constituent parts (e.g., via deselect).

Common implementations include JSONPointer and JSONLocation.

protocol JSONReference: CustomStringConvertible {
  func select(member: String) -> Self
  func select(index: Int) -> Self
  func get(from value: JSON) -> JSON?
  func set(to json: JSON, in value: JSON) throws -> JSON
  func mutate(_ json: inout JSON, with proc: (inout JSON) throws -> Void) throws
}

protocol SegmentableJSONReference: JSONReference {
  associatedtype Segment: JSONReferenceSegment
  var segments: [Segment] { get }
  func select(segment: Segment) -> Self
  var deselect: (Self, Segment)? { get }
}

JSONPatch implements RFC 6902 to express a sequence of operations that transform one JSON document into another.

Supported Operations (JSONPatchOperation)

• add(path, value): Adds value at path.
• remove(path): Removes the value at path.
• replace(path, value): Replaces the value at path with value.
• move(path, from): Moves the value from from to path.
• copy(path, from): Copies the value from from to path.
• test(path, value): Fails if the value at path does not match value.

Using JSONPatch

You can initialize a JSONPatch from a JSON string, data, or a URL, and then apply it to an existing JSON instance using apply(to:).

To generate a patch between two existing JSON values, use source.patch(to: target).

let jsonstr = """
  [
    { "op": "test", "path": "/a/b/c", "value": "foo" },
    { "op": "remove", "path": "/a/b/c" },
    { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] },
    { "op": "replace", "path": "/a/b/c", "value": 42 },
    { "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
    { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" }
  ]
"""
let patch = try JSONPatch(string: jsonstr)
var json: JSON = ... // your existing JSON
try json.apply(patch: patch)

DynamicJSON allows you to access specific values within a JSON document using several different syntaxes, ranging from native Swift-like member lookup to standardized reference strings.

To access the first element of an array arr inside an object object within a JSON document json1:

• Dynamic member lookup: Use dot notation and optional chaining.
• Keypath lookup: Use Swift KeyPath syntax.
• Subscript lookup: Use standard string-based subscripts.
• Reference lookup: Use [ref:] with a JSONPointer, JSONPath, or JSONLocation string/object.

// Assuming json1 is a JSON document containing { "object": { "arr": [1, 2, 3] } }

// 1. Dynamic member lookup
json1.object?.arr?[0]

// 2. Keypath lookup
json1[keyPath: \.object?.arr?[0]]

// 3. Subscript lookup
json1["object"]?["arr"]?[0]

// 4. Reference lookup (using strings)
try json1[ref: "/object/arr/0"] // JSON Pointer
try json1[ref: "$.object.arr[0]"] // JSON Path

// 5. Reference lookup (using JSONReference objects)
let p: JSONReference = ... 
json1[ref: p]

For complex validation scenarios involving multiple schemas, external references, or custom dialects, use the JSONSchemaRegistry API.

1. Initialize a Registry: Create a JSONSchemaRegistry instance.
2. Register Schemas: Load schemas from strings, files, or via a JSONSchemaProvider (like StaticJSONSchemaFileProvider) to make them discoverable by URI.
3. Obtain a Validator: Use registry.validator(for: dialect:) to get a JSONSchemaValidator for a specific schema resource.
4. Perform Validation: Call validator.validate(json) on your JSON instance to receive a JSONSchemaValidationResult.

// Create a new schema registry
let registry = JSONSchemaRegistry()

// Register a schema resource from a string literal
try registry.register(resource: JSONSchemaResource(string: #"""
  {
    "$id": "https://example.com/schema/test",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "prop1": { ... }
    }
  }
""""))

// Load a schema resource from a file
try registry.loadSchema(from: URL(filePath: "/Users/objecthub/foo.json"))

// Make JSON schema stored in json files under the given directory discoverable
registry.register(provider: 
  StaticJSONSchemaFileProvider(
    directory: URL(filePath: "/Users/objecthub/myschema"),
    base: JSONSchemaIdentifier(string: "http://example.com/schemas")!)
)

// Obtain a validator for a schema
guard let validator = try? registry.validator(for: "https://example.com/schema/test") else {
  // Handle error
}

// Validate a JSON instance `json`
let result = validator.validate(json)
print("valid = \(result.isValid)")