Skip to content

Commit 59fb352

Browse files
LittleCoinCoinLittleCoinCoin
authored
Merge pull request #25 from LittleCoinCoin/schema-updates
feat(schemas): add package schema v1.2.2 with conda channel support
2 parents b45934d + 524d328 commit 59fb352

8 files changed

Lines changed: 644 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ JSON schemas for the CrackingShells organization package ecosystem.
77
This repository contains JSON schemas for validating Hatch metadata:
88

99
- **Package Schema**: Validates individual package metadata. [Learn More](docs/package/overview.md)
10-
- Latest: `package/v1.2.1/hatch_pkg_metadata_schema.json`
11-
- Versioned: `package/v1.2.1/hatch_pkg_metadata_schema.json`, `package/v1.2.0/hatch_pkg_metadata_schema.json`
10+
- Latest: `package/v1.2.2/hatch_pkg_metadata_schema.json`
11+
- Versioned: `package/v1.2.2/hatch_pkg_metadata_schema.json`, `package/v1.2.1/hatch_pkg_metadata_schema.json`, `package/v1.2.0/hatch_pkg_metadata_schema.json`
1212
- Deprecated: `package/v1.0/hatch_pkg_metadata_schema.json`, `package/v1.1.0/hatch_pkg_metadata_schema.json`
1313

1414
- **Registry Schema**: Validates the central package registry. [Learn More](docs/registry/overview.md)

‎docs/package/examples.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,62 @@
22

33
This document provides examples of valid package metadata files compliant with the Hatch Package Schema.
44

5+
## v1.2.2 Conda Channel Support Example
6+
7+
```json
8+
{
9+
"$schema": "https://raw.githubusercontent.com/crackingshells/Hatch-Schemas/main/package/v1.2.2/hatch_pkg_metadata_schema.json",
10+
"package_schema_version": "1.2.2",
11+
"name": "bioinformatics_package",
12+
"version": "1.0.0",
13+
"description": "A bioinformatics package with conda channel support",
14+
"tags": ["bioinformatics", "conda", "maboss"],
15+
"author": {
16+
"name": "Jane Doe",
17+
"email": "jane.doe@example.com"
18+
},
19+
"license": {
20+
"name": "MIT"
21+
},
22+
"entry_point": {
23+
"mcp_server": "mcp_server.py",
24+
"hatch_mcp_server": "hatch_mcp_server.py"
25+
},
26+
"tools": [
27+
{"name": "simulate", "description": "Run MaBoSS simulation."},
28+
{"name": "analyze", "description": "Analyze simulation results."}
29+
],
30+
"dependencies": {
31+
"hatch": [],
32+
"python": [
33+
{
34+
"name": "maboss",
35+
"version_constraint": ">=2.5.0",
36+
"package_manager": "conda",
37+
"channel": "colomoto"
38+
},
39+
{
40+
"name": "biopython",
41+
"version_constraint": ">=1.78",
42+
"package_manager": "conda",
43+
"channel": "conda-forge"
44+
},
45+
{
46+
"name": "requests",
47+
"version_constraint": ">=2.25.0",
48+
"package_manager": "pip"
49+
}
50+
],
51+
"system": [],
52+
"docker": []
53+
},
54+
"citations": {
55+
"origin": "Jane Doe, \"Bioinformatics MCP Server for Hatch!\", 2025",
56+
"mcp": "Jane Doe, \"MaBoSS Integration Tools for Hatch!\", 2025"
57+
}
58+
}
59+
```
60+
561
## v1.2.1 Dual Entry Point Example
662

763
```json

‎docs/package/fields.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -147,17 +147,21 @@ This document provides detailed information about each field in the Package Sche
147147
- **Each Dependency**:
148148
- **name** (String): Name of the Python package
149149
- **version_constraint** (String): Version constraint (e.g., ">=1.0.0")
150-
- **package_manager** (String, default: "pip"): Package manager to use
150+
- **package_manager** (String, default: "pip"): Package manager to use ("pip" or "conda")
151+
- **channel** (String, optional): Conda channel to use when package_manager is "conda" (e.g., "colomoto", "conda-forge", "bioconda")
151152
- **Example**:
152153
```json
153154
"python": [
154155
{
155156
"name": "numpy",
156-
"version_constraint": ">=1.20.0"
157+
"version_constraint": ">=1.20.0",
158+
"package_manager": "pip"
157159
},
158160
{
159-
"name": "pandas",
160-
"version_constraint": ">=1.3.0"
161+
"name": "maboss",
162+
"version_constraint": ">=2.5.0",
163+
"package_manager": "conda",
164+
"channel": "colomoto"
161165
}
162166
]
163167
```

‎docs/package/overview.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,15 @@ The Package Schema (`hatch_pkg_metadata_schema.json`) defines the structure for
66

77
## Current Version
88

9-
The current version of the Package Schema is **v1.2.1**.
9+
The current version of the Package Schema is **v1.2.2**.
10+
11+
### Version History
12+
13+
- **v1.2.2**: Added conda channel support for Python dependencies
14+
- **v1.2.1**: Introduced dual entry point support
15+
- **v1.2.0**: Enhanced dependency management
16+
- **v1.1.0**: Added comprehensive validation
17+
- **v1.0**: Initial release
1018

1119
## Schema Structure
1220

‎docs/package/v1.2.2_migration_guide.md‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
# Migration Guide: Schema v1.2.1 → v1.2.2
2+
3+
## Overview
4+
5+
Schema version 1.2.2 introduces **conda channel support** for Python dependencies, enabling packages to specify conda channels for package installation. This enhancement allows for more flexible dependency management, particularly for scientific packages that are distributed through specialized conda channels like `colomoto`, `conda-forge`, or `bioconda`.
6+
7+
## Key Changes in v1.2.2
8+
9+
### 1. Conda Package Manager Support
10+
11+
**v1.2.1 (Pip Only)**:
12+
```json
13+
{
14+
"package_schema_version": "1.2.1",
15+
"dependencies": {
16+
"python": [
17+
{
18+
"name": "numpy",
19+
"version_constraint": ">=1.20.0",
20+
"package_manager": "pip"
21+
}
22+
]
23+
}
24+
}
25+
```
26+
27+
**v1.2.2 (Conda with Channel Support)**:
28+
```json
29+
{
30+
"package_schema_version": "1.2.2",
31+
"dependencies": {
32+
"python": [
33+
{
34+
"name": "maboss",
35+
"version_constraint": ">=2.5.0",
36+
"package_manager": "conda",
37+
"channel": "colomoto"
38+
},
39+
{
40+
"name": "numpy",
41+
"version_constraint": ">=1.20.0",
42+
"package_manager": "pip"
43+
}
44+
]
45+
}
46+
}
47+
```
48+
49+
### 2. New Channel Field
50+
51+
The new optional `channel` field allows specifying conda channels:
52+
53+
- **Type**: String (optional)
54+
- **Pattern**: `^[a-zA-Z0-9_\-]+$`
55+
- **Description**: Conda channel to use when `package_manager` is 'conda'
56+
- **Examples**: `"colomoto"`, `"conda-forge"`, `"bioconda"`
57+
- **Usage**: Only applicable when `package_manager` is `"conda"`
58+
59+
## Migration Steps
60+
61+
### Step 1: Update Schema Version
62+
63+
Change the `package_schema_version` from `"1.2.1"` to `"1.2.2"`:
64+
65+
```json
66+
{
67+
"package_schema_version": "1.2.2"
68+
}
69+
```
70+
71+
### Step 2: Add Conda Dependencies (Optional)
72+
73+
If your package requires conda packages, update the Python dependencies:
74+
75+
**Before (v1.2.1)**:
76+
```json
77+
"dependencies": {
78+
"python": [
79+
{
80+
"name": "some-package",
81+
"version_constraint": ">=1.0.0"
82+
}
83+
]
84+
}
85+
```
86+
87+
**After (v1.2.2)**:
88+
```json
89+
"dependencies": {
90+
"python": [
91+
{
92+
"name": "some-package",
93+
"version_constraint": ">=1.0.0",
94+
"package_manager": "conda",
95+
"channel": "conda-forge"
96+
}
97+
]
98+
}
99+
```
100+
101+
## Common Use Cases
102+
103+
### Scientific Computing Packages
104+
105+
Many scientific packages are available through specialized conda channels:
106+
107+
```json
108+
{
109+
"dependencies": {
110+
"python": [
111+
{
112+
"name": "maboss",
113+
"version_constraint": ">=2.5.0",
114+
"package_manager": "conda",
115+
"channel": "colomoto"
116+
},
117+
{
118+
"name": "bioconductor-deseq2",
119+
"version_constraint": ">=1.30.0",
120+
"package_manager": "conda",
121+
"channel": "bioconda"
122+
},
123+
{
124+
"name": "pytorch",
125+
"version_constraint": ">=1.9.0",
126+
"package_manager": "conda",
127+
"channel": "pytorch"
128+
}
129+
]
130+
}
131+
}
132+
```
133+
134+
### Mixed Package Managers
135+
136+
You can mix pip and conda dependencies in the same package:
137+
138+
```json
139+
{
140+
"dependencies": {
141+
"python": [
142+
{
143+
"name": "numpy",
144+
"version_constraint": ">=1.20.0",
145+
"package_manager": "pip"
146+
},
147+
{
148+
"name": "maboss",
149+
"version_constraint": ">=2.5.0",
150+
"package_manager": "conda",
151+
"channel": "colomoto"
152+
}
153+
]
154+
}
155+
}
156+
```
157+
158+
## Validation Rules
159+
160+
### Channel Field Validation
161+
162+
- The `channel` field is **optional**
163+
- Only valid when `package_manager` is `"conda"`
164+
- Must match pattern: `^[a-zA-Z0-9_\-]+$`
165+
- Common valid channels: `colomoto`, `conda-forge`, `bioconda`, `pytorch`, `nvidia`
166+
167+
### Package Manager Enum
168+
169+
The `package_manager` field now accepts:
170+
- `"pip"` (default)
171+
- `"conda"`
172+
173+
## Complete Example
174+
175+
Here's a complete v1.2.2 package with conda channel support:
176+
177+
```json
178+
{
179+
"$schema": "https://raw.githubusercontent.com/crackingshells/Hatch-Schemas/main/package/v1.2.2/hatch_pkg_metadata_schema.json",
180+
"package_schema_version": "1.2.2",
181+
"name": "bioinformatics_package",
182+
"version": "1.0.0",
183+
"description": "A bioinformatics package with conda dependencies",
184+
"tags": ["bioinformatics", "conda"],
185+
"author": {
186+
"name": "Jane Doe",
187+
"email": "jane.doe@example.com"
188+
},
189+
"license": {
190+
"name": "MIT"
191+
},
192+
"entry_point": {
193+
"mcp_server": "mcp_server.py",
194+
"hatch_mcp_server": "hatch_mcp_server.py"
195+
},
196+
"dependencies": {
197+
"python": [
198+
{
199+
"name": "maboss",
200+
"version_constraint": ">=2.5.0",
201+
"package_manager": "conda",
202+
"channel": "colomoto"
203+
},
204+
{
205+
"name": "biopython",
206+
"version_constraint": ">=1.78",
207+
"package_manager": "conda",
208+
"channel": "conda-forge"
209+
},
210+
{
211+
"name": "requests",
212+
"version_constraint": ">=2.25.0",
213+
"package_manager": "pip"
214+
}
215+
]
216+
}
217+
}
218+
```
219+
220+
## Backward Compatibility
221+
222+
- **Existing v1.2.1 and earlier packages continue to work unchanged**
223+
- No breaking changes to existing packages
224+
- The `channel` field is optional and only used with conda
225+
- Migration to v1.2.2 is optional but recommended for packages requiring conda dependencies
226+
227+
## Benefits of Migration
228+
229+
1. **Conda Channel Support**: Access to specialized scientific package repositories
230+
2. **Flexible Package Management**: Mix pip and conda dependencies as needed
231+
3. **Better Scientific Computing Support**: Access to bioconda, conda-forge, and other channels
232+
4. **Future-Proof**: Foundation for additional package manager enhancements
233+
234+
## Troubleshooting
235+
236+
### Common Migration Issues
237+
238+
**Issue**: Channel validation fails
239+
**Solution**: Ensure channel name matches pattern `^[a-zA-Z0-9_\-]+$`
240+
241+
**Issue**: Channel specified with pip package manager
242+
**Solution**: Only use `channel` field when `package_manager` is `"conda"`
243+
244+
**Issue**: Schema validation fails
245+
**Solution**: Ensure `package_schema_version` is exactly `"1.2.2"`
246+
247+
### Getting Help
248+
249+
- Check validation error messages for specific guidance
250+
- Refer to the complete examples in this guide
251+
- Review conda channel documentation for valid channel names
252+
253+
## Next Steps
254+
255+
After migration:
256+
1. Test your package with conda dependencies
257+
2. Update your documentation to reflect conda requirements
258+
3. Consider incrementing your package version to indicate the new capabilities
259+
4. Update any CI/CD pipelines to handle conda installations

‎docs/usage/access.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,8 @@ Access schema files directly from the GitHub repository:
3232

3333
```bash
3434
# Direct access to schema files (always current from main branch)
35-
https://raw.githubusercontent.com/crackingshells/Hatch-Schemas/main/package/v1.2.0/hatch_pkg_metadata_schema.json
35+
https://raw.githubusercontent.com/crackingshells/Hatch-Schemas/main/package/v1.2.2/hatch_pkg_metadata_schema.json
36+
https://raw.githubusercontent.com/crackingshells/Hatch-Schemas/main/package/v1.2.1/hatch_pkg_metadata_schema.json
3637
https://raw.githubusercontent.com/crackingshells/Hatch-Schemas/main/registry/v1.2.0/hatch_all_pkg_metadata_schema.json
3738
```
3839

@@ -45,7 +46,8 @@ You can reference these schemas in your JSON files using the `$schema` property:
4546

4647
```json
4748
{
48-
"$schema": "https://raw.githubusercontent.com/crackingshells/Hatch-Schemas/main/package/v1.2.0/hatch_pkg_metadata_schema.json",
49+
"$schema": "https://raw.githubusercontent.com/crackingshells/Hatch-Schemas/main/package/v1.2.2/hatch_pkg_metadata_schema.json",
50+
"package_schema_version": "1.2.2",
4951
"name": "my_package",
5052
"version": "1.0.0",
5153
"description": "My awesome package",

0 commit comments

Comments
 (0)