---
title: "JSON Support Section for README"
---

## JSON Support (New in v2.0)

The boilerplate package now supports JSON format alongside the traditional RDS format. JSON offers several advantages for managing boilerplate text:

- **Human readable**: Edit directly in any text editor
- **Version control friendly**: See exactly what changed in git diffs  
- **Language agnostic**: Use with Python, JavaScript, or other tools
- **Web compatible**: Build web-based editors and APIs

### Quick Start with JSON

```{r json-init, eval=FALSE}
# Initialise with JSON format (recommended for new projects)
boilerplate_init(
  data_path = "my_project/data",
  format = "json",
  create_dirs = TRUE,
  confirm = FALSE
)

# Import JSON database
db <- boilerplate_import_json(
  data_path = "my_project/data",
  format = "json"
)

# Save in both formats
boilerplate_save_json(
  db = db,
  format = "both",  # Creates both .json and .rds
  confirm = FALSE
)
```

### Migrating from RDS to JSON

If you have existing RDS databases, you can easily migrate them:

```{r migrate, eval=FALSE}
# Migrate a single file
boilerplate_rds_to_json(
  input_path = "boilerplate/data/methods_db.rds",
  pretty = TRUE
)

# Migrate entire directory to unified JSON
boilerplate_migrate_to_json(
  source_path = "boilerplate/data",
  output_path = "boilerplate/data_json", 
  format = "unified",  # Single JSON file
  validate = TRUE
)
```

### JSON Schema Validation

Ensure your JSON databases are properly structured:

```{r validate, eval=FALSE}
# Validate JSON structure
validation <- validate_boilerplate_json(
  "boilerplate/data/boilerplate_unified.json"
)

# Run validation before commits
# Rscript -e "boilerplate::validate_boilerplate_json('data/boilerplate_unified.json')"
```

### GitHub Actions Integration

Add automatic validation to your repository by including our GitHub Actions workflow:

```yaml
# .github/workflows/validate-boilerplate.yml
name: Validate Boilerplate
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: r-lib/actions/setup-r@v2
      - run: |
          Rscript -e "boilerplate::validate_boilerplate_json('data')"
```

### JSON Structure Example

```json
{
  "methods": {
    "sample": {
      "default": "We recruited {{n}} participants from {{location}}.",
      "large": "We recruited {{n}} participants ({{n_male}} male, {{n_female}} female)."
    },
    "analysis": {
      "regression": {
        "text": "We used {{model_type}} regression with {{software}}.",
        "reference": "Field 2013",
        "keywords": ["regression", "statistical analysis"]
      }
    }
  },
  "measures": {
    "demographics": {
      "age": {
        "name": "age",
        "description": "Age in years",
        "type": "continuous",
        "range": [18, 100],
        "unit": "years"
      }
    }
  }
}
```

### Direct JSON Editing

With JSON format, you can make quick edits without R:

1. Open the JSON file in any text editor
2. Make your changes
3. Validate before committing:
   ```bash
   Rscript -e "boilerplate::validate_boilerplate_json('boilerplate_unified.json')"
   ```

### Lab Workflow with Central JSON Database

For research groups, we recommend a central GitHub repository:

```{r lab-workflow, eval=FALSE}
# Setup new project with central database
source("https://raw.githubusercontent.com/your-lab/boilerplate/main/setup.R")
setup_boilerplate_for_project()

# Update from central repository
update_from_central(show_changes = TRUE)

# Contribute changes back
prepare_contribution(
  category = "methods",
  output_path = "contributions"
)
```

### Advantages for Research Workflows

1. **Collaboration**: Non-R users can view and suggest edits via GitHub
2. **Transparency**: Pull requests show exact text changes for review
3. **History**: Git blame shows who changed what text and when
4. **Integration**: Easy to build web tools, Shiny apps, or Python scripts
5. **Portability**: Share databases across projects and languages

### Backward Compatibility

All existing RDS-based workflows continue to work. The package automatically detects the format:

```{r backward-compat, eval=FALSE}
# Works with both RDS and JSON
db <- boilerplate_import()  # Auto-detects format

# Save in your preferred format
boilerplate_save(db, format = "rds")   # Traditional
boilerplate_save(db, format = "json")  # New
boilerplate_save(db, format = "both")  # Both formats
```
