Quick Start

Get up and running with ISL Transform in just 5 minutes!

What is ISL?

ISL is a JSON-to-JSON transformation language that makes data transformations simple and intuitive.

⌨️ If it looks like a JSON it’s a valid ISL :)

Step 1: Add ISL to Your Project

Maven

<dependency>
    <groupId>com.intuit.isl</groupId>
    <artifactId>isl-transform</artifactId>
    <version>[version]</version>
</dependency>

Gradle

dependencies {
    implementation("com.intuit.isl:isl-transform:[version]")
}

Requirements: Java 21 or higher

Step 2: Write Your First Transformation

Let’s transform a product JSON into a simpler format.

Input JSON:

{
  "title": "IPod Nano - 8GB",
  "id": 632910392,
  "vendor": "Apple",
  "status": "active",
  "tags": "Emotive, Flash Memory, MP3, Music"
}

ISL Transformation:

{
    id: $input.id,
    name: $input.title,
    description: `${$input.title} by ${$input.vendor}`,
    isActive: if( $input.status == 'active' ) true else false,
    tags: $input.tags | split(',') | map( $ | trim )
}

Note that quotation marks around property names are optional in ISL to make the code more readable. You only need to use them for properties with special names like "first name": $input.firstName

Output JSON:

{
  "id": 632910392,
  "name": "IPod Nano - 8GB",
  "description": "IPod Nano - 8GB by Apple",
  "isActive": true,
  "tags": ["Emotive", "Flash Memory", "MP3", "Music"]
}

Step 3: Run It in Java/Kotlin

Java Example

import com.intuit.isl.common.OperationContext;
import com.intuit.isl.runtime.TransformCompiler;
import com.intuit.isl.runtime.ITransformer;
import com.intuit.isl.utils.JsonConvert;
import com.fasterxml.jackson.databind.JsonNode;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        // 1. Define your ISL script
        String islScript = """
            {
                id: $input.id,
                name: $input.title,
                description: `${ $input.title } by ${ $input.vendor }`,
                isActive: if( $input.status == 'active' ) true else false,
                tags: $input.tags | split(',') | map( $ | trim )
            }
            """;
        
        // 2. Compile the script (do this once, reuse many times!)
        TransformCompiler compiler = new TransformCompiler();
        // Make sure you cache this transformer if you plan to reuse it
        ITransformer transformer = compiler.compileIsl("product-transform", islScript);
        
        // 3. Prepare your input data
        String inputJson = """
            {
              "title": "IPod Nano - 8GB",
              "id": 632910392,
              "vendor": "Apple",
              "status": "active",
              "tags": "Emotive, Flash Memory, MP3, Music"
            }
            """;
        
        // 4. Create context and set variables
        // Make sure you don't cache this context. This is unique per execution
        OperationContext context = new OperationContext();
        context.setVariable("$input", JsonConvert.convert(inputJson));
        
        // 5. Execute the transformation
        JsonNode result = transformer.runTransformSync("run", context);
        
        // 6. Print the result
        System.out.println(JsonConvert.mapper.writerWithDefaultPrettyPrinter()
                                           .writeValueAsString(result));
    }
}

Kotlin Example

import com.intuit.isl.common.OperationContext
import com.intuit.isl.runtime.TransformCompiler
import com.intuit.isl.utils.JsonConvert

fun main() {
    // 1. Define your ISL script
    val islScript = """
        {
            id: ${'$'}input.id,
            name: ${'$'}input.title,
            description: `${'$'}{${'$'}input.title} by ${'$'}{${'$'}input.vendor}`,
            isActive: if ( ${'$'}input.status == 'active' ) true else false,
            tags: ${'$'}input.tags | split(',') | map( ${'$'} | trim )
        }
    """.trimIndent()
    
    // 2. Compile the script (do this once, reuse many times!)
    val compiler = TransformCompiler()
    val transformer = compiler.compileIsl("product-transform", islScript)
    
    // 3. Prepare your input data
    val inputJson = """
        {
          "title": "IPod Nano - 8GB",
          "id": 632910392,
          "vendor": "Apple",
          "status": "active",
          "tags": "Emotive, Flash Memory, MP3, Music"
        }
    """.trimIndent()
    
    // 4. Create context and set variables
    val context = OperationContext()
    context.setVariable("\$input", JsonConvert.convert(inputJson))
    
    // 5. Execute the transformation
    val result = transformer.runTransformSync("run", context)
    
    // 6. Print the result
    println(JsonConvert.mapper.writerWithDefaultPrettyPrinter().writeValueAsString(result))
}

🎯 Key Concepts

• Variables start with $: $input, $name, $total
• Modifiers use pipes |: $text | trim | upperCase
• String interpolation uses backticks: `Hello ${$name}!`
• Arrays use [...]: [1, 2, 3]
• Objects use {...}: { name: $value }
• Functions use @.: @.Date.Now()

⚡ Performance Tips

• Pre-compile once, reuse many times: Compilation is expensive (~0.5ms), execution is fast (~0.03ms)
• Don’t cache OperationContext: Create a new context for each transformation
• Pre-compiled transformations are 19x faster than compiling every time!

📚 Next Steps

Now that you’ve got the basics, explore more features:

1. Language Overview - Learn ISL syntax and structure
2. Modifiers Reference - 100+ built-in modifiers for strings, arrays, objects, dates, and more
3. Functions - Create reusable functions and custom modifiers
4. Conditionals - If/else, switch statements, and regex matching
5. Math Operations - Math expressions and functions
6. Best Practices - Performance optimization and patterns
7. Examples - Real-world transformation examples

🚀 What Can ISL Do?

• ✅ Transform JSON to JSON with minimal code
• ✅ Parse and format dates with timezone support
• ✅ Process arrays with map, filter, reduce
• ✅ Handle XML and CSV conversions
• ✅ Perform cryptographic operations (SHA, HMAC, Base64)
• ✅ Execute complex conditionals and loops
• ✅ Call custom Java/Kotlin functions
• ✅ 29,000+ transformations per second (single-threaded, pre-compiled)

💡 Common Use Cases

• API Response Mapping: Transform external API responses to your internal format
• Data Enrichment: Add calculated fields, format data, apply business rules
• ETL Pipelines: Extract, transform, and load data between systems
• Configuration-Driven Transformations: Let users define transformations without code
• Microservice Integration: Normalize data between different service contracts

🆘 Need Help?

• Documentation: Check the full documentation
• Examples: Browse example transformations
• Support: See support options

---

Ready to dive deeper? Start with the Language Overview or explore the Modifiers Reference!