Skip to main content
skill CX Codex

json-parser — Claude Code skill: parsing JSON and setup

json-parser is a skill that parses and checks JSON from construction APIs, IoT sensors, and BIM exports, turning nested records into tables for structured-data projects.

MIT 115 installs ★ 434 updated 2026-10-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill json-parser -a claude-code
Open on GitHub

What json-parser does

This skill reads JSON from a file or a string, reports parse errors, and counts records. It flattens nested objects into single-level fields and converts records to pandas.DataFrame values. Nested data can also be queried with dot-notation paths.

The code includes a base parser plus BIM and IoT variants. The BIM parser looks for elements under elements, objects, or entities, flattens them, and gathers properties from properties, params, parameters, or attributes. The IoT parser maps sensor readings to an identifier, timestamp, value, unit, and location.

Schema checks compare flattened data with required field names and return present and missing fields. The skill needs python3 available, and table conversion relies on pandas. That dependency matters when the agent is asked to build a DataFrame.

What it helps with

  • parse JSON from a file or string
  • flatten nested records into columns
  • turn JSON data into a pandas.DataFrame
  • read values through a dotted path
  • check required fields against a schema

Example prompts for the agent

  • Use the json-parser skill to read bim_export.json and turn its records into a DataFrame.
  • Validate this JSON against the required fields project.id and project.name.
  • Extract the sensor readings from the nested payload and prepare a table.

How to install json-parser

1Skills CLI (Vercel)

npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill json-parser -a claude-code

2Manually: put the files in place

~/.claude/skills/json-parser/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/json-parser/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about json-parser

How do I install json-parser in Claude Code?

Run npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill json-parser -a claude-code. The installed skill is available at ~/.claude/skills/json-parser/SKILL.md.

What does json-parser do?

It loads JSON from files or strings, checks required fields, flattens nested structures, and creates pandas.DataFrame objects. Separate handlers cover BIM elements and IoT sensor readings.

What does json-parser need to create a DataFrame?

The implementation uses Python and pandas. The environment needs the python3 binary available.

Source text

SKILL.md · MIT
---
name: "json-parser"
description: "Parse and validate JSON data from construction APIs, IoT sensors, and BIM exports. Transform nested JSON to flat DataFrames."
homepage: "https://datadrivenconstruction.io"
metadata: {"openclaw": {"emoji": "🏷️", "os": ["win32"], "homepage": "https://datadrivenconstruction.io", "requires": {"bins": ["python3"]}}}
---
# JSON Parser for Construction Data

## Overview
Construction systems increasingly use JSON for data exchange - from IoT sensors to BIM metadata exports. This skill handles parsing, validation, and flattening of JSON structures.

## Python Implementation

```python
import json
import pandas as pd
from typing import Dict, Any, List, Optional, Union
from dataclasses import dataclass
from pathlib import Path


@dataclass
class JSONParseResult:
    """Result of JSON parsing operation."""
    success: bool
    data: Any
    errors: List[str]
    record_count: int


class ConstructionJSONParser:
    """Parse JSON data from construction sources."""

    def __init__(self):
        self.errors: List[str] = []

    def parse_file(self, file_path: str) -> JSONParseResult:
        """Parse JSON from file."""
        try:
            with open(file_path, 'r', encoding='utf-8') as f:
                data = json.load(f)
            return JSONParseResult(True, data, [], self._count_records(data))
        except json.JSONDecodeError as e:
            return JSONParseResult(False, None, [f"JSON Error: {e}"], 0)
        except Exception as e:
            return JSONParseResult(False, None, [str(e)], 0)

    def parse_string(self, json_string: str) -> JSONParseResult:
        """Parse JSON from string."""
        try:
            data = json.loads(json_string)
            return JSONParseResult(True, data, [], self._count_records(data))
        except json.JSONDecodeError as e:
            return JSONParseResult(False, None, [f"JSON Error: {e}"], 0)

    def _count_records(self, data: Any) -> int:
        """Count records in data."""
        if isinstance(data, list):
            return len(data)
        elif isinstance(data, dict):
            return 1
        return 0

    def flatten_json(self, data: Dict, prefix: str = '') -> Dict[str, Any]:
        """Flatten nested JSON to single-level dict."""
        flat = {}
        for key, value in data.items():
            new_key = f"{prefix}_{key}" if prefix else key

            if isinstance(value, dict):
                flat.update(self.flatten_json(value, new_key))
            elif isinstance(value, list):
                if all(isinstance(i, (str, int, float, bool, type(None))) for i in value):
                    flat[new_key] = value
                else:
                    for i, item in enumerate(value):
                        if isinstance(item, dict):
                            flat.update(self.flatten_json(item, f"{new_key}_{i}"))
                        else:
                            flat[f"{new_key}_{i}"] = item
            else:
                flat[new_key] = value
        return flat

    def to_dataframe(self, data: Union[List[Dict], Dict]) -> pd.DataFrame:
        """Convert JSON data to DataFrame."""
        if isinstance(data, list):
            flat_records = [self.flatten_json(r) if isinstance(r, dict) else {'value': r} for r in data]
            return pd.DataFrame(flat_records)
        elif isinstance(data, dict):
            if all(isinstance(v, list) for v in data.values()):
                # Dict of lists - columnar format
                return pd.DataFrame(data)
            else:
                flat = self.flatten_json(data)
                return pd.DataFrame([flat])
        return pd.DataFrame()

    def extract_elements(self, data: Dict, path: str) -> List[Any]:
        """Extract elements using dot notation path."""
        parts = path.split('.')
        current = data

        for part in parts:
            if isinstance(current, dict) and part in current:
                current = current[part]
            elif isinstance(current, list) and part.isdigit():
                current = current[int(part)]
            else:
                return []

        return current if isinstance(current, list) else [current]

    def validate_schema(self, data: Dict,
                        required_fields: List[str]) -> Dict[str, Any]:
        """Validate JSON against required fields."""
        flat = self.flatten_json(data)
        missing = [f for f in required_fields if f not in flat]
        present = [f for f in required_fields if f in flat]

        return {
            'valid': len(missing) == 0,
            'missing_fields': missing,
            'present_fields': present,
            'completeness': len(present) / len(required_fields) * 100
        }


# BIM JSON Parser
class BIMJSONParser(ConstructionJSONParser):
    """Specialized parser for BIM JSON exports."""

    def parse_bim_elements(self, data: Dict) -> pd.DataFrame:
        """Parse BIM elements from JSON export."""
        elements = []

        # Common BIM JSON structures
        if 'elements' in data:
            elements = data['elements']
        elif 'objects' in data:
            elements = data['objects']
        elif 'entities' in data:
            elements = data['entities']
        elif isinstance(data, list):
            elements = data

        if not elements:
            return pd.DataFrame()

        # Flatten each element
        flat_elements = []
        for elem in elements:
            if isinstance(elem, dict):
                flat = self.flatten_json(elem)
                flat_elements.append(flat)

        return pd.DataFrame(flat_elements)

    def extract_properties(self, element: Dict) -> Dict[str, Any]:
        """Extract properties from BIM element."""
        props = {}

        # Common property locations in BIM JSON
        for key in ['properties', 'params', 'parameters', 'attributes']:
            if key in element and isinstance(element[key], dict):
                props.update(element[key])

        return props


# IoT JSON Parser
class IoTJSONParser(ConstructionJSONParser):
    """Parser for IoT sensor data."""

    def parse_sensor_reading(self, data: Dict) -> Dict[str, Any]:
        """Parse single sensor reading."""
        return {
            'sensor_id': data.get('sensor_id') or data.get('id'),
            'timestamp': data.get('timestamp') or data.get('time'),
            'value': data.get('value') or data.get('reading'),
            'unit': data.get('unit', ''),
            'location': data.get('location', '')
        }

    def parse_sensor_batch(self, data: List[Dict]) -> pd.DataFrame:
        """Parse batch of sensor readings."""
        readings = [self.parse_sensor_reading(r) for r in data]
        return pd.DataFrame(readings)
```

## Quick Start

```python
parser = ConstructionJSONParser()

# Parse from file
result = parser.parse_file("bim_export.json")
if result.success:
    df = parser.to_dataframe(result.data)
    print(f"Loaded {len(df)} records")

# Flatten nested JSON
flat = parser.flatten_json(result.data)

# Extract specific path
elements = parser.extract_elements(result.data, "project.building.floors")
```

## Common Use Cases

### 1. BIM Metadata
```python
bim_parser = BIMJSONParser()
result = bim_parser.parse_file("revit_export.json")
elements = bim_parser.parse_bim_elements(result.data)
```

### 2. IoT Sensors
```python
iot_parser = IoTJSONParser()
readings = iot_parser.parse_sensor_batch(sensor_data)
```

### 3. API Response
```python
parser = ConstructionJSONParser()
result = parser.parse_string(api_response)
df = parser.to_dataframe(result.data)
```

## Resources
- **DDC Book**: Chapter 2.1 - Semi-structured Data

© datadrivenconstruction · MIT · datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction

Similar skills

All skills for Data and databases →

From the same set156

The whole set →
cwicr-unit-converter cwicr-unit-converter converts between metric and imperial construction units, normalizing BIM and CWICR data across different measurement systems. Eliminates conversion errors when working with mixed data sources. CX Codex +1 115installs clash-detection-analysis clash-detection-analysis detects geometric clashes between IFC BIM elements, identifying physical intersections and clearance violations before construction starts. CX Codex +1 115installs scenario-planner scenario-planner models construction scenarios and compares options by cost, schedule, and resources. Helps you see what happens if you double the crew or compress the timeline. CX Codex +1 115installs ontology-mapper ontology-mapper maps construction data elements to standard schemas like IFC, COBie, and Uniclass for cross-system semantic consistency. CX Codex +1 115installs weather-api weather-api is a Claude Code skill that retrieves weather forecasts and historical data and assesses conditions for construction work. It supports scheduling outdoor tasks. CX Codex +1 115installs capacity-planning capacity-planning forecasts staffing demand and identifies workforce gaps across construction projects. Helps evaluate capacity before pursuing new bids. CX Codex +1 115installs cwicr-location-factor cwicr-location-factor is a Claude Code skill that applies regional labor, material, and equipment factors to CWICR estimates. Compare project costs across regions. CX Codex +1 115installs email-construction email-construction generates structured construction emails: RFI responses, submittal transmittals, change order notices, and meeting invites. CX Codex +1 115installs

Project sponsors

Companies that keep this analytics open