Dependencies Format Reference

Complete specification for dependencies.json configuration file.

---

File Location

The dependencies.json file must be placed at the root of your repository.

my-project/
├── dependencies.json    
├── src/
├── tests/
└── README.md

---

Minimal Configuration

The simplest valid dependencies.json:

{
  "repos": []
}

This creates an empty dependency list with no sub-dependencies.

---

Full Configuration Schema

{
  "repos": [
    {
      "name": "repository_identifier",
      "url": "https://github.com/org/repo.git",
      "rama": "main",
      "comment": "Optional description"
    }
  ],
  "min_mt5_build": 5830,
  "other_languages": [
    {
      "name": "Python",
      "version": "3.10",
      "requirements" : "requirements.txt"
    }
  ],
  "hooks": {
    "pre_install": [],
    "post_install": [],
    "post_install_only_on_success": true,
    "pre_update": [],
    "post_update": [],
    "post_update_only_on_success": false
  }
}

---

Field Specifications

repos (Array) - Required

List of repository dependencies.

Type: Array of objects
Required: Yes
Default: None
Minimum: 0 items

Object Structure:

Field	Type	Required	Description
name	String	Yes	Unique repository identifier (alphanumeric, underscores allowed)
url	String	Yes	Git repository URL (HTTPS or SSH)
rama	String	Yes	Branch name or tag (e.g., "main", "develop", "v1.0.0")
comment	String	No	Description or purpose of repository

Validation Rules:

• name must be unique across all repos
• name must be alphanumeric + underscores (no spaces or special chars)
• url must be valid Git URL
• rama must exist in the repository
• comment is free text, max 500 characters

Example:

{
  "repos": [
    {
      "name": "core_lib",
      "url": "https://github.com/trading/core-lib.git",
      "rama": "main",
      "comment": "Core trading library with indicators"
    },
    {
      "name": "data_processor",
      "url": "git@github.com:trading/data-processor.git",
      "rama": "develop",
      "comment": "Data cleaning and normalization"
    }
  ]
}

---

min_mt5_build (Integer) - Optional

Minimum MetaTrader 5 build requirement.

Type: Integer
Required: No
Default: None

Example:

{
  "min_mt5_build": 5830
}

---

other_languages (Array) - Optional

Programming languages and versions required by the project.

Type: Array of objects
Required: No
Default: Empty array

Object Structure:

Field	Type	Required	Description
name	String	Yes	Language name (e.g., "Python", "Node.js")
version	String	No	Semantic version (e.g., "3.10", "18.0.0", ">=3.10")
requirements	String\String Array	No	Requirements file

Example:

{
  "other_languages": [
    {
      "name": "Python",
      "version": "3.10",
      "requirements" : "requirements.txt"
    },
    {
      "name": "Node.js",
      "version": "18.0"
    },
    {
      "name": "Git"
    }
  ]
}

---

hooks (Object) - Optional

Command execution at specific lifecycle points.

Type: Object
Required: No
Default: Empty hooks (no commands execute)

Structure:

{
  "hooks": {
    "pre_install": [],
    "post_install": [],
    "post_install_only_on_success": true,
    "pre_update": [],
    "post_update": [],
    "post_update_only_on_success": false
  }
}

Hook Arrays:

• pre_install: Commands before cloning/pulling
• post_install: Commands after successful install
• pre_update: Commands before pulling updates
• post_update: Commands after pulling updates

Conditional Flags:

• post_install_only_on_success: Only run if ALL installs succeeded
• post_update_only_on_success: Only run if ALL updates succeeded

Hook Command Object:

Field	Type	Required	Description
command	String	Yes	Shell command to execute
permitir_fallo	Boolean	No	Continue if fails (default: false)
timeout_ms	Integer	No	Max execution time (default: 60000)

Example:

{
  "hooks": {
    "pre_install": [
      {
        "command": "echo 'Starting installation'",
        "permitir_fallo": false,
        "timeout_ms": 5000
      }
    ],
    "post_install": [
      {
        "command": "python -m pip install -r requirements.txt",
        "permitir_fallo": true,
        "timeout_ms": 120000
      },
      {
        "command": "python setup.py install",
        "permitir_fallo": true,
        "timeout_ms": 60000
      }
    ],
    "post_install_only_on_success": true
  }
}

See HOOKS.md for detailed hook documentation.

---

Complete Example

{
  "repos": [
    {
      "name": "core_library",
      "url": "https://github.com/trading/core-lib.git",
      "rama": "main",
      "comment": "Essential trading library with indicators and utilities"
    },
    {
      "name": "data_processor",
      "url": "https://github.com/trading/data-processor.git",
      "rama": "develop",
      "comment": "Time series data cleaning and normalization"
    },
    {
      "name": "ml_models",
      "url": "https://github.com/trading/ml-models.git",
      "rama": "v2.1.0",
      "comment": "Pre-trained machine learning models"
    }
  ],
  "min_mt5_build": 5830,
  "other_languages": [
    {
      "name": "Python",
      "version": "3.10"
    },
    {
      "name": "Node.js",
      "version": "18.0"
    }
  ],
  "hooks": {
    "pre_install": [
      {
        "command": "git --version",
        "permitir_fallo": false,
        "timeout_ms": 5000
      }
    ],
    "post_install": [
      {
        "command": "pip install -r requirements.txt",
        "permitir_fallo": true,
        "timeout_ms": 120000
      }
    ],
    "post_install_only_on_success": true,
    "pre_update": [],
    "post_update": [],
    "post_update_only_on_success": false
  }
}

---

Validation Rules

Repository Rules

• Repository names must be unique
• URLs must be accessible
• Branches/tags must exist

File Rules

• Must be valid JSON
• All required fields present
• Proper data types
• UTF-8 encoding

Nested Dependencies

TSNDep automatically processes nested dependencies:

main-project/
├── repo-a/
│   └── dependencies.json (has repo-b, repo-c)
│       ├── repo-b/
│       │   └── dependencies.json (has repo-d)
│       └── repo-c/
└── repo-d/

Duplicate Prevention: If repo-d appears at multiple levels, it's only cloned once.

---

Common Configurations

Simple Project (Single Dependency)

{
  "repos": [
    {
      "name": "helper_lib",
      "url": "https://github.com/org/helper.git",
      "rama": "main"
    }
  ]
}

Production Project (Multiple Dependencies)

{
  "repos": [
    {
      "name": "core",
      "url": "https://github.com/org/core.git",
      "rama": "stable"
    },
    {
      "name": "data",
      "url": "https://github.com/org/data.git",
      "rama": "stable"
    },
    {
      "name": "ml",
      "url": "https://github.com/org/ml.git",
      "rama": "v3.1.0"
    }
  ],
  "min_mt5_build": 5830,
  "hooks": {
    "post_install_only_on_success": true,
    "post_install": [
      {
        "command": "python scripts/validate.py",
        "permitir_fallo": false,
        "timeout_ms": 30000
      }
    ]
  }
}

Development Project (Multiple Branches)

{
  "repos": [
    {
      "name": "core",
      "url": "https://github.com/org/core.git",
      "rama": "develop",
      "comment": "Core library (dev branch)"
    },
    {
      "name": "features",
      "url": "https://github.com/org/features.git",
      "rama": "feature/new-indicators",
      "comment": "New features being developed"
    }
  ]
}

---

Best Practices

Do

• Keep repository names descriptive
• Use stable branches for production (e.g., "main", "stable")
• Document purpose in comment
• Use semantic versioning for tags
• Pin to specific versions when possible

Don't

• Use spaces in repository names
• Leave comment empty for important repos
• Point to unknown/unstable branches
• Have circular dependencies
• Use different branch names for same repo