README.md

JSON Transmute

Define transformations of JSON with JSON.

This document does not describe a specific implementation, it describes the Transmute "protocol" that implementations should adhere to.

Aside from documenting the operations of Transmute, this repository contains test JSON files, which can be used to validate an implementation.

Introduction

type JSON = null|boolean|number|string|array|object

Transmute(Expression: JSON, Context: JSON) -> JSON

Expression : Describes a new JSON object created from Context. Expression is always fully recursive.

Context : Application specific data.

Expressions

expression describes the resulting JSON. It can contain operator expressions referencing context. Any valid JSON is a valid transmute expression. Without any operator, expression simply describes the resulting JSON value.

let expression = {
    "person": {
        "firstname": "Alice"
    }
}
let context = {
    "description": "this context isn't being referenced in expression"
}
Transmute(expression, context) === {
    "person": {
        "firstname": "Alice"
    }
}

JSON-Path

Property values must be checked if they're JSON-Path strings, that is, they're starting with a $ (dollar) symbol. In that case, the JSON-Path is evaluated against context and matching value is retrieved.

let expression = "$.person.firstname"
let context = {
    "person": {
        "firstname": "Albert"
    }
}
Transmute(expression, context) === ["Albert"]

let expression = "$.products.*.price"
let context = {
    "products": [
        {
            "price": "$4.00"
        },
        {
            "price": "$12.99"
        }
    ]
}
Transmute(expression, context) === ["$4.00", "$12.99"]

let expression = "$.products.*.title"
let context = {
    "products": [
        {
            "price": "$4.00"
        },
        {
            "price": "$12.99"
        }
    ]
}
Transmute(expression, context) === []

Operators

• #coalesce exclude null values
• #concat concatenate (multiple) arrays
• #extend copy object and modify
• #first first element of arrays
• #format string formatting
• #map create arrays
• #sum calculate sum of arrays of numbers
• #transmute defer evaluation

Test validation

Test JSON files define objects with three properties: expression, context, result. Implementations are valid, if they're able to produce result from expression and context.